从零构建AI Agent：核心开发实战指南
2026年，AI Agent 已经从演示视频走进生产系统：它能查资料、改代码、跑测试、发邮件、做报表，甚至在你睡觉时处理一整条业务流程。但真正从零构建一个可靠 Agent，难点从来不是「调通一个大模型」，而是把目标、工具、记忆、规划、执行、评测和安全拼成一个可观测、可回滚、可迭代的系统。本文以工程实战为主线，带你从空目录开始，搭建一个单 Agent 的最小闭环，再逐步补齐生产级能力。读完后，你应该能独立完成一个可用的 Agent 原型，并知道下一步该优化什么。
一、先定义 Agent：目标驱动的闭环系统
很多人把 Agent 等同于「会调用工具的聊天机器人」。这只说对了一半。聊天机器人以「回复下一句话」为目标，Agent 以「完成一个任务」为目标。前者可以没有状态，后者必须有状态；前者失败时只需道歉，后者失败时要能重试、换策略、求助人类。
一个最小 Agent 至少具备四种能力：第一，目标分解，把「帮我做竞品分析」拆成搜索、抓取、对比、写报告；第二，工具使用，能调用搜索、数据库、代码执行器、邮件 API；第三，记忆，能记住任务状态、用户偏好和中间结果；第四，反思，能根据工具返回结果判断下一步，而不是一条路走到黑。
自主性可以分层：L0 是纯问答；L1 是模型建议工具调用，人类执行；L2 是 Agent 自动调用低风险工具，高风险操作需审批；L3 是在限定域内自主完成长任务。生产系统大多数停留在 L2，这不是技术不行，而是权限、审计和成本的要求。本文的目标是 L2：Agent 能自动完成大部分步骤，但涉及写操作、付费、对外发送时，必须有人类审批或强约束。
还要明确边界：不要一上来做「万能 Agent」。选一个垂直任务，定义清晰的输入输出、成功标准和禁止行为。比如「每天 9 点生成一份竞品价格变动报告，只读公开网页，不执行购买，不联系任何人」。边界越清楚，后面越好评测。
二、架构总览：六层一循环
一个可维护的 Agent 架构可以拆成六层。接口层负责接收用户请求、文件、网页链接，并返回结果；编排层负责状态机、计划、重试和中断；模型层封装不同模型、提示词、结构化输出和路由；工具层注册工具、校验参数、执行沙箱和权限；记忆层管理短期上下文、长期向量库和结构化状态；可观测层记录 trace、token、延迟、成本和失败原因。六层之外只有一个循环：观察、思考、行动、再观察。
这个循环听起来简单，工程上却容易失控。模型可能反复调用同一个工具，可能把工具返回的错误当成成功，可能在上下文里丢失关键约束。解决办法不是写更长的提示词，而是把循环显式化：用状态机管理阶段，用预算限制步数，用结构化输出约束动作，用 trace 记录每一步的输入输出。
我建议从单体编排器开始，不要过早引入多智能体。多智能体适合任务可并行、角色边界清晰的场景，比如一个负责检索、一个负责写作、一个负责审校。但多智能体也会带来通信成本、状态同步和调试困难。单 Agent 加工具，通常能覆盖 80% 的业务需求。
在数据流上，用户请求先进入接口层，生成 task_id 和 trace_id；编排层创建初始状态，调用规划器生成计划；执行器按计划调用工具，把观察结果写回状态；反思器判断是否完成、是否需要重规划；最后输出结果并归档轨迹。每个环节都要能单独测试，而不是只能端到端碰运气。
三、技术选型：2026 年的最小可运行栈
语言与框架方面，Python 仍然是 Agent 工程的首选，生态最完整。Web 服务用 FastAPI，数据校验用 Pydantic，异步任务用 asyncio 加消息队列。编排层可以用 LangGraph 这类图编排框架，也可以自己写一个两百行的状态机。我的建议是：先自己写，理解循环和状态；等流程复杂到需要可视化、断点恢复和人工介入时，再引入框架。
模型层不要绑定单一供应商。2026 年的常见做法是模型路由：规划、复杂推理用强模型；意图分类、摘要、格式化用便宜的小模型；敏感数据走私有化部署。路由策略要可配置，按任务类型、上下文长度、成本和延迟选择，而不是硬编码在业务代码里。
存储方面，短期状态放 Redis，设置 TTL；任务元数据放 PostgreSQL；长期语义记忆用 pgvector 或 Qdrant；文件放对象存储。不要把所有东西都塞进向量库。向量库擅长相似检索，不擅长精确状态查询和事务。
可观测性从第一天就要有。用 OpenTelemetry 记录 span，至少覆盖模型调用、工具调用、检索和审批。日志里不要只打印「开始」「结束」，要记录 step、action、tool_name、latency、token_in、token_out、error_type。没有这些字段，后面排查失败会非常痛苦。
部署先用 Docker Compose 跑通 API、Redis、PostgreSQL 和 worker，再考虑 Kubernetes。不要为了「生产级」提前上复杂基础设施。Agent 的瓶颈通常在评测和工具质量，不在容器编排。
四、项目骨架与模型调用层
一个清晰的项目骨架能让后续迭代省很多时间。建议从下面的结构开始：
python agent/ app/ main.py orchestrator.py model_client.py tools/ registry.py search.py memory/ state.py eval/ cases.jsonl pyproject.toml
模型调用层不要直接在业务代码里调 SDK。封装一个 ModelClient，统一处理超时、重试、结构化输出、token 统计和错误映射。这样以后换模型、加缓存、做降级，只改一个地方。
python class ModelClient: def init(self, client, model, timeout=60): self.client = client self.model = model self.timeout = timeout
async def complete(self, messages, schema=None):
for attempt in range(3):
try:
return await self.client.chat(
model=self.model,
messages=messages,
response_format=schema,
timeout=self.timeout,
)
except TimeoutError:
if attempt == 2:
raise
await asyncio.sleep(2 ** attempt)
结构化输出是 Agent 稳定的关键。规划器输出计划、执行器输出动作、反思器输出判断，都应该有明确的 schema。不要让模型自由文本返回「我觉得下一步可以搜索一下」，而是要求它返回 action_type、tool_name、arguments、reason。解析失败时进入修复分支，而不是把错误文本继续喂给下一步。
配置要外置。模型名、温度、最大步数、预算、工具白名单、审批策略都放在配置文件或环境变量里。提示词也要版本化，至少记录 prompt_version，方便回滚和对比。
五、工具系统：Agent 的手脚与边界
工具是 Agent 与外部世界交互的接口，也是风险最高的地方。一个好的工具定义至少包含：名称、描述、输入 schema、输出 schema、副作用等级、权限范围、超时和重试策略。描述要写给模型看，明确「什么时候用」「什么时候不要用」「参数含义」「失败会返回什么」。
工具按风险分级：read 表示只读，比如搜索、查数据库；write 表示写操作，比如发邮件、改工单；dangerous 表示不可逆或高成本操作，比如付款、删除数据。read 可以自动执行，write 需要审批或二次确认，dangerous 必须人工审批并记录审计日志。
2026 年，MCP 已经成为工具接入的重要协议。它让 Agent 以标准方式连接文件系统、数据库、浏览器和第三方服务。但协议标准化不等于安全自动化。接入 MCP 服务时，仍然要做工具白名单、参数校验、网络出口限制和权限隔离。
python TOOLS = {}
def tool(name, description, schema, risk='read'): def deco(fn): TOOLS[name] = { 'fn': fn, 'description': description, 'schema': schema, 'risk': risk, } return fn return deco
工具执行要幂等。搜索可以重复，但发邮件、创建订单不能。给每次调用带 idempotency_key，写入前先查是否已执行。工具失败时返回结构化错误，比如 error_type、retryable、message，而不是抛一个裸异常。模型看到 retryable=false 时应该换策略，而不是无限重试。
最后，工具数量要克制。每多一个工具，模型选择错误的概率就增加。把低频工具收进子 Agent 或按场景动态加载，主 Agent 只保留最常用的五到八个。
六、记忆系统：让 Agent 记住该记的
记忆不是「把聊天记录全塞进上下文」。上下文窗口再大，也有成本和注意力衰减。合理的记忆分四类：工作记忆，当前任务的计划、步骤和观察；情景记忆，历史任务的轨迹和结果；语义记忆，领域知识、用户偏好、文档片段；程序记忆，工具使用规范和成功策略。
工作记忆放在状态对象里，结构化存储，不依赖模型自己记。情景记忆可以摘要后存 PostgreSQL，按任务类型和用户检索。语义记忆用向量库，但检索时要加元数据过滤，比如时间、来源、权限，避免把过期或无权访问的内容召回来。
python class AgentState(BaseModel): task: str plan: list[str] = [] step: int = 0 observations: list[dict] = [] budget: int = 20 status: str = 'idle'
上下文管理要有预算。给系统提示、工具描述、历史观察、检索结果分别设 token 上限。超过阈值时，优先压缩旧观察，保留最近三步和关键结论；把完整轨迹写入外部存储，需要时再检索。不要简单截断，截断容易丢掉约束和错误信息。
记忆还要会「忘」。过期价格、临时链接、用户明确删除的数据，都要有清理策略。长期记忆写入前做去重和置信度判断，避免把模型的猜测当成事实存进去。
七、规划与推理：ReAct、Plan-and-Execute 与动态重规划
ReAct 适合短任务和探索型任务：模型交替输出思考和动作，根据观察决定下一步。它的优点是灵活，缺点是容易绕圈，长任务中可能忘记总目标。Plan-and-Execute 适合步骤相对明确的任务：先列出计划，再逐步执行，每步完成后检查是否需要修订。
实战中常用混合策略：先让规划器生成三到七步的高层计划，执行器用 ReAct 完成单步，反思器在每步后判断计划是否仍然有效。触发重规划的条件要明确，比如连续两次工具失败、发现关键信息缺失、预算消耗超过一半、用户中途改变目标。
计划要结构化，不要只存一段自然语言。每一步至少包含 step_id、goal、suggested_tool、success_criteria。执行器可以根据实际情况换工具，但目标不能悄悄改变。反思器输出 continue、replan、ask_human、finish 四种决策，避免模型自由发挥。
python plan = planner.create(task) for step in plan: result = executor.run(step) if result.needs_replan: plan = planner.revise(plan, result)
规划器最常见的错误是「计划太细」。把「打开网页、点击按钮、复制文本」都写成步骤，既脆弱又浪费 token。正确做法是计划到业务动作，比如「获取竞品定价页」「提取价格和套餐」「对比昨日数据」，具体操作交给工具。
还要防止无限循环。设置最大步数、最大工具调用次数、最大 token 预算和最大墙钟时间。任何一项超限就进入失败分支，输出已完成部分和失败原因，而不是继续烧钱。
八、执行循环：状态机、重试与可观测性
执行循环建议用显式状态机：idle、planning、acting、observing、reflecting、waiting_human、done、failed。每次状态转换都记录原因和耗时。这样出问题时能回答三个问题：卡在哪一步、为什么卡、当时看到了什么。
重试要分类。网络超时、限流可以指数退避重试；参数错误、权限不足不应重试，应该修正参数或求助人类；工具返回空结果可以换关键词重试一次，但不要无限换。重试次数和退避策略放在工具配置里，不要写死在循环里。
python while state.status not in ('done', 'failed'): action = await planner.next(state) if action.type == 'tool': result = await executor.run(action, state) state.observations.append(result) elif action.type == 'final': state.status = 'done' state.step += 1 if state.step > state.budget: state.status = 'failed'
可观测性要覆盖轨迹。每个任务一个 trace_id，每次模型调用和工具调用一个 span，记录输入摘要、输出摘要、延迟、token、成本和错误。不要把完整敏感数据写进日志，用哈希或脱敏字段代替。
人类介入是生产系统的一部分。审批、补充信息、纠正方向都应该能暂停和恢复。实现上可以把状态存入 Redis，等待审批回调后继续执行。不要让请求线程一直挂着，也不要把审批做成不可恢复的断点。
九、评测：没有评测集就没有 Agent 工程
Agent 的评测不能只看最终回答像不像。至少要分四层：任务成功率，是否完成目标；轨迹质量，步骤是否合理、工具调用是否准确；成本与延迟，平均 token、工具次数、端到端耗时；安全性，是否越权、是否泄露数据、是否执行了禁止操作。
先建一个 50 到 200 条的小评测集，覆盖典型任务、边界任务和对抗任务。每条包含输入、期望结果、允许的工具、禁止的行为和评分规则。每次改提示词、换模型、加工具，都跑一遍回归。没有评测集，优化就是盲人摸象。
失败分类比总分更有用。把失败分成规划错误、工具选择错误、参数错误、观察误读、上下文丢失、权限拒绝、模型幻觉、超时。每周看一次失败分布，优先修高频且高影响的问题。
LLM-as-judge 可以用于开放式回答，但要有校准。给 judge 明确的评分 rubric，抽样人工复核，定期检查 judge 与人工的一致性。不要让 judge 既当运动员又当裁判。
上线前做小流量金丝雀，对比旧版本的完成率、成本和投诉率。上线后监控任务成功率、人工介入率、平均步数和异常工具调用。指标突然变化时，先看工具和模型版本，再看提示词。
十、安全、权限与成本控制
Agent 的安全边界比聊天机器人复杂，因为它能行动。首要风险是提示词注入：网页、文档、邮件里的恶意指令可能让 Agent 忽略系统约束。防御不能只靠提示词，要在工具层做权限校验，在输出层做敏感信息过滤，在编排层限制可执行动作。
最小权限是核心原则。每个工具只授予完成任务所需的最小范围；数据库账号只读；文件系统只挂载工作目录；网络出口走白名单；密钥不进入模型上下文。高风险操作必须人工审批，审批界面要展示完整参数和影响范围。
成本控制要前置。给每个任务设 token 预算、工具调用预算和金额预算；超过阈值暂停并通知。缓存常见检索和模型结果；用模型路由把简单任务交给小模型；限制上下文长度；对长任务做阶段性摘要。不要等账单出来才发现 Agent 在循环调用。
审计日志要不可篡改，至少保留任务输入、计划、工具调用、审批记录和最终输出。涉及个人信息的数据要脱敏，保留期限要明确。安全不是上线前的一次检查，而是每次新增工具都要重新评估。
十一、部署与运维：从本地 Demo 到生产服务
生产部署建议把 API 和 worker 分开。API 负责接收请求、鉴权、创建任务和查询状态；worker 负责执行 Agent 循环。状态放 Redis 或 PostgreSQL，worker 保持无状态，方便水平扩展和故障重启。长任务用队列解耦，避免 HTTP 超时。
版本化要覆盖模型、提示词、工具和编排逻辑。每次发布记录版本号，支持按任务回放。出问题时能快速回滚到上一个稳定版本，而不是在线上改提示词。
SLO 至少定义三条：任务成功率、P95 端到端延迟、人工介入率。再加成本指标，比如每任务平均 token 和工具费用。监控告警要能定位到具体工具或模型，而不是只报「错误率上升」。
密钥管理用专门的 secrets 服务，不要写进环境变量文件后提交仓库。数据库连接、第三方 API key、审批回调签名都要轮换。容器镜像最小化，禁用不必要权限，限制出站网络。
扩容时先看瓶颈。模型限流就加队列和退避；工具慢就加缓存或异步；状态存储热就分片。不要盲目加 worker，Agent 的瓶颈往往在上游 API 配额。
十二、实战案例：竞品情报 Agent
假设我们要做一个竞品情报 Agent：每天读取三家竞品的公开定价页和更新日志，提取价格、套餐、功能变化，生成一份中文简报，发现价格变动时提醒负责人。约束是只读公开网页，不登录后台，不联系任何人，不执行购买。
工具集只需要五个：搜索、网页抓取、正文提取、差异对比、报告写入。搜索用于发现新页面，抓取用于获取 HTML，正文提取把页面转成结构化文本，差异对比与昨日快照比较，报告写入保存 Markdown 并发送站内通知。每个工具都标记为 read 或 write，报告写入需要审批。
工作流分四步：第一，规划器读取任务和昨日快照，生成抓取计划；第二，执行器逐个抓取页面，提取价格和套餐；第三，反思器检查是否缺页、是否解析失败，必要时重试或换来源；第四，生成简报并对比差异，人工确认后发布。
状态里保存竞品列表、页面 URL、快照时间、提取字段、差异结果和报告草稿。每次运行生成 trace，记录每个页面的抓取状态。评测集包含正常页面、改版页面、反爬页面和价格未变页面，分别检查提取准确率、差异召回率和误报率。
这个案例的关键不是模型多强，而是工具可靠、状态清晰、失败可恢复。页面改版时，提取器返回结构化错误，反思器决定换选择器还是标记人工；价格未变时，不要为了「有输出」而编造变化。上线第一个月，重点看误报和漏报，而不是报告写得多漂亮。
十三、常见坑与进阶路线
第一个坑是过度设计。还没跑通单 Agent，就上多智能体、知识图谱、自研向量库。结果是每个模块都能演示，合起来不能完成任务。正确顺序是：单 Agent 加三个工具跑通，再加记忆，再加评测，最后才考虑多 Agent。
第二个坑是没有评测。凭感觉改提示词，今天好明天坏。第三个坑是工具太多，模型选择困难。第四个坑是上下文太长，关键约束被淹没。第五个坑是忽略延迟，用户等三十秒就流失。第六个坑是权限过大，Agent 能删库、能发邮件、能付款。第七个坑是没有幂等，重试导致重复下单。
进阶方向可以按需选择。多智能体适合并行检索和角色分工；计算机使用适合没有 API 的旧系统，但要做好沙箱和人工接管；MCP 生态适合快速接入外部工具，但要严格白名单；长期记忆适合个性化助手，但要解决隐私和过期问题；强化学习适合有明确奖励信号的垂直任务，但数据成本高。
一个务实的 2026 年路线图是：第一周跑通单 Agent 闭环；第二周补齐工具校验、重试和 trace；第三周建评测集并修高频失败；第四周加审批、预算和部署；之后每月迭代工具和提示词，按失败分布决定优先级。
十四、结语：从能跑到可靠
从零构建 AI Agent，本质上是做系统工程，而不是写一段神奇的提示词。你需要定义目标、拆解任务、设计工具、管理状态、限制权限、建立评测、监控成本。模型会升级，框架会变化，但这些工程原则不会过时。
如果你今天就开始，建议先选一个只读、低风险、结果可验证的任务，比如竞品页面监控、文档摘要、日志分析。用最小栈跑通「计划、调用、观察、反思、输出」五步，记录每一步的输入输出，再逐步加工具和记忆。不要追求一次做完，追求每天都能评测、每天都能回滚。
当你的 Agent 能稳定完成一个垂直任务，失败时知道为什么失败，成本可控，权限可审计，它才真正从 Demo 变成了产品。2026 年的机会不属于会调模型的人，而属于能把 Agent 工程化的人。