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,让模型决策、动作执行和结果观察形成完整循环。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义 Agent 状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通