如何用好 AI Agent：跨公司高质量原始资料

收集日期：2026-08-31；本周期增量窗口：2026-08-25 至 2026-08-31。优先官方文档、官方工程博客、官方仓库和公司员工原文；“日期未标注”表示页面是持续更新的产品文档或原始 PDF 未显示发布日期，不代表内容不可靠。

一句话结论

这些资料的共同结论是：先用最简单的单模型/单 Agent 方案，只有在任务确实需要动态决策、工具调用或并行协作时才增加编排；同时用清晰的工具接口、可复现的规则/技能、沙盒、检查点、评估和人工监督控制风险。

资料清单

本周期新增（2026-08-25 至 2026-08-31）

19. Claude Code 2.1.251：模型切换钩子、恢复成本与更严格的沙盒边界

• 作者/团队： Anthropic / Claude Code 团队
• 日期： 2026-08-28；访问日期：2026-08-31
• 链接： https://github.com/anthropics/claude-code/releases/tag/v2.1.251
• 来源类型： 官方产品发布说明 / 开源项目变更记录
• 核心方法： 新增 PreModelSwitch/PostModelSwitch 钩子，可阻止、确认或标注模型切换；恢复钩子获得 session 新鲜度和重新缓存成本；同时修复符号链接越界读写、脚本路径权限检查、沙盒进程清理、MCP 握手无限等待和流式工具调用恢复等问题。
• 适用场景： 长时间 coding agent、后台/远程会话、模型路由、恢复运行、沙盒执行和高权限工具调用。
• 可靠性： 高。Anthropic 官方发布说明，能确认已实现的产品行为；具体可用性仍取决于 Claude Code 版本和部署环境。

20. OpenAI Agents SDK：恢复 handoff 时先提交状态，避免失败重试丢失 guardrail 结果

• 作者/团队： OpenAI Agents SDK 开源团队；Kazuhiro Sera 等
• 日期： 2026-08-28（提交时间）；访问日期：2026-08-31
• 链接： https://github.com/openai/openai-agents-python/commit/287594c6ce2b723de162c6f77d7e60c2c3e686b8
• 来源类型： 官方开源仓库提交与回归测试
• 核心方法： 在可能失败的 session append 之前，先发布已完成 handoff 和 tool guardrail 结果，并把已提交的 handoff 归一化为可恢复的 run again 状态；测试覆盖审批、guardrail、流式和恢复路径。恢复逻辑因此不会把“已经发生的副作用”误认为尚未发生。
• 适用场景： 多 Agent handoff、需要审批的写工具、流式运行、session 持久化失败后的自动恢复和长任务状态机。
• 可靠性： 高（窄范围）。这是可审阅的官方代码和测试变更，证明一个具体故障模式已被处理，不等于所有持久化实现都天然幂等。

21. Google ADK 2.8.0：把调用上限、评估指标、遥测与恢复安全纳入运行时

• 作者/团队： Google Agent Development Kit 开源团队
• 日期： 2026-08-25；发布：2026-08-26；访问日期：2026-08-31
• 链接： https://github.com/google/adk-python/releases/tag/v2.8.0
• 来源类型： 官方开源框架版本发布说明
• 核心方法： 增加 ADK_MAX_LLM_CALLS 调用上限、AgentEvaluator 自定义指标、按 invocation/workflow 统计 token 与工具/推理调用的实验性遥测，并支持 RemoteA2aAgent 原生 task mode；同版本还修复嵌套 HITL 多轮暂停/恢复、重复事件、重复工具执行、prompt injection 和恢复时错误匹配等问题。
• 适用场景： long-running agents、A2A/多 Agent、HITL 暂停恢复、预算与停止条件、trace/成本评估和生产调试。
• 可靠性： 高。官方版本说明和对应提交；遥测明确为 opt-in/experimental，不能当作默认 GA 能力。

22. Microsoft Agent Framework 1.16.0：checkpoint 和 workflow state 改为调用方隔离的快照

• 作者/团队： Microsoft Agent Framework 团队
• 日期： 2026-08-27；发布：2026-08-28；访问日期：2026-08-31
• 链接： https://github.com/microsoft/agent-framework/releases/tag/python-1.16.0；实现细节：https://github.com/microsoft/agent-framework/commit/44c8cf6a2012898c17acbb7487bb41614b869633
• 来源类型： 官方开源框架版本发布说明 / 实现与一致性测试
• 核心方法： checkpoint storage 的 save/load/list/get_latest 返回深拷贝，State 的 set/get/export/import 也隔离嵌套可变对象，防止调用方后续修改悄悄改变已保存快照；配套 conformance tests 验证内存和文件存储都满足所有权契约。
• 适用场景： checkpoint/rollback、并发 workflow、暂停恢复、长任务状态审计和多执行器共享状态。
• 可靠性： 高（窄范围）。官方 release、实现和测试均可核验；深拷贝也意味着状态对象需支持相应复制约束。

本周期新增（2026-08-22 至 2026-08-24）

17. OpenAI Agents SDK：取消清理与 Guardrail 流式异常修复

• 作者/团队： OpenAI Agents SDK 开源团队；Henry Su 等贡献者
• 日期： 2026-08-23（提交时间）；访问日期：2026-08-24
• 链接： sandbox cancellation cleanup；streaming guardrail exception
• 来源类型： 官方开源仓库提交/测试变更
• 核心方法： 沙盒任务被取消时完成依赖清理，并用测试覆盖取消路径；流式运行中触发 input guardrail 后，max_turns 不再覆盖原始 guardrail 异常。它们把“停止”和“拒绝”当作需要保留语义的状态转换，而不是普通异常吞掉。
• 适用场景： 长时间代码 Agent、沙盒执行、可取消任务、流式交互和需要安全拦截的工具调用。
• 可靠性： 高（窄范围）。这是官方仓库的可审阅代码与测试变更，不是完整架构指南；具体行为应随 SDK 版本复核。

18. Google ADK：Agent 恢复时避免重复合成用户事件

• 作者/团队： Google Agent Development Kit 开源团队
• 日期： 2026-08-23（提交时间）；访问日期：2026-08-24
• 链接： https://github.com/google/adk-python/commit/e753651b7df26febe00bde2cb043225e644cd207
• 来源类型： 官方开源仓库提交/运行时修复
• 核心方法： 修复单轮 Agent 恢复时重复生成 synthetic user event 的问题，避免恢复流程把同一输入再次注入会话历史。该修复把 resume/replay 的幂等性作为 Agent 状态管理的一部分。
• 适用场景： 可暂停/恢复的长任务、session replay、自动重试、checkpoint 恢复和需要准确审计轨迹的 Agent 系统。
• 可靠性： 高（窄范围）。这是官方仓库中的具体修复，说明一个已识别的运行时问题；不应外推为所有恢复系统都采用同一实现。

1. Building effective agents

• 作者/团队： Anthropic，Engineering 团队
• 日期： 2024-12-19
• 链接： https://www.anthropic.com/engineering/building-effective-agents
• 核心方法： 从增强型 LLM 开始，按需增加 prompt chaining、routing、parallelization、orchestrator-workers、evaluator-optimizer，最后才使用自主 Agent。强调“能用简单方案解决就不要上 Agent”；直接调用 API 便于调试，工具要有清晰文档；Agent 必须从环境反馈获得 ground truth，设置停止条件、沙盒和 guardrails，并通过评估迭代。
• 可靠性： 极高。Anthropic 官方工程文章，明确说明来自与数十个客户及自身构建经验；但页面也提示 2024 年工具生态已有变化，应把它作为架构原则而非最新产品说明。

2. Effective context engineering for AI agents

• 作者/团队： Anthropic Applied AI team：Prithvi Rajasekaran、Ethan Dixon、Carly Ryan、Jeremy Hadfield；Rafi Ayub、Hannah Moran、Cal Rueb、Connor Jennings 等参与
• 日期： 2025-09-29
• 链接： https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• 核心方法： 从“Prompt Engineering”升级到“Context Engineering”：管理 Agent 每一步可见的完整状态，而不只是写一段更好的提示词。关注有限的“注意力预算”，避免把无关内容全部塞进上下文；让 Agent 通过工具逐步检索信息，而不是一次性加载完整数据；强调 progressive disclosure（渐进式披露）、上下文压缩、结构化记笔记和多 Agent 架构。
• 可靠性： 极高。Anthropic 员工署名的官方工程文章，适合作为长任务和复杂上下文设计的核心材料。

3. Claude Code：Best practices

• 作者/团队： Anthropic / Claude Code 官方文档团队
• 日期： 持续更新
• 链接： https://code.claude.com/docs/en/best-practices
• 核心方法： 给 Agent 一个可以运行的验证信号；先探索、再计划、再实现；提供具体上下文；用 CLAUDE.md、权限、MCP、hooks、skills 和 subagents 固化环境；主动管理上下文；尽早纠偏；使用并行会话和独立复核，但对高风险动作保留人工审批。
• 可靠性： 极高。当前官方文档，直接来自 Claude Code 的真实工作流。

4. A Practical Guide to Building Agents

• 作者/团队： OpenAI，Business/Developer Resources 团队
• 日期： 未标注（官方 PDF；以页面当前版本为准）
• 链接： https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf
• 核心方法： 用“模型 + 工具 + 指令/护栏”构成 Agent；先识别是否真的需要 Agent，再选择单 Agent 或多 Agent。实操上先建立清晰的任务边界和成功标准，给工具定义明确的输入输出，逐步增加能力，使用 guardrails、人工介入和评估来管理高风险动作。
• 可靠性： 极高。OpenAI 官方一手指南，适合作为入门总纲；发布日期未显示，引用时建议保留访问日期。

5. OpenAI Agents SDK：Intro / orchestration / guardrails / tracing

• 作者/团队： OpenAI，Agents SDK 官方文档团队
• 日期： 未标注（持续更新文档）
• 链接： https://openai.github.io/openai-agents-python/
• 核心方法： 采用少量原语：Agent、handoff、guardrails；用 tracing 观察和调试完整轨迹；根据任务选择 Responses API（自己掌握 loop、tool dispatch、state）或 Agents SDK（由 runtime 管理 turns、tools、guardrails、handoffs、sessions）。涉及真实文件/仓库时使用隔离 sandbox；多 Agent 时明确区分 handoff 与 manager-style orchestration。
• 可靠性： 极高。官方 SDK 文档，适合直接落地；API 和版本会变化，不应把当前版本细节当成长期架构标准。

6. OpenAI：New tools for building agents

• 作者/团队： OpenAI 产品/开发者团队
• 日期： 2025-03-11
• 链接： https://openai.com/index/new-tools-for-building-agents/
• 核心方法： 用 Responses API 作为构建 Agent 的核心 API；使用 web search、file search、computer use 等工具；用 Agents SDK 管理 Agent 循环、工具调用、handoff、guardrails 和 tracing。推荐的分工是：模型负责推理，工具负责行动，应用负责权限与状态。
• 可靠性： 高。官方产品发布文章；产品能力和接口信息应结合最新开发者文档复核。

7. OpenAI：Building agents 学习路径

• 作者/团队： OpenAI Developer Education / Developer Platform
• 日期： 未标注（当前开发者站版本）
• 链接： https://developers.openai.com/tracks/building-agents
• 核心方法： 将 Agent 拆成模型、工具、状态/记忆和编排四类基础能力；从单 Agent 和明确工具开始，逐步加入 sessions、handoffs、guardrails、tracing 与评估。
• 可靠性： 高。官方学习路径，适合作为实现顺序和阅读地图。

8. OpenAI：Evaluate agent workflows

• 作者/团队： OpenAI Developer Platform
• 日期： 未标注（持续更新）
• 链接： https://developers.openai.com/api/docs/guides/agent-evals
• 核心方法： 用 traces 观察 Agent 的实际运行路径，再用 datasets、graders 和 eval runs 做系统评估；不要只看最终回答，要检查工具选择、参数、handoff、错误恢复、成本和延迟。
• 可靠性： 极高。官方评估文档；是把 Agent 从 Demo 推向生产的关键资料。

9. Gemini API：代理概览

• 作者/团队： Google AI for Developers / Gemini API 文档团队
• 日期： 未标注（持续更新；页面当前为公开预览相关文档）
• 链接： https://ai.google.dev/gemini-api/docs/agents?hl=en
• 核心方法： Google 托管式 Agent 在隔离 Linux 沙盒中执行代码、管理文件和浏览网页；通过网络 allowlist 限制出站访问；对外部工具/API 设置权限边界；敏感工作流加入人工监督，先检查 Agent 的操作和输出。页面还区分通用托管 Agent 与 Deep Research Agent，并提供自定义指令、技能和数据的扩展方式。
• 可靠性： 极高。Google 官方 API 文档；产品处于预览/快速演进阶段，适合参考安全和运行时实践，不宜假设所有功能已 GA。

10. Agent Development Kit（ADK）官方文档

• 作者/团队： Google，Agent Development Kit 团队
• 日期： 未标注（持续更新）
• 链接： https://adk.dev/
• 核心方法： 用可组合 Agent、工具、sessions/state、callbacks、evaluation 和 deployment 组织工作流；从单 Agent 开始，必要时用 sequential/parallel/loop 等编排；将长期状态和运行轨迹显式化，避免把所有上下文塞进单次 prompt；用评估和可观测性验证工具调用与最终结果。
• 可靠性： 高。Google 官方开源项目文档；工程细节可信，但框架 API 与最佳实践会随版本变化，需结合版本号引用。

11. AI agent orchestration patterns

• 作者/团队： Microsoft Azure Architecture Center / Microsoft Learn
• 日期： 未标注（持续更新）
• 链接： https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns
• 核心方法： 先选择最低复杂度：直接模型调用 → 单 Agent + 工具 → 多 Agent 编排。多 Agent 只在单 Agent 无法可靠处理、需要跨领域专业化、不同安全边界或并行化时采用；系统讲解 sequential、concurrent/parallel、group chat、handoff、manager 等模式，并强调协调开销、延迟、成本、失败模式和迭代上限。
• 可靠性： 极高。微软官方架构中心，适合做企业系统设计依据；它是架构指导而非某一产品的唯一实现方案。

12. Cursor：Agent Overview

• 作者/团队： Cursor / Anysphere 官方文档团队
• 日期： 未标注（持续更新）
• 链接： https://cursor.com/docs/agent/overview
• 核心方法： Agent 由系统提示/规则、工具、模型三部分组成；工具包括代码库搜索、网页、读写文件、Shell、浏览器等。使用 checkpoints 保护探索性修改，用消息队列安排后续任务，需要纠偏时在下一次工具调用前追加指令；长任务可以用 /goal 设定持续目标，并结合规则、自定义模式和定期检查。
• 可靠性： 高。Cursor 官方产品文档，直接反映真实工作流；部分功能正在逐步推出，使用时应确认账户和版本是否可用。

13. Scaling long-running autonomous coding

• 作者： Wilson Lin（Cursor）
• 日期： 2026-01-14
• 链接： https://cursor.com/blog/scaling-agents
• 核心方法： Cursor 在同一项目上并发运行数百个 Agent、持续数周的工程复盘。关键经验：扁平共享文件协作会导致重复劳动、规避困难任务和无人负责；改用“规划者—执行者—评审者”的层级流水线；周期性从干净初始状态重启以对抗漂移；不同角色选择不同模型；减少不必要的 aggregator；结构化程度应介于无结构与过度编排之间；提示设计对长期专注和协作质量极其重要。
• 可靠性： 极高（工程经验）。Cursor 员工原文，包含实际运行规模和失败尝试；属于单家公司内部实验，不应直接等同于普适最优解。

14. Cascade Workflows

• 作者/团队： Windsurf/Cascade 官方文档（当前文档站已迁移到 Devin Docs，保留 .windsurf/ 路径与产品概念）
• 日期： 未标注（持续更新）
• 链接： https://docs.devin.ai/desktop/cascade/workflows
• 核心方法： 把 PR review、部署、测试、格式化等重复流程写成可版本控制的 Markdown workflow；用 /workflow-name 手动调用，步骤按顺序执行，也可以调用其他 workflow。Workflow 手动触发，不会被 Cascade 自动调用；需要模型自动判断是否使用的复杂程序，应改用 Skill。
• 可靠性： 高。官方产品文档；由于 Windsurf/Cascade 文档出现迁移/品牌变化，作为 Windsurf 资料引用时应注明当前承载站点和版本状态。

15. Cascade Skills

• 作者/团队： Windsurf/Cascade 官方文档（当前文档站已迁移到 Devin Docs）
• 日期： 未标注（持续更新）
• 链接： https://docs.devin.ai/desktop/cascade/skills
• 核心方法： 用 SKILL.md 把多步骤程序、参考资料、脚本、模板和检查表封装成可复用技能；通过 progressive disclosure 只向模型暴露名称/描述，真正调用时再加载完整内容，降低上下文开销；区分 workspace/global scope；适合部署、代码审查、测试等复杂流程。区分 Skill（可由模型动态调用）、Rule（行为约束）和 Workflow（手动调用）。
• 可靠性： 高。官方文档且给出目录结构、格式和调用机制；品牌/实现持续变化，需按当前版本验证。

16. AGENTS.md：目录级上下文与约束

• 作者/团队： Windsurf/Cascade / Devin Desktop 官方文档团队
• 日期： 未标注（持续更新）
• 链接： https://docs.devin.ai/desktop/cascade/agents-md
• 核心方法： 在仓库根目录和子目录放置 AGENTS.md，让规则按文件位置自动生效：根目录规则 always-on，子目录规则只作用于对应路径；用于架构决策、编码规范、测试要求和目录特定约束。比依赖 Agent 的临时记忆更可复现、更适合团队协作和版本控制。
• 可靠性： 高。官方实现文档；它描述的是 Cascade/Devin 当前规则系统，不是所有 Agent 产品的通用标准，但可迁移为团队级 AGENTS.md 约定。

可抽取的共识工作流

1. 先判定是否需要 Agent： 单次调用、RAG 或固定脚本能解决时不要增加 Agent loop。
2. 从单 Agent + 少量工具开始： 工具接口、参数、错误返回和权限边界比“更复杂的框架”更重要。
3. 按任务增加编排： 固定子任务用 chaining/sequential；独立视角用 parallel；任务拆分不确定时用 orchestrator-workers；需要质量闭环时用 evaluator-optimizer。
4. 给 Agent 可验证反馈： 每一步拿到工具结果、测试结果或环境状态，而不是只凭模型自述判断进展。
5. 让工作流可复现： 把长期规则放到 AGENTS.md/Rules，把多步骤程序放到 Skills，把明确要手动执行的流程放到 Workflows。
6. 控制长任务： 沙盒、网络 allowlist、检查点、最大迭代次数、周期性重启、可取消/可恢复语义、人工审批和 tracing/evaluation 缺一不可。
7. 按角色选择模型： 规划、执行、审查可能需要不同模型；用真实任务评估，而不是只按模型名选择。

可靠性说明

• 最高可信： 官方文档、官方工程博客、作者署名的内部工程复盘。
• 需要保留上下文： 产品文档通常持续更新；原文中的版本、功能可用性和性能数字都应记录访问日期/版本。
• 避免过度外推： Cursor 的长时间多 Agent 实验、Anthropic 的客户经验和各家 SDK 都是强信号，但不能直接当作所有领域的统一最佳实践；应通过自己的任务集、成本、延迟、成功率和安全指标复验。