从零开发AI Agent:从选型到部署全流程

作者:快去debug2026.11.17 03:42浏览量:0

简介:本文给出一套可落地的AI Agent开发方法,覆盖统一模型接入、单智能体骨架、结构化输出、工具调用、RAG、记忆、工作流、多智能体协作与FastAPI部署。附代码骨架、排错清单、成本优化与效果评估,帮助开发者降低试错成本,构建稳定可用的智能体应用。

从零开发一个AI Agent,通常可以拆成四件事:选一个模型、给它工具、给它记忆、把它包成服务。下面按真实开发顺序展开,每一步都给出可运行的代码骨架、排错提示和工程建议。

一、第一步不是写代码,而是解决“模型从哪来”

新手最容易卡在模型接入上:不同厂商的SDK、鉴权方式、参数命名各不相同,换一次模型就要重写一遍调用层。更麻烦的是选型:同一个Agent任务,用旗舰模型和用轻量模型,成本、延迟和效果可能差异明显。

建议先把模型层抽象成统一接口。如果使用兼容OpenAI协议的大模型服务或统一API网关,可以在同一套代码里切换不同模型,并基于真实任务做横向评测。选型阶段不必迷信“最强模型”,而应按任务分层:

  • 意图识别、分类、格式转换:优先用轻量模型,降低成本。
  • 复杂推理、长文写作、代码生成:使用能力更强的旗舰模型。
  • 高并发在线问答:关注P95延迟、限流策略和缓存能力。
  • 离线批处理:优先关注单位Token成本。

一个稳妥的原则是:先跑通最小闭环,再做模型分层优化。不要一开始就把所有能力都交给最强模型,否则很容易在后期发现成本不可控。

agent">二、环境搭建与第一个Agent

先创建虚拟环境并安装依赖:

  1. python -m venv .venv && source .venv/bin/activate
  2. pip install openai httpx pydantic python-dotenv

第一个调用示例如下:

  1. import os
  2. from openai import OpenAI
  3. client = OpenAI(
  4. api_key=os.environ["LLM_API_KEY"],
  5. base_url=os.environ.get("LLM_BASE_URL"), # 统一接入层地址
  6. )
  7. def chat(messages, model="your-model", **kw):
  8. try:
  9. resp = client.chat.completions.create(
  10. model=model,
  11. messages=messages,
  12. **kw
  13. )
  14. except Exception as e:
  15. return f"调用失败: {type(e).__name__}: {e}"
  16. # 正确读取 choices[0],并处理空内容
  17. if not resp.choices or not resp.choices[0].message.content:
  18. return ""
  19. return resp.choices[0].message.content
  20. print(chat([{"role": "user", "content": "用一句话解释什么是Agent"}]))

关键点:

  • API Key 只从环境变量读取,不要写进代码或提交到 Git。
  • base_url 抽成配置项,切换模型服务时业务代码零改动。
  • 必须处理 resp.choices 为空、message.content 为空、网络超时、限流等异常情况。
  • 如果返回内容为空,不要继续拼接上下文,否则容易把错误传播到后续步骤。

三、单智能体骨架:Prompt + 结构化输出 + 工具调用

Agent 与普通 Chatbot 的分界线是:能否自主决策并调用工具。一个最小可用的单智能体包含三层。

1. 角色指令:System Prompt

System Prompt 要写清:

  • 身份和任务边界;
  • 可用工具;
  • 输出格式;
  • 失败处理方式;
  • 是否需要引用来源;
  • 是否需要先规划再回答。

例如:

  1. SYSTEM_PROMPT = """你是一个任务规划助手。
  2. 如果任务需要外部信息,必须调用 search_web。
  3. 如果信息不足,不要编造答案。
  4. 最终回答必须简洁、结构化,并标注依据。"""

模糊的“你是一个助手”几乎等于没写。

2. 结构化输出

为了让下游程序稳定解析,建议用 JSON Schema 或 Pydantic 模型约束输出:

  1. from pydantic import BaseModel
  2. class Plan(BaseModel):
  3. steps: list[str]
  4. need_search: bool
  5. try:
  6. completion = client.beta.chat.completions.parse(
  7. model="your-model",
  8. messages=[
  9. {"role": "system", "content": "请把任务拆解成结构化步骤。"},
  10. {"role": "user", "content": "拆解任务:调研2026年RAG优化方案"}
  11. ],
  12. response_format=Plan,
  13. )
  14. parsed = completion.choices[0].message.parsed
  15. except Exception as e:
  16. parsed = None
  17. print("结构化输出失败:", e)
  18. if parsed:
  19. print(parsed.steps, parsed.need_search)

注意:client.beta.chat.completions.parse 依赖较新的 OpenAI SDK、模型能力以及 Pydantic 支持。不同模型服务对 response_format、json_schema、function calling 的兼容程度不同。如果当前模型不支持 parse,可以退化为“普通调用 + JSON 解析 + 校验重试”:

  1. import json
  2. def parse_json_with_retry(text: str, model_cls):
  3. try:
  4. data = json.loads(text)
  5. return model_cls.model_validate(data)
  6. except Exception:
  7. return None

结构化输出的核心不是“让模型说它是 JSON”,而是“确保返回内容能被程序校验”。

3. 工具调用:Function Calling / Tool Use

工具描述写得好不好,直接决定模型调用准确率。一个最小工具定义如下:

  1. tools = [{
  2. "type": "function",
  3. "function": {
  4. "name": "search_web",
  5. "description": "搜索互联网获取实时信息,当问题涉及时效性内容时调用",
  6. "parameters": {
  7. "type": "object",
  8. "properties": {
  9. "query": {"type": "string", "description": "搜索关键词"}
  10. },
  11. "required": ["query"],
  12. },
  13. },
  14. }]

工具循环的标准写法是:

  1. 模型返回 tool_calls;
  2. 本地执行工具;
  3. 把结果作为 role: "tool" 消息回填;
  4. 再次请求模型;
  5. 直到模型给出最终答案。

完整示例:

  1. import json
  2. def execute_tool(name: str, raw_args: str):
  3. args = json.loads(raw_args or "{}")
  4. if name == "search_web":
  5. return {
  6. "query": args.get("query", ""),
  7. "result": "这是搜索结果的占位内容"
  8. }
  9. return {"error": f"未知工具: {name}"}
  10. def run_agent(user_input: str, max_rounds=6):
  11. messages = [
  12. {"role": "system", "content": SYSTEM_PROMPT},
  13. {"role": "user", "content": user_input}
  14. ]
  15. for _ in range(max_rounds):
  16. resp = client.chat.completions.create(
  17. model="your-model",
  18. messages=messages,
  19. tools=tools
  20. )
  21. msg = resp.choices[0].message
  22. messages.append(msg.model_dump())
  23. if not msg.tool_calls:
  24. return msg.content
  25. for call in msg.tool_calls:
  26. result = execute_tool(call.function.name, call.function.arguments)
  27. messages.append({
  28. "role": "tool",
  29. "tool_call_id": call.id,
  30. "content": json.dumps(result, ensure_ascii=False)
  31. })
  32. return "达到最大工具调用轮数,请简化任务或增加预算。"

务必设置最大循环轮数,例如 5~8 轮。否则模型可能反复调用工具,把 Token 消耗完。

rag-agent-">四、RAG知识库:让Agent回答私有数据

RAG 的固定流程是:

  1. 文档解析;
  2. 切分 chunking;
  3. 向量化 embedding;
  4. 存入向量库;
  5. 检索召回后拼进 Prompt。

最小示例如下:

  1. import os
  2. import numpy as np
  3. def embed(text: str):
  4. resp = client.embeddings.create(
  5. model=os.environ.get("EMBEDDING_MODEL", "embedding-model"),
  6. input=text
  7. )
  8. return resp.data[0].embedding
  9. class InMemoryVectorDB:
  10. def __init__(self):
  11. self.docs = []
  12. self.vectors = []
  13. def add(self, text: str, vector):
  14. self.docs.append(text)
  15. self.vectors.append(vector)
  16. def search(self, query_vector, top_k=5):
  17. q = np.array(query_vector)
  18. scores = []
  19. for i, v in enumerate(self.vectors):
  20. v = np.array(v)
  21. denom = (np.linalg.norm(q) * np.linalg.norm(v)) or 1e-8
  22. score = float(np.dot(q, v) / denom)
  23. scores.append((score, i))
  24. scores.sort(reverse=True)
  25. return [
  26. {"text": self.docs[i], "score": score}
  27. for score, i in scores[:top_k]
  28. ]
  29. vector_db = InMemoryVectorDB()
  30. def retrieve(query, top_k=5):
  31. q_emb = embed(query)
  32. hits = vector_db.search(q_emb, top_k=top_k)
  33. return "\n".join(h["text"] for h in hits)
  34. prompt = f"""仅依据以下资料回答,资料不足时明确说明:
  35. ---资料---
  36. {retrieve(user_query)}
  37. ---资料结束---
  38. 问题:{user_query}"""

生产环境建议不要自己从零实现向量检索,可以选择 Chroma、FAISS、pgvector、Milvus 等组件。重点不是组件本身,而是评估链路:

  • 切分是否合理;
  • embedding 模型是否适合领域文本;
  • 召回质量是否足够;
  • 是否需要混合检索;
  • 是否给答案加引用来源。

实践中的效果瓶颈通常不在模型,而在检索质量。三个高性价比优化:

  1. 按语义段落切分,而不是简单按固定字数切分。
  2. 混合检索:先做向量召回,再做关键词重排。
  3. 给召回结果加引用编号,让模型输出时标注来源,便于核查。

五、记忆机制:短期靠上下文,长期靠存储

Agent 的记忆可以分成两类。

短期记忆

短期记忆通常放在 messages 里,但上下文太长会导致成本上升和效果下降。可以保留最近 N 轮,并把更早内容压缩成摘要:

  1. def compress_messages(messages, keep=6):
  2. if len(messages) <= keep:
  3. return messages
  4. old = messages[:-keep]
  5. recent = messages[-keep:]
  6. summary = chat([
  7. {"role": "system", "content": "请压缩历史对话,保留关键结论和用户偏好。"},
  8. {"role": "user", "content": json.dumps(old, ensure_ascii=False)}
  9. ])
  10. return [{"role": "system", "content": f"历史摘要:{summary}"}] + recent

长期记忆

长期记忆可以把用户偏好、历史结论抽取成结构化条目,存入数据库或向量库。最小表结构可以包括:

  1. user_id: 用户标识
  2. memory_type: preference / fact / task / summary
  3. content: 记忆内容
  4. importance: 重要程度
  5. created_at: 写入时间
  6. metadata: 来源、标签等
  7. embedding: 可选向量字段

长期记忆的关键是:不要一上来就做复杂图数据库或自动推理。先用简单的 key-value 或关系表跑通,再考虑向量召回。

六、工作流与多智能体协作

工作流 是用代码把流程写死,路径可预测、成本可控、易调试;自主智能体 让模型自己规划路径,灵活但不稳定。工程上的正确姿势通常是 混合模式:

  • 主干用工作流保证可靠性;
  • 在需要开放探索的节点交给自主规划;
  • 对关键节点增加校验、重试和人工审核。

多智能体协作适合任务能被清晰切分的场景,比如:

  • 研究员;
  • 资料收集员;
  • 写作员;
  • 审校员。

角色之间通过消息传递协作,每个 Agent 只保留自己那部分 Prompt 和工具,上下文更干净、效果更稳。但要警惕:Agent 数量增加会带来调用次数和 Token 消耗的乘数级增长。能用单 Agent 加好工具解决的需求,不要轻易上多 Agent。

七、服务化与部署

用 FastAPI 把 Agent 包成 HTTP 服务,注意流式返回、超时控制和异常关闭。

  1. from fastapi import FastAPI
  2. from pydantic import BaseModel
  3. from fastapi.responses import StreamingResponse
  4. from typing import AsyncGenerator
  5. app = FastAPI()
  6. class ChatRequest(BaseModel):
  7. message: str
  8. session_id: str | None = None
  9. @app.get("/health")
  10. def health():
  11. return {"status": "ok"}
  12. def run_agent(message: str):
  13. # 最小占位实现,实际项目可替换为真实 Agent 主循环
  14. for i in range(3):
  15. yield f"data: {message} chunk {i}\n\n"
  16. @app.post("/agent/chat")
  17. async def agent_chat(req: ChatRequest):
  18. async def event_stream() -> AsyncGenerator[str, None]:
  19. try:
  20. for chunk in run_agent(req.message):
  21. yield chunk
  22. except Exception as e:
  23. yield f"data: [ERROR] {type(e).__name__}: {e}\n\n"
  24. finally:
  25. yield "data: [DONE]\n\n"
  26. return StreamingResponse(
  27. event_stream(),
  28. media_type="text/event-stream",
  29. headers={
  30. "Cache-Control": "no-cache",
  31. "X-Accel-Buffering": "no"
  32. }
  33. )

服务化需要注意:

  • SSE 流式返回要处理客户端断开;
  • 上游模型调用要设置超时;
  • 对长输出设置最大 Token 或最大字符数;
  • 对外接口要限流,避免被恶意调用;
  • 密钥通过环境变量、密钥管理服务或容器 secret 注入;
  • 多用户场景要做数据隔离,避免不同用户上下文串线。

Docker 部署可以采用如下 Dockerfile:

  1. FROM python:3.11-slim
  2. WORKDIR /app
  3. COPY requirements.txt .
  4. RUN pip install --no-cache-dir -r requirements.txt
  5. COPY . .
  6. EXPOSE 8000
  7. HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  8. CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
  9. CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

生产环境还建议加入:

  • 多阶段构建,减小镜像体积;
  • 结构化日志;
  • 按用户配额;
  • 接口限流;
  • 输入内容安全过滤;
  • 敏感数据脱敏。

八、成本与稳定性优化清单

问题 处理方式
Token成本过高 分层选模型;缓存高频问答;压缩历史上下文
工具调用不准 优化工具description;减少工具数量;增加示例
输出格式不稳定 用JSON Schema约束 + 校验失败自动重试
响应慢 开启流式输出;并行调用独立工具
效果难评估 建20~50条固定测试集,每次改动跑回归
成本对比失真 标注模型版本、输入输出Token、缓存命中率、并发量

成本归因不要只看账单总额,建议至少记录:

  • 模型名称与版本;
  • 输入 Token;
  • 输出 Token;
  • 工具调用次数;
  • 缓存命中率;
  • 平均上下文长度;
  • 重试次数;
  • 并发量;
  • P50 / P95 / P99 延迟;
  • 单任务成本。

只有在效果达标的前提下,才可以选择更经济的模型组合。否则单纯追求低成本,会牺牲最终体验。

九、FAQ:常见问题快速排查

1. 怎么选模型?

先做小规模评测。把任务分成简单任务、中等任务和复杂任务:

  • 简单任务用轻量模型;
  • 复杂任务用旗舰模型;
  • 对延迟敏感的任务,优先测试轻量模型和小模型;
  • 对质量要求高的任务,再引入强模型或人工复核。

2. 工具调用不准怎么办?

可以从四个方面优化:

  • 把工具描述写得更具体;
  • 减少工具数量;
  • 增加调用示例;
  • 对工具参数做严格校验,并在失败时让模型重试。

3. RAG效果差如何定位?

把链路拆开评估:

  • 检索阶段:召回是否命中正确文档;
  • 生成阶段:模型是否基于资料回答;
  • 引用阶段:答案是否能对应来源;
  • 切分阶段:是否把关键段落切断。

如果召回错误,优化切分、embedding 或混合检索;如果召回正确但回答错误,优化 Prompt 和引用约束。

4. 如何评估Agent效果?

建议建立固定测试集,每次改动跑回归。常见指标包括:

  • 任务完成率;
  • 格式合规率;
  • 工具调用准确率;
  • 引用准确率;
  • 平均响应时间;
  • P95延迟;
  • 单任务Token成本;
  • 用户满意度。

5. 什么时候需要多智能体?

当任务可以清晰拆分成多个角色,并且单 Agent 加工具无法稳定完成时,再考虑多智能体。否则优先考虑:更好的工具、更清晰的流程、更完整的测试集。

十、开发顺序建议

推荐顺序如下:

  1. 统一模型接入层;
  2. 单 Agent + 工具调用;
  3. RAG 知识库;
  4. 短期与长期记忆;
  5. 工作流编排;
  6. FastAPI 服务化;
  7. Docker 部署;
  8. 多智能体协作。

每一步都跑通测试再往下走,比一次性堆完所有模块再调试效率高得多。AI Agent 的核心不是堆概念,而是把模型、工具、记忆和流程组合成一个可验证、可观测、可维护的系统。