1. 从理论到实战：为什么你的AI代理需要“思维框架”？

朋友们，咱们已经一起走过了ADK的基础搭建和模块化探索，现在，是时候聊聊真正让AI代理“聪明”起来的核心了——它的“思维”方式。你可能会问，大模型不是已经很聪明了吗？直接问它问题不就行了？我刚开始也是这么想的，直到我亲手构建了几个代理，然后被现实狠狠上了一课。

我让一个代理帮我规划一个简单的周末旅行。我告诉它：“帮我找找北京周边，适合两天一夜、预算一千块左右的放松去处。”结果呢？它直接给我吐出了一大段文字，里面混杂了长城、故宫（这显然不是“周边”）、几个网红民宿的名字，还有一句“建议您自驾或乘坐高铁”。听起来好像有点用，但仔细一想，它漏掉了最关键的信息：这些地方具体怎么组合？交通时间是否允许？民宿是否有空房、价格是否在预算内？它只是把一些相关信息“堆砌”给了我，并没有真正“思考”如何解决我的问题。

这就是问题的关键。一个没有结构化思维的AI代理，就像一个知识渊博但做事没有条理的朋友。它可能知道很多，但无法系统性地解决问题。它会跳跃、会遗漏、会在复杂任务中迷失方向。而认知架构，就是给这位朋友一套高效的思维方法论。它不改变朋友的知识储备（LLM的能力），但教会他如何有条理地分析、规划和执行。

在实战中，我深刻体会到，没有认知架构的代理，其行为是脆弱且不可预测的。它可能这次运气好给出了正确答案，下次遇到类似但稍有变化的问题就完全跑偏。而像CoT（链式思考）、ReAct（推理与行动）和ToT（思想之树）这些架构，它们的作用就是将LLM强大的生成能力，约束和引导到一个可控、可解释、可复现的推理轨道上。ADK的强大之处，就在于它没有把这些架构停留在论文里或者提示词技巧的层面，而是提供了工程化的“脚手架”，让我们能像搭积木一样，把这些高级思维模式构建到我们的代理中。

所以，这篇实战指南，我想和你分享的，不是枯燥的理论，而是我踩过坑、调过参、最终让代理“开窍”的那些具体方法和代码。我们会看到，如何用ADK把CoT的“一步步想”变成可调试的日志，如何把ReAct的“思考-行动”循环变成稳定处理用户请求的流水线，以及如何初步探索ToT这种用于复杂决策的“头脑风暴”模式。我们的目标很明确：让你手里的AI代理，从一个简单的问答机，升级为一个有逻辑、有规划、能真正干活的智能伙伴。

2. 夯实基础：将链式思考（CoT）工程化为可调试的推理链

链式思考（CoT）可能是我们最熟悉的认知增强技术了，“让我们一步步思考”这句咒语几乎成了标配。但在ADK中构建生产级应用时，我们不能只靠一句魔法提示词。我们需要的是一个可靠、可观察、可干预的推理链。

2.1 超越简单提示：在ADK中实现结构化CoT输出

最开始，我像大多数人一样，只是在 LlmAgent 的 instructions 参数里加上“请逐步推理”。这确实有效，但很快遇到了瓶颈：当代理的推理步骤很长时，它的输出会变得杂乱无章，我想从中提取中间结论或者检查它的推理逻辑非常困难。日志里是一大段文本，出了问题只能靠猜。

后来，我发现了ADK配合结构化输出的威力。核心思路是：引导LLM用机器友好（同时也是人友好）的格式来组织它的思考过程。比如，我们可以要求LLM以XML或JSON格式输出。这样做有几个巨大的好处：

1. 可解析性：ADK可以轻松地解析出每一步的结论，并可能将其作为状态（State）存储起来，供后续步骤使用。
2. 可调试性：在日志中，推理结构一目了然，哪里逻辑断了，哪里假设错了，看得清清楚楚。
3. 可控性：我们可以基于清晰的中间结果，通过回调函数（Callbacks）进行干预，例如在关键步骤进行验证或补充信息。

下面是一个我常用的、让CoT结构化的指令模板，你可以直接用在你的 LlmAgent 初始化里：

from adk.agents import LlmAgent
from adk.llms import OpenAIChatCompletionsModel

# 初始化模型
llm = OpenAIChatCompletionsModel(model="gpt-4")

# 创建带有结构化CoT指令的代理
agent = LlmAgent(
    llm=llm,
    instructions="""你是一个逻辑分析助手。对于任何需要多步推理的问题，请严格按照以下格式输出你的思考过程和最终答案：

<reasoning>
<step number="1">[第一步的详细推理和结论]</step>
<step number="2">[第二步的详细推理和结论，基于第一步]</step>
...（根据需要添加更多步骤）
</reasoning>
<final_answer>[基于以上所有推理步骤得出的最终答案]</final_answer>

请确保每个<step>标签内的内容是完整的子结论。"""
)

当你运行这个代理时，得到的响应就不再是一团乱麻的文本，而是规整的XML。你可以写一个简单的后处理工具（或利用ADK的 PostProcessor）来解析这个XML，把每一步的结论提取出来，打印到日志，甚至存入数据库用于后续分析。当用户问“你为什么得出这个结论？”时，你可以直接把 <reasoning> 部分漂亮地渲染给他看，解释性瞬间拉满。

2.2 动态CoT与回调函数：在推理的关键节点“踩刹车”

有些复杂任务，光有静态的CoT指令还不够。比如，一个财务分析代理在推理到某一步时，可能需要查询最新的汇率；或者一个代码生成代理在设计架构时，需要确认用户的技术栈偏好。这时，我们需要在推理链的特定步骤插入外部动作。

ADK的 Callbacks 机制在这里派上了大用场。你可以注册回调函数，在LLM生成内容前、后等关键节点执行自定义逻辑。结合结构化CoT，我们可以实现“动态CoT”。

设想一个场景：代理正在帮用户拆解一个项目计划。当它的CoT推理进行到“步骤3：评估所需第三方API”时，我们希望它暂停一下，自动调用一个工具去查询内部API目录的可用性和文档，然后将查询结果作为额外信息补充到它的后续推理中。

虽然ADK的标准流程是完整的“思考-行动”循环，但我们可以通过设计，在单一的“思考”阶段内模拟这种中断和继续。一种实践模式是使用 State 来标记CoT的当前阶段，并在回调中检查这个状态，决定是否需要插入工具调用或额外的提示。这更像是一种“宏观CoT”与“微观ReAct”的结合，对于处理那些需要中途获取信息的深度推理任务非常有效。

通过将CoT工程化，我们得到的不仅仅是一个更准确的答案，更是一个透明、可审计、可增强的推理过程。这是构建可信AI系统的第一步。

3. 构建行动核心：ReAct模式在ADK中的工业化实现

如果说CoT让代理“想得清楚”，那么ReAct（Reason + Act）就让代理“做得出来”。它是现代AI代理的标配思维循环。在ADK中实现ReAct，绝不是简单写个 while 循环调用LLM那么简单。我们需要考虑错误处理、状态持久化、工具管理等一系列工程问题。幸运的是，ADK为我们准备好了大部分积木。

3.1 使用内置规划器：快速搭建ReAct智能体

ADK很可能提供了开箱即用的ReAct规划器（例如 adk.planning.ReActPlanner）。这是最快上手的路径。它的作用就是封装了那个经典的“思考(Thought) -> 行动(Action) -> 观察(Observation)”循环逻辑。你只需要关心三件事：LLM、工具列表、和任务目标。

下面是一个模拟的代码示例，展示了如何使用一个规划器来构建一个客服处理代理：

# 假设的导入，实际包名可能不同
from adk.agents import LlmAgent
from adk.planners import ReActPlanner
from adk.tools import FunctionTool
from adk.llms import OpenAIChatCompletionsModel
import json

# 1. 定义工具
def search_knowledge_base(query: str) -> str:
    """模拟查询知识库。返回相关文章片段。"""
    # 这里应该是连接向量数据库或ES的代码
    print(f"[工具调用] 搜索知识库: {query}")
    return f"关于'{query}'，知识库中找到：建议重启服务，并检查端口8080是否被占用。"

def create_support_ticket(title: str, description: str, priority: str = "medium") -> str:
    """模拟创建工单。返回工单ID。"""
    print(f"[工具调用] 创建工单: 标题-{title}, 优先级-{priority}")
    return f"工单已创建，ID: TICKET-{hash(title)}，工程师将尽快处理。"

# 将函数包装为ADK工具
search_tool = FunctionTool(func=search_knowledge_base)
ticket_tool = FunctionTool(func=create_support_ticket)

# 2. 初始化LLM和代理
llm = OpenAIChatCompletionsModel(model="gpt-4")
agent = LlmAgent(llm=llm)

# 3. 创建ReAct规划器，并将代理和工具装配进去
planner = ReActPlanner(
    agent=agent,
    tools=[search_tool, ticket_tool],
    max_iterations=10  # 防止死循环
)

# 4. 运行规划器处理用户请求
user_query = "我的应用报错了，显示端口冲突，怎么办？"
try:
    final_response = planner.run(task=user_query)
    print("代理最终回复:", final_response)
except Exception as e:
    print(f"规划过程出错: {e}")

在这个例子中，ReActPlanner 会驱动 agent 围绕 user_query 展开思考。它可能会先思考：“用户遇到端口冲突错误，我应该先查知识库看看常见解决方案。”于是调用 search_knowledge_base 工具。得到观察结果后，再思考：“知识库建议重启和检查端口。但用户可能已经试过了。我需要询问用户是否已尝试，或者直接帮ta创建工单。”从而可能调用 create_support_ticket 工具或生成一个询问用户的回复。这一切的循环控制、工具选择、结果传递，都由 planner 默默完成了。

3.2 深入循环内部：自定义Runner与状态管理

使用内置规划器很方便，但当你需要更精细的控制时，你就需要理解并可能自定义运行器（Runner）。Runner是ADK的引擎，它管理着整个对话状态（State）和事件流（Events）。

想象一下，你要构建一个能处理多轮复杂咨询的代理，比如保险理赔。用户第一次来说了事故概况，代理调用工具评估了初步责任；用户第二次补充了照片，代理需要结合之前的评估结果和新的照片来调用定损工具。这里的关键是状态（State）如何在ReAct循环中保持和传递。

在ADK中，Session 和 State 对象就是用来做这个的。每一次工具调用的结果、LLM的思考，都可以被妥善地保存在状态中。下一个循环的“思考”，其上下文就包含了之前所有的“观察”和“思考”。这样，代理就有了“记忆”。

下面是一个更贴近底层、展示状态流转的概念性代码片段，帮助你理解其工作原理：

# 概念性代码，展示状态流转
from adk.sessions import Session

session = Session()  # 创建一个会话，它内部管理着State

# 模拟第一轮交互
user_input_1 = "我想理赔我的汽车保险，昨天追尾了。"
session.add_user_message(user_input_1)

# Planner/Agent基于当前session.state生成 Thought 和 Action
# 假设Action是调用责任评估工具
tool_result = assess_liability(session.state.get("accident_details"))
session.add_tool_result("assess_liability", tool_result)  # 工具结果存入状态

# 状态现在包含了：用户消息1，工具结果1

# 模拟第二轮交互
user_input_2 = "这是现场的照片。"
session.add_user_message(user_input_2)
# 此时，Agent在思考时，其上下文会自动包含之前的所有信息（消息1、工具结果1、消息2）
# 它因此可以做出更连贯的决策，比如调用照片定损工具。

通过深入Runner和State，你可以实现诸如“在连续3次工具调用失败后自动转人工”、“根据对话历史动态调整工具调用策略”等高级功能。这才是ReAct模式在ADK中发挥威力的精髓——它不仅仅是一个循环，而是一个可观测、可控制、有状态的智能工作流。

4. 应对复杂决策：思想之树（ToT）的ADK实践初探

当我们面对创意写作、复杂策略制定或者有多重约束条件的规划问题时，一条路走到黑的ReAct可能就不够用了。这时，我们需要像人类一样“头脑风暴”，生成多种思路，然后评估、比较、筛选。这就是思想之树（Tree of Thoughts, ToT）模式。

在ADK中实现完整的ToT是一个高级话题，因为它涉及并行探索、评估和回溯，但ADK的模块化特性让我们可以搭建出它的雏形。其核心思想是：使用一个“管理者”代理（Manager）来协调多个“工作者”代理（Worker），每个工作者探索不同的思维路径。

4.1 使用AgentTool构建树状探索

AgentTool 是一个强大的工具，它允许一个代理将另一个代理当作工具来调用。这正好可以用来构建树状结构。管理者代理负责分解任务，生成不同的思考方向（分支），然后调用不同的工作者代理去深入探索每个方向。

假设我们要策划一个市场活动，管理者代理可能生成三个分支思路：“情感共鸣方向”、“产品功能强调方向”、“价格促销方向”。然后，它可以并行或串行地启动三个工作者代理，每个代理专门负责细化其中一个方向的具体方案。

from adk.agents import LlmAgent
from adk.tools import AgentTool
from adk.llms import OpenAIChatCompletionsModel

# 创建专门的工作者代理
creative_worker = LlmAgent(
    llm=llm,
    instructions="你是一个创意文案专家，专注于情感化、故事性的表达。请根据给定的方向，细化具体方案。"
)
feature_worker = LlmAgent(
    llm=llm,
    instructions="你是一个产品专家，专注于突出产品的核心功能和独特卖点。请根据给定的方向，细化具体方案。"
)

# 将工作者代理包装成工具
creative_tool = AgentTool(agent=creative_worker, name="brainstorm_creative")
feature_tool = AgentTool(agent=feature_worker, name="brainstorm_feature")

# 创建管理者代理，它可以使用这些特殊的“代理工具”
manager_agent = LlmAgent(
    llm=llm,
    tools=[creative_tool, feature_tool],  # 注意，工具列表里是AgentTool
    instructions="""你是策划经理。请对任务进行多角度思考，生成不同的策划方向，并调用合适的专家团队（工具）对每个方向进行深化。
    例如，对于“推广新款智能手表”任务，你可以：
    1. 思考方向A：主打健康关怀情感牌 -> 调用 brainstorm_creative 工具。
    2. 思考方向B：主打运动监测专业功能 -> 调用 brainstorm_feature 工具。
    请评估各团队返回的方案，并给出综合建议。"""
)

# 运行管理者代理
result = manager_agent.run("为我们的新款智能手表策划一个社交媒体推广活动")

在这个架构中，creative_worker 和 feature_worker 各自进行了一次独立的“思考-生成”过程（可以看作一个小型的CoT），而 manager_agent 则执行了更上层的“生成思路-分配任务-评估结果”的ToT流程。ADK的 AgentTool 优雅地处理了代理间的调用和结果返回。

4.2 评估、回溯与资源控制

简单的分支探索还不够，真正的ToT需要对分支进行评估和选择。我们可以在管理者代理的指令中要求它对返回的结果进行评估，或者，更工程化的做法是引入一个评估工具。

这个评估工具可以是一个简单的函数，根据一些标准（如方案的新颖性、可行性、成本）进行打分；也可以又是一个专门的评估代理。管理者在收到各个分支的结果后，调用评估工具对它们排序，决定是否继续深入某个分支（让工作者再次细化），还是剪掉表现差的分支。

def evaluate_proposal(proposal: str, criteria: dict) -> float:
    """评估提案质量的工具（简化版）。"""
    score = 0.0
    if "情感" in criteria and "故事" in proposal:
        score += 0.4
    if "功能" in criteria and "精准" in proposal:
        score += 0.6
    # ... 更复杂的评估逻辑
    return score

evaluation_tool = FunctionTool(func=evaluate_proposal)
# 将评估工具也加入管理者代理的工具箱
manager_agent.tools.append(evaluation_tool)

资源控制是另一个挑战。并行运行多个代理可能会消耗大量Token和计算资源。在实际项目中，我们需要通过设置 max_iterations、max_parallel_branches（如果使用并行运行器）等参数来控制探索的广度和深度。ADK的灵活性和透明性，让我们能够根据实际成本和性能需求，对ToT探索过程进行精细化的调控。

虽然完整的ToT实现依然复杂，但通过ADK提供的 AgentTool、自定义工具和状态管理，我们已经可以构建出具备多路径探索和初步评估能力的代理，这在解决开放式、无标准答案的问题时，价值巨大。

5. 让思维持续进化：记忆集成与自我优化

一个只会单次思考的代理，能力是有限的。真正的智能体现在能够从历史中学习，并优化未来的决策。这就是记忆（Memory）系统和自我优化机制的价值所在。

5.1 利用长期记忆为认知提供上下文

ADK可以很方便地与向量数据库等外部存储集成，为代理赋予长期记忆。这个记忆体可以在认知过程的关键时刻被调用。例如，在ReAct循环开始“思考”之前，我们可以先从记忆库中检索与当前用户和任务相关的历史记录。

设想一个个性化学习助手代理。当用户问“我今天该学点什么？”时，代理的思考不应该从零开始。它的CoT过程可以是：

1. 步骤一（检索记忆）：从记忆库中查询该用户过去的学习记录、掌握的知识点、偏好的学习风格。
2. 步骤二（分析现状）：结合检索到的信息，分析用户当前的知识缺口和学习进度。
3. 步骤三（制定计划）：生成今天的学习建议。

在ADK中，我们可以通过一个自定义的 RetrievalTool 来实现第一步。这个工具在代理的思考链中被调用，其返回的结果（观察）会成为后续推理的重要上下文。这样，代理的每一次“思考”都建立在个性化的历史信息之上，决策质量显著提升。

5.2 基于评估的认知架构迭代

最后，也是最重要的一点：没有评估，就没有优化。尤其是当我们引入了复杂的认知架构后，如何知道我们的CoT提示词写得好不好？ReAct的循环次数设置是否合理？ToT的分支评估标准是否有效？

ADK内置的评估框架是我们的“罗盘”。我们可以为代理设计专门的评估任务（Benchmark）。例如，针对一个客服代理，我们可以构建一个测试集，里面包含100个不同类型的用户问题。然后，我们定义评估指标：任务完成率、平均解决轮次、工具调用准确率等。

当我们调整了代理的认知架构（比如改进了CoT的指令模板，或者在ReAct中增加了一个新的工具），我们就重新运行这个评估测试集。通过对比指标的变化，我们就能量化地知道这次调整是让代理变得更聪明了，还是更笨了。这种数据驱动的开发方式，让我们摆脱了对代理行为的“玄学”猜测，能够稳定、持续地优化其认知能力。

我自己的经验是，为每个重要的代理建立一个简单的评估流水线，是项目成功的关键。它可能一开始只是几个手工测试用例，但随着项目复杂，它会演进成自动化的集成测试。ADK在这方面的设计，让这种评估变得可行。通过不断地测试、测量、调整，我们才能真正“解锁”AI代理的思维密码，让它朝着我们期望的方向不断进化。

从结构化的CoT，到稳健的ReAct循环，再到探索性的ToT雏形，最后用记忆和评估让它持续学习，这就是在ADK中构建高级认知代理的实战路径。每一步都有对应的工具和模式可以依托，而不是空中楼阁。动手去实现它们，你会真切地感受到，你正在赋予一段代码真正的“思考”能力。