ADK-Python项目中状态变量引用格式的注意事项

在基于ADK-Python框架开发顺序工作流代理时，开发者需要特别注意状态变量的引用方式。本文深入解析状态变量在代理间传递时的正确使用方法，帮助开发者避免常见陷阱。

状态变量传递机制解析

ADK框架提供了代理间状态共享的能力，允许前一个代理的输出作为后一个代理的输入。这种机制通过内存状态存储实现，为复杂工作流提供了数据传递的便利通道。

常见误区与正确写法

许多开发者容易犯的一个典型错误是使用引号包裹状态变量名。例如：

# 错误写法（文档中原示例）
prompt = "基于这个创意继续发展：'generated_story'"

# 正确写法
prompt = "基于这个创意继续发展：{generated_story}"

关键区别在于：

1. 错误写法会将字符串'generated_story'直接作为文本内容传递
2. 正确写法使用花括号语法，框架会自动替换为状态存储中的实际值

底层原理剖析

当使用花括号语法时，ADK框架会在运行时执行以下操作：

1. 解析提示模板中的变量占位符
2. 从当前会话状态中查找匹配的键值
3. 执行字符串替换，将占位符替换为实际值
4. 生成最终发送给LLM的完整提示

最佳实践建议

1. 变量命名规范：使用下划线命名法，保持变量名清晰明确
2. 空值处理：在模板中加入条件判断，处理可能未设置的变量
3. 调试技巧：在开发阶段打印最终生成的提示，验证变量替换结果
4. 类型安全：确保状态变量与提示中的预期类型匹配

典型应用场景示例

考虑一个多步骤内容生成工作流：

# 第一步代理设置状态
state["article_outline"] = "1.引言\n2.主体\n3.结论"

# 第二步代理引用状态
prompt = """根据以下大纲扩展文章内容：
{article_outline}

请为每个部分撰写3-5个段落："""

这种模式使得复杂工作流的开发变得清晰且易于维护。

总结

正确理解和使用ADK-Python的状态变量引用语法，是开发高效工作流代理的关键。记住避免使用引号包裹变量名，转而采用花括号语法，可以确保状态值被正确传递和替换。随着对框架的深入理解，开发者可以构建出更加复杂和强大的自动化工作流。