Agent 基本结构
把模型、指令、上下文、状态、工具、运行器、护栏和追踪组织成可测试结构。
学习目标
- 能说明Agent 基本结构解决什么问题，以及何时适用。
- 能解释为什么“把授权写在提示词里就认为安全”是误区。
学习前需要掌握
背景与问题
“模型加几个工具”可以做出演示，但任务增加后很快会遇到职责混杂：模型以为已经写入，数据库却没有变化；工具权限被提示词控制；恢复运行时又不知道哪些动作已经执行。
架构要把这些责任明确分配，让系统可以分别验证模型建议、应用控制和外部效果。它描述的是数据与控制如何流动，而不是组件数量越多越好。
概念定义
Agent 架构说明每个组件的职责、数据流、信任边界与停止控制，而不只是画一个“LLM + Tools”框。
直观理解
像软件架构：模型不是整个应用，运行器负责调度，工具适配外部世界，状态存储当前事实，护栏与日志负责控制和诊断。
核心原理
模型层接收与当前任务相关的指令和上下文，产生回答或工具调用候选。工具描述影响模型怎样选择动作，但描述中的“只读”不能替代真实实现中的只读权限。
运行器负责解析候选、验证参数、检查授权、执行工具并反馈结果，同时控制轮次、超时和中断。关键业务约束应在确定性代码中执行；模型不应靠自报结果决定是否绕过限制。
状态层保存任务标识、已验证事实、待办项和副作用记录。模型上下文可以是状态的一个视图，但不能成为唯一事实来源；重启后应能区分已提交、待审批和结果未知的操作。
横切能力覆盖整个流程：护栏检查风险，追踪关联模型与工具事件，评测检查任务是否达标。架构中的每条边都应说明数据格式、信任级别和失败时的去向，否则局部组件通过测试也可能在组合后失效。
案例：生成月度费用报告的组件分工
模型把“汇总本月费用”转成查询候选；运行器检查允许的月份和账户，再调用只读账单工具。工具返回带币种和记录来源的明细，确定性汇总代码计算总额，模型只负责解释异常和组织文字。
报告保存到草稿目录后，状态层记录文件路径、输入版本和校验结果。发送或发布是另一条受授权控制的动作。若查询超时，运行器记录失败并按策略恢复；不能让模型用估计金额填满报告，再把格式完整误判为任务完成。
理解与实践步骤
- 定义 Agent 指令和输出契约
- 配置最小工具集
- 设计状态所有权
- 加入审批与护栏
- 定义追踪字段和评测集
实际应用
- 生产 Agent 架构
- 可观测工作流
常见错误
- 让提示词承担实际权限检查，认为模型被告知不越界就足够安全。
- 多个组件各自修改任务完成状态，却没有唯一状态所有者和一致的更新规则。
- 只有最终答复日志，无法关联工具输入、执行结果、审批和停止原因。
输入、输出与执行边界
输入
- 指令
- 上下文
- 工具定义
- 应用状态
输出
- 运行轨迹
- 最终输出
- 错误或审批中断
能力
- 生产 Agent 架构
- 可观测工作流
安全风险与信任边界
规划器给出的步骤只是候选计划，执行器仍需核对动作对象、参数和实际结果。记忆与检索材料应保留来源和有效时间，避免将外部文本或过期记录提升为新的任务指令；模块划分本身不会自动建立可信边界。
性能与失败模式
将总延迟拆成规划、检索、工具执行与结果验证，才能判断瓶颈。增加模块会增加调用和状态传递成本；比较架构时应固定任务集与资源预算，同时记录成功率、错误恢复和重复操作，而不只比较回答长度。
推荐学习资料
OpenAI Agents SDK 文档
系统介绍 Agent、工具、Handoff、Guardrail、Session 与追踪等核心组件。
OpenAI · OpenAI
资料笔记
openai/openai-agents-python
OpenAI Agents SDK 的 Python 源码、文档、示例与集成测试仓库。
OpenAI · GitHub
仓库信息
构建和研究多 Agent 工作流
主要语言：Python包含数据集或实验需要额外环境