HHUAN Lab技术教程 / 项目实践 / 阅读笔记
返回文章列表
9 分钟阅读技术教程知识笔记卡

AI Agent 编排入门：从工具调用、MCP 到可观测工作流

基于 OpenAI Agents、MCP、Anthropic tool use 与 LangGraph 文档，整理一套面向工程落地的 Agent 编排思路。

AI AgentsOpenAIMCPLangGraphTool Calling

很多 Agent 项目一开始会被写成一个“大提示词加一组工具”的脚本。它能跑通 demo，但一旦进入真实业务，就会遇到三个问题：工具边界不清楚、状态难以恢复、执行过程不可观测。更稳妥的做法，是先把 Agent 看成一个受约束的工作流，再决定模型、工具、协议和运行框架的职责。

本文不是逐字复述某一份文档，而是综合 OpenAI Agents 与工具文档、Model Context Protocol、Anthropic tool use 说明，以及 LangGraph 的工作流定位，整理一个可落地的设计框架。[agent-001][agent-002][agent-003][agent-004][agent-005]

先把 Agent 拆成四层

一个可维护的 Agent 系统，通常可以拆成四层：

  • 模型层：负责理解输入、规划下一步、生成工具参数或最终回答。
  • 工具层：把外部能力封装成可调用接口，例如搜索、数据库查询、工单创建、代码执行。
  • 协议层：规定模型或宿主如何发现工具、描述工具、传递上下文。
  • 编排层：管理状态、分支、重试、人工确认、日志和可观测性。

OpenAI Agents 文档把工具、交接、追踪等能力放进 Agent 应用的核心构件里，说明 Agent 不只是单轮模型调用，而是围绕工具和执行轨迹组织起来的应用形态。[agent-001] OpenAI 的工具文档也强调了模型可以调用不同类型工具，例如函数工具、文件搜索或网页搜索，开发者需要把工具定义成清晰、可控的接口。[agent-002]

Agent 工程化的关键，不是让模型“什么都能做”，而是让模型只在明确边界内选择下一步。

工具调用：先设计接口，再设计提示词

工具调用最容易犯的错，是先写提示词，后补工具。这样会导致工具描述混乱、参数语义漂移、失败路径没有定义。更好的顺序是：

  1. 写出业务动作清单。
  2. 把动作拆成幂等或接近幂等的工具。
  3. 为每个工具写清输入、输出、失败原因和副作用。
  4. 再让模型在这些工具之间选择。

Anthropic 的 tool use 文档把工具使用描述为模型与外部函数之间的交互模式，核心是让模型在需要时生成符合工具 schema 的调用请求。[agent-004] OpenAI 的工具文档同样把工具定义、调用和结果回传作为模型使用外部能力的基础流程。[agent-002]

概念上可以把工具登记写成这样：

type ToolSpec = {
  name: string;
  purpose: string;
  inputSchema: Record<string, unknown>;
  sideEffect: "read-only" | "writes-data" | "external-action";
  failurePolicy: "retry" | "ask-human" | "stop";
};
 
const tools: ToolSpec[] = [
  {
    name: "searchKnowledgeBase",
    purpose: "检索内部技术文档，返回候选段落和来源链接。",
    inputSchema: { query: "string", topK: "number" },
    sideEffect: "read-only",
    failurePolicy: "retry"
  },
  {
    name: "createIssue",
    purpose: "在项目管理系统中创建待办事项。",
    inputSchema: { title: "string", description: "string", priority: "string" },
    sideEffect: "writes-data",
    failurePolicy: "ask-human"
  }
];

这段代码不是某个 SDK 的完整 API，而是一个设计草图：你需要在实现前明确工具的副作用和失败策略。真正接 SDK 时，再映射到对应平台的工具定义格式。

MCP：把工具发现从“硬编码”中拆出来

Model Context Protocol 的价值在于，它提供了一套让应用向模型或宿主暴露上下文和工具的协议思路。MCP 官方介绍把它定位为连接 AI 应用与外部数据、工具、系统的开放协议。[agent-003]

这意味着工具层不一定要完全硬编码在 Agent 进程里。对于需要连接多个数据源的系统，可以把一部分能力拆成 MCP server：

  • 文档系统提供搜索和读取工具。
  • Git 平台提供 issue、PR、CI 状态工具。
  • 内部知识库提供实体查询和引用追踪工具。
  • 业务系统提供只读查询工具，写操作再加人工确认。

这样做的好处是边界更清楚：Agent 编排层负责“什么时候调用”，MCP server 负责“能力如何暴露”。但它也带来新约束：工具描述需要稳定，权限模型需要清楚，错误信息要能被上层恢复。

LangGraph：把长任务当成有状态图

当 Agent 从一次问答变成长任务时，状态管理会变得比提示词更重要。LangGraph 官方文档强调它面向长期运行、有状态的 Agent，并支持 durable execution、human-in-the-loop、记忆和可观测能力。[agent-005]

这类能力适合处理以下场景：

  • 多步骤研究：搜索、筛选、阅读、总结、生成草稿。
  • 代码维护：定位问题、修改文件、运行测试、提交补丁。
  • 审批流：模型提出动作，人类确认后执行写操作。
  • 异步任务：外部 API 慢、需要重试或等待回调。

从工程角度看，LangGraph 的“图”不是为了显得复杂，而是为了让状态、分支和恢复点显式化。一个简单的研究型 Agent 可以画成：

用户问题
  -> 规划检索词
  -> 调用搜索工具
  -> 筛选来源
  -> 阅读与提取证据
  -> 生成回答草稿
  -> 检查引用
  -> 输出

如果任何一步失败，系统应该知道失败发生在哪里，以及是否可以重试、降级或请求人工介入。

一个可执行的落地顺序

如果从零开始做一个 Agent，不建议一上来就接很多工具。可以按这个顺序推进：

  1. 只读工具优先：先接搜索、读取、检索类工具，验证模型是否能稳定选择工具。
  2. 明确来源回传：工具结果必须带来源、时间、置信度或错误类型。
  3. 加入执行轨迹：记录每次工具选择、输入、输出摘要和失败原因。
  4. 再接写操作：创建工单、发消息、改数据库这类操作，先加人工确认。
  5. 抽出协议边界：工具变多后，再考虑 MCP server 或独立工具服务。
  6. 图化长任务：任务超过两三步后，使用工作流或状态图管理恢复点。

这套顺序综合了多个来源的共同方向：工具调用需要清晰 schema，Agent 应用需要追踪和编排，协议层可以降低工具集成耦合，长任务需要状态和恢复能力。[agent-001][agent-002][agent-003][agent-005]

需要保留的风险意识

这里有几个容易被忽略的限制：

  • 工具 schema 清楚，不等于模型总能选对工具。
  • MCP 解决的是连接协议问题，不自动解决权限、审计和数据治理。
  • 有状态工作流能提高可恢复性，但也会增加运行时复杂度。
  • 写操作必须默认谨慎，尤其是涉及外部系统、用户数据或资金动作时。

综合这些资料可以推断：Agent 的成熟度不取决于“接了多少工具”，而取决于工具边界、状态恢复、观测能力和人工控制是否成体系。这是工程判断，不是某个文档的单独结论。

参考资料

  1. [agent-001] OpenAI Developers, “Agents”, https://developers.openai.com/api/docs/guides/agents
  2. [agent-002] OpenAI Developers, “Tools”, https://developers.openai.com/api/docs/guides/tools
  3. [agent-003] Model Context Protocol, “Introduction”, https://modelcontextprotocol.io/docs/getting-started/intro
  4. [agent-004] Anthropic Docs, “Tool use overview”, https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
  5. [agent-005] LangChain Docs, “LangGraph overview”, https://docs.langchain.com/oss/python/langgraph/overview