开发一个 Agent，还需要哪些东西？

专栏：AI Agent 开发｜05

一、上一章的三件套已经能跑，为什么还不够？

最小 Agent 其实很简单：一个模型、几个工具，再加一段控制循环。

while not done: context = build_context(state) action = model(context, tools) result = runtime.execute(action) state.update(result)

如果任务只是“查一次天气再回答”，它已经够用了。

但需求稍微变一下，问题马上出现：用户聊了十轮以后上下文怎么控制？下次再来要不要记住偏好？付款前谁审批？任务跑一半进程重启怎么办？改了 Prompt 以后怎么知道效果变好还是变差？

图 1 真实 Agent 的技术栈，是需求一层层把新能力“逼”出来的

二、先别背“十一层技术栈”，把 Runtime 放在中间看

原稿把 Agent 技术栈拆成很多层，这能做总图，但对第一次接触的人容易产生两个误会：一是以为它们存在严格的上下层依赖；二是以为做 Agent 必须把所有东西一次装齐。

更容易理解的方式是：Runtime / Agent Loop 是中间的执行器，周围有几类能力给它提供信息、动作和工程保障。

图 2 Agent 技术栈更像围绕 Runtime 协作的能力地图，而不是一栋严格的六层楼

1. Model：负责理解、生成和做决策

Model 仍然是核心能力来源。Runtime 会把当前任务和工具信息交给模型，模型再决定是直接回答，还是提出 Tool Call。

工程上通常会把模型调用封装成 Provider / Model Adapter，而不是让业务代码到处直接写某一家 SDK。原因很简单：以后换模型、做路由、增加超时或统计 Usage 时，改一个入口比改几十个业务文件容易。

2. Context + State：先解决“这一轮要让模型看到什么”

上一章已经出现了 Context Builder。它关心的是本轮输入：用户要求、前面必要的 Tool Result、系统约束、可用工具，以及可能检索到的材料。

State 则更宽一点，它表示当前 Run 的任务状态：已经做了哪些步骤、哪些工具调用完成了、是否等待审批、还剩多少预算等。

3. Memory：只有需要“跨时间记住”时才出现

Memory 不是 Agent 的必选组件。很多一次性任务根本不需要长期记忆。

只有当产品真的需要“用户下次再来仍然记得某些信息”，才需要把偏好、历史事实或任务经验持久化。它可能放在普通数据库、专门的 Memory Store，或者通过检索把相关信息重新找回来。

Redis、向量数据库都只是可能的实现，不应该把“短期 Memory=Redis、长期 Memory=Vector DB”当成定义。

4. Tools：把“模型会说”变成“系统能做”

Tool 可以是本地 Python 函数、公司内部 API、搜索服务、数据库操作，也可以是代码执行、浏览器或电脑操作。

重要的不是 Tool 越多越好，而是 Runtime 必须知道：工具叫什么、参数怎么校验、谁有权限调用、失败怎么处理、结果怎样回填。

5. Workflow / Orchestration：哪些步骤固定，哪些允许动态

不是所有任务都应该全部交给模型自由决定。真实产品更常见的是外层流程比较确定，局部节点允许 Agent 动态处理。

例如“提交报销”可以固定为：解析票据 → 校验 → Agent 处理异常 → 人工审批 → 入账。这里 Agent 只是整个 Workflow 的一部分。

当流程需要暂停、恢复、人工介入或多 Agent 协作时，才会开始需要更强的 Orchestration / durable execution 能力。

6. MCP / Tool Integration：工具越来越多以后，怎么接得整齐

Function Calling 是模型表达工具调用的一种机制；MCP 则解决 Agent/应用怎样以标准方式连接外部工具、资源等能力。两者不是同一个层级的“二选一协议”。

你完全可以先用普通函数 Tool。等外部系统越来越多、希望复用和标准化工具接入时，再学习 MCP。

三、横着贯穿整个系统的，还有 4 类工程能力

1. Security / Guardrails / HITL

模型提出动作，不代表动作就应该执行。工具执行前后可以做校验；删除、付款、发邮件等高风险动作还可以要求人工审批。

安全不是最后上线前补一个“Prompt 防注入”就结束，它还包括身份、权限、租户隔离、Secret、Tool 边界和数据访问控制。

2. Evaluation：回答“这个 Agent 到底有没有变好”

Prompt、模型、工具描述改一次，最终轨迹就可能变化。没有固定任务集，你只能凭感觉判断“好像更聪明了”。

Eval 的基本思路是保留一组代表性任务，反复跑回归：结果是否正确、工具是否选对、任务是否完成、步数和成本是否合理。

3. Tracing / Observability：回答“它到底在哪一步错了”

一个 Agent Run 可能包含很多模型轮次和工具调用。线上报错时，只看最终一句“失败了”几乎没法排查。

Tracing 会把 Run、模型轮次、Tool Call、Handoff、Guardrail 等事件串成一条轨迹。这样才能知道：第几轮用了哪个工具、参数是什么、耗时多少、失败发生在哪里。

4. Storage / Deployment：让状态和服务真的活下来

Agent 需要保存会话、任务状态、审批状态、文件或评测数据时，还是要回到普通软件工程：数据库、对象存储、缓存、队列。

部署也一样，没有哪套“Agent 专用服务器”。容器、网关、Secret、日志、监控、扩缩容，都是把 Runtime 稳定运行起来的基础设施。

四、什么时候该加哪一块？不要按照地图从左到右安装

图 3 地图的真正用法：遇到一个问题，再找到对应能力

这张图比“完整依赖清单”更重要，因为真实项目的技术栈应该按问题成长。

五、框架到底放在这张地图的什么位置？

到这里再看 OpenAI Agents SDK、LangGraph、LangChain 等框架会容易很多。它们不是“完整技术栈本身”，而是帮你封装其中一部分能力。

• Agent SDK 类框架通常帮你管理模型轮次、Tool、Handoff、Guardrail、Session、Tracing 等。

• LangGraph 这类 Runtime / Orchestration 工具更关注持久化状态、durable execution、Human-in-the-loop、长任务恢复等。

• 数据库、对象存储、业务权限、真实评测数据、部署方式仍然要根据你的产品自己设计。

所以选框架时先问“它帮我解决地图上的哪几个问题”，而不是先问“哪个框架最强”。

六、一个适合学习阶段的项目骨架，应该先长什么样

这一篇不建议像原稿那样第一版就建 memory、MCP、eval、observability 十几个目录。更适合学习的方式是先留出清楚边界：

agent_project/ ├── app/ │ ├── runtime/ # Agent Loop / 状态推进 │ ├── models/ # Model Provider 封装 │ ├── tools/ # Tool 定义与 Registry │ └── context/ # Context Builder ├── tests/ ├── .env.example └── pyproject.toml

等需求出现，再新增：

# 需要跨会话记忆 app/memory/ # 需要 Graph / 审批 / 可恢复流程 app/workflows/ # 工具接入开始标准化 app/integrations/mcp/ # 开始做回归评测 evals/ # 需要自己补充 Trace / Metrics app/observability/

这种结构的好处是：每个目录都是因为真实需求出现才建立，不会第一天就得到一个“看起来生产级、实际上全是空文件夹”的项目。

七、几个原稿里需要特别纠正的认识

• Agent 技术栈不是固定“十一板块，一个都不能少”。不同产品需要的能力不同，地图是导航，不是验收清单。

• Memory 不是 Agent 必需品，也不等于 Redis + pgvector。

• MCP 很重要，但不是所有 Tool 都必须经过 MCP；本地函数和普通 API Tool 仍然很常见。

• 框架之间也不是严格覆盖同一层。SDK、Runtime、Workflow Engine、Observability 平台关注点会重叠。

• 安全、Eval、Tracing 应该尽早建立最小版本，但不代表第一天就搭完整企业平台。

八、这一篇只需要记住一句话

Agent 技术栈不是“有哪些热门组件”，而是：为了让一个模型驱动的循环能长期、受控、可验证地完成任务，你分别需要哪些信息、动作、状态和工程保障。

九、下一篇

下一篇 06《Message、Role、Instruction 到底是什么？》会回到最靠近模型的一层，从一条最普通的 messages 请求开始，看 system/developer/user/assistant 分别承担什么角色，以及“对话历史”和 Runtime State 为什么不是一回事。