22-官方API与参数语义手册
核对日期：2026-05-18
官方资料：Overview https://docs.langchain.com/oss/javascript/langchain/overview；Agents https://docs.langchain.com/oss/javascript/langchain/agents；Models https://docs.langchain.com/oss/javascript/langchain/models；Tools https://docs.langchain.com/oss/javascript/langchain/tools；Structured output https://docs.langchain.com/oss/javascript/langchain/structured-output；Runtime https://docs.langchain.com/oss/javascript/langchain/runtime。
官方概念
本章不是 API 全量复制，而是把官方 TypeScript 文档中最常用、最容易误用的 API 参数拆成“语义、适用场景、边界、测试方法”。LangChain v1 的官方 API 设计围绕 Runnable、Agent Graph、Tool schema、Runtime context、Middleware 和 Structured output 展开。
如果只知道 API 名字，不知道参数语义，就会出现典型问题：Agent 能跑但工具乱调、结构化输出偶发失败、runtime context 泄露进 prompt、streaming 只处理文本不处理工具事件。
机制
Agent API 语义
| 参数/概念 | 官方语义 | 工程语义 | 常见误用 |
|---|---|---|---|
model | Agent 使用的 chat model | 决定 tool calling、structured output、上下文长度、成本 | 只写模型名，不锁 provider 和参数 |
tools | Agent 可调用工具列表 | 工具暴露面和权限面 | 把所有工具一次性暴露 |
systemPrompt / dynamic prompt | 系统指令或由 middleware 动态生成 | 任务目标、输出要求、少量稳定规则 | 把权限策略写进 prompt |
responseFormat | 结构化输出 schema/strategy | 下游 API contract | 只测 happy path，不测 schema failure |
middleware | Agent 生命周期拦截/包装逻辑 | 动态模型、工具过滤、guardrails、trace | 中间件里藏大量业务规则 |
checkpointer | 保存短期会话/graph state | thread 级恢复、HITL 暂停恢复 | 用内存 checkpointer 上生产 |
store | 长期记忆存储 | 跨会话用户画像、偏好、历史 | 自动记住所有用户输入 |
contextSchema | runtime context 类型约束 | user/tenant/role/requestId 等控制面数据 | 不校验 context，工具读到 undefined |
典型初始化伪代码：
const contextSchema = z.object({
userId: z.string(),
tenantId: z.string(),
roles: z.array(z.string()),
requestId: z.string(),
});
const agent = createAgent({
model,
tools,
responseFormat: answerSchema,
middleware: [authMiddleware, piiMiddleware, tracingMiddleware],
contextSchema,
});
Model API 语义
| 能力 | 语义 | 适合 | 验收 |
|---|---|---|---|
invoke | 单次完整响应 | 分类、抽取、非流式问答 | 断言响应结构、usage、错误 |
stream | 增量 chunk | UI 打字机、长答案 | 断言 done/error/chunk 协议 |
batch | 批量并发调用 | eval、离线抽取 | 控制并发和失败隔离 |
maxRetries | SDK 层重试 | 429、短暂网络失败 | 不重试认证/参数错误 |
timeout | 单次请求超时 | 防止请求挂死 | 超时进入可恢复错误 |
temperature | 随机性 | 创意任务高，抽取低 | 评测任务建议低温 |
maxTokens | 输出 token 限制 | 成本和长度控制 | 超限时有截断策略 |
| provider class | 使用 provider 专属参数 | reasoning、cache、baseURL、logprobs | 单独写 provider 回归 |
工程判断：model 参数不是“随便填个模型名”。它决定工具调用格式、结构化输出策略、token 预算、streaming 事件、错误码和成本。
Messages API 语义
| Message 类型 | 用途 | 不应该承载 |
|---|---|---|
| system | 稳定任务边界、角色、输出规则 | 机密、权限、临时用户数据 |
| user/human | 用户输入 | 未经净化的可执行指令 |
| assistant/AI | 模型输出、tool call 请求 | 人工写入的业务真相 |
| tool | 工具执行结果 | 原始内部响应、堆栈、密钥 |
多轮对话中，messages 是“模型可见上下文”。不要把 runtime context、数据库连接、权限 token、内部 trace 全塞进去。真正的控制数据应放在 runtime context。
Tools API 语义
| 字段/能力 | 官方语义 | 工程要求 |
|---|---|---|
name | 模型引用工具的稳定名称 | 短、明确、不可和其他工具混淆 |
description | 告诉模型何时用工具 | 写触发条件和不适用条件 |
schema | 输入参数结构 | 每个字段尽量有描述、枚举、范围 |
execute | 工具执行函数 | 走网关、校验权限、记录审计 |
| runtime context | 工具读取用户/租户/配置 | 不进入模型可见内容 |
| return object | 结构化工具结果 | 给后续模型或业务层消费 |
| return command | 更新 graph state | 需要考虑 reducer 和并发 |
工具 schema 示例：
const searchTicket = tool(
async ({ ticketId }, runtime) => {
const { userId, tenantId } = runtime.context;
return ticketGateway.search({ ticketId, userId, tenantId });
},
{
name: "search_ticket",
description: "查询当前租户下的工单。仅当用户明确提供工单 ID 时使用。",
schema: z.object({
ticketId: z.string().regex(/^TICKET-[0-9]+$/).describe("工单 ID"),
}),
},
);
Structured Output API 语义
| 参数/策略 | 语义 | 适用 | 风险 |
|---|---|---|---|
responseFormat: schema | 自动选择策略 | 起步最快 | 需要确认最终选择 |
providerStrategy(schema) | provider 原生 schema 输出 | 原生支持强的模型 | provider 兼容性 |
toolStrategy(schema) | 用 tool call 产出结构 | 支持 tool calling 的模型 | 多一次 tool call 语义 |
handleError | schema 失败时反馈模型 | 抽取/分类脏数据 | 错误信息不能泄露内部规则 |
| union schema | 多种结构之一 | 多任务输出 | 模型可能同时给多个结构 |
结构化输出不是“永不失败”。你必须定义失败时是重试、降级、拒答，还是把错误返回给人工处理。
Runtime API 语义
| Runtime 数据 | 生命周期 | 谁能读 | 是否进 prompt |
|---|---|---|---|
userId | 单次请求/会话 | middleware、tools | 通常不直接进 |
tenantId | 单次请求/会话 | retriever、tools | 不直接进 |
roles | 单次请求/会话 | tool filter、ACL | 不直接进 |
requestId | 单次请求 | tracing、audit | 不进 |
featureFlags | 单次请求/部署 | middleware | 不直接进 |
store | 跨会话 | tools、middleware | 只注入筛选后的内容 |
executionInfo | run/thread | audit、debug | 不进 |
Streaming API 语义
| 事件/模式 | 表达什么 | UI 怎么处理 | 测试怎么写 |
|---|---|---|---|
| token/message chunk | 模型增量输出 | append 到答案区域 | 拼接后等于最终答案 |
| update | Agent 步骤更新 | 显示进度状态 | 断言工具调用顺序 |
| custom | 工具自定义进度 | 进度条/日志面板 | 断言事件结构 |
| error | 流中错误 | 展示可恢复错误 | 断言不会卡 loading |
| interrupt | HITL 暂停 | 显示审批 UI | 断言 thread id 保存 |
| done | 结束事件 | 收尾、保存结果 | 断言只出现一次 |
Python 差异
Python 使用 create_agent、Pydantic/TypedDict、snake_case 参数和不同 provider 包；TypeScript 使用 createAgent、zod、JS provider 包和 contextSchema。概念对应，不代表 API 可以逐字翻译。双栈项目应统一 JSON schema、eval case 和 trace 字段，而不是统一代码写法。
工程边界
- API 参数必须进入代码审查，不要让 prompt 改动绕过 review。
- 工具 schema 是模型和业务之间的契约，字段变更要当 breaking change。
- runtime context 是控制面数据，默认不暴露给模型。
- streaming 是协议，不是 UI 效果；必须定义错误和中断事件。
常见反模式
| 反模式 | 后果 |
|---|---|
只关注 createAgent | 真实问题会落在 model/tool/middleware/context 上 |
| schema 太宽松 | 模型产生看似合法但业务不可用的参数 |
| 工具返回大段原始 JSON | 上下文膨胀，敏感字段泄露 |
| runtime context 未校验 | 工具在 undefined 上执行错误逻辑 |
| streaming 无 done/error | 前端卡住，结果不可审计 |
练习任务
- 给
LangChain/src/tools/tool.ts写一份工具字段审查清单。 - 给
LangChain/src/runtime/types.ts增加requestId，并让 audit 记录它。 - 给学习手册的离线
AgentMiddleware增加wrapToolCall概念，并写测试。