函式工具讓智慧體能夠呼叫你的應用程式碼。你負責定義函式及其引數。智慧體要求呼叫函式後，你的程式碼會回傳結果，任務執行框架則會繼續執行該回合。
你的處理常式可以在應用程式伺服器、背景工作程序或你掌控的環境中執行。將環境附加至工作階段，並不會自動在該環境中執行函式工具。
如果你使用 Responses API 的函式呼叫，就能在此處說明的工作階段流程中重複使用現有的函式實作。
設定智慧體時，請將函式定義新增至 agent.tools，並提供名稱、說明及用於定義引數的 JSON Schema：
1234567891011{
"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 中的函式項目如下所示：
1234567{
"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 中的項目：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const 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 },
],
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14import 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])
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24result := 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)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25var 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());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18require "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])
任務執行框架收到所需結果後，會繼續執行該回合。請追蹤工作階段事件與項目，以查看該回合的執行結果並擷取其輸出。
擷取工作階段以找出待處理動作。如果你已執行過函式，請使用相同的 turn_id 和 call_id 提交已儲存的結果。
對於具有副作用的函式，請依工作階段、回合及呼叫 ID 持久儲存結果。如果函式可能已執行成功，但未儲存結果，請先確認執行結果，再決定是否重新執行函式。
函式預設會預先載入。若要延後載入某個函式，請在其定義中設定 defer_loading: true，並在 agent.tools 中加入 { "type": "tool_search" }。完整範例請參閱工具搜尋。
