Session 17:Agent Model API——理解模型接口与调用机制
开发 Agent 时,经常会使用 LangChain 的 Chat Model 接口,或者直接调用模型供应商提供的 SDK。
1. Agent 实际上是怎么调用模型的?
开发 Agent 时,经常会使用 LangChain 的 Chat Model 接口,或者直接调用模型供应商提供的 SDK。调用代码可能只有几行,但这几行背后包含了消息结构、模型参数、工具定义、响应内容和异常处理等多个部分。
以 Research Agent 为例,模型需要根据研究主题判断应该搜索什么资料。应用程序将任务说明和当前状态组织成消息,发送给模型。模型可能直接返回文本,也可能要求调用搜索工具。应用程序执行工具后,再把结果传回模型,由模型继续分析。
这个过程可以简化成:
应用程序
↓ 发送消息和参数
模型 API
↓ 返回文本或工具调用请求
应用程序
↓ 执行工具并组织结果
模型 API
↓ 返回下一步决策或最终结果
模型本身并不会因为收到了工具定义,就自动连接你的数据库或调用搜索服务。模型通常只是返回一条结构化的工具调用请求,真正的工具执行仍然发生在应用程序或框架中。
理解这一点之后,Model API、Agent Framework 和 Tool Runtime 之间的边界就比较清晰了。
2. 消息结构与角色
模型 API 通常会接收一组消息。不同角色用来表达消息来源和用途。
常见角色包括:
| 角色 | 用途 |
|---|---|
system |
提供整体行为指令,部分接口仍支持该角色 |
developer |
定义应用层指令、约束和行为要求 |
user |
用户输入或提交给模型的任务内容 |
assistant |
模型此前的回复或工具调用请求 |
tool |
工具执行后的返回结果,具体格式依 API 而异 |
system 与 developer 的支持方式会因 API 和供应商而有所区别。在部分接口中,开发者指令使用专门的字段或消息类型。实际调用时应以当前接口文档为准,不能假定所有模型都使用完全相同的消息协议。
例如,Research Agent 的请求可以包含:
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 风格:
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 风格:
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 如果需要返回下一步搜索计划,可以约定一个结构化结果:
{
"decision": "search_more",
"queries": [
"LLM context compression methods",
"agent context management architecture"
],
"reason": "当前材料缺少生产环境中的实践证据"
}
这个 JSON 是一个应用层约定示例。真实请求需要通过所用 API 支持的结构化输出机制约束格式,并由程序进一步校验字段和取值。
5. Tool Calling 在 API 层面是什么?
Tool Calling 是 Agent 开发中很重要的一项能力。它通常包含三个步骤:
- 应用程序把工具的名称、描述和参数 Schema 发送给模型。
- 模型返回工具调用请求。
- 应用程序执行工具,并将结果返回给模型。
假设有一个搜索工具:
tools = [ { "type": "function", "name": "search_web", "description": "搜索与研究主题相关的资料", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "搜索关键词", } }, "required": ["query"], "additionalProperties": False, }, "strict": True, }]
这是一种工具定义示例,具体字段嵌套和严格模式的要求取决于所用 API。
模型可能返回类似这样的调用请求:
{
"name": "search_web",
"arguments": {
"query": "agent context optimization production"
}
}
应用程序拿到调用请求后,需要根据工具注册表找到对应函数、解析参数、检查权限并执行工具。执行结果再被组织成 API 所要求的工具输出格式,交还给模型。
这里至少有三项工作不能省略:
- 参数必须经过程序校验,不能因为模型生成了参数就默认合法。
- 工具执行必须受到权限和资源限制。
- 工具结果必须与原始调用关联,避免把不同调用的结果混在一起。
对于并行工具调用,还需要正确匹配每个调用与其返回结果。
6. 流式输出、多模态与结构化输出
Model API 不只有文本输入和文本输出。
流式输出可以让应用程序逐步接收生成结果,适合交互式界面、实时反馈和较长内容生成。不过,流式响应可能只包含部分文本或尚未完整的结构化内容,不能在数据尚未完整时就直接执行高风险操作。
多模态接口可以根据模型能力接收图像、音频或其他形式的输入与输出。Research Agent 也可能需要分析截图、文档图片或音频转写结果,但具体支持哪些媒体格式、大小和任务类型,需要按模型接口确认。
结构化输出则用于约束模型响应的形式,例如让模型返回固定字段的 JSON。它可以降低解析难度,但不能代替业务验证。模型即使返回了完全符合 Schema 的结果,也仍可能给出错误的研究结论。
因此,实际工程中通常会同时使用三种能力:
- 通过 Tool Calling 让模型提出操作请求。
- 通过结构化输出规范模型与程序之间的数据交换。
- 通过程序校验和业务规则判断结果是否可以进入下一步。
7. 为什么需要统一的 Model Client?
当项目只调用一个模型时,直接使用供应商 SDK 通常比较简单。但如果需要在不同供应商之间切换,或者为不同任务配置不同模型,就需要考虑接口差异。
统一封装的目标不是抹平所有模型能力差异,而是把常见调用流程、错误分类、日志、超时和模型配置放到相对稳定的接口后面。
例如:
from typing import Protocol, Anyclass ModelClient(Protocol): def generate( self, messages: list[dict[str, Any]], *, model: str, timeout: float, ) -> Any: ...
这只是一个简化的 Python 接口示例。真实项目还需要定义工具调用结果、流式响应、结构化输出和错误类型等契约。
应用层可以根据任务选择模型:
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 接口完成。
例如,一个简单的图可能包含:
准备消息
↓
调用模型
↓
判断模型响应
├─ 普通文本 → 校验并结束
└─ 工具调用 → 执行 Tool
↓
返回结果
↓
再次调用模型
LangGraph 可以管理节点、状态更新、条件边、重试和 Checkpoint 等机制,但它不会自动替应用程序实现所有模型供应商的 API 适配,也不会自动决定每个任务应该使用哪个模型。
如果使用 LangChain 的模型封装,部分 API 适配、消息转换和工具调用解析可以由相应集成提供。若直接使用供应商 SDK,这些工作可能需要应用程序自己完成。
所以,设计时要先明确职责:API 提供模型交互能力,SDK 或适配层处理接口调用,Agent 框架组织流程,应用程序负责业务规则、权限、状态和资源预算。
9. 总结
理解 Model API,重点是弄清楚应用程序究竟向模型发送了什么、模型返回了什么,以及模型与程序之间的职责边界。
消息角色定义交互内容,模型参数影响生成行为,Tool Calling 让模型能够提出结构化的工具请求,结构化输出规范数据格式,流式与多模态能力扩展了交互方式。SDK 和 Agent 框架可以简化调用,但不会自动替应用程序完成所有业务逻辑。
在 Agent 项目中,建议先建立清晰的 Model Client 和错误处理约定,再根据需要引入 LangGraph 等流程框架。这样后续切换模型、增加工具或调整路由策略时,不必将模型供应商的差异散落到所有业务节点中。