如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

函数

定义函数、处理待完成的调用并返回结果。

函数工具让智能体可以调用您的应用代码。您负责定义函数及其参数。智能体发起调用请求,您的代码返回结果,随后执行框架继续处理当前轮次。

您的处理程序可以在应用服务器、工作进程或您控制的环境中运行。将环境关联到会话后,函数工具不会自动在该环境中运行。

如果您使用 Responses API 的函数调用功能,可以在本文介绍的会话流程中复用现有的函数实现。

定义函数

向 agent.tools 添加函数定义这一步应在配置智能体时完成。请指定函数名称和描述,并用 JSON 模式定义其参数:

{
  "type": "function",
  "name": "get_customer",
  "description": "Look up a customer by ID.",
  "parameters": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"],
    "additionalProperties": false
  }
}

处理待办操作

当智能体需要函数结果时,会话会发出 agent.session.requires_action 事件。从 event.session.required_actions 中读取待完成的调用。如果不使用流式传输,您也可以获取会话并读取 session.required_actions。

以下是 required_actions 中的一个函数调用条目:

{
  "type": "function_call",
  "turn_id": "turn_123",
  "call_id": "call_123",
  "name": "get_customer",
  "arguments": { "customer_id": "123" }
}

使用条目中提供的参数运行指定的函数。请根据 required_actions 判断哪些调用仍需返回结果。仅凭会话历史记录中的 function_call 条目,无法确定该调用是否仍在等待结果。

返回结果

请将 agent.session.input.tool_result 发送到会话事件端点。从待办操作中复制 turn_id 和 call_id:

  • 如果调用成功,请设置 success: true,并以字符串或受支持的内容数组形式提供 output。如果结果是 JSON 对象,请将其序列化为字符串。
  • 如果调用出错,请设置 success: false,并在 error 中提供智能体可以使用的错误信息。

对于每个待完成的 get_customer 调用,请查询客户并返回结果。示例中的 action 是 required_actions 中的条目:

返回函数结果
const result = {
  turn_id: action.turn_id,
  call_id: action.call_id,
};
let outcome;

outcome = {
  success: true,
  output: JSON.stringify(getCustomer(action.arguments)),
};

await client.beta.agents.sessions.events.create(sessionId, {
  events: [
    { type: "agent.session.input.tool_result", ...result, ...outcome },
  ],
});

执行框架收到所需结果后,会继续处理当前轮次。请跟踪会话事件和条目,以确认该轮次的执行结果并获取其输出。

结果大小

如果 API 因工具结果过大而拒绝接收,请将结果缩小至不足 4 MiB(4,194,304 字节),为 Agents API 元数据预留少量空间。请在调用仍在等待结果时,使用相同的 turn_id 和 call_id 重试。

断开连接后恢复

获取会话以查找待办操作。如果您已经运行过某个函数,请使用相同的 turn_id 和 call_id 提交已保存的结果。

对于有副作用的函数,请按会话 ID、轮次 ID 和调用 ID 持久化存储结果。如果函数可能已经执行成功,但未保存结果,请先核实执行结果,再决定是否重新运行该函数。

按需加载函数

默认情况下,函数会预先加载。要延迟加载某个函数,请在其定义中设置 defer_loading: true,并将 { "type": "tool_search" } 添加到 agent.tools。完整示例请参阅工具搜索。