AI Agent / 系统课时
定义 Agent 状态
定义 Agent 状态
本篇解决 Agent Runtime 中运行数据如何组织的问题。通过设计统一状态对象,将任务目标、消息记录、执行步骤、工具结果、错误信息和完成状态集中管理,为后续循环调度与故障恢复提供稳定基础。
学习目标
- 理解 Agent 状态需要保存哪些运行信息
- 掌握面向循环执行设计状态结构的方法
- 能够定义一个最小可用的 Agent 状态模型
Agent 状态解决什么问题
Agent 运行过程中会不断产生新信息:用户目标需要保存,模型回复需要记录,工具调用结果需要传递,错误需要用于重试或终止判断。如果这些数据分散在函数参数或临时变量中,循环执行会迅速变得难以维护。
状态对象的核心作用是提供一个可持续更新的上下文。每一次模型决策、工具执行和结果观察,都读取当前状态并产生新的状态。
设计核心状态字段
一个最小 Agent 状态通常包含以下部分:
| 字段 | 作用 |
|---|---|
| goal | 当前任务目标 |
| messages | 模型与用户交互历史 |
| steps | 已执行步骤记录 |
| tool_results | 工具调用结果 |
| error | 最近一次错误 |
| status | 当前运行阶段 |
状态字段不应该无限扩张。只保存下一轮决策真正需要的信息,可以降低上下文膨胀和状态迁移成本。
实现最小状态模型
下面使用 Python 定义一个简单状态结构。该模型适合作为 Runtime 内部数据载体,后续可以继续增加持久化、追踪编号等字段。
python
from dataclasses import dataclass, field
from typing import List, Dict, Optional
@dataclass
class AgentState:
goal: str
# 保存模型看到的上下文消息
messages: List[Dict[str, str]] = field(default_factory=list)
# 保存已经完成的执行步骤
steps: List[str] = field(default_factory=list)
tool_results: List[Dict[str, str]] = field(default_factory=list)
error: Optional[str] = None
status: str = "running"
state = AgentState(goal="查询订单状态")
state.messages.append({"role": "user", "content": "查询订单 A001"})
print(state.status)
print(state.goal)预期输出
text
running
查询订单状态状态更新与生命周期
Agent 状态通常经历几个阶段:创建初始状态、加入用户输入、记录模型决策、保存工具结果、判断继续执行或结束。
如果任务成功,状态应明确进入 completed;如果遇到不可恢复问题,应记录 error 并结束循环,而不是依赖异常堆栈作为唯一信息来源。
常见设计错误
一种常见问题是把整个对话历史、所有工具返回内容全部永久保存。长期运行的 Agent 会因为状态过大导致模型输入成本升高。
另一种问题是状态字段没有明确责任,例如同时使用 result、output、response 保存类似信息,最终导致循环逻辑无法判断应该读取哪个字段。
本课总结
- Agent 状态是 Runtime 中连接各执行阶段的数据中心。
- 最小状态应覆盖目标、消息、步骤、工具结果和运行状态。
- 良好的状态设计需要控制信息范围,避免无效数据持续累积。
下一课预告
下一课将基于状态模型实现最小 Agent Loop,让模型决策、动作执行和结果观察形成完整循环。
按自己的节奏,确认真正理解。