Appel d’outils par programmation

L’appel d’outils par programmation permet à un modèle d’écrire et d’exécuter du JavaScript pour coordonner ses outils. Un programme peut appeler des outils en parallèle, utiliser des boucles et des conditions, et conserver les résultats intermédiaires dans l’environnement d’exécution hébergé. Cette approche est utile lorsqu’une tâche nécessite une série d’appels d’outils liés entre eux ou le traitement de sorties d’outils volumineuses avant de renvoyer un résultat.

Dans l’API Responses, votre application détermine si l’appel d’outils par programmation est disponible et quels outils éligibles le modèle peut appeler directement, depuis un programme ou des deux façons. Elle continue d’exécuter tous les appels d’outils gérés côté client. L’API Agents active l’appel d’outils par programmation par défaut et gère la boucle de l’agent pour vous.

Consultez la page du modèle avant d’activer l’appel d’outils par programmation.

Comprenez l’environnement d’exécution

OpenAI exécute chaque programme généré dans un nouvel environnement V8 isolé. Cet environnement prend en charge JavaScript avec await au niveau supérieur, mais ne fournit ni Node.js, ni installation de paquets, ni accès direct au réseau, ni système de fichiers à usage général, ni exécution de sous-processus, ni console, ni état JavaScript persistant entre les exécutions de programmes. Les programmes ne peuvent interagir avec des systèmes externes que par l’intermédiaire des outils activés dans la requête et peuvent produire des sorties avec text(...) ou image(...).

Pour les requêtes à l’API Responses, l’appel d’outils par programmation prend en charge les workflows soumis à une politique de non-conservation des données (ZDR), sans nécessiter de conteneur persistant pour l’exécution du code. La ZDR doit être activée pour l’organisation ou le projet ; le paramètre store: false permet de poursuivre l’exécution sans état, mais n’active pas à lui seul la ZDR. L’éligibilité et la conservation des données dépendent de l’ensemble de la requête, notamment du modèle, des outils et des services tiers utilisés ; consultez les contrôles des données.

Choisissez quand utiliser l’appel d’outils par programmation

Utilisez l’appel d’outils par programmation lorsqu’une étape présente un flux de contrôle prévisible et que le code peut renvoyer un résultat structuré plus compact. Utilisez l’appel direct d’outils lorsqu’un seul appel suffit, que chaque résultat nécessite une nouvelle appréciation du modèle ou que le travail exige une approbation ou la préservation des citations ou des artefacts natifs.

Configurez l’appel d’outils par programmation

Pour l’API Responses, ajoutez l’outil hébergé programmatic_tool_calling à la requête. Définissez ensuite allowed_callers pour chaque outil éligible que le programme peut appeler.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28[
  {
    "type": "function",
    "name": "get_inventory",
    "description": "Return an object with sku (string) and available_units (number).",
    "parameters": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" }
      },
      "required": ["sku"],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" },
        "available_units": { "type": "number" }
      },
      "required": ["sku", "available_units"],
      "additionalProperties": false
    },
    "allowed_callers": ["programmatic"]
  },
  {
    "type": "programmatic_tool_calling"
  }
]

allowed_callers contrôle la façon dont le modèle peut appeler un outil :

parameters décrit les arguments de la fonction. Lorsqu’une fonction renvoie des données structurées prévisibles, output_schema décrit l’objet JSON encodé dans sa chaîne function_call_output.output. Définissez les deux pour que le JavaScript généré puisse utiliser les champs renvoyés de manière fiable.

Outils pris en charge

Les types d’outils suivants prennent en charge allowed_callers: ["programmatic"] :

• function et custom
• mcp
• apply_patch
• shell local et hébergé
• code_interpreter

Pour les outils MCP, la politique require_approval de l’outil peut suspendre le programme jusqu’à ce que vous approuviez l’appel.

Pour les outils hébergés par OpenAI, consultez les consignes de l’outil relatives à la conservation des données et à la sécurité avant de l’activer dans un programme.

Combinez avec la recherche d’outils

La recherche d’outils s’exécute en tant qu’outil de premier niveau de l’API Responses, et non depuis le JavaScript généré. Les outils de type fonction, personnalisés et MCP configurés avec defer_loading: true ne sont pas initialement disponibles pour un programme. Une fois que le modèle a chargé un outil correspondant, un programme ultérieur peut l’appeler via tools.* si son paramètre allowed_callers inclut "programmatic". Un programme déjà en cours d’exécution ne peut pas appeler la recherche d’outils : le modèle doit donc charger les outils différés avant de démarrer un programme qui en a besoin.

Guidez le choix du mode d’appel lorsque les deux modes sont disponibles

Lorsque votre application permet au modèle d’appeler une fonction directement ou depuis un programme, attribuez chaque mode d’appel à une étape précise du workflow. Des instructions génériques comme « utilisez efficacement l’appel d’outils par programmation » ne précisent pas la limite souhaitée. Par exemple :

<tool_orchestration>
Use Programmatic Tool Calling for [bounded stage] using only [eligible tools].
Run independent calls concurrently when safe. Use only documented tool input
and output fields.

Process and reduce the intermediate results, then emit exactly [program result shape],
including the evidence needed for the final answer.

Stop when [condition] is met. Retry transient failures at most [R] times.
Do not repeat completed calls or perform side-effecting actions. If a required
result is still missing, return a clear structured failure.

Use direct tool calls for [semantic judgment, approval, or final validation].
</tool_orchestration>

Voici un exemple d’utilisation de ce modèle :

<tool_orchestration>
Use Programmatic Tool Calling to compare inventory with demand for sku_123
using only get_inventory and get_demand. Run both calls concurrently. Use
only documented tool input and output fields.

Process and reduce the intermediate results, then emit exactly one JSON object
with sku, available_units, requested_units, and shortage_units, where
shortage_units is max(requested_units - available_units, 0). Include
available_units and requested_units as evidence for the calculation.

Stop when both tool results contain the required fields. Retry transient
failures at most 1 time. Do not repeat completed calls or perform
side-effecting actions. If a required result is still missing, return a clear
structured failure.

Use direct tool calls only for approval before any inventory-changing action.
</tool_orchestration>

Pour les workflows qui nécessitent les deux modes, définissez un seul passage de relais et évitez d’alterner entre les modes d’appel ou de répéter le travail. Si une solution de repli sûre existe, définissez-la une seule fois et limitez le nombre de tentatives.

Comprenez les éléments de réponse des programmes

Chaque appel à l’API renvoie toujours l’objet standard de l’API Responses. L’appel d’outils par programmation n’introduit pas d’enveloppe de réponse distincte. Lorsque le modèle utilise l’appel d’outils par programmation, le tableau output de la réponse peut contenir :

• Un élément program contenant le JavaScript généré, un call_id et une valeur opaque fingerprint servant à reprendre ou à rejouer le programme.
• Un élément function_call créé par le programme. Il possède son propre call_id, que votre application utilise pour renvoyer le résultat de la fonction. Son champ caller.caller_id correspond au call_id du programme.
• Un élément program_output contenant le résultat final et l’état du programme. Son champ call_id correspond au call_id du programme, et son champ status vaut completed ou incomplete.

Ce sont des éléments distincts de premier niveau dans response.output ; le champ caller consigne la relation entre leurs exécutions.

Par exemple, un programme peut se mettre en pause pendant que votre application exécute get_inventory et get_demand :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31[
  {
    "type": "program",
    "id": "prog_123",
    "call_id": "call_prog_123",
    "code": "const [stock, demand] = await Promise.all([tools.get_inventory({ sku: 'sku_123' }), tools.get_demand({ sku: 'sku_123' })]); text(JSON.stringify({ sku: stock.sku, available_units: stock.available_units, requested_units: demand.requested_units, shortage_units: Math.max(demand.requested_units - stock.available_units, 0) }));",
    "fingerprint": "opaque_replay_state"
  },
  {
    "type": "function_call",
    "id": "fc_123",
    "call_id": "call_inventory_123",
    "name": "get_inventory",
    "arguments": "{\"sku\":\"sku_123\"}",
    "caller": {
      "type": "program",
      "caller_id": "call_prog_123"
    }
  },
  {
    "type": "function_call",
    "id": "fc_456",
    "call_id": "call_demand_123",
    "name": "get_demand",
    "arguments": "{\"sku\":\"sku_123\"}",
    "caller": {
      "type": "program",
      "caller_id": "call_prog_123"
    }
  }
]

Ces exemples ne montrent que les éléments pertinents de response.output ; ils omettent l’objet Responses standard qui les englobe. Une fois que votre application a renvoyé les résultats des fonctions imbriquées, une réponse ultérieure peut contenir l’élément program_output complet :

1
2
3
4
5
6
7{
  "type": "program_output",
  "id": "prog_out_123",
  "call_id": "call_prog_123",
  "result": "{\"sku\":\"sku_123\",\"available_units\":42,\"requested_units\":31,\"shortage_units\":0}",
  "status": "completed"
}

La chaîne JSON dans program_output.result respecte la structure du résultat du programme définie dans vos instructions. L’élément program_output qui l’entoure respecte le contrat de l’API présenté ci-dessus. Ces deux contrats sont distincts. Un élément message final peut arriver avec la sortie du programme ou dans une réponse ultérieure. Continuez donc jusqu’à recevoir ce message.

OpenAI exécute le JavaScript généré par le modèle dans l’environnement d’exécution hébergé. Votre application exécute les appels de fonction renvoyés qui relèvent du client ; elle n’exécute pas le JavaScript généré.

Renvoyez le résultat de la fonction sous la forme d’un élément function_call_output. Copiez la valeur de caller depuis l’appel de fonction sans la modifier. Le service utilise cette valeur pour reprendre le bon programme.

Poursuivez après les appels de fonction gérés côté client

Un programme peut se mettre en pause plusieurs fois lorsqu’il atteint des outils gérés côté client. Continuez jusqu’à ce que la réponse contienne un message final de l’assistant :

1. Envoyez la requête avec l’outil hébergé et les fonctions qui autorisent les appels par programmation.
2. Exécutez chaque appel de fonction renvoyé qui relève du client.
3. Renvoyez chaque résultat de fonction avec les valeurs d’origine de call_id et de caller.
4. Traitez toute réponse incomplète avant de continuer.
5. Si la réponse ne contient aucun élément function_call en attente ni aucun élément message final, poursuivez à partir de cette réponse. Avec store: false, renvoyez ses éléments de sortie ; pour une réponse stockée, utilisez previous_response_id.
6. Arrêtez-vous lorsque la réponse contient un élément message final. Lisez response.output_text ou le contenu de refus du message.

L’exemple suivant utilise store: false, conserve tous les éléments de réponse et renvoie chaque résultat de fonction au programme :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

const client = new OpenAI();

const implementations = {
  get_inventory: async ({ sku }) => ({ sku, available_units: 42 }),
  get_demand: async ({ sku }) => ({ sku, requested_units: 31 }),
};

const tools = [
  {
    type: "function",
    name: "get_inventory",
    description:
      "Return an object with sku (string) and available_units (number).",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false,
    },
    output_schema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        available_units: { type: "number" },
      },
      required: ["sku", "available_units"],
      additionalProperties: false,
    },
    allowed_callers: ["programmatic"],
    strict: true,
  },
  {
    type: "function",
    name: "get_demand",
    description:
      "Return an object with sku (string) and requested_units (number).",
    parameters: {
      type: "object",
      properties: { sku: { type: "string" } },
      required: ["sku"],
      additionalProperties: false,
    },
    output_schema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        requested_units: { type: "number" },
      },
      required: ["sku", "requested_units"],
      additionalProperties: false,
    },
    allowed_callers: ["programmatic"],
    strict: true,
  },
  { type: "programmatic_tool_calling" },
];

const input = [
  {
    role: "user",
    content: "Compare inventory with demand for sku_123.",
  },
];

while (true) {
  const response = await client.responses.create({
    model: "YOUR_MODEL_ID",
    store: false,
    input,
    tools,
  });

  if (response.status !== "completed") {
    throw new Error(`Response ended with status ${response.status}`);
  }

  // Preserve replayable output, including program and reasoning items.
  input.push(...toResponseInputItems(response.output));

  const calls = response.output.filter((item) => item.type === "function_call");

  if (calls.length === 0) {
    const message = response.output.find((item) => item.type === "message");
    if (message) {
      const refusal = message.content.find((part) => part.type === "refusal");
      console.log(response.output_text || refusal?.refusal || "");
      break;
    }
    continue;
  }

  const outputs = await Promise.all(
    calls.map(async (call) => {
      const run = implementations[call.name];
      if (!run) throw new Error(`Unknown tool: ${call.name}`);

      const result = await run(JSON.parse(call.arguments));
      return {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(result),
        // Preserve caller so the runtime can resume the correct program.
        caller: call.caller,
      };
    })
  );

  input.push(...outputs);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117import json

from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"


def get_inventory(sku):
    return {"sku": sku, "available_units": 42}


def get_demand(sku):
    return {"sku": sku, "requested_units": 31}


implementations = {
    "get_inventory": get_inventory,
    "get_demand": get_demand,
}

tools = [
    {
        "type": "function",
        "name": "get_inventory",
        "description": "Return an object with sku (string) and available_units (number).",
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "available_units": {"type": "number"},
            },
            "required": ["sku", "available_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {
        "type": "function",
        "name": "get_demand",
        "description": "Return an object with sku (string) and requested_units (number).",
        "parameters": {
            "type": "object",
            "properties": {"sku": {"type": "string"}},
            "required": ["sku"],
            "additionalProperties": False,
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "sku": {"type": "string"},
                "requested_units": {"type": "number"},
            },
            "required": ["sku", "requested_units"],
            "additionalProperties": False,
        },
        "allowed_callers": ["programmatic"],
    },
    {"type": "programmatic_tool_calling"},
]

input_items = [
    {
        "role": "user",
        "content": "Compare inventory with demand for sku_123.",
    }
]

while True:
    response = client.responses.create(
        model=model,
        store=False,
        input=input_items,
        tools=tools,
    )

    if response.status != "completed":
        raise RuntimeError(f"Response ended with status {response.status}")

    # Preserve every output item, including program and reasoning items.
    input_items.extend(item.model_dump(exclude_none=True) for item in response.output)

    calls = [item for item in response.output if item.type == "function_call"]
    if not calls:
        message = next(
            (item for item in response.output if item.type == "message"), None
        )
        if message:
            refusal = next(
                (part.refusal for part in message.content if part.type == "refusal"),
                "",
            )
            print(response.output_text or refusal)
            break
        continue

    for call in calls:
        run = implementations.get(call.name)
        if run is None:
            raise ValueError(f"Unknown tool: {call.name}")

        result = run(**json.loads(call.arguments))
        input_items.append(
            {
                "type": "function_call_output",
                "call_id": call.call_id,
                "output": json.dumps(result),
                # Preserve caller so the runtime can resume the correct program.
                "caller": call.caller.model_dump() if call.caller else None,
            }
        )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179package main

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

type toolArguments struct {
	SKU string `json:"sku"`
}

func main() {
	client := openai.NewClient()
	input := responses.ResponseInputParam{
		responses.ResponseInputItemParamOfMessage(
			"Compare inventory with demand for sku_123.",
			responses.EasyInputMessageRoleUser,
		),
	}
	tools := []responses.ToolUnionParam{
		functionTool(
			"get_inventory",
			"Return an object with sku (string) and available_units (number).",
			"available_units",
		),
		functionTool(
			"get_demand",
			"Return an object with sku (string) and requested_units (number).",
			"requested_units",
		),
		programmaticTool(),
	}

	for {
		response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
			Model: "gpt-6-astra",
			Store: openai.Bool(false),
			Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
			Tools: tools,
		})
		if err != nil {
			panic(err)
		}
		if response.Status != "completed" {
			panic(fmt.Errorf("response ended with status %s", response.Status))
		}

		// Preserve every output item, including program and reasoning items.
		input = append(input, outputAsInput(response.Output)...)

		calls := functionCalls(response.Output)
		if len(calls) == 0 {
			if text, ok := finalMessageText(response); ok {
				fmt.Println(text)
				break
			}
			continue
		}

		for _, call := range calls {
			result, err := runTool(call.Name, call.Arguments)
			if err != nil {
				panic(err)
			}
			output, err := json.Marshal(result)
			if err != nil {
				panic(err)
			}

			toolOutput := responses.ResponseInputItemParamOfFunctionCallOutput(string(output))
			toolOutput.OfFunctionCallOutput.CallID = openai.String(call.CallID)
			caller := call.Caller.AsProgram()
			if caller.CallerID == "" {
				panic("function call is missing its program caller")
			}
			// Preserve caller so the runtime can resume the correct program.
			toolOutput.OfFunctionCallOutput.Caller.OfProgram =
				&responses.ResponseInputItemFunctionCallOutputCallerProgramParam{
					CallerID: caller.CallerID,
				}
			input = append(input, toolOutput)
		}
	}
}

func functionTool(name, description, resultField string) responses.ToolUnionParam {
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"sku": map[string]any{"type": "string"},
		},
		"required":             []string{"sku"},
		"additionalProperties": false,
	}
	outputSchema := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"sku":       map[string]any{"type": "string"},
			resultField: map[string]any{"type": "number"},
		},
		"required":             []string{"sku", resultField},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction(name, parameters, true)
	tool.OfFunction.Description = openai.String(description)
	tool.OfFunction.AllowedCallers = []string{"programmatic"}
	tool.OfFunction.OutputSchema = outputSchema
	return tool
}

func programmaticTool() responses.ToolUnionParam {
	tool := responses.NewToolProgrammaticToolCallingParam()
	return responses.ToolUnionParam{OfProgrammaticToolCalling: &tool}
}

func outputAsInput(
	output []responses.ResponseOutputItemUnion,
) []responses.ResponseInputItemUnionParam {
	input := make([]responses.ResponseInputItemUnionParam, 0, len(output))
	for _, item := range output {
		var converted responses.ResponseInputItemUnion
		if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
			panic(err)
		}
		input = append(input, converted.ToParam())
	}
	return input
}

func functionCalls(
	output []responses.ResponseOutputItemUnion,
) []responses.ResponseFunctionToolCall {
	calls := make([]responses.ResponseFunctionToolCall, 0)
	for _, item := range output {
		if item.Type == "function_call" {
			calls = append(calls, item.AsFunctionCall())
		}
	}
	return calls
}

func finalMessageText(response *responses.Response) (string, bool) {
	for _, item := range response.Output {
		if item.Type != "message" {
			continue
		}
		text := response.OutputText()
		if text != "" {
			return text, true
		}
		for _, content := range item.AsMessage().Content {
			if content.Type == "refusal" {
				return content.AsRefusal().Refusal, true
			}
		}
		return "", true
	}
	return "", false
}

func runTool(name, argumentsJSON string) (map[string]any, error) {
	var arguments toolArguments
	if err := json.Unmarshal([]byte(argumentsJSON), &arguments); err != nil {
		return nil, fmt.Errorf("parse %s arguments: %w", name, err)
	}

	switch name {
	case "get_inventory":
		return map[string]any{"sku": arguments.SKU, "available_units": 42}, nil
	case "get_demand":
		return map[string]any{"sku": arguments.SKU, "requested_units": 31}, nil
	default:
		return nil, fmt.Errorf("unknown tool: %s", name)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125require "json"
require "openai"

client = OpenAI::Client.new

def get_inventory(sku:)
  {
    sku: sku,
    available_units: 42
  }
end

def get_demand(sku:)
  {
    sku: sku,
    requested_units: 31
  }
end

implementations = {
  "get_inventory" => method(:get_inventory),
  "get_demand" => method(:get_demand)
}
tools = [
  {
    type: :function,
    name: "get_inventory",
    description: "Return an object with sku (string) and available_units (number).",
    parameters: {
      type: :object,
      properties: { sku: { type: :string } },
      required: ["sku"],
      additionalProperties: false
    },
    output_schema: {
      type: :object,
      properties: {
        sku: { type: :string },
        available_units: { type: :number }
      },
      required: %w[sku available_units],
      additionalProperties: false
    },
    allowed_callers: [:programmatic],
    strict: true
  },
  {
    type: :function,
    name: "get_demand",
    description: "Return an object with sku (string) and requested_units (number).",
    parameters: {
      type: :object,
      properties: { sku: { type: :string } },
      required: ["sku"],
      additionalProperties: false
    },
    output_schema: {
      type: :object,
      properties: {
        sku: { type: :string },
        requested_units: { type: :number }
      },
      required: %w[sku requested_units],
      additionalProperties: false
    },
    allowed_callers: [:programmatic],
    strict: true
  },
  { type: :programmatic_tool_calling }
]
input = [
  {
    role: :user,
    content: "Compare inventory with demand for sku_123."
  }
]

loop do
  response = client.responses.create(
    model: "gpt-6-astra",
    store: false,
    input: input,
    tools: tools
  )
  unless response.status == OpenAI::Responses::ResponseStatus::COMPLETED
    raise "Response ended with status #{response.status}"
  end

  # Preserve every output item, including program and reasoning items.
  input.concat(response.output)
  calls = response.output.grep(OpenAI::Models::Responses::ResponseFunctionToolCall)

  if calls.empty?
    message = response.output.find do |item|
      item.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)
    end
    next unless message.is_a?(OpenAI::Models::Responses::ResponseOutputMessage)

    refusal = message.content.find do |content|
      content.is_a?(OpenAI::Models::Responses::ResponseOutputRefusal)
    end
    text = response.output_text
    if text.empty? &&
       refusal.is_a?(OpenAI::Models::Responses::ResponseOutputRefusal)
      text = refusal.refusal
    end
    puts(text)
    break
  end

  calls.each do |call|
    implementation = implementations.fetch(call.name) do
      raise ArgumentError, "Unknown tool: #{call.name}"
    end
    result = implementation.call(**JSON.parse(call.arguments, symbolize_names: true))
    output = {
      type: :function_call_output,
      call_id: call.call_id,
      output: JSON.generate(result)
    }
    # Preserve caller so the runtime can resume the correct program.
    output[:caller] = call.caller_.to_h if call.caller_
    input << output
  end
end

Lorsque vous stockez les réponses, vous pouvez poursuivre à partir de previous_response_id au lieu de renvoyer tous les éléments des réponses précédentes. Envoyez les nouveaux éléments function_call_output comme entrée suivante. Avec store: false, renvoyez la séquence complète dans l’ordre, en incluant tous les éléments program, de raisonnement, d’appel de fonction, de sortie d’appel de fonction et program_output.

Pour les requêtes sans état adressées à un modèle de raisonnement, renvoyez chaque élément de raisonnement reçu. Chaque élément inclut encrypted_content par défaut. Consultez le guide sur l’état de la conversation pour connaître le fonctionnement général des échanges sans état.

Concevez des outils pour les programmes

• Renvoyez des données structurées et compactes que JavaScript peut examiner sans avoir à analyser du texte rédigé.
• Utilisez output_schema pour définir les champs et les types attendus dans les résultats de chaque outil, et documentez son comportement en cas d’erreur. Si la structure du résultat n’est pas connue à l’avance, conservez l’appel direct de l’outil afin que le modèle puisse examiner le résultat.
• Définissez la structure exacte du résultat du programme et les éléments de preuve requis. Renvoyez une indication d’échec claire et structurée lorsque le programme ne peut pas produire de résultat valide.
• Rendez les appels de fonction idempotents lorsque c’est possible. Une nouvelle tentative ou une réexécution ne devrait pas reproduire un effet de bord dangereux.
• Vérifiez les arguments et les autorisations de chaque appel dans votre application, même lorsqu’il provient d’un programme hébergé.
• Donnez aux outils des noms et des descriptions précis pour que le modèle puisse les combiner correctement.
• Exigez une approbation au niveau de l’application avant toute action à fort impact, quel que soit l’appelant.

Évaluez l’appel d’outils par programmation

L’appel d’outils par programmation peut réduire la quantité de résultats intermédiaires d’outils ajoutés au contexte du modèle, mais son effet dépend de la tâche et des réponses des outils. Prenez d’abord l’appel direct d’outils comme référence, puis comparez les deux approches sur des tâches représentatives.

Définissez le niveau de qualité attendu de la réponse finale et les éléments de preuve requis avant de mesurer l’efficacité. Évaluez la consommation de tokens et les appels d’outils, ainsi que l’exactitude, l’exhaustivité et la couverture des éléments de preuve. Explicitez tout compromis accepté sur la qualité.

Mesurez :

• L’exactitude et l’exhaustivité de la réponse finale, ainsi que la couverture des éléments de preuve.
• Le nombre de tokens en entrée et au total, la latence de bout en bout et le coût.
• Les tours du modèle, les appels d’outils, les nouvelles tentatives et le comportement de reprise après échec.
• Les résultats en matière de sécurité, en particulier pour les effets de bord et les exigences d’approbation.
• L’adéquation entre le mode d’appel effectivement utilisé et l’étape prévue du workflow.

API Agents

Dans l’API Agents, l’appel d’outils par programmation s’exécute dans le harnais d’agent géré par OpenAI et est activé par défaut. Le harnais fournit à l’agent un outil exec et rend ses outils existants accessibles depuis le JavaScript généré. Vous n’avez pas besoin d’encapsuler ces outils dans des programmes en ligne de commande ni de les installer dans le bac à sable.

Pour désactiver l’appel d’outils par programmation, ajoutez cette entrée dans agent.tools :

1234{
  "type": "programmatic_tool_calling",
  "enabled": false
}

Si vous omettez l’entrée ou son champ enabled, l’appel d’outils par programmation reste activé. Une entrée ne contenant que le type, { "type": "programmatic_tool_calling" }, le laisse également activé. La configuration de allowed_callers et la boucle de continuation Responses présentées ci-dessus décrivent l’intégration avec l’API Responses.

L’appel d’outils par programmation fonctionne également dans les sessions limitées à la conversation, avec environment.type défini sur none. Bash, les serveurs MCP d’exécution et les autres outils qui s’exécutent dans un bac à sable nécessitent toujours un environnement d’exécution.

Orchestrer un outil en JavaScript ne change pas l’endroit où il s’exécute. Un appel au shell exécute des commandes dans le bac à sable ; l’environnement d’exécution JavaScript ne lance pas lui-même de processus système. Les serveurs MCP d’exécution utilisent toujours le bac à sable, et les outils de type fonction appellent toujours votre serveur d’application. L’agent traite leurs résultats avant de décider quels éléments intégrer au contexte du modèle.

Utilisez les recommandations ci-dessus sur le choix du mode d’appel pour définir les étapes du workflow qui doivent utiliser du code. Consultez les guides Fonctions et Connexions MCP pour configurer l’API Agents et gérer les appels.

Guides connexes

• Utilisez l’appel de fonction pour définir des fonctions gérées côté client.
• Utilisez la recherche d’outils pour différer le chargement des définitions d’outils volumineuses jusqu’à ce qu’un modèle en ait besoin.
• Utilisez l’état de la conversation pour poursuivre les requêtes de l’API Responses, qu’elles soient stockées ou sans état.
• Consultez les contrôles des données avant de choisir un mode de stockage.