OpenAI 函数工具

函数工具让智能体调用应用代码。应用定义函数及参数，智能体请求调用，应用返回结果后框架继续轮次。

处理器可运行在应用服务器、工作进程或自管环境。为会话附加环境，不会自动让函数工具在其中执行。已有 Responses函数调用实现可复用于此会话流程。

定义函数

配置智能体时，在 agent.tools 添加函数名、描述及参数JSON Schema：

来源示例 1（json）：

程序文字说明26：按ID查询客户。

{
  "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。

函数动作结构如下：

来源示例 2（json）：

{
  "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 中的条目：

来源示例 3（javascript）：

// [中文] 示例 3：返回结果。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// [中文] 结果使用待处理动作的 turn_id 和 call_id；成功返回 output，失败返回 error，避免重复执行已有副作用。
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 },
  ],
});

来源示例 4（python）：

## [中文] 示例 4：返回结果。
## [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
## [中文] 结果使用待处理动作的 turn_id 和 call_id；成功返回 output，失败返回 error，避免重复执行已有副作用。
import json

action = action.to_dict()

result = {
    "type": "agent.session.input.tool_result",
    "turn_id": action["turn_id"],
    "call_id": action["call_id"],
}

output = get_customer(action["arguments"])
result.update(success=True, output=json.dumps(output))

client.beta.agents.sessions.events.create(session_id, events=[result])

来源示例 5（go）：

// [中文] 示例 5：返回结果。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
// [中文] 从待处理动作读取客户 ID，查询后以对应 turn_id、call_id 返回工具结果，不把历史调用当作仍待处理。
result := openai.AgentSessionInputParamAgentSessionInputToolResult{
    TurnID: action.TurnID,
    CallID: action.CallID,
}

arguments := action.Arguments.(map[string]any)
customerID := arguments["customer_id"].(string)
var customer any
if customerID == "123" {
    customer = map[string]any{"name": "Example Customer", "plan": "pro"}
}
output, err := json.Marshal(map[string]any{"found": customer != nil, "customer": customer})
if err != nil {
    panic(err)
}
result.Success = true
result.Output = openai.AgentFunctionCallOutputParamUnion{OfString: openai.String(string(output))}

err = client.Beta.Agents.Sessions.Events.New(ctx, session.ID, openai.BetaAgentSessionEventNewParams{
    Events: []openai.AgentSessionInputParamUnion{{OfParamAgentSessionInputToolResult: &result}},
})
if err != nil {
    panic(err)
}

来源示例 6（java）：

// [中文] 示例 6：返回结果。
// [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
var json = new JsonMapper();

var result =
    AgentSessionInputParam.AgentSessionInputToolResult.builder()
        .turnId(action.turnId())
        .callId(action.callId());
var arguments = json.valueToTree(action._arguments());

boolean found = arguments.path("customer_id").asText().equals("123");
var output = json.createObjectNode().put("found", found);
if (found)
  output.putObject("customer").put("name", "Example Customer").put("plan", "pro");
else output.putNull("customer");
result.success(true).output(json.writeValueAsString(output));

client
    .beta()
    .agents()
    .sessions()
    .events()
    .create(
        EventCreateParams.builder()
            .sessionId(sessionId)
            .addEvent(result.build())
            .build());

来源示例 7（ruby）：

## [中文] 示例 7：返回结果。
## [中文] 向会话事件端点提交输入；各事件的关联标识按载荷保留。
## [中文] 结果使用待处理动作的 turn_id 和 call_id；成功返回 output，失败返回 error，避免重复执行已有副作用。
require "json"

result = {
  type: "agent.session.input.tool_result",
  turn_id: action.turn_id,
  call_id: action.call_id
}
arguments = action.arguments

customer_id = arguments[:customer_id] || arguments["customer_id"]
customer = (customer_id == "123") ? {
  name: "Example Customer",
  plan: "pro"
} : nil
result[:success] = true
result[:output] = JSON.generate(found: !customer.nil?, customer: customer)

client.beta.agents.sessions.events.create(session.id, events: [result])

所需结果返回后，框架继续轮次。通过会话事件与项目检查最终结果和输出。

结果大小

结果因过大被拒时，缩至4 MiB（4,194,304字节）以下，预留API元数据空间。调用仍待处理时，以相同 turn_id 和 call_id 重试。

断连后恢复

读取会话寻找待处理动作。函数已执行时，使用相同 turn_id、call_id 提交已保存结果。

有副作用的函数，按会话、轮次、调用ID持久保存结果。可能已成功却没有保存结果时，先检查操作结果再决定是否重跑。

按需加载函数

默认急切加载全部函数。要延迟某函数，在定义上设 defer_loading: true，并在 agent.tools 包含 { "type": "tool_search" }，完整示例见工具搜索。