ai-agents

AI Agent 开发——架构中心

使用此技能判断工作流是否应采用 Agent、适合哪种 Agent 形态、应使用哪种协议边界，以及上线前必须具备哪些生产控制措施。

默认原则：明确的控制流、受限的工具、类型化契约、可审计的状态、高风险操作需经人工批准，并从第一天起采集遥测数据。

保持此文件精简。仅在需要时，从 references/index.md、assets/ 和同级技能中加载详细内容。

何时使用此技能

当用户询问以下内容时，使用此技能：

• Agent 架构或运营模式决策
• 是否应构建 Agent 的评估
• MCP 与 A2A 协议的选择
• 对现有 Agent 系统进行生产就绪度审查
• 评估、可观测性、上线或安全规划
• 需求已明确后的框架选择
• 新 Agent 规范的起始模板
• 图工程、Agent／工作流图、状态机编排、循环图，或 DAG 与循环设计的比较
• 循环工程、运行至完成的编码 Agent、自我改进工作流、评估器反馈循环，或有界自主迭代
• 不确定“图”指的是执行控制流、改进网络，还是知识／上下文图

深入了解时使用其他技能

• 多个 Agent 共用的平台（LLM 网关、模型路由、Agent 身份、MCP 网关、追踪、成本、EU／UK 分类）→ ai-agent-platform
• 提示词契约和结构化输出 → ../ai-prompt-engineering/SKILL.md
• 检索、分块、重排序、搜索质量 → ../ai-rag/SKILL.md
• 向量大脑的实现、架构、摄取脚本、清单和检索工具契约 → ../ai-vector-brain/SKILL.md
• 机器人构建（支持、销售、对话设计、LangGraph）→ ../ai-bot-builder/SKILL.md
• 语音机器人（STT／TTS 流水线、电话系统、延迟）→ ../ai-voice-bots/SKILL.md
• MCP 服务设置、传输方式、服务构建 → ../agents-mcp/SKILL.md
• 子 Agent、委派契约、最小权限工具 → ../agents-subagents/SKILL.md
• 基于 CLI 的工具（非交互式、幂等、适用于 Agent 的模式）→ ../software-devtools/SKILL.md
• 评估框架、攻击套件、回归门禁 → ../qa-agent-testing/SKILL.md
• 部署护栏和模型运维 → ../ai-mlops/SKILL.md
• 应用安全和高风险控制措施 → ../software-security-appsec/SKILL.md
• 模型和推理成本调优 → ../ops-cost-optimization/references/ai-api-cost-guide.md、../ai-llm-inference/SKILL.md
• 知识／上下文图、检索架构和图支持的记忆 → ../ai-context-layer/SKILL.md、../ai-rag/SKILL.md、../ai-vector-brain/SKILL.md

默认工作流

1. 运行是否构建的决策关卡：如果更简单的工作流、表单或工具就能满足需求，就不要构建 Agent；只有在确有必要具备自主能力时才继续。
2. 定义任务环境：性能衡量指标、环境、感知信息／传感器、操作／工具、可观测性、确定性、时间范围，以及单 Agent 还是多 Agent 交互。
3. 选择控制流；生产环境默认使用工作流／FSM／DAG。
4. 选择协议边界：MCP 用于工具／数据，A2A 用于 Agent 交接。
5. 定义契约：工具架构、交接载荷（设置委派深度上限：references/multi-agent-patterns.md）、状态模型、成功标准。
6. 发布前添加评估和遥测。
7. 为不可逆操作添加人工审批、回滚和紧急停止开关。
8. 从模板入手，再将实现细节交由专门技能处理。

拓扑升级关卡

从一个边界明确的工作流或 Agent 开始，并将其保留为控制方案。只有当任务包含可独立执行的分支、需要实质不同的工具权限，或必须将验证器与生成器隔离时，才升级为多 Agent。升级前，记录单 Agent 的失败情况、拟定的交接契约，以及额外的延迟和成本预算。只有当同一组任务能改善目标结果且不增加未解决的交接失败时，才接受该拓扑；否则保留更简单的控制方案。

升级前先衡量成本：用两种方案运行同一组任务，并在结果变化旁记录 token 和延迟倍数。只有当结果提升值得按当前价格承担这些倍数时才升级；价格应查阅当前提供商的定价页面（参见 ../ops-cost-optimization/references/ai-api-cost-guide.md），切勿凭记忆估算。

已知陷阱

• 当工作流、表单或普通工具调用更简单时，仍将“Agent”视为默认交互模式
• 将 MCP 用作整体 Agent 架构，而不是工具和资源集成层
• 在缺少来源信息（A13）、保留策略、纠错流程（A11 — 遗忘路径）和用户价值证明的情况下添加长期记忆。使用 ai-context-layer/patterns-catalog.md 选择一种命名模式，并使用 ai-context-layer/anti-patterns-catalog.md 进行全面检查
• 让规划器循环在没有明确的步数、预算和升级限制时递归。步数上限无法发现振荡和虚构的观察结果；使用 references/agent-debugging-patterns.md 诊断循环故障
• 在尚未具备评估器覆盖、回滚控制和人工审批路径时，就发布自主操作
• 对推理密集型任务默认采用多 Agent 拓扑，而不考虑在相同 token 预算下，单个强 Agent 是否能达到或超越它。扩展前，确认任务确实可并行化，或确实需要多样化的工具／角色；相关证据和范围限制见 ../agents-subagents/SKILL.md § 单个强 Agent 优于团队的情况

常见反模式

• 以聊天为先的 Agent 设计，没有状态模型、契约或操作边界
• 尚未了解单 Agent 的失效模式，就引入多 Agent 拓扑
• 根据便利性而非最小权限原则定义工具接口
• 发布后才添加评估，使其沦为可观测性作秀，而不是发布关卡
• 仅受炒作、基准测试截图或营销分类影响来选择提供商或框架

快速参考

问题	默认答案
这应该是一个 Agent 吗？	从 references/build-vs-not-decision.md 开始；默认答案是“否”，除非任务量、模糊性和价值足以证明自主性合理。
任务环境是什么？	在选择框架前，说明性能指标、环境、感知信息／传感器、操作／工具、可观测性、确定性、时间范围和其他 Agent。
哪种控制流合适？	优先选择工作流／FSM／DAG；只有在无法对分支进行显式建模时才使用规划器／执行器。
MCP 还是 A2A？	外部工具／数据使用 MCP，Agent 间协调使用 A2A；多 Agent 系统也需要工具时，两者都用。
何时使用多 Agent？	仅在角色、交接约定和验证者职责都明确时使用。
何时添加长期记忆？	仅在具备来源信息、保留规则、用户同意且价值明确时添加。从 ai-context-layer/patterns-catalog.md 中选择一个明确命名的模式（应用编排使用 P2、自我编辑使用 P3、时间型使用 P4、对话型使用 P6）。执行反模式检查——A1（不保存原始对话记录）、A11（必须提供遗忘路径）、A13（来源信息必不可少）。
推出前必须具备什么？	评测套件、遥测、操作限制、人工升级机制、回滚路径和紧急停止开关。
这是“图工程”还是“循环工程”？	从 references/graph-and-loop-engineering.md 开始；在选择运行时或数据存储前，先明确图的用途。

自主性形态 — 如何托管 Agent 以实现全天候运行

持续运行 Agent 的三种部署形态。根据触发模型选择，而非根据框架选择。

形态	触发方式	适用场景	主要指南
A — 触发式 / 托管运行	Webhook、队列、计划任务、/fire	按事件执行 Agent 任务、计划任务、从外部来源扇出	../ai-coding-agents-state/references/webhook-and-queue-triggers.md + ../ai-coding-agents-state/references/durable-trigger-integration.md
B — 常驻机器人 / 语音服务	会话、WebSocket、SIP 呼叫	具有对话状态的支持 / 销售 / 语音机器人	../ai-bot-builder/references/production-deployment.md + ../ai-bot-builder/references/stateful-rollout-and-blue-green.md + ../ai-voice-bots/references/production-deployment.md
C — 自主循环	PRD + 循环驱动器，直至满足验收条件	长周期工作：重构、迁移、研究、Ralph-Loop 类任务	references/autonomous-loop-patterns.md

托管式或自托管式循环：当你需要自定义沙箱或出站流量策略、私有网络中的工具、数据驻留或确定性重放时，选择自托管；否则优先选择供应商托管的 Agent 运行时。做出决定前，请查阅供应商文档，了解会话持久化、空闲计费和沙箱限制。

跨形态要求：

• 预算和终止开关执行：../agents-hooks/references/budget-and-loop-hooks.md
• 全天候运行模式（SLO、值班、运行手册）：references/24-7-operating-model.md
• 供应商故障转移和密钥轮换：../ai-bot-builder/references/secret-rotation-and-model-fallback.md
• 托管位置（Vercel / Fly.io / Railway / Cloudflare / Render）：../software-paas-hosting/SKILL.md 和 ../software-paas-hosting/references/agent-hosting-matrix.md

架构选择

需求	默认 Agent 形态	说明
确定性业务流程	工作流 Agent	最适合作为可审计生产行为的默认选择。
有界的外部操作	工具调用型 Agent	保持工具范围狭窄、类型明确，并限定权限范围。
以知识为依据的回答	RAG Agent	要求提供引用、检索遵循 ACL，并在缺少证据时拒绝回答。
带分支的长程多步骤工作	规划器 / 执行器	使用严格的步骤预算、检查点和重新规划限制。
职责明确的专业角色	多 Agent 编排器	交接即 API；尽早加入验证者 / 评估者角色。根据 MAST 失效分类（Cemri 等，2025，arXiv:2503.13657）评估设计——不要重新推导该分类：../agents-subagents/references/mast-failure-taxonomy.md。
桌面或浏览器控制	OS Agent	要求沙箱隔离、UI 验证和操作门控。
代码更改和 CI 反馈	SWE Agent	要求仓库隔离、测试、审查门控和回滚。
自主改进代码、提示词或产物	研究 / 实验 Agent	固定评估指标、限定修改范围，并采用保留 / 回退循环。

自主改进循环

研究／实验 Agent 自主迭代：提出更改 → 应用更改 → 评估 → 保留或还原 → 重复。只要有可衡量的评估函数，这种模式就适用于任何对象。

组件	用途	示例
修改范围	Agent 可以更改的内容	一个文件（train.py）、一个提示词、一个配置
评估函数	如何为结果评分	val_bpb、是／否检查清单（3-6 个问题）、延迟测量
保留／还原规则	何时保留更改	分数提高则保留；分数下降则还原
终止条件	何时停止	N 轮、达到目标分数或手动停止
记录台账	实验历史	Git 提交、results.tsv、附有原因说明的变更日志

设计约束：

• 缩小修改范围（一个文件、一个提示词）。范围越广，越容易累积不易察觉的回归问题。
• 使用二元或标量指标，而不是主观评分。“标题是否包含具体数字？”比“给标题质量打 1-10 分”更好。
• 3-6 项评估标准最为合适。标准过多会导致钻空子；过少则会遗漏故障模式。
• 保留变更日志，以便后续模型从上一个 Agent 停下的地方继续。

参见：autoresearch（ML 训练）、Lehmann 的技能优化改编方案（提示词／技能改进）。

协议选择

如果系统需要……	使用
工具调用、数据库访问、文件访问、提示词、资源	MCP
任务交接、Agent 卡片、多 Agent 路由	A2A
工具和协作 Agent 两者	MCP + A2A

协议默认规则：

• 将 MCP 视为工具／数据集成层，而不是 Agent 架构本身。
• 将 A2A 交接视为带有模式验证和 trace_id 传播的版本化 API。
• MCP 有两种标准传输方式：stdio 和 Streamable HTTP；仅支持 SSE 的服务已过时。A2A 通过 /.well-known/agent-card.json 中的 Agent Card 进行发现；没有任务 ID 和状态枚举的交接就不是 A2A，无论它被称作什么。已验证的线路级事实：references/protocol-decision-tree.md § Protocol Facts。
• 对于远程 MCP，请明确限定授权范围和身份；不要只依赖网络信任。
• stdio 服务配置是一条由客户端运行的命令：切勿根据不可信输入构建该命令，并应对启动服务的主机进行沙箱隔离。本地传输安全控制措施：../agents-mcp/references/mcp-security.md § Local stdio。

Agent 即代码模式

将 Agent 角色定义为结构化、版本化的产物，并明确其专业知识、约束和预期输出。此模式将 Agent 定义视为可审查的代码，而不是临时编写的提示词字符串。

定义完善的 Agent 规范包括：

字段	用途
角色	Agent 负责什么（例如“架构师”“QA 审查员”）
专业知识	领域知识和能力
约束	禁止事项、权限边界
预期输出	生成的产物（规范、审查意见、计划、代码）
交互规则	如何与其他 Agent 或人类沟通

优点：可以在 PR 中审查 Agent、比较不同版本的差异，并按照明确的角色边界将其组合成团队。

有关当前交付方法，以及何时借鉴 GSD、BMAD、Spec Kit、OpenSpec、MADD 或 AI-SDLC，请参见 references/agent-delivery-methods.md。

随任务复杂度调整 Agent 规模

让 Agent 的复杂程度与任务复杂度相匹配。修复 Bug 时不要采用完整的多 Agent 编排，迁移平台时也不要只用一个提示词。

任务复杂度	Agent 方案
配置更改、拼写错误	直接使用提示词，无需 Agent 基础设施
Bug 修复、小型功能	使用工具范围受限的单个 Agent
多模块功能	负责人 + 2-3 个专用工作 Agent
跨服务迁移	完整编排，包含角色定义、讨论和验证

是否升级方案应由实际观察到的模糊性决定，而不是基于假定的复杂度。

生产环境默认设置

• 保持状态明确、可序列化且可重放。
• 将所有状态外置到文件中——计划、进度、决策和依赖项输出都持久化到结构化文件中，以便任何 Agent 会话都能在不继承上下文的情况下恢复。
• 保持工具接口精简；发布任务，而不是原始后端的复杂性。
• 限制重试次数、预算、上下文大小和递归深度。
• 将检索到的内容和工具内容视为不可信输入。
• 切勿在同一个模型上下文中同时放入不可信内容、私有数据和具备数据外传能力的工具。应拆分为一个看不到原始不可信文本的特权规划器，以及一个隔离的读取器；后者的输出应视为数据，而非指令（Debenedetti 等人，2025 年，CaMeL）；注入分类器是第二层防护，而非安全边界。
• 使用一致的追踪机制，监测大模型调用、检索、记忆操作和工具调用。
• 数据库写入、财务操作、法律/合规操作和破坏性操作必须经过人工审批。
• 与其采用隐蔽的不安全回退方案，不如拒绝执行或降级运行。

有关新上下文工作 Agent、持久状态以及会话与项目边界，请参阅 references/context-rotation-and-state.md。

模板和入口

• 标准 Agent 规范 → assets/core/agent-template-standard.md
• 快速原型规范 → assets/core/agent-template-quick.md
• 专用 Agent 规范 → assets/core/agent-template-specialized.md
• AI 原生 SDLC 操作手册 → assets/agent-template-ainative-sdlc.md
• 安全检查关卡 → assets/checklists/agent-safety-checklist.md
• 工具架构模板 → assets/tools/tool-definition.md
• 工具验证清单 → assets/tools/tool-validation-checklist.md
• 多 Agent 入门模式 → assets/multi-agent/manager-worker-template.md、assets/multi-agent/evaluator-router-template.md
• RAG 入门模板 → ../ai-rag/SKILL.md assets/；Agent 端检索规则 → references/rag-patterns.md；知识库布局 → assets/knowledge-base/kb-architecture.md
• 使用报告 --pricing 文件 → assets/pricing-template.json（不包含费率）

脚本

脚本	用途
scripts/agent_eval_runner.py	读取 JSONL 任务/预期/实际三元组并报告通过率（离线）。采用失败关闭策略：格式错误或不完整的记录均计为失败。对于对抗性测试套件和多轮测试框架，请交由 ../qa-agent-testing/SKILL.md 处理。
scripts/claude-usage.py	解析 Claude Code 使用日志，包括每个会话下子 Agent 的对话记录，并生成令牌报告；每个 API 响应只计数一次（根据消息 ID 和请求 ID 去重行）。只有使用 --pricing <file> 才会计算费用（费率需从服务提供商的定价页面复制；架构见 assets/pricing-template.json）；不使用该参数时，费用标记为 unpriced。使用该参数时，未知模型或没有独立 1 小时费率的 1 小时缓存写入均标记为 unpriced（退出码为 3），绝不会按默认费率计价。stats-cache.json 中的 daily 没有可计价的令牌，使用 --pricing 时会以退出码 3 退出；models --pricing 则会读取日志，其中包含缓存写入 TTL 的细分信息。
scripts/codex-usage.py	解析 Codex 使用日志并生成令牌报告，跳过重新发送的令牌事件。只有使用 --pricing <file> 才会计算费用，并遵循相同的失败关闭规则，退出码为 3。每份报告按事件计价，与 traces 相同。Codex 日志不包含服务层级或上下文类别，因此脚本会假定使用标准层级和基础上下文，打印相应说明，并将费用标记为 estimated。

导航

• 完整深入指南 → references/index.md
• 我们应该构建这个吗？ → references/build-vs-not-decision.md
• MCP 与 A2A → references/protocol-decision-tree.md
• 当前运行默认设置 → references/modern-best-practices.md
• 交付方法与规划系统 → references/agent-delivery-methods.md
• 评估与遥测 → references/evaluation-and-observability.md
• CLI 使用情况跟踪 → references/coding-agent-usage-tracking.md
• 上下文轮换与持久状态 → references/context-rotation-and-state.md
• 部署安全 → references/deployment-ci-cd-and-safety.md
• 自主循环 / Ralph-Loop 类 → references/autonomous-loop-patterns.md
• 图工程、循环工程与图类型消歧 → references/graph-and-loop-engineering.md
• 7×24 运行模式（SLO、值班、运行手册） → references/24-7-operating-model.md
• 工具架构与契约 → references/tool-design-specs.md、references/api-contracts-for-agents.md
• 决策与经济效益 → Agent 经济效益与 ROI、成熟度与集群治理、框架全景
• 架构 → AI 引擎层、OODA 循环架构、收件箱引擎（事件驱动式接入）、OS Agent 能力、代码/SWE Agent、语音与多模态 Agent
• 协调 → A2A 交接模式、多 Agent 模式、多 Agent 系统的博弈论、委托代理理论
• 上下文与记忆 → 上下文工程、上下文图模式、记忆系统速查
• SDK 模式 → Claude Agent SDK、Pydantic AI
• 运维与安全 → Agent 运维、防护措施实施、升级处理模式
• 精选外部来源 → data/sources.json；无法浏览时，请依据其中的内容回答有关框架排名、生命周期、传输/身份验证、A2A 成熟度及定价的问题，说明假设，并将相关说法标记为未经验证

相关技能

• 选择 Agent、单次调用、RAG 还是微调，以及广义 LLM 系统设计 → ../ai-architecture-advisor/SKILL.md
• LangGraph 机器人实现 → ../ai-bot-builder/SKILL.md
• RAG 实现 → ../ai-rag/SKILL.md
• Vector-brain 实现 → ../ai-vector-brain/SKILL.md
• MCP 实现 → ../agents-mcp/SKILL.md
• 子 Agent 编排 → ../agents-subagents/SKILL.md
• Swarm 和并行调度 → ../agents-swarm-orchestration/SKILL.md
• Hook 防护措施和生命周期 → ../agents-hooks/SKILL.md
• 技能打包 → ../agents-skills/SKILL.md
• 项目记忆 → ../agents-memory/SKILL.md
• 评估测试框架 → ../qa-agent-testing/SKILL.md
• 可观测性 → ../qa-observability/SKILL.md
• 安全与 AppSec → ../software-security-appsec/SKILL.md

使用说明

• 从这里入手了解架构和生产环境要求，不要将其作为深入的实现指南。
• 优先采用稳定的能力指导，而不是过时的框架排名。
• 仅在用户的方向明确后，才加载详细参考资料。
• 确保建议具有可操作性：涵盖契约、故障模式、关卡、遥测和回滚。

经验总结循环

当以往的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史或它是唯一可用的备选时，才查阅 learnings.md。否则跳过这两个文件。

应用经验后，如果遇到了值得记住的模式、值得避免的错误或令人意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目。不要修改 SKILL.md 本身。