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

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

一句话结论

这些资料的共同结论是：先用最简单的单模型/单 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 都是强信号，但不能直接当作所有领域的统一最佳实践；应通过自己的任务集、成本、延迟、成功率和安全指标复验。