Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

agents-best-practices

"模型提议行动；运行框架（harness）负责验证、授权、执行、记录并返回观测。"

一个与提供商无关的 Agent Skill（智能体技能），用于设计、生成 MVP 蓝图、审计、重构并解释 agentic harness（智能体运行框架）。

它不仅适用于编码智能体：研究、支持、运维、销售、财务、数据分析、采购、法律工作流、医疗工作流、教育以及工作流自动化智能体，都需要相同的核心运行时纪律。

安装 — 任选其一：

A. 使用 skills（任意兼容智能体）：

npx skills add DenisSergeevitch/agents-best-practices -g

-g 标志会在用户级别全局安装，以便每个项目都能发现它。

B. 或将以下提示词粘贴给你的 AI 智能体：

Install the agents-best-practices skill for me:

1. Clone https://github.com/DenisSergeevitch/agents-best-practices into my
   user-level skills directory as `agents-best-practices/`.
   Use the skill directory my agent reads on this machine, for example:
   - Codex: ~/.codex/skills/
   - Claude Code: ~/.claude/skills/
2. Verify that SKILL.md, icon.jpeg, and the references/ directory are present.
3. Confirm the install path when done.

C. 手动安装路径：

# Codex
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "${CODEX_HOME:-$HOME/.codex}/skills/agents-best-practices"

# Claude Code, user-level
mkdir -p "$HOME/.claude/skills"
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  "$HOME/.claude/skills/agents-best-practices"

# Claude Code, project-level
mkdir -p .claude/skills
git clone https://github.com/DenisSergeevitch/agents-best-practices.git \
  .claude/skills/agents-best-practices

用例 · 这是什么 · 理念 · 结构 · 来源

---

用例

安装后，当对话涉及智能体架构、harness 设计、工具权限、规划模式、工作流编排、上下文与记忆、技能、连接器、可观测性、评测（evals）、提示缓存或生产就绪性时，该技能会自动激活。三种常见用法：

案例 1 — 生成 MVP 智能体蓝图

你有一个业务领域，需要的是最小但有用、可安全上生产的智能体运行框架，而不是一份模糊的最佳实践清单。

You    > Build an agent for account renewal risk. It should read CRM,
         support tickets, and usage data, then draft renewal actions.

Agent  > Start with an approval-gated Level 2 harness.
         The MVP has one job: produce a renewal-risk brief plus draft
         next actions for a human account owner.

         Core loop:
           user/task -> context builder -> model call -> typed tool call
           -> schema validation -> permission check -> execution or pause
           -> structured observation -> next step or final brief

         Minimal tools:
           - read_account_profile      read_private_data
           - list_support_tickets      read_private_data
           - fetch_usage_summary       read_private_data
           - draft_customer_email      draft_external_message
           - request_approval          approval_gate

         Launch gate:
           20 historical accounts, trace review, no unapproved external
           sends, and human acceptance on at least 80% of draft actions.

主要参考文档为 references/mvp-agent-blueprint.md。

案例 2 — 审计现有智能体运行框架

你已有一个可用的智能体，但它脆弱、成本高、权限过宽或难以调试。

You    > Our research agent sometimes runs tools forever and forgets why
         it made a decision after context compaction. Audit the harness.

Agent  > The failure points are runtime-level, not prompt-level:
           - no hard step/tool/time/cost budget
           - compaction preserves prose but loses active approvals
           - tool results are unbounded and mix trusted/untrusted data
           - no event trace for model output -> tool call -> observation

         Fix order:
           1. Add loop budgets and termination reasons.
           2. Store plan, approvals, todos, and artifacts outside the prompt.
           3. Make compaction rehydrate active state, not chat history.
           4. Add evals for injection, missing tool result, timeout, and
              budget exhaustion.

从 references/agentic-loop.md、references/context-memory-compaction.md、references/security-observability.md 和 references/evals.md 开始。

案例 3 — 设计工具、权限与连接器

你需要智能体与真实系统协作，同时避免把每个 API 都变成不安全的大而全工具。

You    > The ops agent needs Slack, Linear, Google Drive, and our internal
         deploy API. How should tools and permissions work?

Agent  > Split by risk class. Reads can be autonomous when scoped.
         Drafts can be autonomous when labeled. External writes, deploys,
         destructive actions, privileged access, and financial operations
         require an approval record outside the model.

         Do not expose generic send_message, write_database, or run_command.
         Wrap each action as a narrow typed tool with structured results and
         deterministic permission checks.

使用 references/tools-and-permissions.md 和 references/skills-and-connectors.md。

该技能还适用于

• "如何添加规划模式，又不让智能体变得被动？" -> 使用 references/planning-and-goals.md。
• "大型任务何时应拆解为工作流？" -> 使用 references/workflow-orchestration.md。
• "自动压缩应如何保留进行中的工作？" -> 使用 references/context-memory-compaction.md。
• "最小的安全编码智能体运行框架是什么？" -> 使用 references/coding-agents.md。
• "应如何评测智能体运行框架？" -> 使用 references/evals.md。
• "如何在长期运行的智能体中让提示缓存生效？" -> 使用 references/prompt-caching-and-cost.md。
• "如何同时支持 OpenAI、Anthropic 和 OpenAI 兼容 API？" -> 使用 references/provider-api-patterns.md。
• "上线前应检查什么？" -> 使用 references/checklists.md。

---

"保持循环简单，让运行时严谨。"

这是什么

面向构建 agentic 系统的人员的参考文档，其中模型只是运行时的一部分。它帮助设计包含以下内容的 harness：

• 与提供商无关的模型-工具-观测循环，
• 窄而强类型的工具与结构化工具结果，
• 模型之外的运行时权限检查，
• 规划模式与需审批方可执行的机制，
• 面向大型可分解任务的工作流编排，
• 带预算、检查点、验证与停止规则的目标式循环，
• 上下文、记忆、检索与自动压缩（auto-compaction），
• 技能、MCP 与外部连接器治理，
• 感知提示缓存的上下文布局与成本遥测，
• 可观测性、评测（evals）、上线门禁与事件响应。

这是围绕智能体（agent）的控制平面：instructions -> context builder -> model call -> tool proposal -> validation -> permission decision -> execution or approval pause -> observation -> next step or final answer。

它不是什么

• 不仅面向编程智能体。
• 默认不是多智能体框架。
• 不能替代运行时授权、沙箱隔离或审计日志。
• 不是仅靠提示词（prompt）的安全策略。
• 也不是对外暴露 execute_anything、send_message 或 write_database 等宽泛工具的理由。

请先使用单智能体 MVP。只有在可度量的失败证明有必要时，再添加目标循环、连接器与更广的自主性。

目录结构

agents-best-practices/
├── README.md                                 # public-facing overview and install notes
├── SKILL.md                                  # skill entry point and trigger rules
├── icon.jpeg                                 # skill image used by the README
└── references/
    ├── mvp-agent-blueprint.md                # domain-specific MVP harness blueprint
    ├── coding-agents.md                      # repository-facing coding-agent harness overlay
    ├── architecture.md                       # component model and harness boundaries
    ├── agentic-loop.md                       # loop invariants, retries, budgets, stopping
    ├── tools-and-permissions.md              # typed tools, risk classes, approvals
    ├── planning-and-goals.md                 # planning mode and long-running goals
    ├── workflow-orchestration.md             # decomposed workflows, packets, verification
    ├── context-memory-compaction.md          # context, memory, retrieval, compaction
    ├── prompt-caching-and-cost.md            # stable prefixes and cost-aware context
    ├── skills-and-connectors.md              # Agent Skills, MCP, connectors, tool search
    ├── system-prompts-instructions.md        # instruction hierarchy and templates
    ├── provider-api-patterns.md              # OpenAI, Anthropic, compatible APIs
    ├── security-observability.md             # guardrails, tracing, launch gates
    ├── evals.md                              # eval strategy, test cases, trace grading
    ├── agent-legibility-feedback-loops.md    # source-of-truth artifacts and cleanup
    ├── checklists.md                         # implementation and audit checklists
    ├── coverage-audit.md                     # topic coverage verification
    └── source-links.md                       # official references and further reading

设计哲学

本技能要解决的核心矛盾：智能体如何在真实系统中完成有用工作，同时避免把模型变成不受审计的操作者？ 答案是一小组运行时规则：

1. 由运行时框架（harness）执行，而非模型 — 模型负责提议；应用代码负责校验、授权、执行与记录。
2. 每次工具调用都有结果 — 拒绝、超时、参数格式错误和中止同样属于观测（observation）。
3. 风险改变循环 — 读取、草稿、写入、对外通信、金融操作、破坏性操作和特权操作需要不同的权限路径。
4. 草稿与提交分离 — 高风险副作用需要在提示词之外的审批记录。
5. 上下文是构建出来的，不是一次性倾倒的 — 只检索足够的信息，标注信任边界，并在压缩后保留活跃状态。
6. 长时间运行的任务需要预算 — 步数、时间、token、成本和工具调用预算都是产品的一部分。
7. 技能与连接器渐进式披露 — 先暴露名称与描述；仅在相关时加载详细工作流。
8. 重复出现的失败应沉淀为框架能力 — 校验器、工具、文档、评测或策略优于反复在提示词里给建议。

请先阅读 SKILL.md。当用户要求创建或构建智能体时，使用 references/mvp-agent-blueprint.md。

关于 Agent Skills

Agent Skills 将可复用的领域知识打包，使兼容的智能体仅在相关时才发现、加载并应用某条工作流。本仓库使用可移植的 SKILL.md 入口，可作为 Codex skill、Claude Code skill，或适用于其他支持 Agent Skills 的运行时。

参考资料

• Agent Skills 规范：agentskills.io/specification
• OpenAI 的 function calling、tools、agents、guardrails、sandboxing、Responses 与 prompt caching 文档列于 references/source-links.md。
• Anthropic 的 agent、context engineering、tool writing、long-running harness、MCP 与 Agent Skills 参考资料列于 references/source-links.md。
• MCP 规范与治理参考资料列于 references/source-links.md。

许可证

MIT — 见 LICENSE。

致谢

以 Agent Skill 形式编写，面向与提供商无关的智能体运行时框架（harness）设计。相关建议综合了 OpenAI、Anthropic、OpenAI 兼容 API、Agent Skills、MCP 与外部连接器工作流中的常见生产级 harness 模式。