从零基础到能落地一个 Agent：12 步手把手，每一步都附权威论文与官方规范、可复制代码、预期结果和自测清单
由 网络精灵 整理 · 2026-08-24 · AI 导航原创教程 · 参考 ReAct / RAG / Toolformer / Reflexion / AutoGen / AgentBench / OWASP LLM Top10 等
保姆级第一眼：Agent 不是"一问一答"，而是一个不断转圈的循环。把下图刻进脑子，后面 12 步全是在强化这个环里的某一格。
本教程所有代码用 Python 3.10+，模型以 OpenAI 兼容接口为例（DeepSeek / 硅基流动 / 智谱都兼容同一套调用方式）。
# 确认 Python 版本
python --version
# 建个虚拟环境（推荐，避免污染全局）
python -m venv agent-env
# Windows 激活：
agent-env\Scripts\activate
# macOS / Linux 激活：
source agent-env/bin/activate
# 装常用库
pip install openai langchain langchain-community chromadb# 把 Key 放进环境变量（每次开终端先 export）
export OPENAI_API_KEY="sk-你的key"
# 用兼容端点（如 DeepSeek）时额外指定 base_url
export OPENAI_BASE_URL="https://api.deepseek.com/v1".env + python-dotenv，并把 .env 加入 .gitignore。from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("OPENAI_API_KEY"),
base_url=os.getenv("OPENAI_BASE_URL"), # 兼容端点，可留空用官方
)
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "用一句话解释什么是 AI Agent"}],
)
print(resp.choices[0].message.content)普通聊天：你问 → 它答 → 结束（单次映射）。
Agent：你给目标 → 它规划 → 调工具 → 看结果 → 再规划 → … → 目标达成（循环）。
记三个词就够了：规划（想下一步）、记忆（记得上下文）、工具（能干实事）。
# 给模型一个会"自己决定要不要查"的设定，看它如何分步回答
prompt = "北京今天适合穿什么？如果你不知道天气，请说'我需要查天气工具'"
# 直接问 LLM（没接工具）→ 它大概率会说"我需要查天气工具"
# 这就是 Agent 的起点：知道自己"能力边界"拿"帮我总结本周团队群消息并写一封周报邮件"练手，把它拆成 Agent 能执行的步骤：
from openai import OpenAI
import os, json
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL"))
sys = """你是任务拆解器。用户输入一句话目标，你输出 JSON：
{"steps": ["步骤1","步骤2",...], "need_tool": true/false}
只输出 JSON，不要解释。"""
user = "查北京天气并邮件发给我"
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role":"system","content":sys},{"role":"user","content":user}],
response_format={"type":"json_object"}, # 强制 JSON 输出
)
data = json.loads(resp.choices[0].message.content)
print(data){"steps":["查北京天气","起草邮件","发送"],"need_tool":true}。这就是 Agent 后续做"要不要调工具"判断的数据来源。response_format=json_object 或 function calling 约束，比靠 prompt 说"只输出 JSON"更稳。from langchain_community.vectorstores import Chroma
from langchain.text_splitter import RecursiveCharacterTextSplitter
# 1) 切片：把文档切成 300 字左右的小块
text = open("产品手册.txt", encoding="utf-8").read()
chunks = RecursiveCharacterTextSplitter(chunk_size=300, chunk_overlap=30).split_text(text)
# 2) 向量化并入库
# 中文推荐本地 BGE（首次自动下载，离线可用，无需任何 Key/联网）
from langchain_community.embeddings import HuggingFaceEmbeddings
embed = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5")
# 若改用 OpenAI embedding（需 OPENAI_API_KEY，与它用的是哪个 base_url 无关）：
# from langchain_community.embeddings import OpenAIEmbeddings
# embed = OpenAIEmbeddings()
vec = Chroma.from_texts(chunks, embed, persist_directory="./db")
# 3) 检索：问一个问题，取最相关的 3 块
hits = vec.similarity_search("如何重置密码？", k=3)
context = "\n---\n".join(h["page_content"] for h in hits)
# 4) 拼进 prompt 让 LLM 回答（此处省略 chat 调用，同第3步）
print("喂给模型的资料：\n", context)tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询某城市当前天气",
"parameters": {
"type": "object",
"properties": {"city": {"type":"string","description":"城市名，如 北京"}},
"required": ["city"]
}
}
}]
# 让模型决定要不要调工具
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role":"user","content":"北京今天天气怎么样？"}],
tools=tools,
)
msg = resp.choices[0].message
if msg.tool_calls:
print("模型要调工具：", msg.tool_calls[0].function.name, msg.tool_calls[0].function.arguments)
# 这里你真实执行 get_weather(city)，再把结果填回对话，让模型继续tool_calls，指明要调 get_weather 并带参数 {"city":"北京"}。你的程序执行后把结果回填，模型据此生成最终回答——这就是 Agent "动手"的最小闭环。企业微信、GitHub、Slack 等做成 MCP Server 后，dsh / Claude / Codex 等任意支持 MCP 的 Agent 都能零适配调用，工具名形如 mcp__wecom__send_message。详见 企业微信 × dsh 实战。
| 模式 | 提出 | 适用 | 风险 |
|---|---|---|---|
| ReAct | Yao 2022 | 探索型、工具密集 | 易空转，需 max_steps |
| Plan-and-Solve | Wang 2023 | 多步明确任务 | 计划僵化难应变 |
| Reflexion | Shinn 2023 | 需高质量产出 | 多一轮调用增成本 |
# 伪代码：生成答案后，让模型自我检查
draft = llm("写一段产品介绍：" + topic)
review = llm(f"检查下面这段文字有无事实错误/语气问题，给出修改建议：\n{draft}")
final = llm(f"根据修改建议重写：\n{draft}\n建议：{review}")
# 这就是 Reflexion 的极简版：生成 → 反思 → 修订| 角色 | 职责 |
|---|---|
| Planner 主管 | 拆解任务、分发、汇总 |
| Researcher | 查资料 / RAG 检索 |
| Writer | 起草内容 |
| Critic | 审查、提修改意见 |
| Executor | 调工具执行 |
# 评测集示例（questions.json）
[
{"q":"查北京天气并邮件发我","expect_tool":"get_weather"},
{"q":"我们的退款政策是什么","expect_src":"退款政策.txt"},
{"q":"随便写首诗","expect_tool":null}
]
# 跑 Agent，对比实际输出与 expect，统计：
# 任务完成率 / 工具准确率 / 幻觉率 / 平均步数 / 成本| 风险 | 标准 | 对策 |
|---|---|---|
| 提示注入 | LLM01 | 输入隔离、工具描述不信任用户文本 |
| 权限过大 | LLM06 | 最小权限 + 关键动作人工确认 |
| 数据泄露 | LLM02 | 输出过滤、脱敏、Key 走环境变量 |
# app.py
from fastapi import FastAPI
from openai import OpenAI
import os
app = FastAPI()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL"))
@app.post("/agent")
def run_agent(goal: str):
# 这里放你的 Agent 循环逻辑（规划→工具→反思）
resp = client.chat.completions.create(model="deepseek-chat", messages=[{"role":"user","content":goal}])
return {"result": resp.choices[0].message.content}
# 启动：uvicorn app:app --host 0.0.0.0 --port 8000# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn","app:app","--host","0.0.0.0","--port","8000"]# requirements.txt（Dockerfile 里 pip install -r 需要它）
fastapi
uvicorn[standard]
openaidocker build -t myagent . && docker run -p 8000:8000 myagent 后，POST /agent 即可调用。会话状态用 thread_id 存 Redis，服务本身无状态便于扩缩。| 论文 | 作者 / 年 | 贡献 |
|---|---|---|
| Retrieval-Augmented Generation (RAG) | Lewis et al., 2020 | RAG 原论文 |
| ReAct | Yao et al., 2022 | 推理+行动交错 |
| Chain-of-Thought | Wei et al., 2022 | 思维链 |
| Tree of Thoughts | Yao et al., 2023 | 树状推理+回溯 |
| Reflexion | Shinn et al., 2023 | 语言自我反思 |
| Generative Agents | Park et al., 2023 | 社会性智能体 |
| AgentBench | Liu et al., 2023 | Agent 基准 |
| LLM-as-a-Judge | Zheng et al., 2023 | LLM 当裁判 |
| 资源 | 域名 |
|---|---|
| MCP 规范 | modelcontextprotocol.io |
| OpenAI 文档（Function Calling / Prompt） | platform.openai.com/docs |
| Anthropic 文档（Tool Use / Prompt） | docs.anthropic.com |
| LangChain / LangGraph | docs.langchain.com |
| AutoGen | github.com/microsoft/autogen |
| Agent 综述（Lilian Weng） | lilianweng.github.io |
| LLM 安全标准 | owasp.org（LLM Top 10） |