Appel de fonction | OpenAI API

L’appel de fonction (également appelé appel d’outil) offre aux modèles OpenAI un moyen puissant et flexible d’interagir avec des systèmes externes et d’accéder à des données autres que leurs données d’entraînement. Ce guide vous montre comment connecter un modèle aux données et aux actions fournies par votre application. Nous verrons comment utiliser les outils de type fonction (définis par un schéma JSON) et les outils personnalisés, qui acceptent du texte libre en entrée et en sortie.

Pour les sessions de l’API Agents, utilisez les Fonctions pour enregistrer des fonctions et traiter les demandes d’action de la session. Les exemples de ce guide présentent les intégrations avec l’API Responses et Chat Completions.

Si votre application comporte de nombreuses fonctions ou des schémas volumineux, vous pouvez associer l’appel de fonction à la recherche d’outils pour différer le chargement des outils rarement utilisés et ne les charger que lorsque le modèle en a besoin. Seuls gpt-5.4 et les modèles ultérieurs prennent en charge tool_search.

GPT-6 Astra nécessite l’API Responses pour les appels d’outils. Les exemples Chat Completions utilisent GPT-5.6 pour des raisons de compatibilité. Consultez le guide de migration pour mettre à jour une intégration existante.

Fonctionnement

Commençons par quelques termes clés liés aux appels d’outils. Une fois ce vocabulaire commun établi, nous vous montrerons comment procéder à l’aide d’exemples pratiques.

Un résultat d’appel de fonction ou un résultat d’appel d’outil est la réponse qu’un outil génère à partir des données d’entrée de l’appel d’outil du modèle. Ce résultat peut être du JSON structuré ou du texte brut et doit contenir une référence à un appel d’outil précis du modèle (identifié par call_id dans les exemples qui suivent). Pour compléter notre exemple météo :

Le modèle a accès à un outil get_weather qui prend location comme argument.
En réponse à un prompt comme « Quel temps fait-il à Paris ? », le modèle renvoie un appel d’outil contenant un argument location dont la valeur est Paris
Le résultat de l’appel d’outil peut être un objet JSON (par exemple, {"temperature": "25", "unit": "C"}, indiquant une température actuelle de 25 degrés), le contenu d’une image ou le contenu d’un fichier.

Nous renvoyons ensuite au modèle la définition de l’outil, le prompt d’origine, l’appel d’outil du modèle et le résultat de cet appel pour obtenir enfin une réponse textuelle comme :

The weather in Paris today is 25C.

Déroulement des appels d’outils

L’appel d’outil est une conversation en plusieurs étapes entre votre application et un modèle via l’API OpenAI. Il se déroule en cinq grandes étapes :

Envoyez une requête au modèle avec les outils qu’il pourrait appeler
Recevez un appel d’outil du modèle
Exécutez du code côté application avec les données d’entrée de l’appel d’outil
Envoyez une deuxième requête au modèle avec le résultat de l’outil
Recevez une réponse finale du modèle (ou d’autres appels d’outils)

Schéma des étapes de l’appel de fonction

Avec Responses, votre application peut poursuivre ce processus aussi longtemps que la tâche nécessite des appels d’outils. Si vous souhaitez un framework qui prend en charge les opérations d’orchestration récurrentes autour de cette boucle, consultez la comparaison entre l’API Responses et l’Agents SDK.

Exemple d’outil de type fonction

Voyons un exemple complet d’appel d’outil avec une fonction get_horoscope qui récupère l’horoscope du jour pour un signe astrologique.

Exemple complet d’appel d’outil

Python

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
70import OpenAI from "openai";

const openai = new OpenAI();

// 1. Define a list of callable tools for the model

const tools = [
  {
    type: "function",
    function: {
      name: "get_horoscope",
      description: "Get today's horoscope for an astrological sign.",
      parameters: {
        type: "object",
        properties: {
          sign: {
            type: "string",
            description: "An astrological sign like Taurus or Aquarius",
          },
        },
        required: ["sign"],
        additionalProperties: false,
      },
      strict: true,
    },
  },
];

function getHoroscope(sign) {
  return `${sign}: Next Tuesday you will befriend a baby otter.`;
}

const messages = [
  { role: "user", content: "What is my horoscope? I am an Aquarius." },
];

// 2. Prompt the model with tools defined
let response = await openai.chat.completions.create({
  model: "gpt-5.6",
  messages,
  tools,
});

messages.push(response.choices[0].message);

for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  if (toolCall.type !== "function") continue;

  if (toolCall.function.name === "get_horoscope") {
    // 3. Execute the function logic for get_horoscope
    const args = JSON.parse(toolCall.function.arguments);
    const horoscope = getHoroscope(args.sign);

    // 4. Provide function call results to the model
    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      content: JSON.stringify({ horoscope }),
    });
  }
}

response = await openai.chat.completions.create({
  model: "gpt-5.6",
  messages,
  tools,
});

// 5. The model should be able to give a response!
console.log(response.choices[0].message.content);

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
67from openai import OpenAI
import json

client = OpenAI()

# 1. Define a list of callable tools for the model
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_horoscope",
            "description": "Get today's horoscope for an astrological sign.",
            "parameters": {
                "type": "object",
                "properties": {
                    "sign": {
                        "type": "string",
                        "description": "An astrological sign like Taurus or Aquarius",
                    },
                },
                "required": ["sign"],
                "additionalProperties": False,
            },
            "strict": True,
        },
    },
]


def get_horoscope(sign):
    return f"{sign}: Next Tuesday you will befriend a baby otter."


messages = [{"role": "user", "content": "What is my horoscope? I am an Aquarius."}]

# 2. Prompt the model with tools defined
response = client.chat.completions.create(
    model="gpt-5.6",
    messages=messages,
    tools=tools,
)

messages.append(response.choices[0].message)

for tool_call in response.choices[0].message.tool_calls or []:
    if tool_call.function.name == "get_horoscope":
        # 3. Execute the function logic for get_horoscope
        args = json.loads(tool_call.function.arguments)
        horoscope = get_horoscope(args["sign"])

        # 4. Provide function call results to the model
        messages.append(
            {
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps({"horoscope": horoscope}),
            }
        )

response = client.chat.completions.create(
    model="gpt-5.6",
    messages=messages,
    tools=tools,
)

# 5. The model should be able to give a response!
print(response.choices[0].message.content)

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
69package main

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

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

func main() {
	client := openai.NewClient()
	tool := horoscopeChatTool()
	messages := []openai.ChatCompletionMessageParamUnion{
		openai.UserMessage("What is my horoscope? I am an Aquarius."),
	}
	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6", Messages: messages, Tools: []openai.ChatCompletionToolUnionParam{tool},
		ReasoningEffort: shared.ReasoningEffortNone,
	})
	if err != nil {
		panic(err)
	}
	messages = append(messages, completion.Choices[0].Message.ToParam())

	for _, call := range completion.Choices[0].Message.ToolCalls {
		if call.Type != "function" || call.Function.Name != "get_horoscope" {
			continue
		}
		var arguments struct {
			Sign string `json:"sign"`
		}
		if err := json.Unmarshal([]byte(call.Function.Arguments), &arguments); err != nil {
			panic(err)
		}
		horoscope := getHoroscope(arguments.Sign)
		messages = append(messages, openai.ToolMessage(horoscope, call.ID))
	}

	completion, err = client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6", Messages: messages, Tools: []openai.ChatCompletionToolUnionParam{tool},
		ReasoningEffort: shared.ReasoningEffortNone,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(completion.Choices[0].Message.Content)
}

func horoscopeChatTool() openai.ChatCompletionToolUnionParam {
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"sign": map[string]any{"type": "string", "description": "An astrological sign like Taurus or Aquarius"},
		},
		"required":             []string{"sign"},
		"additionalProperties": false,
	}
	return openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
		Function: shared.FunctionDefinitionParam{
			Name: "get_horoscope", Description: openai.String("Get today's horoscope for an astrological sign."), Parameters: parameters, Strict: openai.Bool(true),
		},
	}}
}

func getHoroscope(sign string) string {
	return fmt.Sprintf("%s: Next Tuesday you will befriend a baby otter.", sign)
}

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
59import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionToolMessageParam;
import java.util.List;
import java.util.Map;

FunctionDefinition horoscope =
    FunctionDefinition.builder()
        .name("get_horoscope")
        .description("Get today's horoscope for an astrological sign.")
        .parameters(
            FunctionParameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties",
                    JsonValue.from(
                        Map.of(
                            "sign",
                            Map.of(
                                "type", "string",
                                "description",
                                    "An astrological sign like Taurus or Aquarius"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("sign")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-5.6")
        .addUserMessage("What is my horoscope? I am an Aquarius.")
        .addFunctionTool(horoscope)
        .build();

var assistant = client.chat().completions().create(params).choices().get(0).message();
var calls = assistant.toolCalls().orElseThrow(() -> new IllegalStateException("No tool calls"));
var followUp = params.toBuilder().addMessage(assistant);
record HoroscopeArguments(String sign) {}

for (var toolCall : calls) {
  var function = toolCall.asFunction();
  if (function.function().name().equals("get_horoscope")) {
    String sign = function.function().arguments(HoroscopeArguments.class).sign();
    followUp.addMessage(
        ChatCompletionToolMessageParam.builder()
            .toolCallId(function.id())
            .content(sign + ": Embrace an unexpected opportunity today.")
            .build());
  }
}

client.chat().completions().create(followUp.build()).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

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
60require "json"
require "openai"

client = OpenAI::Client.new
messages = [
  {
    role: :user,
    content: "What is my horoscope? I am an Aquarius."
  }
]
tools = [
  {
    type: :function,
    function: {
      name: "get_horoscope",
      description: "Get today's horoscope for an astrological sign.",
      parameters: {
        type: :object,
        properties: { sign: { type: :string } },
        required: ["sign"],
        additionalProperties: false
      },
      strict: true
    }
  }
]

first_completion = client.chat.completions.create(
  model: "gpt-5.6",
  messages: messages,
  tools: tools
)
assistant_message = first_completion.choices.fetch(0).message
tool_calls = assistant_message.tool_calls || []
raise "The model did not call get_horoscope" if tool_calls.empty?

messages << {
  role: :assistant,
  content: assistant_message.content,
  tool_calls: tool_calls.map(&:to_h)
}
tool_calls.each do |tool_call|
  next unless tool_call.is_a?(OpenAI::Models::Chat::ChatCompletionMessageFunctionToolCall)
  next unless tool_call.function.name == "get_horoscope"

  arguments = JSON.parse(tool_call.function.arguments, symbolize_names: true)
  sign = arguments.fetch(:sign)
  messages << {
    role: :tool,
    tool_call_id: tool_call.id,
    content: "#{sign}: Embrace an unexpected opportunity today."
  }
end

final_completion = client.chat.completions.create(
  model: "gpt-5.6",
  messages: messages,
  tools: tools
)
puts(final_completion.choices.fetch(0).message.content)

Exemple complet d’appel d’outil

Python

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
77import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

const openai = new OpenAI();

// 1. Define a list of callable tools for the model

const tools = [
  {
    type: "function",
    name: "get_horoscope",
    description: "Get today's horoscope for an astrological sign.",
    parameters: {
      type: "object",
      properties: {
        sign: {
          type: "string",
          description: "An astrological sign like Taurus or Aquarius",
        },
      },
      required: ["sign"],
      additionalProperties: false,
    },
    strict: true,
  },
];

function getHoroscope(sign) {
  return `${sign}: Next Tuesday you will befriend a baby otter.`;
}

// Create a running input list we will add to over time

let input = [
  { role: "user", content: "What is my horoscope? I am an Aquarius." },
];

// 2. Prompt the model with tools defined
let response = await openai.responses.create({
  model: "gpt-6-astra",
  tools,
  input,
});

// Preserve model output for the next turn
input.push(...toResponseInputItems(response.output));

for (const item of response.output) {
  if (item.type !== "function_call") continue;

  if (item.name === "get_horoscope") {
    // 3. Execute the function logic for get_horoscope
    const { sign } = JSON.parse(item.arguments);
    const horoscope = getHoroscope(sign);

    // 4. Provide function call results to the model
    input.push({
      type: "function_call_output",
      call_id: item.call_id,
      output: horoscope,
    });
  }
}

console.log("Final input:");
console.log(JSON.stringify(input, null, 2));

response = await openai.responses.create({
  model: "gpt-6-astra",
  instructions: "Respond only with a horoscope generated by a tool.",
  tools,
  input,
});

// 5. The model should be able to give a response!
console.log("Final output:");
console.log(response.output_text);

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
72from openai import OpenAI
import json

client = OpenAI()

# 1. Define a list of callable tools for the model
tools = [
    {
        "type": "function",
        "name": "get_horoscope",
        "description": "Get today's horoscope for an astrological sign.",
        "parameters": {
            "type": "object",
            "properties": {
                "sign": {
                    "type": "string",
                    "description": "An astrological sign like Taurus or Aquarius",
                },
            },
            "required": ["sign"],
        },
    },
]


def get_horoscope(sign):
    return f"{sign}: Next Tuesday you will befriend a baby otter."


# Create a running input list we will add to over time
input_list = [{"role": "user", "content": "What is my horoscope? I am an Aquarius."}]

# 2. Prompt the model with tools defined
response = client.responses.create(
    model="gpt-6-astra",
    tools=tools,
    input=input_list,
)

# Save function call outputs for subsequent requests
input_list += response.output

for item in response.output:
    if item.type == "function_call":
        if item.name == "get_horoscope":
            # 3. Execute the function logic for get_horoscope
            sign = json.loads(item.arguments)["sign"]
            horoscope = get_horoscope(sign)

            # 4. Provide function call results to the model
            input_list.append(
                {
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": horoscope,
                }
            )

print("Final input:")
print(input_list)

response = client.responses.create(
    model="gpt-6-astra",
    instructions="Respond only with a horoscope generated by a tool.",
    tools=tools,
    input=input_list,
)

# 5. The model should be able to give a response!
print("Final output:")
print(response.model_dump_json(indent=2))
print("\n" + response.output_text)

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
75package main

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

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

func main() {
	client := openai.NewClient()
	tool := horoscopeResponseTool()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is my horoscope? I am an Aquarius.")},
		Tools: []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}

	var functionOutput responses.ResponseInputItemUnionParam
	for _, output := range response.Output {
		if output.Type != "function_call" {
			continue
		}
		call := output.AsFunctionCall()
		if call.Name != "get_horoscope" {
			continue
		}
		var arguments struct {
			Sign string `json:"sign"`
		}
		if err := json.Unmarshal([]byte(call.Arguments), &arguments); err != nil {
			panic(err)
		}
		functionOutput = responses.ResponseInputItemParamOfFunctionCallOutput(getHoroscope(arguments.Sign))
		functionOutput.OfFunctionCallOutput.CallID = openai.String(call.CallID)
	}
	if functionOutput.OfFunctionCallOutput == nil {
		panic("the model did not call get_horoscope")
	}

	response, err = client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:              "gpt-6-astra",
		PreviousResponseID: openai.String(response.ID),
		Instructions:       openai.String("Respond only with a horoscope generated by a tool."),
		Input:              responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{functionOutput}},
		Tools:              []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

func horoscopeResponseTool() responses.ToolUnionParam {
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"sign": map[string]any{"type": "string", "description": "An astrological sign like Taurus or Aquarius"},
		},
		"required":             []string{"sign"},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction("get_horoscope", parameters, true)
	tool.OfFunction.Description = openai.String("Get today's horoscope for an astrological sign.")
	return tool
}

func getHoroscope(sign string) string {
	return fmt.Sprintf("%s: Next Tuesday you will befriend a baby otter.", sign)
}

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
71import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;

FunctionTool horoscope =
    FunctionTool.builder()
        .name("get_horoscope")
        .description("Get today's horoscope for an astrological sign.")
        .parameters(
            FunctionTool.Parameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties",
                    JsonValue.from(
                        Map.of(
                            "sign",
                            Map.of(
                                "type", "string",
                                "description",
                                    "An astrological sign like Taurus or Aquarius"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("sign")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();

var firstResponse =
    client
        .responses()
        .create(
            ResponseCreateParams.builder()
                .model("gpt-6-astra")
                .input("What is my horoscope? I am an Aquarius.")
                .addTool(horoscope)
                .build());

var functionCall =
    firstResponse.output().stream()
        .flatMap(item -> item.functionCall().stream())
        .filter(call -> call.name().equals("get_horoscope"))
        .findFirst()
        .orElseThrow(() -> new IllegalStateException("The model did not call get_horoscope"));

record HoroscopeArguments(String sign) {}

String sign = functionCall.arguments(HoroscopeArguments.class).sign();
ResponseCreateParams followUp =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .instructions("Respond only with a horoscope generated by a tool.")
        .previousResponseId(firstResponse.id())
        .inputOfResponse(
            List.of(
                ResponseInputItem.ofFunctionCallOutput(
                    ResponseInputItem.FunctionCallOutput.builder()
                        .callId(functionCall.callId())
                        .output(sign + ": Embrace an unexpected opportunity today.")
                        .build())))
        .addTool(horoscope)
        .build();

client.responses().create(followUp).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

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
48require "json"
require "openai"

client = OpenAI::Client.new
tools = [
  {
    type: :function,
    name: "get_horoscope",
    description: "Get today's horoscope for an astrological sign.",
    parameters: {
      type: :object,
      properties: { sign: { type: :string } },
      required: ["sign"],
      additionalProperties: false
    },
    strict: true
  }
]

first_response = client.responses.create(
  model: "gpt-6-astra",
  input: "What is my horoscope? I am an Aquarius.",
  tools: tools
)
function_call = first_response.output.find do |item|
  item.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall) &&
    item.name == "get_horoscope"
end
unless function_call.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)
  raise "The model did not call get_horoscope"
end

arguments = JSON.parse(function_call.arguments, symbolize_names: true)
sign = arguments.fetch(:sign)
response = client.responses.create(
  model: "gpt-6-astra",
  previous_response_id: first_response.id,
  input: [
    {
      type: :function_call_output,
      call_id: function_call.call_id,
      output: "#{sign}: Embrace an unexpected opportunity today."
    }
  ],
  tools: tools
)

puts(response.output_text)

Pour les modèles de raisonnement comme GPT-5 ou o4-mini, tous les éléments de raisonnement renvoyés dans les réponses du modèle contenant des appels d’outils doivent également être retransmis avec les résultats de ces appels.

Définition des fonctions

Les fonctions sont généralement déclarées dans le paramètre tools de chaque requête API. Avec la recherche d’outils, votre application peut également charger des fonctions de manière différée au cours de l’interaction. Dans les deux cas, chaque fonction appelable utilise la même structure de schéma. La définition d’une fonction comporte les propriétés suivantes :

Champ	Description
`type`	La valeur doit toujours être `function`
`name`	Le nom de la fonction (par exemple, `get_weather`)
`description`	Précisions sur les situations dans lesquelles utiliser la fonction et sur la manière de l’utiliser
`parameters`	Schéma JSON définissant les arguments d’entrée de la fonction
`strict`	Indique si le mode strict doit être imposé à l’appel de fonction

Voici un exemple de définition pour une fonction get_weather

12345678910111213141516171819202122{
  "type": "function",
  "name": "get_weather",
  "description": "Retrieves current weather for the given location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and country e.g. Bogotá, Colombia"
      },
      "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Units the temperature will be returned in."
      }
    },
    "required": ["location", "units"],
    "additionalProperties": false
  },
  "strict": true
}

Comme parameters est défini par un schéma JSON, vous pouvez utiliser ses nombreuses fonctionnalités, notamment les types de propriétés, les énumérations, les descriptions, les objets imbriqués et les objets récursifs.

Définition des espaces de noms

Utilisez des espaces de noms pour regrouper les outils apparentés par domaine, comme crm, billing ou shipping. Les espaces de noms facilitent l’organisation d’outils similaires et sont particulièrement utiles lorsque le modèle doit choisir entre des outils destinés à des systèmes ou à des usages différents, par exemple un outil de recherche pour votre CRM et un autre pour votre système de gestion des tickets d’assistance.

12345678910111213141516171819202122232425262728293031323334{
  "type": "namespace",
  "name": "crm",
  "description": "CRM tools for customer lookup and order management.",
  "tools": [
    {
      "type": "function",
      "name": "get_customer_profile",
      "description": "Fetch a customer profile by customer ID.",
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    },
    {
      "type": "function",
      "name": "list_open_orders",
      "description": "List open orders for a customer ID.",
      "defer_loading": true,
      "parameters": {
        "type": "object",
        "properties": {
          "customer_id": { "type": "string" }
        },
        "required": ["customer_id"],
        "additionalProperties": false
      }
    }
  ]
}

Recherche d’outils

Si vous devez donner au modèle accès à un vaste écosystème d’outils, vous pouvez différer le chargement de tout ou partie de ces outils avec tool_search. L’outil tool_search permet au modèle de rechercher des outils pertinents, de les ajouter à son contexte, puis de les utiliser. Seuls gpt-5.4 et les modèles ultérieurs le prennent en charge. Consultez le guide de la recherche d’outils pour en savoir plus.

Nous vous encourageons à définir directement les schémas de vos fonctions, mais nos SDK proposent des utilitaires pour convertir les objets pydantic et zod en schémas. Certaines fonctionnalités de pydantic et de zod ne sont pas prises en charge.

Définissez des objets pour représenter le schéma de la fonction

Python

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
26import OpenAI from "openai";
import { z } from "zod";
import { zodFunction } from "openai/helpers/zod";

const openai = new OpenAI();

const GetWeatherParameters = z.object({
  location: z.string().describe("City and country e.g. Bogotá, Colombia"),
});

const tools = [
  zodFunction({ name: "getWeather", parameters: GetWeatherParameters }),
];

const messages = [
  { role: "user", content: "What's the weather like in Paris today?" },
];

const response = await openai.chat.completions.create({
  model: "gpt-5.6",
  messages,
  tools,
  store: true,
});

console.log(response.choices[0].message.tool_calls);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19from openai import OpenAI, pydantic_function_tool
from pydantic import BaseModel, Field

client = OpenAI()


class GetWeather(BaseModel):
    location: str = Field(..., description="City and country e.g. Bogotá, Colombia")


tools = [pydantic_function_tool(GetWeather)]

completion = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
)

print(completion.choices[0].message.tool_calls)

Bonnes pratiques pour définir des fonctions

Choisissez des noms de fonctions clairs et rédigez des descriptions de paramètres et des instructions précises et détaillées.
- Décrivez explicitement le rôle de la fonction et de chaque paramètre (ainsi que son format), et précisez ce que représente la sortie.
- Utilisez le prompt système pour décrire quand utiliser chaque fonction et quand ne pas l’utiliser. De manière générale, indiquez au modèle exactement ce qu’il doit faire.
- Incluez des exemples et des cas limites, notamment pour corriger les échecs récurrents. (Remarque : l’ajout d’exemples peut nuire aux performances des modèles de raisonnement.)
- Pour les outils à chargement différé, placez les instructions détaillées dans la description de la fonction et gardez une description concise de l’espace de noms. L’espace de noms aide le modèle à choisir ce qu’il doit charger ; la description de la fonction l’aide à utiliser correctement l’outil chargé.
Appliquez les bonnes pratiques du génie logiciel.
- Rendez les fonctions prévisibles et intuitives. (Principe de moindre surprise)
- Utilisez des énumérations et la structure des objets pour empêcher les états invalides. Par exemple, toggle_light(on: bool, off: bool) autorise des appels invalides.
- Passez le test du stagiaire. Un stagiaire, ou toute autre personne, peut-il utiliser correctement la fonction avec les seules informations fournies au modèle ? (Si ce n’est pas le cas, quelles questions vous pose-t-il ? Ajoutez les réponses au prompt.)
Allégez la charge du modèle en utilisant du code chaque fois que possible.
- Ne demandez pas au modèle de renseigner des arguments dont vous connaissez déjà la valeur. Par exemple, si vous disposez déjà d’un order_id obtenu à partir d’un menu précédent, n’incluez pas de paramètre order_id. Définissez plutôt submit_refund() sans paramètres et transmettez order_id dans votre code.
- Regroupez les fonctions qui sont toujours appelées l’une après l’autre. Par exemple, si vous appelez toujours mark_location() après query_location(), intégrez simplement la logique de marquage à la fonction de recherche.
Limitez le nombre de fonctions disponibles dès le départ pour améliorer la précision.
- Évaluez les performances avec différents nombres de fonctions.
- Visez moins de 20 fonctions disponibles au début de chaque tour , même s’il ne s’agit que d’une recommandation indicative.
- Utilisez la recherche d’outils pour différer le chargement des ensembles d’outils volumineux ou rarement utilisés, au lieu de tout exposer dès le départ.
Utilisez les ressources d’OpenAI.
- Générez des schémas de fonctions et améliorez-les progressivement dans le Playground.
- Envisagez l’affinage pour améliorer la précision des appels de fonction lorsque les fonctions sont nombreuses ou les tâches difficiles. (Cookbook)

Utilisation des tokens

En interne, les fonctions sont injectées dans le message système selon une syntaxe sur laquelle le modèle a été entraîné. Les définitions des fonctions appelables sont donc prises en compte dans la limite de contexte du modèle et facturées comme des tokens d’entrée. Si vous atteignez les limites de tokens, nous vous conseillons de limiter le nombre de fonctions chargées dès le départ, de raccourcir les descriptions lorsque c’est possible ou d’utiliser la recherche d’outils pour ne charger les outils à chargement différé qu’en cas de besoin.

Vous pouvez également recourir à l’affinage pour réduire le nombre de tokens utilisés si votre spécification d’outils définit de nombreuses fonctions.

Gestion des appels de fonction

Lorsque le modèle appelle une fonction, vous devez l’exécuter et renvoyer le résultat. Comme les réponses du modèle peuvent contenir zéro, un ou plusieurs appels, il est recommandé de prévoir le cas où il y en a plusieurs.

La réponse contient un tableau tool_calls dont chaque élément comporte un id (utilisé ensuite pour transmettre le résultat de la fonction) et un objet function contenant un name et des arguments encodés en JSON.

Exemple de réponse contenant plusieurs appels de fonction

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[
    {
        "id": "call_12345xyz",
        "type": "function",
        "function": {
            "name": "get_weather",
            "arguments": "{\"location\":\"Paris, France\"}"
        }
    },
    {
        "id": "call_67890abc",
        "type": "function",
        "function": {
            "name": "get_weather",
            "arguments": "{\"location\":\"Bogotá, Colombia\"}"
        }
    },
    {
        "id": "call_99999def",
        "type": "function",
        "function": {
            "name": "send_email",
            "arguments": "{\"to\":\"bob@email.com\",\"body\":\"Hi bob\"}"
        }
    }
]

Exécutez les appels de fonction et ajoutez les résultats

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15messages.push(completion.choices[0].message);

for (const toolCall of completion.choices[0].message.tool_calls ?? []) {
  if (toolCall.type !== "function") continue;

  const name = toolCall.function.name;
  const args = JSON.parse(toolCall.function.arguments);

  const result = await callFunction(name, args);
  messages.push({
    role: "tool",
    tool_call_id: toolCall.id,
    content: result.toString(),
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14messages.append(completion.choices[0].message)

for tool_call in completion.choices[0].message.tool_calls or []:
    name = tool_call.function.name
    args = json.loads(tool_call.function.arguments)

    result = call_function(name, args)
    messages.append(
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result),
        }
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16messages = append(messages, completion.Choices[0].Message.ToParam())

for _, toolCall := range completion.Choices[0].Message.ToolCalls {
	if toolCall.Type != "function" {
		continue
	}
	var arguments functionArguments
	if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &arguments); err != nil {
		panic(err)
	}
	result, err := callFunction(toolCall.Function.Name, arguments)
	if err != nil {
		panic(err)
	}
	messages = append(messages, openai.ToolMessage(result, toolCall.ID))
}

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
36import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionToolMessageParam;
import java.util.List;
import java.util.Map;

var assistant = client.chat().completions().create(params).choices().get(0).message();
var history = params.toBuilder().addMessage(assistant);
for (var item : assistant.toolCalls().orElseThrow()) {
  var call = item.asFunction();
  String output;
  if (call.function().name().equals("get_weather")) {
    record Coordinates(double latitude, double longitude) {}
    Coordinates coordinates = call.function().arguments(Coordinates.class);
    output =
        JsonValue.from(
                Map.of(
                    "latitude", coordinates.latitude(),
                    "longitude", coordinates.longitude(),
                    "temperature_c", 18))
            .toString();
  } else if (call.function().name().equals("send_email")) {
    record Email(String to, String body) {}
    Email message = call.function().arguments(Email.class);
    output = JsonValue.from(Map.of("to", message.to(), "status", "sent")).toString();
  } else {
    throw new IllegalArgumentException("Unknown function: " + call.function().name());
  }
  history.addMessage(
      ChatCompletionToolMessageParam.builder().toolCallId(call.id()).content(output).build());
  System.out.println(call.id() + " " + output);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18message = completion.choices.fetch(0).message
messages << message

Array(message.tool_calls).each do |tool_call|
  next unless tool_call.is_a?(
    OpenAI::Models::Chat::ChatCompletionMessageFunctionToolCall
  )

  name = tool_call.function.name
  arguments = JSON.parse(tool_call.function.arguments)
  result = call_function(name, arguments)

  messages << {
    role: :tool,
    tool_call_id: tool_call.id,
    content: JSON.generate(result)
  }
end

Le tableau output de la réponse contient une entrée dont le champ type a pour valeur function_call. Chaque entrée comporte un call_id (utilisé ensuite pour transmettre le résultat de la fonction), un name et des arguments encodés en JSON.

Exemple de réponse contenant plusieurs appels de fonction

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23[
    {
        "id": "fc_12345xyz",
        "call_id": "call_12345xyz",
        "type": "function_call",
        "name": "get_weather",
        "arguments": "{\"location\":\"Paris, France\"}"
    },
    {
        "id": "fc_67890abc",
        "call_id": "call_67890abc",
        "type": "function_call",
        "name": "get_weather",
        "arguments": "{\"location\":\"Bogotá, Colombia\"}"
    },
    {
        "id": "fc_99999def",
        "call_id": "call_99999def",
        "type": "function_call",
        "name": "send_email",
        "arguments": "{\"to\":\"bob@email.com\",\"body\":\"Hi bob\"}"
    }
]

Si vous utilisez la recherche d’outils, des éléments tool_search_call et tool_search_output peuvent également apparaître avant un function_call. Une fois la fonction chargée, traitez l’appel de fonction de la manière présentée ici.

Exécutez les appels de fonction et ajoutez les résultats

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

input.push(...toResponseInputItems(response.output));

for (const toolCall of response.output) {
  if (toolCall.type !== "function_call") {
    continue;
  }

  const name = toolCall.name;
  const args = JSON.parse(toolCall.arguments);

  const result = await callFunction(name, args);
  input.push({
    type: "function_call_output",
    call_id: toolCall.call_id,
    output: result.toString(),
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17input_messages += response.output

for tool_call in response.output:
    if tool_call.type != "function_call":
        continue

    name = tool_call.name
    args = json.loads(tool_call.arguments)

    result = call_function(name, args)
    input_messages.append(
        {
            "type": "function_call_output",
            "call_id": tool_call.call_id,
            "output": json.dumps(result),
        }
    )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19input = append(input, responseOutputAsInput(response.Output)...)

for _, output := range response.Output {
	if output.Type != "function_call" {
		continue
	}
	toolCall := output.AsFunctionCall()
	var arguments functionArguments
	if err := json.Unmarshal([]byte(toolCall.Arguments), &arguments); err != nil {
		panic(err)
	}
	result, err := callFunction(toolCall.Name, arguments)
	if err != nil {
		panic(err)
	}
	toolOutput := responses.ResponseInputItemParamOfFunctionCallOutput(result)
	toolOutput.OfFunctionCallOutput.CallID = openai.String(toolCall.CallID)
	input = append(input, toolOutput)
}

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
47import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

response.output().stream()
    .map(item -> JsonValue.from(item).convert(ResponseInputItem.class))
    .forEach(input::add);
response.output().stream()
    .flatMap(item -> item.functionCall().stream())
    .forEach(
        call -> {
          String result;
          if (call.name().equals("get_weather")) {
            record Coordinates(double latitude, double longitude) {}

            Coordinates coordinates = call.arguments(Coordinates.class);
            result =
                JsonValue.from(
                        Map.of(
                            "latitude", coordinates.latitude(),
                            "longitude", coordinates.longitude(),
                            "temperature_c", 18))
                    .toString();
          } else if (call.name().equals("send_email")) {
            record Email(String to, String body) {}

            Email message = call.arguments(Email.class);
            result = JsonValue.from(Map.of("to", message.to(), "status", "sent")).toString();
          } else {
            throw new IllegalArgumentException("Unknown function: " + call.name());
          }
          var output =
              ResponseInputItem.ofFunctionCallOutput(
                  ResponseInputItem.FunctionCallOutput.builder()
                      .callId(call.callId())
                      .output(result)
                      .build());
          input.add(output);
          System.out.println(call.callId() + " " + result);
        });

1
2
3
4
5
6
7
8
9
10
11
12
13
14input.concat(response.output)

response.output.each do |tool_call|
  next unless tool_call.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)

  arguments = JSON.parse(tool_call.arguments)
  result = call_function(tool_call.name, arguments)

  input << {
    type: :function_call_output,
    call_id: tool_call.call_id,
    output: JSON.generate(result)
  }
end

Dans l’exemple ci-dessus, nous utilisons une fonction hypothétique call_function pour acheminer chaque appel. Voici une implémentation possible :

Exécutez les appels de fonction et ajoutez les résultats

Python

1
2
3
4
5
6
7
8
9const callFunction = async (name, args) => {
  if (name === "get_weather") {
    return getWeather(args.latitude, args.longitude);
  }
  if (name === "send_email") {
    return sendEmail(args.to, args.body);
  }
  throw new Error(`Unknown function: ${name}`);
};

1
2
3
4
5
6def call_function(name, args):
    if name == "get_weather":
        return get_weather(**args)
    if name == "send_email":
        return send_email(**args)
    raise ValueError(f"Unknown function: {name}")

1
2
3
4
5
6
7
8
9
10func callFunction(name string, arguments functionArguments) (string, error) {
	switch name {
	case "get_weather":
		return getWeather(arguments.Location), nil
	case "send_email":
		return sendEmail(arguments.To, arguments.Body), nil
	default:
		return "", fmt.Errorf("unknown function: %s", name)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16def call_function(name, arguments)
  case name
  when "get_weather"
    FunctionCallingExample.get_weather(
      arguments.fetch("latitude"),
      arguments.fetch("longitude")
    )
  when "send_email"
    FunctionCallingExample.send_email(
      arguments.fetch("to"),
      arguments.fetch("body")
    )
  else
    raise ArgumentError, "Unknown function: #{name}"
  end
end

Format des résultats

Le résultat transmis dans le message function_call_output devrait généralement être une chaîne de caractères, dont vous choisissez le format (JSON, codes d’erreur, texte brut, etc.). Le modèle interprétera cette chaîne selon les besoins.

Pour les fonctions qui renvoient des images ou des fichiers, vous pouvez transmettre un tableau d’objets image ou fichier au lieu d’une chaîne de caractères.

Si votre fonction ne renvoie aucune valeur (par exemple, send_email), renvoyez une chaîne de caractères qui indique la réussite ou l’échec, comme "success".

Intégration des résultats à la réponse

Après avoir ajouté les résultats à messages, vous pouvez les renvoyer au modèle pour obtenir une réponse finale.

Renvoyez les résultats au modèle

Python

1
2
3
4
5
6const completion = await openai.chat.completions.create({
  model: "gpt-5.6",
  messages,
  tools,
  store: true,
});

1
2
3
4
5
6
7completion = client.chat.completions.create(
    model="gpt-5.6",
    messages=messages,
    tools=chat_tools,
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9completion, err = client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
	Model:           "gpt-5.6",
	Messages:        messages,
	Tools:           tools,
	ReasoningEffort: shared.ReasoningEffortNone,
})
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
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
54import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.chat.completions.ChatCompletionAssistantMessageParam;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionMessageFunctionToolCall;
import com.openai.models.chat.completions.ChatCompletionToolMessageParam;
import java.util.List;
import java.util.Map;

FunctionDefinition weather =
    FunctionDefinition.builder()
        .name("get_weather")
        .description("Get the weather for a city.")
        .parameters(
            FunctionParameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("city")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-5.6")
        .addUserMessage("What is the weather in Paris?")
        .addMessage(
            ChatCompletionAssistantMessageParam.builder()
                .addToolCall(
                    ChatCompletionMessageFunctionToolCall.builder()
                        .id("call_weather")
                        .function(
                            ChatCompletionMessageFunctionToolCall.Function.builder()
                                .name("get_weather")
                                .arguments("{\"city\":\"Paris\"}")
                                .build())
                        .build())
                .build())
        .addMessage(
            ChatCompletionToolMessageParam.builder()
                .toolCallId("call_weather")
                .content("{\"city\":\"Paris\",\"temperature_c\":18}")
                .build())
        .addFunctionTool(weather)
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

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
48require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-5.6",
  messages: [
    {
      role: :user,
      content: "What is the weather in Paris?"
    },
    {
      role: :assistant,
      tool_calls: [
        {
          id: "call_weather",
          type: :function,
          function: {
            name: "get_weather",
            arguments: '{"city":"Paris"}'
          }
        }
      ]
    },
    {
      role: :tool,
      tool_call_id: "call_weather",
      content: '{"city":"Paris","temperature_c":18}'
    }
  ],
  tools: [
    {
      type: :function,
      function: {
        name: "get_weather",
        description: "Get the weather for a city",
        parameters: {
          type: :object,
          properties: { city: { type: :string } },
          required: ["city"],
          additionalProperties: false
        },
        strict: true
      }
    }
  ]
)

puts(completion.choices.fetch(0).message.content)

Après avoir ajouté les résultats à input, vous pouvez les renvoyer au modèle pour obtenir une réponse finale.

Renvoyez les résultats au modèle

Python

1
2
3
4
5const response = await openai.responses.create({
  model: "gpt-6-astra",
  input,
  tools,
});

1
2
3
4
5
6
7response = client.responses.create(
    model="gpt-6-astra",
    input=input_messages,
    tools=responses_tools,
)

print(response.output_text)

1
2
3
4
5
6
7
8response, err = client.Responses.New(context.Background(), responses.ResponseNewParams{
	Model: "gpt-6-astra",
	Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
	Tools: tools,
})
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
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
55import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseFunctionToolCall;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;

FunctionTool weather =
    FunctionTool.builder()
        .name("get_weather")
        .description("Get the weather for a city.")
        .parameters(
            FunctionTool.Parameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("city")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .inputOfResponse(
            List.of(
                ResponseInputItem.ofEasyInputMessage(
                    EasyInputMessage.builder()
                        .role(EasyInputMessage.Role.USER)
                        .content("What is the weather like in Paris?")
                        .build()),
                ResponseInputItem.ofFunctionCall(
                    ResponseFunctionToolCall.builder()
                        .callId("call_weather")
                        .name("get_weather")
                        .arguments("{\"city\":\"Paris\"}")
                        .build()),
                ResponseInputItem.ofFunctionCallOutput(
                    ResponseInputItem.FunctionCallOutput.builder()
                        .callId("call_weather")
                        .output("{\"city\":\"Paris\",\"temperature_c\":18}")
                        .build())))
        .addTool(weather)
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

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
41require "openai"

client = OpenAI::Client.new
input = [
  {
    role: :user,
    content: "What is the weather like in Paris?"
  },
  {
    type: :function_call,
    call_id: "call_weather",
    name: "get_weather",
    arguments: '{"city":"Paris"}'
  },
  {
    type: :function_call_output,
    call_id: "call_weather",
    output: '{"city":"Paris","temperature_c":18}'
  }
]
tools = [
  {
    type: :function,
    name: "get_weather",
    description: "Get the weather for a city",
    parameters: {
      type: :object,
      properties: { city: { type: :string } },
      required: ["city"],
      additionalProperties: false
    },
    strict: true
  }
]
response = client.responses.create(
  model: "gpt-6-astra",
  input: input,
  tools: tools
)

puts(response.output_text)

Réponse finale

"It's about 15°C in Paris, 18°C in Bogotá, and I've sent that email to Bob."

Configurations supplémentaires

Choix des outils

Par défaut, le modèle détermine quand utiliser des outils et combien en utiliser. Vous pouvez imposer un comportement précis avec le paramètre tool_choice.

Automatique : (Par défaut) Appelez zéro, une ou plusieurs fonctions. tool_choice: "auto"
Obligatoire : Appelez une ou plusieurs fonctions. tool_choice: "required"
Fonction imposée : Appelez exactement une fonction précise. tool_choice: {"type": "function", "name": "get_weather"}
Outils autorisés : Limitez les appels d’outils que le modèle peut effectuer à un sous-ensemble des outils à sa disposition.

Quand utiliser allowed_tools

Vous pouvez configurer une liste allowed_tools pour ne rendre disponible qu’un sous-ensemble d’outils au fil des requêtes au modèle, sans modifier la liste d’outils transmise, afin de maximiser les économies réalisées grâce à la mise en cache des prompts.

123456789"tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
        { "type": "function", "name": "get_weather" },
        { "type": "function", "name": "search_docs" }
    ]
  }
}

Vous pouvez également définir tool_choice sur "none" pour obtenir le même comportement que si vous ne transmettiez aucune fonction.

Lorsque vous utilisez la recherche d’outils, tool_choice s’applique toujours aux outils qui peuvent être appelés à ce stade du tour. C’est particulièrement utile après avoir chargé un sous-ensemble d’outils, lorsque vous souhaitez limiter le modèle à ce sous-ensemble.

Appels de fonction en parallèle

Sur les modèles compatibles à partir de GPT-5, les fonctions peuvent être appelées en parallèle lorsque des outils intégrés sont également disponibles. Les outils intégrés ne peuvent pas être inclus dans un lot d’appels de fonction en parallèle.

Le modèle peut choisir d’appeler plusieurs fonctions au cours d’un même tour. Vous pouvez l’en empêcher en définissant parallel_tool_calls sur false, ce qui garantit qu’aucun outil ou un seul outil sera appelé.

Remarque : Actuellement, si vous utilisez un modèle affiné et que celui-ci appelle plusieurs fonctions au cours d’un même tour, le mode strict sera désactivé pour ces appels.

Remarque concernant gpt-4.1-nano-2025-04-14 : Cette version de gpt-4.1-nano peut parfois inclure plusieurs appels au même outil si les appels d’outils en parallèle sont activés. Il est recommandé de désactiver cette fonctionnalité lorsque vous utilisez cette version.

Mode strict

Définir strict sur true garantit que les appels de fonction respectent le schéma de la fonction, au lieu de simplement tenter de s’y conformer. Nous recommandons de toujours activer le mode strict.

Le mode strict s’appuie sur notre fonctionnalité de sorties structurées et impose donc quelques exigences :

additionalProperties doit être défini sur false pour chaque objet dans parameters.
Tous les champs de properties doivent être marqués comme required.

Vous pouvez indiquer qu’un champ est facultatif en ajoutant null parmi les options de type (voir l’exemple ci-dessous).

Si vous transmettez strict: true et que votre schéma ne respecte pas les exigences ci-dessus, la requête sera rejetée avec des précisions sur les contraintes manquantes. Si vous omettez strict, le comportement par défaut dépend de l’API : les requêtes Responses tentent de normaliser votre schéma pour le rendre conforme au mode strict lorsque c’est possible, et reviennent à des appels de fonction non stricts, sans garantie de conformité, si le schéma ne peut pas être rendu compatible avec le mode strict. Dans ce cas, l’outil présent dans la réponse affichera strict: false. Les requêtes Chat Completions restent non strictes par défaut. Pour désactiver le mode strict dans Responses et conserver des appels de fonction non stricts, sans garantie de conformité, définissez explicitement strict: false.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retrieves current weather for the given location.",
        "strict": true,
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia"
                },
                "units": {
                    "type": ["string", "null"],
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Units the temperature will be returned in."
                }
            },
            "required": ["location", "units"],
            "additionalProperties": false
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retrieves current weather for the given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia"
                },
                "units": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Units the temperature will be returned in."
                }
            },
            "required": ["location"],
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22{
    "type": "function",
    "name": "get_weather",
    "description": "Retrieves current weather for the given location.",
    "strict": true,
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country e.g. Bogotá, Colombia"
            },
            "units": {
                "type": ["string", "null"],
                "enum": ["celsius", "fahrenheit"],
                "description": "Units the temperature will be returned in."
            }
        },
        "required": ["location", "units"],
        "additionalProperties": false
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20{
    "type": "function",
    "name": "get_weather",
    "description": "Retrieves current weather for the given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City and country e.g. Bogotá, Colombia"
            },
            "units": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Units the temperature will be returned in."
            }
        },
        "required": ["location"],
    }
}

Le mode strict est activé pour tous les schémas générés dans le Playground.

Bien que nous recommandions d’activer le mode strict, celui-ci présente quelques limites :

Certaines fonctionnalités de JSON Schema ne sont pas prises en charge. (Consultez les schémas pris en charge.)

Pour les modèles affinés en particulier :

Les schémas font l’objet d’un traitement supplémentaire lors de la première requête, puis sont mis en cache. Si vos schémas varient d’une requête à l’autre, cela peut augmenter la latence.
Les schémas sont mis en cache pour améliorer les performances et ne sont pas éligibles à la politique de non-conservation des données.

Streaming

Le streaming permet de montrer la progression en indiquant quelle fonction est appelée pendant que le modèle renseigne ses arguments, voire en affichant les arguments en temps réel.

Le streaming des appels de fonction ressemble beaucoup à celui des réponses classiques : vous définissez stream sur true et recevez des fragments contenant des objets delta.

Streaming des appels de fonction

Python

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
40import { OpenAI } from "openai";

const openai = new OpenAI();

const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get current temperature for a given location.",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "City and country e.g. Bogotá, Colombia",
          },
        },
        required: ["location"],
        additionalProperties: false,
      },
      strict: true,
    },
  },
];

const stream = await openai.chat.completions.create({
  model: "gpt-5.6",
  messages: [
    { role: "user", content: "What's the weather like in Paris today?" },
  ],
  tools,
  stream: true,
  store: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0].delta;
  console.log(delta.tool_calls);
}

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
36from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current temperature for a given location.",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City and country e.g. Bogotá, Colombia",
                    }
                },
                "required": ["location"],
                "additionalProperties": False,
            },
            "strict": True,
        },
    }
]

stream = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    print(delta.tool_calls)

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
40package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string", "description": "City and country e.g. Bogotá, Colombia"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
		Function: shared.FunctionDefinitionParam{Name: "get_weather", Parameters: parameters, Strict: openai.Bool(true)},
	}}
	stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("What's the weather like in Paris today?"),
		},
		Tools:           []openai.ChatCompletionToolUnionParam{tool},
		ReasoningEffort: shared.ReasoningEffortNone,
	})
	for stream.Next() {
		if len(stream.Current().Choices) > 0 {
			fmt.Println(stream.Current().Choices[0].Delta.ToolCalls)
		}
	}
	if err := stream.Err(); 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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.chat.completions.ChatCompletionChunk;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import java.util.List;
import java.util.Map;

FunctionDefinition weather =
    FunctionDefinition.builder()
        .name("get_weather")
        .description("Get the weather for a city.")
        .parameters(
            FunctionParameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("city")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();
ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-5.6")
        .addUserMessage("What is the weather in Paris?")
        .addFunctionTool(weather)
        .build();

try (StreamResponse<ChatCompletionChunk> stream =
    client.chat().completions().createStreaming(params)) {
  stream.stream()
      .flatMap(chunk -> chunk.choices().stream())
      .flatMap(choice -> choice.delta().toolCalls().stream())
      .flatMap(List::stream)
      .forEach(System.out::println);
}

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
34require "openai"

client = OpenAI::Client.new
stream = client.chat.completions.stream(
  model: "gpt-5.6",
  messages: [
    {
      role: :user,
      content: "What is the weather in Paris?"
    }
  ],
  tools: [
    {
      type: :function,
      function: {
        name: "get_weather",
        description: "Get the weather for a city",
        parameters: {
          type: :object,
          properties: { city: { type: :string } },
          required: ["city"],
          additionalProperties: false
        },
        strict: true
      }
    }
  ]
)

stream.each do |event|
  next unless event.is_a?(OpenAI::Helpers::Streaming::ChatChunkEvent)

  puts(event.chunk.choices.first&.delta&.tool_calls)
end

Sortie delta.tool_calls

1
2
3
4
5
6
7
8
9[{"index": 0, "id": "call_DdmO9pD3xa9XTPNJ32zg2hcA", "function": {"arguments": "", "name": "get_weather"}, "type": "function"}]
[{"index": 0, "id": null, "function": {"arguments": "{\"", "name": null}, "type": null}]
[{"index": 0, "id": null, "function": {"arguments": "location", "name": null}, "type": null}]
[{"index": 0, "id": null, "function": {"arguments": "\":\"", "name": null}, "type": null}]
[{"index": 0, "id": null, "function": {"arguments": "Paris", "name": null}, "type": null}]
[{"index": 0, "id": null, "function": {"arguments": ",", "name": null}, "type": null}]
[{"index": 0, "id": null, "function": {"arguments": " France", "name": null}, "type": null}]
[{"index": 0, "id": null, "function": {"arguments": "\"}", "name": null}, "type": null}]
null

Cependant, au lieu d’assembler les fragments pour former une seule chaîne content, vous les assemblez pour former un objet JSON arguments encodé.

Lorsque le modèle appelle une ou plusieurs fonctions, le champ tool_calls de chaque delta est renseigné. Chaque tool_call contient les champs suivants :

Champ	Description
`index`	Indique à quel appel de fonction le `delta` correspond
`id`	Identifiant de l’appel d’outil.
`function`	Delta de l’appel de fonction (`name` et `arguments`)
`type`	Type de `tool_call` (toujours `function` pour les appels de fonction)

De nombreux champs, comme id, function.name et type, ne sont renseignés que dans le premier delta de chaque appel d’outil.

L’extrait de code ci-dessous montre comment agréger les éléments delta dans un objet tool_calls final.

Accumulation des deltas de tool_call

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18const finalToolCalls = {};

for await (const chunk of stream) {
  const toolCalls = chunk.choices[0].delta.tool_calls || [];
  for (const toolCall of toolCalls) {
    const { index } = toolCall;

    const accumulated = (finalToolCalls[index] ??= {
      id: toolCall.id,
      type: toolCall.type,
      function: { name: toolCall.function?.name, arguments: "" },
    });
    accumulated.id ??= toolCall.id;
    accumulated.type ??= toolCall.type;
    accumulated.function.name ??= toolCall.function?.name;
    accumulated.function.arguments += toolCall.function?.arguments ?? "";
  }
}

1
2
3
4
5
6
7
8
9
10final_tool_calls = {}

for chunk in stream:
    for tool_call in chunk.choices[0].delta.tool_calls or []:
        index = tool_call.index

        if index not in final_tool_calls:
            final_tool_calls[index] = tool_call

        final_tool_calls[index].function.arguments += tool_call.function.arguments

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
53package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
		Function: shared.FunctionDefinitionParam{Name: "get_weather", Parameters: parameters, Strict: openai.Bool(true)},
	}}
	stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("What's the weather like in Paris today?"),
		},
		Tools:           []openai.ChatCompletionToolUnionParam{tool},
		ReasoningEffort: shared.ReasoningEffortNone,
	})

	finalToolCalls := map[int64]openai.ChatCompletionChunkChoiceDeltaToolCall{}
	for stream.Next() {
		chunk := stream.Current()
		if len(chunk.Choices) == 0 {
			continue
		}
		for _, toolCall := range chunk.Choices[0].Delta.ToolCalls {
			finalToolCall, ok := finalToolCalls[toolCall.Index]
			if !ok {
				finalToolCalls[toolCall.Index] = toolCall
				continue
			}
			finalToolCall.Function.Arguments += toolCall.Function.Arguments
			finalToolCalls[toolCall.Index] = finalToolCall
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
	fmt.Println(finalToolCalls)
}

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
59import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.chat.completions.ChatCompletionChunk;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

FunctionDefinition weather =
    FunctionDefinition.builder()
        .name("get_weather")
        .description("Get the weather for a city.")
        .parameters(
            FunctionParameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("location", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("location")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();
ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-5.6")
        .addUserMessage("What is the weather in Paris?")
        .addFunctionTool(weather)
        .build();

record ToolCall(String id, String type, String name, StringBuilder arguments) {}
Map<Long, ToolCall> toolCalls = new LinkedHashMap<>();
try (StreamResponse<ChatCompletionChunk> stream =
    client.chat().completions().createStreaming(params)) {
  stream.stream()
      .flatMap(chunk -> chunk.choices().stream())
      .flatMap(choice -> choice.delta().toolCalls().stream())
      .flatMap(List::stream)
      .forEach(
          delta -> {
            ToolCall toolCall =
                toolCalls.computeIfAbsent(
                    delta.index(),
                    ignored ->
                        new ToolCall(
                            delta.id().orElseThrow(),
                            delta.type().orElseThrow().asString(),
                            delta.function().flatMap(function -> function.name()).orElseThrow(),
                            new StringBuilder()));
            delta
                .function()
                .flatMap(function -> function.arguments())
                .ifPresent(toolCall.arguments()::append);
          });
}
toolCalls.values().forEach(System.out::println);

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
48require "openai"

client = OpenAI::Client.new
stream = client.chat.completions.stream(
  model: "gpt-5.6",
  messages: [
    {
      role: :user,
      content: "What is the weather in Paris?"
    }
  ],
  tools: [
    {
      type: :function,
      function: {
        name: "get_weather",
        parameters: {
          type: :object,
          properties: { location: { type: :string } },
          required: ["location"],
          additionalProperties: false
        },
        strict: true
      }
    }
  ]
)

tool_calls = {}
stream.each do |event|
  next unless event.is_a?(OpenAI::Helpers::Streaming::ChatChunkEvent)

  (event.chunk.choices.first&.delta&.tool_calls || []).each do |delta|
    tool_call = tool_calls[delta.index] ||= {
      id: nil,
      type: nil,
      function: {
        name: nil,
        arguments: +""
      }
    }
    tool_call[:id] ||= delta.id
    tool_call[:type] ||= delta.type
    tool_call[:function][:name] ||= delta.function&.name
    tool_call[:function][:arguments] << delta.function&.arguments.to_s
  end
end
puts(tool_calls.sort.to_h.values)

final_tool_calls[0] après accumulation

1
2
3
4
5
6
7
8{
    "index": 0,
    "id": "call_RzfkBpJgzeR0S242qfvjadNe",
    "function": {
        "name": "get_weather",
        "arguments": "{\"location\":\"Paris, France\"}"
    }
}

Le streaming permet de suivre la progression en indiquant quelle fonction est appelée à mesure que le modèle renseigne ses arguments, et même en affichant ces arguments en temps réel.

Le streaming des appels de fonction fonctionne de manière très similaire à celui des réponses classiques : définissez stream sur true pour recevoir différents objets event.

Streaming des appels de fonction

Python

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
33import { OpenAI } from "openai";

const openai = new OpenAI();

const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get current temperature for provided coordinates in celsius.",
    parameters: {
      type: "object",
      properties: {
        latitude: { type: "number" },
        longitude: { type: "number" },
      },
      required: ["latitude", "longitude"],
      additionalProperties: false,
    },
    strict: true,
  },
];

const stream = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{ role: "user", content: "What's the weather like in Paris today?" }],
  tools,
  stream: true,
  store: true,
});

for await (const event of stream) {
  console.log(event);
}

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
32from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get current temperature for a given location.",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and country e.g. Bogotá, Colombia",
                }
            },
            "required": ["location"],
            "additionalProperties": False,
        },
    }
]

stream = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
    stream=True,
)

for event in stream:
    print(event)

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
33package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string", "description": "City and country e.g. Bogotá, Colombia"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction("get_weather", parameters, true)
	stream := client.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What's the weather like in Paris today?")},
		Tools: []responses.ToolUnionParam{tool},
	})
	for stream.Next() {
		fmt.Println(stream.Current().Type)
	}
	if err := stream.Err(); 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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseStreamEvent;
import java.util.List;
import java.util.Map;

FunctionTool weather =
    FunctionTool.builder()
        .name("get_weather")
        .description("Get the weather for a city.")
        .parameters(
            FunctionTool.Parameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("city")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();
ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What is the weather in Paris?")
        .addTool(weather)
        .build();

try (StreamResponse<ResponseStreamEvent> stream = client.responses().createStreaming(params)) {
  stream.stream()
      .forEach(
          event -> {
            System.out.println(event);
            event
                .outputItemAdded()
                .ifPresent(added -> System.out.println("response.output_item.added: " + added));
            event
                .functionCallArgumentsDelta()
                .ifPresent(
                    delta ->
                        System.out.println("response.function_call_arguments.delta: " + delta));
          });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23require "openai"

client = OpenAI::Client.new
stream = client.responses.stream(
  model: "gpt-6-astra",
  input: "What is the weather in Paris?",
  tools: [
    {
      type: :function,
      name: "get_weather",
      description: "Get the weather for a city",
      parameters: {
        type: :object,
        properties: { city: { type: :string } },
        required: ["city"],
        additionalProperties: false
      },
      strict: true
    }
  ]
)

stream.each { |event| puts(event.type) }

Événements de sortie

1
2
3
4
5
6
7
8
9
10{"type":"response.output_item.added","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":""}}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"{\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"location"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\":\""}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"Paris"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":","}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":" France"}
{"type":"response.function_call_arguments.delta","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"delta":"\"}"}
{"type":"response.function_call_arguments.done","response_id":"resp_1234xyz","item_id":"fc_1234xyz","output_index":0,"arguments":"{\"location\":\"Paris, France\"}"}
{"type":"response.output_item.done","response_id":"resp_1234xyz","output_index":0,"item":{"type":"function_call","id":"fc_1234xyz","call_id":"call_1234xyz","name":"get_weather","arguments":"{\"location\":\"Paris, France\"}"}}

Cependant, au lieu d’agréger les fragments dans une seule chaîne content, vous les agrégez dans un objet arguments encodé en JSON.

Lorsque le modèle appelle une ou plusieurs fonctions, un événement de type response.output_item.added est émis pour chaque appel de fonction. Cet événement contient les champs suivants :

Champ	Description
`response_id`	L’identifiant de la réponse à laquelle appartient l’appel de fonction
`output_index`	L’index de l’élément de sortie dans la réponse. Il permet de distinguer les différents appels de fonction de la réponse.
`item`	L’élément d’appel de fonction en cours, qui comprend les champs `name`, `arguments` et `id`

Vous recevez ensuite une série d’événements de type response.function_call_arguments.delta, qui contiennent le delta du champ arguments. Ces événements contiennent les champs suivants :

Champ	Description
`response_id`	L’identifiant de la réponse à laquelle appartient l’appel de fonction
`item_id`	L’identifiant de l’élément d’appel de fonction auquel appartient le delta
`output_index`	L’index de l’élément de sortie dans la réponse. Il permet de distinguer les différents appels de fonction de la réponse.
`delta`	Le delta du champ `arguments`.

L’extrait de code ci-dessous montre comment agréger les éléments delta dans un objet tool_call final.

Accumulation des deltas de tool_call

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16const finalToolCalls = {};

for await (const event of stream) {
  if (
    event.type === "response.output_item.added" &&
    event.item.type === "function_call"
  ) {
    finalToolCalls[event.output_index] = event.item;
  } else if (event.type === "response.function_call_arguments.delta") {
    const index = event.output_index;

    if (finalToolCalls[index]) {
      finalToolCalls[index].arguments += event.delta;
    }
  }
}

1
2
3
4
5
6
7
8
9
10final_tool_calls = {}

for event in stream:
    if event.type == "response.output_item.added":
        final_tool_calls[event.output_index] = event.item
    elif event.type == "response.function_call_arguments.delta":
        index = event.output_index

        if final_tool_calls[index]:
            final_tool_calls[index].arguments += event.delta

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
49package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction("get_weather", parameters, true)
	stream := client.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("What's the weather like in Paris today?"),
		},
		Tools: []responses.ToolUnionParam{tool},
	})

	finalToolCalls := map[int64]responses.ResponseFunctionToolCall{}
	for stream.Next() {
		event := stream.Current()
		if event.Type == "response.output_item.added" && event.Item.Type == "function_call" {
			finalToolCalls[event.OutputIndex] = event.Item.AsFunctionCall()
		}
		if event.Type == "response.function_call_arguments.delta" {
			finalToolCall, ok := finalToolCalls[event.OutputIndex]
			if !ok {
				continue
			}
			finalToolCall.Arguments += event.Delta
			finalToolCalls[event.OutputIndex] = finalToolCall
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
	fmt.Println(finalToolCalls)
}

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
59import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseFunctionToolCall;
import com.openai.models.responses.ResponseStreamEvent;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

FunctionTool weather =
    FunctionTool.builder()
        .name("get_weather")
        .description("Get the weather for a city.")
        .parameters(
            FunctionTool.Parameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("location", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("location")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .strict(true)
        .build();
ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What is the weather in Paris?")
        .addTool(weather)
        .build();

Map<Long, ResponseFunctionToolCall> toolCalls = new LinkedHashMap<>();
try (StreamResponse<ResponseStreamEvent> stream = client.responses().createStreaming(params)) {
  stream.stream()
      .forEach(
          event -> {
            event
                .outputItemAdded()
                .ifPresent(
                    added ->
                        added
                            .item()
                            .functionCall()
                            .ifPresent(call -> toolCalls.put(added.outputIndex(), call)));
            event
                .functionCallArgumentsDelta()
                .ifPresent(
                    delta ->
                        toolCalls.computeIfPresent(
                            delta.outputIndex(),
                            (ignored, call) ->
                                call.toBuilder()
                                    .arguments(call.arguments() + delta.delta())
                                    .build()));
          });
}
toolCalls.values().forEach(System.out::println);

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
42require "openai"

client = OpenAI::Client.new
stream = client.responses.stream(
  model: "gpt-6-astra",
  input: "What is the weather in Paris?",
  tools: [
    {
      type: :function,
      name: "get_weather",
      parameters: {
        type: :object,
        properties: { location: { type: :string } },
        required: ["location"],
        additionalProperties: false
      },
      strict: true
    }
  ]
)

final_tool_calls = {}
stream.each do |event|
  case event
  when OpenAI::Models::Responses::ResponseOutputItemAddedEvent
    item = event.item
    next unless item.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)

    final_tool_calls[event.output_index] = {
      id: item.id,
      call_id: item.call_id,
      name: item.name,
      type: item.type,
      arguments: item.arguments.dup
    }
  when OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
    tool_call = final_tool_calls[event.output_index]
    tool_call[:arguments] << event.delta if tool_call
  end
end

puts(final_tool_calls.sort.to_h.values)

final_tool_calls[0] après accumulation

1
2
3
4
5
6
7{
    "type": "function_call",
    "id": "fc_1234xyz",
    "call_id": "call_2345abc",
    "name": "get_weather",
    "arguments": "{\"location\":\"Paris, France\"}"
}

Lorsque le modèle a terminé les appels de fonction, un événement de type response.function_call_arguments.done est émis. Cet événement contient l’intégralité de l’appel de fonction, avec les champs suivants :

Champ	Description
`response_id`	L’identifiant de la réponse à laquelle appartient l’appel de fonction
`output_index`	L’index de l’élément de sortie dans la réponse. Il permet de distinguer les différents appels de fonction de la réponse.
`item`	L’élément d’appel de fonction, qui comprend les champs `name`, `arguments` et `id`.

Outils personnalisés

Les outils personnalisés fonctionnent de manière très similaire aux outils de type fonction définis par un schéma JSON. Toutefois, au lieu de recevoir des instructions explicites sur les données d’entrée requises par votre outil, le modèle peut lui transmettre une chaîne de caractères quelconque en entrée. Cela permet d’éviter d’encapsuler inutilement une réponse dans du JSON ou d’appliquer une grammaire personnalisée à la réponse (voir ci-dessous).

L’exemple de code suivant montre comment créer un outil personnalisé qui attend en réponse une chaîne de texte contenant du code Python.

Exemple d’appel d’outil personnalisé

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "Use the code_exec tool to print hello world to the console.",
  tools: [
    {
      type: "custom",
      name: "code_exec",
      description: "Executes arbitrary Python code.",
    },
  ],
});

console.log(response.output);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    input="Use the code_exec tool to print hello world to the console.",
    tools=[
        {
            "type": "custom",
            "name": "code_exec",
            "description": "Executes arbitrary Python code.",
        }
    ],
)
print(response.output)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfCustom("code_exec")
	tool.OfCustom.Description = openai.String("Executes arbitrary Python code.")

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the code_exec tool to print hello world to the console.")},
		Tools: []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Use code_exec to print hello world.")
        .addTool(
            CustomTool.builder()
                .name("code_exec")
                .description("Executes arbitrary Python code.")
                .build())
        .build();

client.responses().create(params).output().forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use code_exec to print hello world.",
  tools: [
    {
      type: :custom,
      name: "code_exec",
      description: "Executes arbitrary Python code."
    }
  ]
)

puts(response.output)

Comme précédemment, le tableau output contient un appel d’outil généré par le modèle. Cette fois, toutefois, les données d’entrée de l’appel d’outil sont fournies en texte brut.

12345678910111213141516[
  {
    "id": "rs_6890e972fa7c819ca8bc561526b989170694874912ae0ea6",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6890e975e86c819c9338825b3e1994810694874912ae0ea6",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_aGiFQkRWSWAIsMQ19fKqxUgb",
    "input": "print(\"hello world\")",
    "name": "code_exec"
  }
]

Grammaires non contextuelles

Une grammaire non contextuelle (CFG) est un ensemble de règles qui définissent comment produire du texte valide dans un format donné. Pour un outil personnalisé, vous pouvez fournir une CFG qui contraint le texte que le modèle lui transmet en entrée.

Vous pouvez fournir une CFG personnalisée à l’aide du paramètre grammar lors de la configuration d’un outil personnalisé. Nous prenons actuellement en charge deux syntaxes de CFG pour définir les grammaires : lark et regex.

CFG Lark

Exemple de grammaire non contextuelle Lark

Python

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
34import OpenAI from "openai";
const client = new OpenAI();

const grammar = `
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT
`;

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "Use the math_exp tool to add four plus four.",
  tools: [
    {
      type: "custom",
      name: "math_exp",
      description: "Creates valid mathematical expressions",
      format: {
        type: "grammar",
        syntax: "lark",
        definition: grammar,
      },
    },
  ],
});

console.log(response.output);

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
34from openai import OpenAI

client = OpenAI()

grammar = """
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT
"""

response = client.responses.create(
    model="gpt-6-astra",
    input="Use the math_exp tool to add four plus four.",
    tools=[
        {
            "type": "custom",
            "name": "math_exp",
            "description": "Creates valid mathematical expressions",
            "format": {
                "type": "grammar",
                "syntax": "lark",
                "definition": grammar,
            },
        }
    ],
)
print(response.output)

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
37package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	grammar := `start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT`
	tool := responses.ToolParamOfCustom("math_exp")
	tool.OfCustom.Description = openai.String("Creates valid mathematical expressions")
	tool.OfCustom.Format = shared.CustomToolInputFormatParamOfGrammar(grammar, "lark")

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the math_exp tool to add four plus four.")},
		Tools: []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

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
33import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.CustomToolInputFormat;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;

String grammar =
    """
    start: expr
    expr: term (SP ADD SP term)*
    term: INT
    SP: " "
    ADD: "+"
    %import common.INT
    """;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Use math_exp to add four plus four.")
        .addTool(
            CustomTool.builder()
                .name("math_exp")
                .description("Creates valid mathematical expressions.")
                .format(
                    CustomToolInputFormat.Grammar.builder()
                        .syntax(CustomToolInputFormat.Grammar.Syntax.LARK)
                        .definition(grammar)
                        .build())
                .build())
        .build();

client.responses().create(params).output().forEach(System.out::println);

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
29require "openai"

client = OpenAI::Client.new
grammar = <<~LARK
  start: expr
  expr: term (SP ADD SP term)*
  term: INT
  SP: " "
  ADD: "+"
  %import common.INT
LARK
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use math_exp to add four plus four.",
  tools: [
    {
      type: :custom,
      name: "math_exp",
      description: "Creates valid mathematical expressions.",
      format: {
        type: :grammar,
        syntax: :lark,
        definition: grammar
      }
    }
  ]
)

puts(response.output)

La sortie de l’outil devrait alors respecter la CFG Lark que vous avez définie :

12345678910111213141516[
  {
    "id": "rs_6890ed2b6374819dbbff5353e6664ef103f4db9848be4829",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6890ed2f32e8819daa62bef772b8c15503f4db9848be4829",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_pmlLjmvG33KJdyVdC4MVdk5N",
    "input": "4 + 4",
    "name": "math_exp"
  }
]

Les grammaires sont définies à l’aide d’une variante de Lark. L’échantillonnage du modèle est contraint à l’aide de LLGuidance. Certaines fonctionnalités de Lark ne sont pas prises en charge :

Assertions avant et arrière dans les expressions régulières de l’analyseur lexical
Quantificateurs non gourmands (*?, +?, ??) dans les expressions régulières de l’analyseur lexical
Priorités des terminaux
Gabarits
Imports (autres que l’import intégré %import common)
Directives %declare

Nous vous recommandons d’utiliser Lark IDE pour expérimenter avec des grammaires personnalisées.

Limitez la complexité de la grammaire

Limitez votre grammaire aux règles et aux motifs dont votre outil a besoin. L’API OpenAI peut renvoyer une erreur si la grammaire est trop complexe. Vérifiez donc que la grammaire souhaitée est compatible avant de l’utiliser dans l’API.

La mise au point des grammaires Lark peut être délicate. Les grammaires les plus simples offrent le fonctionnement le plus fiable. Les grammaires complexes nécessitent souvent des ajustements successifs de leur définition, du prompt et de la description de l’outil pour éviter que le modèle ne se retrouve hors distribution.

Motifs corrects et incorrects

Correct (un seul terminal, borné) :

start: SENTENCE
SENTENCE: /[A-Za-z, ]*(the hero|a dragon|an old man|the princess)[A-Za-z, ]*(fought|saved|found|lost)[A-Za-z, ]*(a treasure|the kingdom|a secret|his way)[A-Za-z, ]*\./

Ne faites PAS ceci (répartition entre plusieurs règles ou terminaux). Cette approche tente de laisser les règles répartir le texte libre entre les terminaux. L’analyseur lexical reconnaîtra les portions de texte libre de manière gloutonne et vous perdrez le contrôle :

start: sentence
sentence: /[A-Za-z, ]+/ subject /[A-Za-z, ]+/ verb /[A-Za-z, ]+/ object /[A-Za-z, ]+/

Les règles en minuscules n’influencent pas le découpage de l’entrée en terminaux : seules les définitions des terminaux le font. Lorsque vous avez besoin de « texte libre entre des ancres », regroupez l’ensemble dans un seul terminal défini par une expression régulière, afin que l’analyseur lexical le reconnaisse en une seule fois, avec la structure voulue.

Terminaux et règles

Lark utilise des terminaux pour les tokens de l’analyseur lexical (par convention, UPPERCASE) et des règles pour les productions de l’analyseur syntaxique (par convention, lowercase). Pour rester dans le sous-ensemble pris en charge et éviter les surprises, le plus pratique est de garder une grammaire explicite, d’éviter toute complexité inutile et de séparer clairement les rôles des terminaux et des règles.

Les terminaux utilisent la syntaxe de la crate Rust regex, et non celle du module re de Python.

Notions clés et bonnes pratiques

L’analyseur lexical s’exécute avant l’analyseur syntaxique

L’analyseur lexical reconnaît les terminaux de manière gloutonne (la correspondance la plus longue l’emporte) avant l’application de toute logique des règles de la CFG. Si vous essayez de « façonner » un terminal en le répartissant entre plusieurs règles, celles-ci ne pourront pas guider l’analyseur lexical : seules les expressions régulières des terminaux le peuvent.

Privilégiez un seul terminal pour extraire du texte à partir de portions de texte libre

Si vous devez reconnaître un motif au sein d’un texte quelconque (par exemple, du langage naturel avec « n’importe quoi » entre les ancres), exprimez-le dans un seul terminal. N’essayez pas d’alterner des terminaux de texte libre et des règles de l’analyseur syntaxique : l’analyseur lexical glouton ne respectera pas les limites prévues et le modèle risque fortement de se retrouver hors distribution.

Utilisez les règles pour combiner des tokens distincts

Les règles sont idéales pour combiner des terminaux explicitement délimités (nombres, mots-clés, ponctuation) en structures plus grandes. Elles ne conviennent pas pour contraindre « ce qui se trouve entre » deux terminaux.

Définissez des terminaux ciblés, bornés et autonomes

Privilégiez les classes de caractères explicites et les quantificateurs bornés ({0,10}, plutôt que des * non bornés partout). Si vous avez besoin de reconnaître « n’importe quel texte jusqu’à un point », préférez une expression comme /[^.\n]{0,10}*\./ à /.+\./ pour éviter une croissance incontrôlée.

Utilisez les règles pour combiner les tokens, pas pour piloter le fonctionnement interne des expressions régulières

Exemple de bonne utilisation des règles :

start: expr
NUMBER: /[0-9]+/
PLUS: "+"
MINUS: "-"
expr: term (("+"|"-") term)*
term: NUMBER

Traitez explicitement les caractères d’espacement

Ne vous appuyez pas sur des directives %ignore sans limites. Des directives d’exclusion non bornées peuvent rendre la grammaire trop complexe ou faire sortir le modèle de sa distribution, voire les deux. Insérez plutôt des terminaux explicites partout où les caractères d’espacement sont autorisés.

Dépannage

Si l’API rejette la grammaire parce qu’elle est trop complexe, simplifiez les règles et les terminaux et supprimez les directives %ignore non bornées.
Si les outils personnalisés sont appelés avec des tokens inattendus, vérifiez que les terminaux ne se chevauchent pas et examinez le comportement glouton de l’analyseur lexical.
Lorsque le modèle dérive « hors distribution » (il produit des sorties excessivement longues ou répétitives, syntaxiquement valides mais sémantiquement incorrectes) :
- Rendez la grammaire plus restrictive.
- Ajustez progressivement le prompt (ajoutez des exemples few-shot) et la description de l’outil (expliquez la grammaire et demandez au modèle de raisonner et de s’y conformer).
- Essayez un effort de raisonnement supérieur (par exemple, passez du niveau Médium au niveau Élevé).

CFG à base d’expressions régulières

Exemple de grammaire hors contexte à base d’expressions régulières

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();

const grammar =
  "^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\\s+(?P<day>\\d{1,2})(?:st|nd|rd|th)?\\s+(?P<year>\\d{4})\\s+at\\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$";

const response = await client.responses.create({
  model: "gpt-6-astra",
  input:
    "Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.",
  tools: [
    {
      type: "custom",
      name: "timestamp",
      description: "Saves a timestamp in date + time in 24-hr format.",
      format: {
        type: "grammar",
        syntax: "regex",
        definition: grammar,
      },
    },
  ],
});

console.log(response.output);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23from openai import OpenAI

client = OpenAI()

grammar = r"^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?\s+(?P<year>\d{4})\s+at\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$"

response = client.responses.create(
    model="gpt-6-astra",
    input="Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.",
    tools=[
        {
            "type": "custom",
            "name": "timestamp",
            "description": "Saves a timestamp in date + time in 24-hr format.",
            "format": {
                "type": "grammar",
                "syntax": "regex",
                "definition": grammar,
            },
        }
    ],
)
print(response.output)

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
28package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	grammar := `^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?\s+(?P<year>\d{4})\s+at\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$`
	tool := responses.ToolParamOfCustom("timestamp")
	tool.OfCustom.Description = openai.String("Saves a timestamp in date and time format.")
	tool.OfCustom.Format = shared.CustomToolInputFormatParamOfGrammar(grammar, "regex")

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.")},
		Tools: []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

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
27import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.CustomToolInputFormat;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;

String grammar =
    "^(January|February|March|April|May|June|July|August|September|October|November|December) "
        + "\\d{1,2}(st|nd|rd|th)? \\d{4} at (0?[1-9]|1[0-2])(AM|PM)$";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Use timestamp to save August 7th 2025 at 10AM.")
        .addTool(
            CustomTool.builder()
                .name("timestamp")
                .description("Saves a timestamp in date and time format.")
                .format(
                    CustomToolInputFormat.Grammar.builder()
                        .syntax(CustomToolInputFormat.Grammar.Syntax.REGEX)
                        .definition(grammar)
                        .build())
                .build())
        .build();

client.responses().create(params).output().forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "openai"

client = OpenAI::Client.new
grammar = "^(January|February|March|April|May|June|July|August|September|October|November|December) \\d{1,2}(st|nd|rd|th)? \\d{4} at (0?[1-9]|1[0-2])(AM|PM)$"
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use timestamp to save August 7th 2025 at 10AM.",
  tools: [
    {
      type: :custom,
      name: "timestamp",
      description: "Saves a timestamp in date and time format.",
      format: {
        type: :grammar,
        syntax: :regex,
        definition: grammar
      }
    }
  ]
)

puts(response.output)

La sortie de l’outil devrait alors respecter la CFG à base d’expressions régulières que vous avez définie :

12345678910111213141516[
  {
    "id": "rs_6894f7a3dd4c81a1823a723a00bfa8710d7962f622d1c260",
    "type": "reasoning",
    "content": [],
    "summary": []
  },
  {
    "id": "ctc_6894f7ad7fb881a1bffa1f377393b1a40d7962f622d1c260",
    "type": "custom_tool_call",
    "status": "completed",
    "call_id": "call_8m4XCnYvEmFlzHgDHbaOCFlK",
    "input": "August 7th 2025 at 10AM",
    "name": "timestamp"
  }
]

Comme avec la syntaxe Lark, les expressions régulières utilisent la syntaxe de la crate Rust regex, et non celle du module re de Python.

Certaines fonctionnalités des expressions régulières ne sont pas prises en charge :

Assertions avant et arrière
Quantificateurs non gloutons (*?, +?, ??)

Notions clés et bonnes pratiques

Le motif doit tenir sur une seule ligne

Pour reconnaître un saut de ligne dans l’entrée, utilisez la séquence d’échappement \n. N’utilisez pas le mode verbeux ou étendu, qui permet de répartir les motifs sur plusieurs lignes.

Fournissez l’expression régulière sous forme d’une simple chaîne contenant le motif

N’encadrez pas le motif avec //.

Suggestions

Bien démarrer

Concepts fondamentaux

SDK et CLI

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Conception de prompts

Raisonnement

Images et vidéo

Realtime et audio

Modèles spécialisés

API Agents

SDK Agents

ChatKit

Recherche et récupération

Connectez des outils et des données

Créez des flux de travail avec des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Développez avec la voix

Connexions

Traitement audio

Passez en production

Performances et qualité

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts fondamentaux

Plan

Build

Test and publish

Conversion specs

Guides

Ressources

Bien démarrer

Guides

File Upload

API

Measurement

Advertiser API

Référence de l’API

Bien démarrer

Fondamentaux

Explorer

Disponible sur

Versions

Flux de travail

Capacités

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendez les capacités de ChatGPT et de Codex

Linux

Windows

Flux de travail de développement

Étendre et automatiser

Environnements

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Bien démarrer

ChatGPT Work

Identité et authentification

Accès à l’espace de travail, stratégies et modèles

Contrôles des plugins et des connecteurs

Utilisation, gouvernance et conformité

Déploiement et fournisseurs de modèles

Communauté

Blog

Communauté

Blog