从 0 到 1 构建 AI Agent：架构、代码与工程实践
AI Agent 是能够自主感知环境、调用工具、循环推理并完成复杂目标的 AI 系统。与单次问答的大模型不同，Agent 具备"思考→行动→观察→再思考"的闭环能力，可以分解多步任务、跨工具协作、持久记忆上下文。本文从核心架构出发，覆盖最小可运行实现、工具定义、记忆管理、框架选型到多 Agent 协作，帮助开发者建立完整的 Agent 构建认知体系。 AI Agent 是以大语言模型（LLM）为核心推理引擎，配备感知输入、规划决策、记忆存储、工具执行四大能力模块的自主 AI 系统。 与普通 LLM 调用的核心区别： OpenAI 在 2025 年发布的 Agents SDK 将其定位描述为："配备指令和工具的 LLM，能通过内置 Agent 循环自动处理工具调用和持续迭代。" 构建一个完整的 Agent，需要理解四个基础模块： Agent 接收外部输入的能力。输入可以是文本、图像、文件、API 返回值、用户指令等。现代多模态模型（GPT-4o、Claude 3.5、Gemini 1.5）已支持文本+图像联合感知。 Agent 分解目标、制定行动计划的推理机制。主流方法： Agent 存储和检索信息的机制： Agent 调用外部能力的接口。本质是将 Python 函数暴露给 LLM，LLM 决定何时调用、传什么参数。常见工具类型：搜索引擎、代码解释器、文件读写、数据库查询、HTTP API 请求。 Agent 的运行遵循一个固定循环，直到任务完成或达到最大步数： 这就是 ReAct 框架的核心。每一轮循环，LLM 接收的 messages 包含：系统提示 + 历史对话 + 所有工具调用记录 + 最新 Observation。 不依赖任何框架，用 Python + OpenAI API 实现一个完整 Agent： 关键设计点： OpenAI Agents SDK 是 Swarm 的生产级升级，2025 年发布，更简洁： SDK 内置了 Agent Loop、自动 Schema 生成、追踪可视化，省去手写循环的工作。 选型建议： 七牛云 AI 推理服务内置的 MCP（Model Context Protocol）支持标准化记忆编排，开发者无需本地部署向量库即可构建带长期记忆的 Agent 应用。 当单个 Agent 能力边界不足以完成复杂任务时，引入多 Agent 协作。主流两种模式： OpenAI Agents SDK 通过 handoffs 机制实现：调度 Agent 在合适时机将控制权移交给专门 Agent，各 Agent 有独立的工具集和系统提示。 每个 Agent 处理一个阶段，输出作为下个 Agent 的输入。适合数据处理、内容生产等有明确顺序的场景。 七牛云 2025 年实践案例中，多智能体采用分层设计：规划层（DeepSeek-R1 擅长推理规划）+ 执行层（DeepSeek-V3 支持函数调用），通过职责分离规避单一模型在推理与工具调用上的能力权衡问题。 Agent 调试的核心难点是"看不见中间过程"，建议从第一行代码就加上追踪： Q：Agent 和 RAG 是什么关系？ Q：构建 Agent 一定要用 GPT-4 吗？成本很高？ Q：Agent 执行过程中出错了怎么办？ Q：Agent 会不会无限循环消耗 Token？ Q：个人开发者适合用 Agent 做什么？ 构建 AI Agent 的核心路径是：理解四大模块（感知/规划/记忆/工具）→ 手写最小 Agent 理解 ReAct 循环 → 选择合适框架上生产 → 逐步扩展工具集和记忆系统。Agent 工程的本质不是框架选择，而是对任务边界的清晰定义和对工具调用失败的鲁棒处理。 延伸资源： 本文内容基于 2026 年 3 月 OpenAI Agents SDK、LangGraph、DeepSeek 最新版本，框架 API 更新较快，建议对照各官方文档最新版本使用。
什么是 AI Agent？
维度 普通 LLM 调用 AI Agent 交互方式 单轮输入→输出 多轮循环，自主决策下一步 工具使用 无 可调用外部 API、代码、数据库 记忆 仅当前上下文窗口 短期 + 长期持久记忆 任务类型 单一问答 多步骤复杂目标分解 自主性 零 可在限定范围内自主行动 Agent 的四大核心模块
1. 感知（Perception）
2. 规划（Planning）
3. 记忆（Memory）
记忆类型 存储位置 特点 实现方式 短期记忆 上下文窗口 会话内可见，重启丢失 messages 列表 长期记忆 外部数据库 跨会话持久，需主动检索 向量数据库（Pinecone、Chroma） 工作记忆 中间变量 任务执行过程中的临时状态 LangGraph State 程序记忆 代码/提示词 固化的行为规则 System Prompt 4. 工具（Tools）
Agent Loop：核心运行机制
用户输入
↓
LLM 推理（输出 Thought + Action 或 Final Answer）
↓
是否调用工具？
├── 是 → 执行工具 → 获取 Observation → 回到 LLM 推理
└── 否 → 输出 Final Answer → 结束最小可运行 Agent（从零手写）
from openai import OpenAI
import json
client = OpenAI(
api_key="你的API_KEY",
base_url="https://api.openai.com/v1" # 或兼容 OpenAI 格式的其他服务地址
)
# ① 定义工具
def get_weather(city: str) -> str:
"""模拟天气查询"""
return f"{city}今天晴，气温 22°C"
def calculate(expression: str) -> str:
"""安全计算数学表达式"""
try:
return str(eval(expression))
except Exception as e:
return f"计算错误: {e}"
# ② 工具注册（生成 JSON Schema，供 LLM 理解）
tools = [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "城市名"}},
"required": ["city"]
}
}
},
{
"type": "function",
"function": {
"name": "calculate",
"description": "计算数学表达式",
"parameters": {
"type": "object",
"properties": {"expression": {"type": "string"}},
"required": ["expression"]
}
}
}
]
# ③ 工具分发映射
tool_map = {"get_weather": get_weather, "calculate": calculate}
# ④ Agent 主循环
def run_agent(user_input: str, max_steps: int = 10):
messages = [
{"role": "system", "content": "你是一个助手，可以查天气和做计算。"},
{"role": "user", "content": user_input}
]
for step in range(max_steps):
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=tools,
tool_choice="auto"
)
msg = response.choices[0].message
# 无工具调用 → 任务完成
if not msg.tool_calls:
print(f"最终回答：{msg.content}")
return msg.content
# 有工具调用 → 执行并回传结果
messages.append(msg)
for tc in msg.tool_calls:
fn_name = tc.function.name
fn_args = json.loads(tc.function.arguments)
result = tool_map[fn_name](**fn_args)
print(f"[工具] {fn_name}({fn_args}) → {result}")
messages.append({
"role": "tool",
"tool_call_id": tc.id,
"content": result
})
return "达到最大步数，任务未完成"
# 运行
run_agent("北京今天适合穿什么？另外 128 * 37 等于多少？")tool_map 将工具名映射到实际函数，避免 eval 动态调用的安全风险role: tool 格式追加到 messages，LLM 下一轮能看到max_steps 防止死循环，生产环境建议设为 15-20用 OpenAI Agents SDK 构建（生产推荐）
from agents import Agent, Runner, function_tool
@function_tool
def search_web(query: str) -> str:
"""搜索互联网获取最新信息"""
# 接入真实搜索 API
return f"搜索 '{query}' 的结果：..."
@function_tool
def run_code(code: str) -> str:
"""在沙箱中执行 Python 代码"""
# 接入代码执行环境
return f"执行结果：..."
# 创建 Agent
agent = Agent(
name="研究助手",
instructions="你是一个研究助手，能搜索信息并执行代码验证结论。",
tools=[search_web, run_code]
)
# 运行
result = Runner.run_sync(agent, "分析 2025 年 AI Agent 框架的发展趋势")
print(result.final_output)框架选型指南
框架 适用场景 学习曲线 特点 裸实现（推荐入门） 学习原理、简单任务 低 完全理解底层机制 OpenAI Agents SDK 快速生产、多 Agent 低 轻量，handoffs 机制优秀 LangGraph 复杂状态机、长任务 高 图结构编排，持久化强 LangChain RAG + Agent 混合 中 生态最全，抽象层多 AutoGen（微软） 多 Agent 对话协作 中 对话驱动，适合模拟场景 记忆系统实战
短期记忆：直接用 messages 列表
# 多轮对话直接在 messages 中追加，自动形成短期记忆
messages = [{"role": "system", "content": "你是助手"}]
messages.append({"role": "user", "content": "我叫小明"})
# ... LLM 回复 ...
messages.append({"role": "user", "content": "我叫什么？"})
# LLM 可从上下文找到答案长期记忆：向量数据库检索
from chromadb import Client
db = Client()
collection = db.get_or_create_collection("agent_memory")
# 存储记忆
collection.add(
documents=["用户偏好：喜欢简短回答"],
ids=["pref_001"]
)
# 检索相关记忆（在构建 System Prompt 前调用）
results = collection.query(query_texts=["用户风格"], n_results=3)
relevant_memory = "\n".join(results["documents"][0])多 Agent 协作设计
模式一：分层调度（Orchestrator + Workers）
用户输入
↓
调度 Agent（Orchestrator）
├── 研究 Agent（负责搜索信息）
├── 代码 Agent（负责执行计算）
└── 写作 Agent（负责生成报告）模式二：流水线（Pipeline）
调试与追踪
# 方法一：打印每步 messages（简单有效）
for msg in messages:
print(f"[{msg['role']}] {str(msg.get('content', ''))[:100]}")
# 方法二：OpenAI Agents SDK 内置追踪
# 运行后自动在 platform.openai.com/traces 生成可视化时间线
# 方法三：LangSmith（LangGraph 生态）
# 设置环境变量后自动追踪每个节点的输入输出
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "你的key"常见问题
RAG（检索增强生成）是一种为 LLM 补充外部知识的技术，本质上是一种"工具"。Agent 可以将 RAG 作为其众多工具之一——当需要查询知识库时调用 RAG，当需要执行代码时调用代码解释器。RAG 回答单次问题，Agent 完成多步任务。
不必。工具调用能力（Function Calling）是选择模型的核心指标。DeepSeek-V3、Kimi K2、Claude 3.5 Haiku、Qwen2.5-72B 均支持工具调用，成本远低于 GPT-4o。建议先用小模型验证逻辑，上线前再评估模型效果和成本的平衡点。
生产级 Agent 需要实现：① 工具调用异常捕获并返回错误信息给 LLM；② max_retries 对同一工具失败后重试逻辑；③ 超时熔断，避免单步卡死整个流程；④ 检查点（Checkpoint）支持，LangGraph 内置此能力。
务必设置 max_steps 上限。此外，可在 System Prompt 中明确指示："如果连续两步没有进展，输出 Final Answer 结束任务"。OpenAI Agents SDK 和 LangGraph 都提供了内置的循环终止机制。
当前最有价值的个人 Agent 场景：① 自动化重复信息收集（竞品监控、新闻摘要）；② 本地文件/邮件智能处理；③ 代码审查和自动修复；④ 个人知识库问答（结合 RAG）。这些场景任务边界清晰、工具需求明确，是 Agent 落地成本最低的切入点。总结
