简介:本文给出一套可落地的AI Agent开发方法,覆盖统一模型接入、单智能体骨架、结构化输出、工具调用、RAG、记忆、工作流、多智能体协作与FastAPI部署。附代码骨架、排错清单、成本优化与效果评估,帮助开发者降低试错成本,构建稳定可用的智能体应用。
从零开发一个AI Agent,通常可以拆成四件事:选一个模型、给它工具、给它记忆、把它包成服务。下面按真实开发顺序展开,每一步都给出可运行的代码骨架、排错提示和工程建议。
新手最容易卡在模型接入上:不同厂商的SDK、鉴权方式、参数命名各不相同,换一次模型就要重写一遍调用层。更麻烦的是选型:同一个Agent任务,用旗舰模型和用轻量模型,成本、延迟和效果可能差异明显。
建议先把模型层抽象成统一接口。如果使用兼容OpenAI协议的大模型服务或统一API网关,可以在同一套代码里切换不同模型,并基于真实任务做横向评测。选型阶段不必迷信“最强模型”,而应按任务分层:
一个稳妥的原则是:先跑通最小闭环,再做模型分层优化。不要一开始就把所有能力都交给最强模型,否则很容易在后期发现成本不可控。
先创建虚拟环境并安装依赖:
python -m venv .venv && source .venv/bin/activatepip install openai httpx pydantic python-dotenv
第一个调用示例如下:
import osfrom openai import OpenAIclient = OpenAI(api_key=os.environ["LLM_API_KEY"],base_url=os.environ.get("LLM_BASE_URL"), # 统一接入层地址)def chat(messages, model="your-model", **kw):try:resp = client.chat.completions.create(model=model,messages=messages,**kw)except Exception as e:return f"调用失败: {type(e).__name__}: {e}"# 正确读取 choices[0],并处理空内容if not resp.choices or not resp.choices[0].message.content:return ""return resp.choices[0].message.contentprint(chat([{"role": "user", "content": "用一句话解释什么是Agent"}]))
关键点:
base_url 抽成配置项,切换模型服务时业务代码零改动。resp.choices 为空、message.content 为空、网络超时、限流等异常情况。Agent 与普通 Chatbot 的分界线是:能否自主决策并调用工具。一个最小可用的单智能体包含三层。
System Prompt 要写清:
例如:
SYSTEM_PROMPT = """你是一个任务规划助手。如果任务需要外部信息,必须调用 search_web。如果信息不足,不要编造答案。最终回答必须简洁、结构化,并标注依据。"""
模糊的“你是一个助手”几乎等于没写。
为了让下游程序稳定解析,建议用 JSON Schema 或 Pydantic 模型约束输出:
from pydantic import BaseModelclass Plan(BaseModel):steps: list[str]need_search: booltry:completion = client.beta.chat.completions.parse(model="your-model",messages=[{"role": "system", "content": "请把任务拆解成结构化步骤。"},{"role": "user", "content": "拆解任务:调研2026年RAG优化方案"}],response_format=Plan,)parsed = completion.choices[0].message.parsedexcept Exception as e:parsed = Noneprint("结构化输出失败:", e)if parsed:print(parsed.steps, parsed.need_search)
注意:client.beta.chat.completions.parse 依赖较新的 OpenAI SDK、模型能力以及 Pydantic 支持。不同模型服务对 response_format、json_schema、function calling 的兼容程度不同。如果当前模型不支持 parse,可以退化为“普通调用 + JSON 解析 + 校验重试”:
import jsondef parse_json_with_retry(text: str, model_cls):try:data = json.loads(text)return model_cls.model_validate(data)except Exception:return None
结构化输出的核心不是“让模型说它是 JSON”,而是“确保返回内容能被程序校验”。
工具描述写得好不好,直接决定模型调用准确率。一个最小工具定义如下:
tools = [{"type": "function","function": {"name": "search_web","description": "搜索互联网获取实时信息,当问题涉及时效性内容时调用","parameters": {"type": "object","properties": {"query": {"type": "string", "description": "搜索关键词"}},"required": ["query"],},},}]
工具循环的标准写法是:
tool_calls;role: "tool" 消息回填;完整示例:
import jsondef execute_tool(name: str, raw_args: str):args = json.loads(raw_args or "{}")if name == "search_web":return {"query": args.get("query", ""),"result": "这是搜索结果的占位内容"}return {"error": f"未知工具: {name}"}def run_agent(user_input: str, max_rounds=6):messages = [{"role": "system", "content": SYSTEM_PROMPT},{"role": "user", "content": user_input}]for _ in range(max_rounds):resp = client.chat.completions.create(model="your-model",messages=messages,tools=tools)msg = resp.choices[0].messagemessages.append(msg.model_dump())if not msg.tool_calls:return msg.contentfor call in msg.tool_calls:result = execute_tool(call.function.name, call.function.arguments)messages.append({"role": "tool","tool_call_id": call.id,"content": json.dumps(result, ensure_ascii=False)})return "达到最大工具调用轮数,请简化任务或增加预算。"
务必设置最大循环轮数,例如 5~8 轮。否则模型可能反复调用工具,把 Token 消耗完。
RAG 的固定流程是:
最小示例如下:
import osimport numpy as npdef embed(text: str):resp = client.embeddings.create(model=os.environ.get("EMBEDDING_MODEL", "embedding-model"),input=text)return resp.data[0].embeddingclass InMemoryVectorDB:def __init__(self):self.docs = []self.vectors = []def add(self, text: str, vector):self.docs.append(text)self.vectors.append(vector)def search(self, query_vector, top_k=5):q = np.array(query_vector)scores = []for i, v in enumerate(self.vectors):v = np.array(v)denom = (np.linalg.norm(q) * np.linalg.norm(v)) or 1e-8score = float(np.dot(q, v) / denom)scores.append((score, i))scores.sort(reverse=True)return [{"text": self.docs[i], "score": score}for score, i in scores[:top_k]]vector_db = InMemoryVectorDB()def retrieve(query, top_k=5):q_emb = embed(query)hits = vector_db.search(q_emb, top_k=top_k)return "\n".join(h["text"] for h in hits)prompt = f"""仅依据以下资料回答,资料不足时明确说明:---资料---{retrieve(user_query)}---资料结束---问题:{user_query}"""
生产环境建议不要自己从零实现向量检索,可以选择 Chroma、FAISS、pgvector、Milvus 等组件。重点不是组件本身,而是评估链路:
实践中的效果瓶颈通常不在模型,而在检索质量。三个高性价比优化:
Agent 的记忆可以分成两类。
短期记忆通常放在 messages 里,但上下文太长会导致成本上升和效果下降。可以保留最近 N 轮,并把更早内容压缩成摘要:
def compress_messages(messages, keep=6):if len(messages) <= keep:return messagesold = messages[:-keep]recent = messages[-keep:]summary = chat([{"role": "system", "content": "请压缩历史对话,保留关键结论和用户偏好。"},{"role": "user", "content": json.dumps(old, ensure_ascii=False)}])return [{"role": "system", "content": f"历史摘要:{summary}"}] + recent
长期记忆可以把用户偏好、历史结论抽取成结构化条目,存入数据库或向量库。最小表结构可以包括:
user_id: 用户标识memory_type: preference / fact / task / summarycontent: 记忆内容importance: 重要程度created_at: 写入时间metadata: 来源、标签等embedding: 可选向量字段
长期记忆的关键是:不要一上来就做复杂图数据库或自动推理。先用简单的 key-value 或关系表跑通,再考虑向量召回。
工作流 是用代码把流程写死,路径可预测、成本可控、易调试;自主智能体 让模型自己规划路径,灵活但不稳定。工程上的正确姿势通常是 混合模式:
多智能体协作适合任务能被清晰切分的场景,比如:
角色之间通过消息传递协作,每个 Agent 只保留自己那部分 Prompt 和工具,上下文更干净、效果更稳。但要警惕:Agent 数量增加会带来调用次数和 Token 消耗的乘数级增长。能用单 Agent 加好工具解决的需求,不要轻易上多 Agent。
用 FastAPI 把 Agent 包成 HTTP 服务,注意流式返回、超时控制和异常关闭。
from fastapi import FastAPIfrom pydantic import BaseModelfrom fastapi.responses import StreamingResponsefrom typing import AsyncGeneratorapp = FastAPI()class ChatRequest(BaseModel):message: strsession_id: str | None = None@app.get("/health")def health():return {"status": "ok"}def run_agent(message: str):# 最小占位实现,实际项目可替换为真实 Agent 主循环for i in range(3):yield f"data: {message} chunk {i}\n\n"@app.post("/agent/chat")async def agent_chat(req: ChatRequest):async def event_stream() -> AsyncGenerator[str, None]:try:for chunk in run_agent(req.message):yield chunkexcept Exception as e:yield f"data: [ERROR] {type(e).__name__}: {e}\n\n"finally:yield "data: [DONE]\n\n"return StreamingResponse(event_stream(),media_type="text/event-stream",headers={"Cache-Control": "no-cache","X-Accel-Buffering": "no"})
服务化需要注意:
Docker 部署可以采用如下 Dockerfile:
FROM python:3.11-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY . .EXPOSE 8000HEALTHCHECK --interval=30s --timeout=5s --retries=3 \CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
生产环境还建议加入:
| 问题 | 处理方式 |
|---|---|
| Token成本过高 | 分层选模型;缓存高频问答;压缩历史上下文 |
| 工具调用不准 | 优化工具description;减少工具数量;增加示例 |
| 输出格式不稳定 | 用JSON Schema约束 + 校验失败自动重试 |
| 响应慢 | 开启流式输出;并行调用独立工具 |
| 效果难评估 | 建20~50条固定测试集,每次改动跑回归 |
| 成本对比失真 | 标注模型版本、输入输出Token、缓存命中率、并发量 |
成本归因不要只看账单总额,建议至少记录:
只有在效果达标的前提下,才可以选择更经济的模型组合。否则单纯追求低成本,会牺牲最终体验。
先做小规模评测。把任务分成简单任务、中等任务和复杂任务:
可以从四个方面优化:
把链路拆开评估:
如果召回错误,优化切分、embedding 或混合检索;如果召回正确但回答错误,优化 Prompt 和引用约束。
建议建立固定测试集,每次改动跑回归。常见指标包括:
当任务可以清晰拆分成多个角色,并且单 Agent 加工具无法稳定完成时,再考虑多智能体。否则优先考虑:更好的工具、更清晰的流程、更完整的测试集。
推荐顺序如下:
每一步都跑通测试再往下走,比一次性堆完所有模块再调试效率高得多。AI Agent 的核心不是堆概念,而是把模型、工具、记忆和流程组合成一个可验证、可观测、可维护的系统。