Agent 核心
知识库简介
Agent 不是“让模型一直思考”，而是模型决策与确定性 runtime 共同组成的受控系统：
目标 + 状态 + 观察
→ 模型提出结构化下一动作
→ runtime 校验策略、权限、预算和审批
→ 工具改变/读取环境
→ observation 回写状态
→ verifier 决定继续、等待或终止本知识库从零建立单 Agent 的供应商无关核心：loop、Agent/工作流边界、状态/context/memory、计划与终止、检查点与幂等、人在回路、不可信 observation，以及一个可运行的离线 runtime。
动态事实边界
资料获取/复核日期为 2026-07-21。各家 Agent SDK、托管 session、审批、memory 与 tracing API 会变化；课程主体只依赖稳定工程边界。产品接入时重新核对官方 SDK 文档、版本和双方实际行为。NIST AI RMF 1.0 官方页面当日仍注明正在修订；本库引用其通用角色/监督原则，不把它当行业合规意见。
在总路线中的位置
它是“单 Agent 与工具”阶段的核心运行时站点。课程目录编号只用于展示与查找，不表示必须先经过排在它前面的每门课。普遍硬前置是：
- Tool Calling（含 Function Calling）：工具契约、调度、错误与审批；
进入会读取不可信 observation 或执行工具的实践前，还应完成总路线的早期安全与评测 milestone。它复用现有章节形成早期质量门，不等于整门 AI 安全或评测体系都是本课的课程级硬前置。
若项目需要通过标准协议连接外部能力或上下文，再在本课前后按互操作需求选修 MCP。直接 SDK、进程内函数或既有服务同样可以构成 Agent runtime；MCP 不是 loop、state、termination 和 recovery 的普遍前置。
本库解决“谁决定下一步、怎样保持状态、何时停止、怎样安全恢复”。之后：
- 环境型 Agent：把 observation–action runtime 落到浏览器、桌面和代码环境；
- Agent Skills：可复用程序性知识；
- Agentic Design Patterns：routing、parallel、planner/evaluator 等组合；
- 工作流自动化：调度、DAG、队列、补偿与生产编排；
- 多Agent协作：多个 Agent 的分工、通信与治理。
学习目标
- 实现 model proposal 与 runtime execution 分离的 observe–decide–act loop。
- 根据路径不确定性、验证、风险和成本选择单次调用、workflow 或 Agent。
- 区分权威 state、event log、context、工作摘要与长期 memory。
- 让计划项、progress、成功证据和所有终止状态可审计。
- 识别 crash window，用 checkpoint、idempotency key、intent digest 和 receipt 恢复。
- 把 clarification、approval、rejection、takeover 和 cancel 做成持久状态。
- 把所有 tool/resource 内容视为不可信 observation。
- 用 deterministic policy 和离线工具测试 runtime，不把模型偶然表现当安全证据。
前置知识
- 提示词工程 与 上下文工程。
- LLM API集成 的 timeout、usage 和 provider adapter。
- Tool Calling 的 schema、call ID、授权、幂等与错误。
- Python dataclass、异常、JSON、hash 与基本测试。
- API 的重试、deadline、idempotency 和认证。
不要求先学 LangChain/CrewAI。先看清 runtime contract，框架只是一种实现。
核心责任图
| 组件 | 可以做 | 不能单独决定 |
|---|---|---|
| model/policy | 提议 action、ask、finish candidate | 权限、审批、真正 completed |
| runtime/harness | 校验、预算、执行、状态迁移、终止 | 代替用户定义业务目标 |
| tool adapter | 调用外部系统、规范化 observation | 提升自身权限/信任 |
| state/event store | 保存事实、checkpoint、审计 | 把摘要变成审批事实 |
| verifier | 检查测试、receipt、外部状态 | 绕过失败/负向标准 |
| human | 澄清、批准、拒绝、接管 | 在信息不足时被迫“橡皮图章” |
推荐学习顺序
| 顺序 | 课程 | 关键问题 | 完成证据 |
|---|---|---|---|
| 1 | Agent Loop 与环境反馈 | model 与 runtime 如何闭环？ | 六组件图 + 一次迭代 |
| 2 | Agent 与工作流的边界 | 什么时候不该用 Agent？ | 有 baseline/风险/回退的 ADR |
| 3 | 状态、上下文与记忆 | 什么是事实源，什么只是本轮视图？ | 五层数据模型 |
| 4 | 计划、进度与终止条件 | 怎样证明进展与完成？ | plan + progress + verifier + stop envelope |
| 5 | 长任务检查点、恢复与幂等 | 崩溃后怎样不重复副作用？ | 四 crash window 与恢复协议 |
| 6 | 人在回路与控制权 | 人类控制怎样可持久、可失效？ | approval contract 与 UI |
| 7 | 不可信工具结果与防护 | 模型被恶意文本诱导时怎样仍安全？ | 模型之外的防御矩阵 |
| 8 | 综合 Agent 项目与自测 | 怎样把边界变成运行证据？ | demo + 68 tests |
建议第一遍 12–16 小时：前 7 课各 60–90 分钟，项目 3–5 小时。
动手实践入口
项目使用 Python 标准库，不联网、不调用真实模型、不需要 key：
以下命令从同时包含 docs/ 与 .website/ 的项目根目录运行：
Push-Location -LiteralPath 'docs\Agent 核心' # 临时进入本章节目录，之后会恢复原工作目录
python -B .\examples\bounded_agent.py # 运行离线 demo；-B 防止生成 __pycache__ 文件
python -B .\examples\test_bounded_agent.py # 用普通解释器运行全部回归测试
python -B -O .\examples\test_bounded_agent.py # 在优化模式下验证关键控制没有依赖 bare assert
python -B -W error .\examples\test_bounded_agent.py # 将任何 Python 警告升级为测试失败
python -B -O -W error .\examples\test_bounded_agent.py # 同时启用优化与“警告即错误”两项更严格检查
Pop-Location # 返回执行命令前所在的目录，避免影响后续终端操作当前基线：
- demo：恶意 observation → 写操作暂停 → checkpoint → 审批 → commit 后模拟 crash → receipt 恢复 → completed；
- 已满足路径：查询确认 ticket 已关闭 → 不提议写操作、不请求审批 →
already_satisfied完成； - close side effect 恰好 1 次；
- 68 个测试；
- 普通、
-O、-W error和-O -W error四种模式全部通过； - 0 网络、0 第三方依赖、0 凭据。
掌握标准
- 能说明 model/policy 提议动作，runtime 才拥有执行控制权。
- 能为真实任务比较确定程序、单次调用、workflow 和 Agent。
- 能从 state/event 重建下一步，不依赖完整聊天历史。
- 能解释摘要为何不能覆盖 approval/state。
- 能定义 progress、completion evidence、waiting/terminal 状态。
- 能画出四个 crash window。
- 能设计同 key/同 intent 缓存与同 key/异 intent 冲突。
- 能设计绑定 fingerprint、state version、scope 和 expiry 的 approval。
- 能让恶意 observation 即使劫持模型也无法越权。
- 能运行并解释 68 tests 和项目限制。
- 能明确何时应退回固定 workflow。
与其他知识库的关系
- 上下文工程 决定每轮哪些 state/observation 进入模型；本库决定事实源和 runtime 状态。
- Tool Calling（含 Function Calling） 提供单次工具契约；本库把调用放进多轮状态机。
- MCP 是可能的能力接入边界，不是 planner。
- 工作流自动化 提供更完整的 durable orchestration、scheduler、queue 与 compensation。
- 环境型 Agent 复用本库 runtime contract，进一步约束浏览器、桌面和编码环境的初态、动作、沙箱、终态与副作用评测。
- 运行监控 把 event、trace、budget 和 stop reason 变成生产可观测性。
- 评测体系 衡量 task success、轨迹、安全、成本与恢复。
- AI安全 扩展 prompt injection、identity、供应链、sandbox 与治理。
主要参考资料
以下优先采用原始论文、第一方工程指南与公开安全/风险框架，获取/复核日期：2026-07-21。
| 主题 | 来源 |
|---|---|
| Agent/workflow 与简单架构 | Anthropic: Building effective agents |
| Agent 构建基础 | OpenAI: A practical guide to building agents |
| 决策—行动—观察 | Yao 等，ReAct |
| Action interface | Yang 等，SWE-agent |
| 多轮 context | Anthropic: Effective context engineering for AI agents |
| Durable workflow | Temporal: Workflow concepts |
| Agentic security | OWASP Top 10 for Agentic Applications 2026 |
| 人类角色与风险 | NIST AI Risk Management Framework |
课程边界
本库讲单 Agent runtime 的不变量，不重复：
- prompt 写法细节：提示词工程；
- context 检索/压缩全套技术：上下文工程；
- 框架 API：LangChain/CrewAI；
- 多 Agent 分工：多Agent协作；
- 生产指标平台：运行监控/LLMOps；
- 系统级安全与法规：AI安全/AI治理。
遇到产品 API 或版本事实，以对应官方文档和实际测试为准。