# Agent Builder

> 指导从零搭建 AI 智能体，涵盖架构设计、提示词工程、工具集成、记忆与评估。当用户需要构建 Agent、设计多智能体系统、选型技术栈或排查智能体行为问题时调用。

- **Type:** Skill
- **Install:** `agentstack add skill-like041123-agent-builder-skill-agent-builder-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [like041123](https://agentstack.voostack.com/s/like041123)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [like041123](https://github.com/like041123)
- **Source:** https://github.com/like041123/agent-builder-skill

## Install

```sh
agentstack add skill-like041123-agent-builder-skill-agent-builder-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 智能体搭建

## 这是关于什么的

把一个 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](https://github.com/like041123)
- **Source:** [like041123/agent-builder-skill](https://github.com/like041123/agent-builder-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-like041123-agent-builder-skill-agent-builder-skill
- Seller: https://agentstack.voostack.com/s/like041123
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.