Session 17:Agent Model API——理解模型接口与调用机制

开发 Agent 时,经常会使用 LangChain 的 Chat Model 接口,或者直接调用模型供应商提供的 SDK。

1. Agent 实际上是怎么调用模型的?

开发 Agent 时,经常会使用 LangChain 的 Chat Model 接口,或者直接调用模型供应商提供的 SDK。调用代码可能只有几行,但这几行背后包含了消息结构、模型参数、工具定义、响应内容和异常处理等多个部分。

以 Research Agent 为例,模型需要根据研究主题判断应该搜索什么资料。应用程序将任务说明和当前状态组织成消息,发送给模型。模型可能直接返回文本,也可能要求调用搜索工具。应用程序执行工具后,再把结果传回模型,由模型继续分析。

这个过程可以简化成:

text
应用程序
   ↓ 发送消息和参数
模型 API
   ↓ 返回文本或工具调用请求
应用程序
   ↓ 执行工具并组织结果
模型 API
   ↓ 返回下一步决策或最终结果

模型本身并不会因为收到了工具定义,就自动连接你的数据库或调用搜索服务。模型通常只是返回一条结构化的工具调用请求,真正的工具执行仍然发生在应用程序或框架中。

理解这一点之后,Model API、Agent Framework 和 Tool Runtime 之间的边界就比较清晰了。

2. 消息结构与角色

模型 API 通常会接收一组消息。不同角色用来表达消息来源和用途。

常见角色包括:

角色 用途
system 提供整体行为指令,部分接口仍支持该角色
developer 定义应用层指令、约束和行为要求
user 用户输入或提交给模型的任务内容
assistant 模型此前的回复或工具调用请求
tool 工具执行后的返回结果,具体格式依 API 而异

system 与 developer 的支持方式会因 API 和供应商而有所区别。在部分接口中,开发者指令使用专门的字段或消息类型。实际调用时应以当前接口文档为准,不能假定所有模型都使用完全相同的消息协议。

例如,Research Agent 的请求可以包含:

text
messages = [    {        "role": "system",        "content": (            "你是一个研究助手。"            "根据证据充分性决定下一步行动。"        ),    },    {        "role": "user",        "content": (            "研究主题:Agent 的上下文优化。"            "请先列出需要验证的核心问题。"        ),    },]

这里的 messages 是应用程序组织的输入。模型 API 根据请求参数和消息内容生成响应。

在多轮任务中,应用程序还需要决定保留哪些历史消息、哪些结果应该转化为状态,以及哪些内容应该从上下文中删除或摘要。这些属于应用层的上下文管理问题。

3. Chat Completions 与 Responses API

OpenAI 的模型接口中,Chat Completions 和 Responses API 都可以用于模型交互,但它们的请求和响应组织方式并不完全相同。

Chat Completions 采用以 messages 为核心的请求形式,响应通常通过 choices 中的消息内容和结束原因表达。

Responses API 则围绕一次 Response 组织输入与输出,可以使用不同类型的输入项和输出项,并支持工具调用等交互能力。

下面是两个简化示例。具体参数和返回结构需要以所使用模型与 SDK 的当前文档为准。

Chat Completions 风格:

text
from openai import OpenAIclient = OpenAI()response = client.chat.completions.create(    model="YOUR_MODEL",    messages=[        {            "role": "user",            "content": "总结 Agent 上下文优化的三个主要问题。",        }    ],)print(response.choices[0].message.content)

Responses API 风格:

text
from openai import OpenAIclient = OpenAI()response = client.responses.create(    model="YOUR_MODEL",    input=(        "总结 Agent 上下文优化的三个主要问题。"    ),)print(response.output_text)

示例中的 YOUR_MODEL 需要替换为当前账户可用、且支持相应 API 的模型标识。

对于新项目,应该根据工具调用、多模态、结构化输出、状态管理和供应商支持等需求选择接口,而不是只比较两种接口的代码长度。

另外,Responses API 并不意味着所有 Agent 状态都自动保存,也不意味着应用程序不再需要维护工具执行结果。是否使用服务端状态、如何关联前后请求,仍然取决于具体 API 能力和应用架构。

4. 模型参数会影响什么?

模型请求通常包含模型标识、输入内容和一组可选参数。

参数或能力 作用 需要注意的地方
model 指定使用的模型 不同模型的能力、价格和限制不同
temperature 在支持的模型中控制采样随机性 并非所有模型都支持相同参数
max_output_tokens 等输出限制 控制输出长度上限 具体名称和计量方式因 API 而异
tools 声明模型可请求调用的工具 声明工具不等于执行工具
tool_choice 等控制项 控制工具调用行为 支持值与约束能力依接口而异
结构化输出配置 约束返回数据的格式 格式正确不等于业务结论正确
流式输出 逐步接收生成内容 需要处理不完整输出和中断

这些参数不是越多越好。对于需要调用工具的 Agent,工具定义、工具选择策略和输出结构往往比单纯调整 temperature 更重要。

例如,Research Agent 如果需要返回下一步搜索计划,可以约定一个结构化结果:

text
{
  "decision": "search_more",
  "queries": [
    "LLM context compression methods",
    "agent context management architecture"
  ],
  "reason": "当前材料缺少生产环境中的实践证据"
}

这个 JSON 是一个应用层约定示例。真实请求需要通过所用 API 支持的结构化输出机制约束格式,并由程序进一步校验字段和取值。

5. Tool Calling 在 API 层面是什么?

Tool Calling 是 Agent 开发中很重要的一项能力。它通常包含三个步骤:

  1. 应用程序把工具的名称、描述和参数 Schema 发送给模型。
  2. 模型返回工具调用请求。
  3. 应用程序执行工具,并将结果返回给模型。

假设有一个搜索工具:

text
tools = [    {        "type": "function",        "name": "search_web",        "description": "搜索与研究主题相关的资料",        "parameters": {            "type": "object",            "properties": {                "query": {                    "type": "string",                    "description": "搜索关键词",                }            },            "required": ["query"],            "additionalProperties": False,        },        "strict": True,    }]

这是一种工具定义示例,具体字段嵌套和严格模式的要求取决于所用 API。

模型可能返回类似这样的调用请求:

text
{
  "name": "search_web",
  "arguments": {
    "query": "agent context optimization production"
  }
}

应用程序拿到调用请求后,需要根据工具注册表找到对应函数、解析参数、检查权限并执行工具。执行结果再被组织成 API 所要求的工具输出格式,交还给模型。

这里至少有三项工作不能省略:

  • 参数必须经过程序校验,不能因为模型生成了参数就默认合法。
  • 工具执行必须受到权限和资源限制。
  • 工具结果必须与原始调用关联,避免把不同调用的结果混在一起。

对于并行工具调用,还需要正确匹配每个调用与其返回结果。

6. 流式输出、多模态与结构化输出

Model API 不只有文本输入和文本输出。

流式输出可以让应用程序逐步接收生成结果,适合交互式界面、实时反馈和较长内容生成。不过,流式响应可能只包含部分文本或尚未完整的结构化内容,不能在数据尚未完整时就直接执行高风险操作。

多模态接口可以根据模型能力接收图像、音频或其他形式的输入与输出。Research Agent 也可能需要分析截图、文档图片或音频转写结果,但具体支持哪些媒体格式、大小和任务类型,需要按模型接口确认。

结构化输出则用于约束模型响应的形式,例如让模型返回固定字段的 JSON。它可以降低解析难度,但不能代替业务验证。模型即使返回了完全符合 Schema 的结果,也仍可能给出错误的研究结论。

因此,实际工程中通常会同时使用三种能力:

  • 通过 Tool Calling 让模型提出操作请求。
  • 通过结构化输出规范模型与程序之间的数据交换。
  • 通过程序校验和业务规则判断结果是否可以进入下一步。

7. 为什么需要统一的 Model Client?

当项目只调用一个模型时,直接使用供应商 SDK 通常比较简单。但如果需要在不同供应商之间切换,或者为不同任务配置不同模型,就需要考虑接口差异。

统一封装的目标不是抹平所有模型能力差异,而是把常见调用流程、错误分类、日志、超时和模型配置放到相对稳定的接口后面。

例如:

text
from typing import Protocol, Anyclass ModelClient(Protocol):    def generate(        self,        messages: list[dict[str, Any]],        *,        model: str,        timeout: float,    ) -> Any:        ...

这只是一个简化的 Python 接口示例。真实项目还需要定义工具调用结果、流式响应、结构化输出和错误类型等契约。

应用层可以根据任务选择模型:

text
def choose_model(task_type: str) -> str:    if task_type == "simple_summary":        return "fast_model"    if task_type == "complex_analysis":        return "reasoning_model"    return "default_model"

这里的模型名称只是逻辑别名。实际配置可以将别名映射到具体供应商、模型标识和参数组合。

统一接口还需要注意能力差异。并非所有模型都支持相同的工具调用格式、结构化输出、上下文长度或多模态能力。封装层应明确能力声明和不支持时的处理方式,而不是假设所有模型都能无缝替换。

8. LangGraph 在这里负责什么?

LangGraph 主要负责组织 Agent 的执行流程、状态和节点之间的转换。模型调用则通常通过模型 SDK 或 LangChain 的 Chat Model 接口完成。

例如,一个简单的图可能包含:

text
准备消息
   ↓
调用模型
   ↓
判断模型响应
   ├─ 普通文本 → 校验并结束
   └─ 工具调用 → 执行 Tool
                    ↓
                 返回结果
                    ↓
                 再次调用模型

LangGraph 可以管理节点、状态更新、条件边、重试和 Checkpoint 等机制,但它不会自动替应用程序实现所有模型供应商的 API 适配,也不会自动决定每个任务应该使用哪个模型。

如果使用 LangChain 的模型封装,部分 API 适配、消息转换和工具调用解析可以由相应集成提供。若直接使用供应商 SDK,这些工作可能需要应用程序自己完成。

所以,设计时要先明确职责:API 提供模型交互能力,SDK 或适配层处理接口调用,Agent 框架组织流程,应用程序负责业务规则、权限、状态和资源预算。

9. 总结

理解 Model API,重点是弄清楚应用程序究竟向模型发送了什么、模型返回了什么,以及模型与程序之间的职责边界。

消息角色定义交互内容,模型参数影响生成行为,Tool Calling 让模型能够提出结构化的工具请求,结构化输出规范数据格式,流式与多模态能力扩展了交互方式。SDK 和 Agent 框架可以简化调用,但不会自动替应用程序完成所有业务逻辑。

在 Agent 项目中,建议先建立清晰的 Model Client 和错误处理约定,再根据需要引入 LangGraph 等流程框架。这样后续切换模型、增加工具或调整路由策略时,不必将模型供应商的差异散落到所有业务节点中。

本文目录