Agent Builder

智能体搭建

这是关于什么的

把一个 AI Agent 从想法跑到上线，中间要做的决策很多：用什么架构、提示词怎么写、工具怎么接、记忆怎么管、怎么测、怎么部署。这个技能把这些决策点整理成一套可执行的方法论。

不绑定具体框架。无论 LangChain、LangGraph、CrewAI、AutoGen、自研，还是平台原生 Agent 能力，架构层面的思考是通用的。架构模式选型看 references/architecture-patterns.md，分阶段流程和检查清单看 references/build-workflow.md，技术栈横向对比看 references/tech-stack.md。

五组件模型

一个完整的智能体由五个核心组件构成，缺一不可：

| 组件 | 职责 | 设计要点 | |------|------|---------| | 感知 | 接收用户输入、环境状态、工具返回 | 输入归一化、上下文窗口管理 | | 规划 | 任务分解、推理决策、步骤编排 | ReAct / Plan-and-Execute / Reflection | | 记忆 | 短期对话历史 + 长期知识检索 | 滑动窗口、摘要压缩、向量检索 | | 工具 | 调用外部 API、数据库、代码执行 | 工具描述、参数校验、错误处理 | | 行动 | 执行工具调用并返回结果 | 结果解析、失败重试、兜底策略 |

六阶段搭建流程

第一步：把需求想清楚

太多 Agent 项目死在需求没想清楚就开始写代码。先回答这些问题，形成一份需求规格：

• 目标：一句话说清这个 Agent 解决什么问题
• 输入输出：用户给什么形态的输入，期望拿到什么形态的输出
• 自主度：Fully Autonomous / Human-in-the-loop / Hybrid
• 失败容忍度：错误率上限、最大成本和调用次数
• 合规边界：哪些动作不能做、哪些需要人工确认

第二步：选架构

按任务复杂度选，不要过度设计：

| 任务特征 | 推荐 | |---------|------| | 单步工具调用 | Tool-Calling Agent | | 多步推理加工具 | ReAct | | 复杂任务分解 | Plan-and-Execute | | 多角色协作 | Multi-Agent | | 长期自治任务 | Autonomous Loop |

详细的选型决策树和混合架构建议在 references/architecture-patterns.md。

第三步：写提示词

系统提示词按这个顺序组织，别乱放：

1. 角色定义（你是谁、擅长什么）
2. 目标约束（要完成什么、不能做什么）
3. 工具说明（可用工具清单、什么时候用、什么时候不用）
4. 推理规范（何时思考、何时行动、何时求助）
5. 输出格式（响应结构、字段定义）
6. 安全边界（禁止行为、敏感操作确认）
7. Few-shot 示例（2-3 个典型输入输出）

几个要点：工具描述要写清"何时用"而非仅"是什么"；用否定式明确边界；复杂决策给决策树不给模糊指令；示例覆盖正常路径和边界情况。

第四步：接工具

工具定义规范：

• 名字用动词加名词，语义清晰（search_docs 而非 tool1）
• 描述说明功能加适用场景加不适用场景
• 参数用 JSON Schema，含类型、必填、枚举、范围
• 返回结构化格式，含成功标志和错误信息

几个容易忽略的点：工具粒度要单一职责，别搞万能工具；错误要返回结构化错误而非抛异常，让 Agent 决策重试或换路；写操作工具要支持幂等或提供取消机制；只读和写操作要标注清楚，写操作需人工确认。

第五步：管记忆

• 短期记忆：对话历史用滑动窗口（保留最近 N 轮）加早期摘要
• 长期记忆：向量数据库存储，按语义检索（Chroma / Pinecone / Weaviate）
• 工作记忆：当前任务状态、中间结果、待办事项
• 压缩策略：上下文超阈值时触发摘要，保留关键事实和决策

第六步：测、评估、部署

测试要分三层：每个工具独立单元测试；端到端集成测试覆盖正常、边界、异常路径；评估指标看任务成功率、平均步数、工具调用准确率、成本、幻觉率。

部署前检查清单：单元测试通过率 100%、集成测试通过率 ≥ 90%、评估指标达标、日志完整、监控告警就位、熔断机制配置（最大步数、成本上限）、回滚方案就绪、灰度发布计划制定。

监控看板要点：实时看任务成功率、平均延迟、并发数；日级看总任务数、总成本、Top 失败原因；周级看指标趋势、用户满意度、成本环比。告警阈值：失败率 > 15%、成本超预算、延迟超上限 2 倍。

五个设计原则

最小自主性原则：不要追求"全自动"而忽视可控性。从 Human-in-the-loop 起步，逐步放权。高风险动作（删除、支付、发布）始终需人工确认。

工具优先于推理：能用工具确定的事实，不要让模型推理。工具返回的事实比模型生成的更可靠，且可追溯。

显式优于隐式：推理过程显式化（如 ReAct 的 Thought 步骤），便于调试与人类审查。避免黑盒决策。

失败优雅降级：工具失败重试 N 次换工具再告知用户求助；规划失败重新规划降级为单步模式返回部分结果；绝不让 Agent 陷入无限循环，设置最大步数与超时。

成本意识：每多一个工具调用都增加延迟与成本。评估是否真的需要多步推理，简单任务用单次 LLM 调用即可。

常见陷阱和对策

| 陷阱 | 现象 | 对策 | |------|------|------| | 工具过载 | Agent 选错工具或不用工具 | 工具数 ≤ 7，描述写清适用场景 | | 推理循环 | 反复思考不行动 | 设置最大步数，强制转入行动 | | 幻觉工具结果 | 编造工具返回值 | 强制工具调用真实执行，校验返回格式 | | 上下文爆炸 | 历史过长导致遗忘或报错 | 滑动窗口 + 摘要压缩 + 向量检索 | | 过度规划 | 计划过细无法执行 | 限制计划层级 ≤ 3 层，粗计划 + 细执行 | | 多 Agent 失控 | 角色边界混乱 | 明确分工契约，引入协调 Agent |

什么时候用这个技能

• 用户要从零搭一个 AI Agent
• 在 ReAct、Plan-and-Execute、Multi-Agent 这些模式间犹豫不决
• 需要设计系统提示、定义工具集、配置记忆
• 已搭的 Agent 出现幻觉、循环、工具误用，要排查
• 要设计多个 Agent 的分工和通信
• 要对 Agent 做测试、评估、上线

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: like041123
• Source: like041123/agent-builder-skill
• License: MIT

Install and usage instructions live in the source repository linked above.