通用 AI Agent 开发步骤

第一阶段：确定 Agent 的定位

第 1 步：定义能力边界

先搞清楚 Agent 要做什么、不做什么。比如：

它能不能访问外部数据？（数据库、文件、API）
它能不能执行写操作？（下单、发邮件、改配置）
它需要什么专业知识？（行业文档、产品手册）

这一步输出一张工具清单，每个工具一行：工具名、功能、入参、出参、触发条件。

第二阶段：选型与技术栈搭建

第 2 步：选大模型

三种路线：

路线	适合场景	例子
闭源 API	追求效果，有预算	GPT-4o、Claude、通义千问
本地开源模型	数据敏感，延迟敏感	Qwen2.5、LLaMA 3
OpenAI 兼容代理	灵活切换	vLLM、Ollama 起的服务

关键：一开始就把模型接入层抽象出来（工厂模式），后面换模型不改业务代码。

第 3 步：选 Agent 框架

LangChain + LangGraph --- 功能最全，生态最大，但 API 变来变去
Semantic Kernel（微软）--- .NET/Java/Python 统一，企业级
AutoGen（微软）--- 多 Agent 对话场景
手写 --- 一个 while 循环就能跑 ReAct，控制力最强

选框架的原则：看文档质量和社区活跃度，不要被 demo 吸引。

第 4 步：选技术组件

组件	选项	选型依据
向量数据库	Chroma / Pinecone / Milvus / Weaviate	数据量小的原型用 Chroma，生产用 Milvus
嵌入模型	text-embedding-3-small / bge-large / text-embedding-v4	和 LLM 同生态最好
文档加载	LangChain Document Loaders	PDF、HTML、数据库、GitHub 都有人写过
文本分块	RecursiveCharacterTextSplitter / Semantic Splitter	简单用按字符，高质量用按语义
配置管理	YAML / .env	YAML 管业务参数，.env 管密钥
日志	Python logging	记录每个工具调用和模型输出

第三阶段：核心开发

第 5 步：写 Prompt（最重要的一步）

一个 Agent 的 Prompt 通常包含这几块：

复制代码

1. 角色定义 --- 你是谁、能做什么
2. 思维链规则 --- 怎么思考、什么时候调工具
3. 工具说明 --- 每个工具什么时候用、怎么传参
4. 输出约束 --- 格式要求、禁区
5. 边界说明 --- 不知道就说不知道

写好 Prompt 的判断标准：删掉所有示例后，模型还能稳定执行正确的工具调用。依赖示例才能跑的 Prompt 换个场景就崩。

第 6 步：注册工具

每个工具三件事：

写函数体（逻辑要简单）
写 description（模型靠这个决定什么时候调你）
定义参数（类型、格式约束）

工具设计的经验：每个工具只做一件事，把多个步骤串起来的逻辑交给 Agent 自己规划，不要在工具内部写 if-else。

第 7 步：实现 Agent 循环

标准 ReAct 循环：

复制代码

循环开始:
  1. 系统 Prompt + 对话历史 → 模型
  2. 模型输出:
     a. 如果输出"思考" → 决定调什么工具
     b. 如果输出工具调用 → 执行工具 → 观察结果 → 回到 1
     c. 如果输出最终回答 → 返回给用户
  3. 达到最大轮数或遇到错误 → 兜底回复

第 8 步：加入中间件（可选）

中间件是在 Agent 执行流程中插入的自定义逻辑，典型用途：

每次调工具前记录日志
每次调模型前检查上下文
根据场景动态切换 Prompt
超时控制、错误重试

中间件的好处是不污染核心循环代码。

第四阶段：RAG（检索增强生成）

第 9 步：搭建知识库管线

复制代码

知识库文件 → 加载 → 分块 → 向量化 → 存入向量库
                     ↓
用户问题 → 向量检索 → 获取相关文档 → 拼入 Prompt → 模型回答

容易踩的坑：

分块太大 ：模型上下文窗口不够；太小：信息碎片化。一般 200-500 token 起步。
只用向量检索不够：关键文档可以用 BM25（关键词搜索）+ 向量检索混合，取交集。
检索结果不做排序：top-k 里可能混进无关内容，需要重排序（reranker）。

第五阶段：UI 与部署

第 10 步：搭界面

别在界面上花太多时间。原型阶段的目标是能看能聊，不是好看。

个人用：Streamlit / Gradio --- 几行代码出对话界面
生产用：React + FastAPI 后端

第 11 步：流式输出

必须做。用户等不了模型想完再看到全部文字。流式输出把"正在打字"的效果给用户，体验好得多。

第四阶段（实际是迭代过程）：Prompt 迭代

贯穿始终：写 Prompt → 跑测试 → 发现问题 → 改 Prompt 或工具描述 → 再跑。

常见问题和解法：

现象	原因	修法
模型不调工具	工具描述不够具体	明确写"什么时候调、传什么参"
模型乱调工具	工具描述有歧义	缩小 scope，或者加约束
模型编造答案	检索内容不够	加大 k 值，或者改 Prompt 强调"不知道就说不知道"
模型忘记之前调过什么	对话历史被截断	增大上下文窗口，或者用摘要压缩历史