関数 | OpenAI API

関数ツールを使うと、エージェントからアプリケーションのコードを呼び出せます。開発者は関数とその引数を定義します。エージェントが関数の呼び出しを要求し、アプリケーションのコードが結果を返すと、ハーネスがターンを続行します。

ハンドラーは、アプリケーションサーバー、ワーカー、または開発者が管理する環境で実行できます。セッションに環境を接続しただけでは、その環境で関数ツールが自動的に実行されることはありません。

Responses API の Function Calling を使用している場合は、ここで説明するセッションの処理手順でも、既存の関数の実装を再利用できます。

関数の定義

agent.tools に関数定義を追加するのは、エージェントの設定時です。関数の名前と説明、引数の JSON スキーマを指定します。

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 内の該当項目です。

関数の結果を返す例

JavaScript

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])

ハーネスは、必要な結果を受け取るとターンを続行します。セッションのイベントと項目を追跡すると、ターンがどのように終了したかを確認し、その出力を取得できます。

結果のサイズ

ツールの結果が大きすぎて API に拒否された場合は、Agents API のメタデータ用に少し余裕を持たせ、結果を 4 MiB（4,194,304 バイト）未満に縮小します。呼び出しがまだ保留中であれば、同じ turn_id と call_id で結果を再送信します。

切断後の復旧

セッションを取得して、保留中のアクションを確認します。関数をすでに実行している場合は、同じ turn_id と call_id を使って、保存済みの結果を送信します。

副作用のある関数では、セッション ID、ターン ID、呼び出し ID の組み合わせごとに結果を永続化します。実行に成功した可能性があるのに結果が保存されていない場合は、関数を再実行する前に実行結果を確認します。

関数のオンデマンド読み込み

デフォルトでは、関数はあらかじめ読み込まれます。必要になるまで関数の読み込みを遅らせるには、関数定義に defer_loading: true を設定し、{ "type": "tool_search" } を agent.tools に追加します。完全な例は「ツール検索」を参照してください。

おすすめ

はじめに

基本概念

SDK と CLI

クラウドプロバイダー

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプトの書き方

推論

画像

リアルタイム処理とオーディオ

特化型モデル

Agents API

Agents SDK

ChatKit

検索と情報取得

ツールとデータの接続

ツールを使ったワークフローの構築

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を使った開発

接続

音声処理

本番稼働の開始

パフォーマンスと品質

評価

コストとスループット

安全性とガバナンス

インフラとアクセス

業務運営

基本概念

計画

開発

テストと公開

コンバージョン仕様

ガイド

リソース

アイデンティティ

ChatGPT プランの利用状況

ガイド

ファイルのアップロード

API

効果測定

広告主向け API

API リファレンス

はじめに

はじめに

基礎

探す

対応プラットフォーム

リリース

ワークフロー

できること

Sites

dot

ChatGPT Space

リファレンス

カスタマイズ

設定ファイル

エージェントの設定

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

機能拡張と自動化

環境

Codex Cloud

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバー安全対策

はじめに

機能設定

ID とアクセス管理