Agent State：一个 Agent 到底需要记录什么？

上一节我们已经把 Agent 最核心的 Main Loop 写出来了。你应该已经能看懂这样一个结构：

while True:
    response = llm.chat(messages)

    if response.tool_call:
        result = execute_tool(response.tool_call)
        messages.append(result)
    else:
        return response.answer

这段代码已经有了 Agent 的“循环感”，但如果我们真拿它去做复杂任务，很快就会遇到一个问题，Agent 到底记得自己现在做到哪里了吗？

比如它已经执行了 8 步，刚刚失败过 2 次，调用过 read_file("app.py")，现在正在等待人工确认，还剩多少步可以跑——这些信息，如果全部散落在局部变量里，后面几乎不可能稳定扩展。

所以这一节我们要解决的核心，是给 Agent 一个真正的“当前运行状态”。

学完以后，你应该能够：

• 区分“Loop 是怎么跑的”和“State 记录了什么”。
• 明确 goal、messages、step、tool_history、status 这些字段的实际作用。
• 理解为什么 Agent 需要显式状态流转，而不是仅靠几个 if/else 猜当前阶段。
• 能设计出一套基础状态机，让 Agent 在 READY → THINKING → TOOL_CALLING → OBSERVING → ... 之间稳定切换。
• 为后续 Session、Run、Human Approval、Tracing 打好结构基础。

这一节可以先抓住一个判断：凡是会影响当前任务是否继续、下一步怎么走、暂停后怎样接着走的信息，都值得考虑进入 State。 至于完整 Prompt、每次耗时和长期项目偏好，它们虽然也重要，却未必都属于 State。我们会一边写代码，一边把这些边界分开。

阅读时先不要把 messages、State 和 Trace 混成一件事。messages 是模型下一轮可能看到的交互历史；State 是程序当前用来控制运行的事实；Trace 则是事后回答“刚才具体发生了什么”的证据。三者会引用同一轮工具调用，但服务的对象不同。

开场引入

如果 Main Loop 是 Agent 的发动机，那么 State 就像仪表盘、里程表、档位、油量和导航信息的集合。

只有发动机，车当然能动。

但你根本不知道：

• 现在挂几档；
• 已经跑了多少公里；
• 还剩多少油；
• 是否已经偏航；
• 是否出现故障；
• 当前是停车、加速还是等待通行。

Agent 也是一样。

上一节我们写 Main Loop 时，经常会出现这样的代码：

messages = []
step = 0
recent_calls = []
finished = False

这些变量刚开始看起来很自然。

但随着功能变多，代码会逐渐变成：

if step > 10:
    ...

if finished:
    ...

if waiting_approval:
    ...

if last_tool_failed:
    ...

if retry_count > 3:
    ...

if current_status == "running":
    ...

你会发现，Agent 明明只是“多做几步”，程序却越来越难看懂。

问题不在于 Python 不够强，而在于我们没有把“运行中的事实”组织成统一结构。

所以我们需要：

AgentState = {
    "goal": "",
    "messages": [],
    "step": 0,
    "tool_history": [],
    "status": "running"
}

这一步看似只是把几个变量放进一个字典，实际上意义很大。

因为从这一刻开始，我们不再把 Agent 看成，“一个不断调用 LLM 的 while 循环。”

而是开始把它看成，“一个状态不断变化的长期运行对象。”

这就是 Agent = Loop + State 这句话真正的含义。

把两者放在一起看，会比单独背这句公式更容易理解：Loop 每跑一轮，都把新结果写进 State；State 反过来决定下一轮还能不能继续，以及该从哪里接上。

例如图右侧的 status 一旦变成 WAITING_APPROVAL，左侧就不能照常执行下一步。这个限制来自运行状态，而不是模型临时“记住了要暂停”。

Loop 负责推进。

State 负责记录。

没有 Loop，Agent 不会继续行动。

没有 State，Agent 不知道自己从哪里来、现在在哪、下一步是否应该继续。

再往后，我们还会加入：

Session
Run
Memory
Checkpoint
Tracing
Human Approval

你会发现，这些能力几乎都和 State 有关系。

比如 Human Approval。

Agent 决定删除一个文件时，不能只是：

print("等待确认")

然后函数结束。

它应该进入：

WAITING_APPROVAL

并且保存：

当前请求什么动作
为什么需要审批
等待谁确认
恢复以后从哪一步继续

再比如服务重启。

如果 Agent 之前已经跑了 12 步，服务重启后想继续执行，就必须能够把之前的状态重新加载出来。

再比如 Tracing。

我们不仅想知道“最后答案是什么”，还想知道：

第 1 步是什么状态
第 2 步调用了哪个 Tool
第 3 步为什么失败
第 4 步为什么转成 WAITING_APPROVAL

所有这些，都需要一个清晰的 State。

所以这一节表面上在讲“字典里应该放哪些字段”，实际上是在给整个 Agent Harness 建立运行模型。

知识地图

这一节承接上一节的 Main Loop，并为后面的 Tool、Context、Session、Human Approval、Tracing 打地基。

我们还可以先看一个状态流转图：

这张图会贯穿整节。