如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 持久儲存結果。如果函式可能已執行成功,但未儲存結果,請先確認執行結果,再決定是否重新執行函式。

視需要載入函式

預設會預先載入函式。若要延後載入某個函式,請在其定義中設定 defer_loading: true,並將 { "type": "tool_search" } 加入 agent.tools。完整範例請參閱工具搜尋。