Recherche d’outils

La recherche d’outils permet au modèle de rechercher des outils et de les charger dans son contexte à mesure qu’il en a besoin. Vous évitez ainsi de charger toutes les définitions d’outils dès le départ, ce qui peut réduire la consommation totale de tokens et le coût global. Pour optimiser les coûts et la latence, la recherche d’outils est conçue pour préserver le cache du modèle. Les nouveaux outils que découvre le modèle sont ajoutés à la fin de sa fenêtre de contexte.

Dans l’API Responses, seuls gpt-5.4 et les modèles ultérieurs prennent en charge tool_search.

La configuration et les exemples qui suivent utilisent l’API Responses. Pour le chargement des fonctions au sein d’une session et la découverte automatique des outils MCP, consultez la section API Agents.

Pour activer la recherche d’outils dans l’API Responses, procédez en deux étapes :

Ajoutez tool_search en tant qu’outil dans votre tableau tools.
Si vous utilisez des fonctions, indiquez defer_loading: true pour celles dont vous souhaitez différer le chargement. Si vous utilisez des serveurs MCP, indiquez defer_loading: true dans la définition de l’outil correspondant au serveur MCP.

Utilisez des espaces de noms lorsque c’est possible

La recherche d’outils prend en charge le chargement différé des fonctions, des espaces de noms et des serveurs MCP. Nous vous recommandons de privilégier les espaces de noms ou les serveurs MCP lorsque c’est possible. Nos modèles ont principalement été entraînés à y rechercher des outils, et les économies de tokens y sont généralement plus importantes.

Dans un espace de noms, defer_loading s’applique aux fonctions qu’il contient, et non à l’objet qui représente l’espace de noms lui-même.

Au début d’une requête, le modèle voit le nom et la description de chaque élément qu’il peut rechercher. Pour un espace de noms ou un serveur MCP, seuls le nom et la description de l’espace ou du serveur sont visibles au départ. Le modèle accède aux détails de chaque fonction lorsque la recherche d’outils la charge. Pour une fonction déclarée individuellement en chargement différé, le modèle voit d’emblée son nom et sa description. En pratique, c’est donc surtout le chargement du schéma des paramètres qui est différé.

Pour économiser autant de tokens que possible, regroupez les fonctions à chargement différé dans des espaces de noms ou sur des serveurs MCP. Donnez à chacun une description claire qui présente les fonctions disponibles dans leur ensemble. Le modèle peut ainsi cibler sa recherche et charger uniquement les fonctions pertinentes. Dans la mesure du possible, limitez chaque espace de noms à moins de 10 fonctions pour optimiser la consommation de tokens et les performances du modèle.

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{
    "tools": [
      {
        "type": "namespace",
        "name": "crm",
        "description": "CRM tools for customer lookup and order management.",
        "tools": [
          {
            "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
            }
          }
        ]
      },
      {
        "type": "tool_search"
      }
    ]
  }

Un espace de noms peut contenir à la fois des outils à chargement différé et des outils à chargement immédiat. Le modèle peut appeler immédiatement les outils pour lesquels defer_loading: true n’est pas spécifié. Il charge les autres outils du même espace de noms via la recherche d’outils.

Modes de recherche d’outils

Choisissez l’un des deux modes de recherche d’outils :

Recherche d’outils hébergée : OpenAI effectue la recherche parmi les outils à chargement différé que vous avez déclarés dans la requête et renvoie les outils chargés dans la même réponse.
Recherche d’outils côté client : le modèle émet un tool_search_call, votre application effectue la recherche, puis vous renvoyez le tool_search_output correspondant.

Commencez par la recherche hébergée si vous connaissez déjà les outils parmi lesquels effectuer la recherche au moment de créer la requête. Utilisez la recherche côté client si la découverte des outils dépend de l’état du projet, de celui du tenant ou d’un autre système que votre application contrôle.

Recherche d’outils hébergée

La recherche hébergée est la solution la plus simple si vous connaissez déjà la liste complète des fonctions, des espaces de noms ou des serveurs MCP parmi lesquels le modèle doit effectuer ses recherches. Déclarez-les dès le départ, ajoutez {"type": "tool_search"} et laissez l’API choisir les outils à charger.

Configuration de la recherche d’outils hébergée

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

const client = new OpenAI();

const crmNamespace = {
  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,
      },
    },
  ],
};

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "List open orders for customer CUST-12345.",
  tools: [crmNamespace, { type: "tool_search" }],
  parallel_tool_calls: false,
});

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
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50from openai import OpenAI

client = OpenAI()

crm_namespace = {
    "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,
            },
        },
    ],
}

response = client.responses.create(
    model="gpt-6-astra",
    input="List open orders for customer CUST-12345.",
    tools=[
        crm_namespace,
        {"type": "tool_search"},
    ],
    parallel_tool_calls=False,
)

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
37
38
39
40
41package 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{"customer_id": map[string]any{"type": "string"}},
		"required":             []string{"customer_id"},
		"additionalProperties": false,
	}
	namespace := responses.ToolParamOfNamespace(
		"CRM tools for customer lookup and order management.",
		"crm",
		[]responses.NamespaceToolToolUnionParam{
			{OfFunction: &responses.NamespaceToolToolFunctionParam{
				Name: "get_customer_profile", Description: openai.String("Fetch a customer profile by customer ID."), Parameters: parameters,
			}},
			{OfFunction: &responses.NamespaceToolToolFunctionParam{
				Name: "list_open_orders", Description: openai.String("List open orders for a customer ID."), DeferLoading: openai.Bool(true), Parameters: parameters,
			}},
		},
	)
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:             "gpt-6-astra",
		Input:             responses.ResponseNewParamsInputUnion{OfString: openai.String("List open orders for customer CUST-12345.")},
		Tools:             []responses.ToolUnionParam{namespace, {OfToolSearch: &responses.ToolSearchToolParam{}}},
		ParallelToolCalls: openai.Bool(false),
	})
	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
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
58import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.NamespaceTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ToolSearchTool;
import java.util.List;
import java.util.Map;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("List open orders for customer CUST-12345.")
        .parallelToolCalls(false)
        .addTool(
            NamespaceTool.builder()
                .name("crm")
                .description("CRM tools for customer lookup and order management.")
                .addTool(
                    NamespaceTool.Tool.Function.builder()
                        .name("get_customer_profile")
                        .description("Fetch a customer profile by customer ID.")
                        .strict(true)
                        .parameters(
                            JsonValue.from(
                                Map.of(
                                    "type",
                                    "object",
                                    "properties",
                                    Map.of("customer_id", Map.of("type", "string")),
                                    "required",
                                    List.of("customer_id"),
                                    "additionalProperties",
                                    false)))
                        .build())
                .addTool(
                    NamespaceTool.Tool.Function.builder()
                        .name("list_open_orders")
                        .description("List open orders for a customer ID.")
                        .deferLoading(true)
                        .strict(true)
                        .parameters(
                            JsonValue.from(
                                Map.of(
                                    "type",
                                    "object",
                                    "properties",
                                    Map.of("customer_id", Map.of("type", "string")),
                                    "required",
                                    List.of("customer_id"),
                                    "additionalProperties",
                                    false)))
                        .build())
                .build())
        .addTool(ToolSearchTool.builder().execution(ToolSearchTool.Execution.SERVER).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
29
30
31
32
33
34
35
36
37
38
39require "openai"

client = OpenAI::Client.new
parameters = {
  type: :object,
  properties: { customer_id: { type: :string } },
  required: ["customer_id"],
  additionalProperties: false
}
response = client.responses.create(
  model: "gpt-6-astra",
  input: "List open orders for customer CUST-12345.",
  parallel_tool_calls: false,
  tools: [
    {
      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: parameters
        },
        {
          type: :function,
          name: "list_open_orders",
          description: "List open orders for a customer ID.",
          defer_loading: true,
          parameters: parameters
        }
      ]
    },
    { type: :tool_search }
  ]
)

puts(response.output)

Si le modèle détermine qu’il a besoin d’un outil à chargement différé, la réponse contient deux éléments de sortie supplémentaires avant l’appel de fonction :

tool_search_call consigne l’étape de recherche hébergée.
tool_search_output contient les outils chargés, que le modèle peut désormais appeler.

Réponse de la recherche d’outils hébergée

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[
  {
    "type": "tool_search_call",
    "execution": "server",
    "call_id": null,
    "status": "completed",
    "arguments": {
      "paths": ["crm"]
    }
  },
  {
    "type": "tool_search_output",
    "execution": "server",
    "call_id": null,
    "status": "completed",
    "tools": [
      {
        "type": "namespace",
        "name": "crm",
        "description": "CRM tools for customer lookup and order management.",
        "tools": [
          {
            "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
            }
          }
        ]
      }
    ]
  },
  {
    "type": "function_call",
    "name": "list_open_orders",
    "namespace": "crm",
    "call_id": "call_abc123",
    "arguments": "{\"customer_id\":\"CUST-12345\"}"
  }
]

En mode hébergé, execution vaut server et call_id vaut null.

Pour les tâches plus complexes, le modèle peut aussi charger plusieurs espaces de noms ou serveurs MCP dans un même tool_search_call. Par exemple, si une tâche nécessite des fonctions issues de plusieurs espaces de noms, le modèle peut choisir d’effectuer la recherche dans ces espaces et de les charger ensemble avant d’appeler les fonctions.

Recherche d’outils côté client

Avec la recherche d’outils côté client, votre application contrôle entièrement la découverte des outils. Ce mode est utile lorsque les outils disponibles dépendent d’informations qu’il serait difficile de déclarer dans la liste tools initiale.

Configurez l’outil tool_search avec execution: "client" et un schéma décrivant les arguments de recherche attendus par votre application :

Configuration de la recherche d’outils côté client

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

const client = new OpenAI();

const firstResponse = await client.responses.create({
  model: "gpt-6-astra",
  input: "Find the shipping ETA tool first, then use it for order_42.",
  tools: [
    {
      type: "tool_search",
      execution: "client",
      description:
        "Find the project-specific tools needed to continue the task.",
      parameters: {
        type: "object",
        properties: {
          goal: { type: "string" },
        },
        required: ["goal"],
        additionalProperties: false,
      },
    },
  ],
  parallel_tool_calls: false,
});

const searchCall = firstResponse.output.find(
  (item) => item.type === "tool_search_call"
);

if (!searchCall) {
  throw new Error("The response did not include a tool search call.");
}

const loadedTools = [
  {
    type: "function",
    name: "get_shipping_eta",
    description: "Look up shipping ETA details for an order.",
    defer_loading: true,
    parameters: {
      type: "object",
      properties: {
        order_id: { type: "string" },
      },
      required: ["order_id"],
      additionalProperties: false,
    },
    strict: true,
  },
];

const searchOutput = {
  type: "tool_search_output",
  execution: "client",
  call_id: searchCall.call_id,
  status: "completed",
  tools: loadedTools,
};

const secondResponse = await client.responses.create({
  model: "gpt-6-astra",
  input: [
    ...toResponseInputItems(firstResponse.output),
    searchOutput,
  ],
});

console.log(secondResponse.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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61from openai import OpenAI

client = OpenAI()

first_response = client.responses.create(
    model="gpt-6-astra",
    input="Find the shipping ETA tool first, then use it for order_42.",
    tools=[
        {
            "type": "tool_search",
            "execution": "client",
            "description": "Find the project-specific tools needed to continue the task.",
            "parameters": {
                "type": "object",
                "properties": {
                    "goal": {"type": "string"},
                },
                "required": ["goal"],
                "additionalProperties": False,
            },
        }
    ],
    parallel_tool_calls=False,
)

search_call = next(
    item for item in first_response.output if item.type == "tool_search_call"
)

loaded_tools = [
    {
        "type": "function",
        "name": "get_shipping_eta",
        "description": "Look up shipping ETA details for an order.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
            },
            "required": ["order_id"],
            "additionalProperties": False,
        },
    }
]

second_response = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first_response.id,
    input=[
        {
            "type": "tool_search_output",
            "execution": "client",
            "call_id": search_call.call_id,
            "status": "completed",
            "tools": loaded_tools,
        },
    ],
)

print(second_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
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
65package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	searchTool := responses.ToolUnionParam{OfToolSearch: &responses.ToolSearchToolParam{
		Execution:   responses.ToolSearchToolExecutionClient,
		Description: openai.String("Find the project-specific tools needed to continue the task."),
		Parameters: map[string]any{
			"type":                 "object",
			"properties":           map[string]any{"goal": map[string]any{"type": "string"}},
			"required":             []string{"goal"},
			"additionalProperties": false,
		},
	}}
	first, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:             "gpt-6-astra",
		Input:             responses.ResponseNewParamsInputUnion{OfString: openai.String("Find the shipping ETA tool first, then use it for order_42.")},
		Tools:             []responses.ToolUnionParam{searchTool},
		ParallelToolCalls: openai.Bool(false),
	})
	if err != nil {
		panic(err)
	}

	callID := ""
	for _, item := range first.Output {
		if item.Type == "tool_search_call" {
			callID = item.CallID
			break
		}
	}
	if callID == "" {
		panic("the response did not include a tool search call")
	}
	loadedTool := responses.ToolParamOfFunction("get_shipping_eta", map[string]any{
		"type":                 "object",
		"properties":           map[string]any{"order_id": map[string]any{"type": "string"}},
		"required":             []string{"order_id"},
		"additionalProperties": false,
	}, true)
	loadedTool.OfFunction.Description = openai.String("Look up shipping ETA details for an order.")
	loadedTool.OfFunction.DeferLoading = openai.Bool(true)
	searchOutput := responses.ResponseInputItemParamOfToolSearchOutput([]responses.ResponseToolSearchOutputItemParamToolUnion{{OfFunction: loadedTool.OfFunction}})
	searchOutput.OfToolSearchOutput.CallID = openai.String(callID)
	searchOutput.OfToolSearchOutput.Execution = responses.ResponseToolSearchOutputItemParamExecutionClient
	searchOutput.OfToolSearchOutput.Status = responses.ResponseToolSearchOutputItemParamStatusCompleted

	second, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:              "gpt-6-astra",
		PreviousResponseID: openai.String(first.ID),
		Input:              responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{searchOutput}},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(second.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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81import 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 com.openai.models.responses.ResponseToolSearchOutputItemParam;
import com.openai.models.responses.ToolSearchTool;
import java.util.List;
import java.util.Map;

ResponseCreateParams searchRequest =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Find the shipping ETA tool, then use it for order_42.")
        .parallelToolCalls(false)
        .addTool(
            ToolSearchTool.builder()
                .execution(ToolSearchTool.Execution.CLIENT)
                .description("Find the project tools needed to continue the task.")
                .parameters(
                    JsonValue.from(
                        Map.of(
                            "type",
                            "object",
                            "properties",
                            Map.of("goal", Map.of("type", "string")),
                            "required",
                            List.of("goal"),
                            "additionalProperties",
                            false)))
                .build())
        .build();

var search = client.responses().create(searchRequest);
var searchCall =
    search.output().stream()
        .flatMap(item -> item.toolSearchCall().stream())
        .findFirst()
        .orElseThrow(() -> new IllegalStateException("No tool search call returned"));

FunctionTool shippingTool =
    FunctionTool.builder()
        .name("get_shipping_eta")
        .description("Look up shipping details for an order.")
        .deferLoading(true)
        .strict(true)
        .parameters(
            FunctionTool.Parameters.builder()
                .putAdditionalProperty("type", JsonValue.from("object"))
                .putAdditionalProperty(
                    "properties", JsonValue.from(Map.of("order_id", Map.of("type", "string"))))
                .putAdditionalProperty("required", JsonValue.from(List.of("order_id")))
                .putAdditionalProperty("additionalProperties", JsonValue.from(false))
                .build())
        .build();

var searchOutput =
    ResponseToolSearchOutputItemParam.builder()
        .callId(searchCall.callId().orElseThrow())
        .execution(ResponseToolSearchOutputItemParam.Execution.CLIENT)
        .status(ResponseToolSearchOutputItemParam.Status.COMPLETED)
        .addTool(shippingTool)
        .build();

var response =
    client
        .responses()
        .create(
            ResponseCreateParams.builder()
                .model("gpt-6-astra")
                .previousResponseId(search.id())
                .inputOfResponse(List.of(ResponseInputItem.ofToolSearchOutput(searchOutput)))
                .build());

var loadedCalls =
    response.output().stream().flatMap(item -> item.functionCall().stream()).toList();
if (loadedCalls.isEmpty()) {
  throw new IllegalStateException("No loaded function call returned");
}
loadedCalls.forEach(call -> System.out.println(call.name() + "(" + call.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
53
54
55
56
57
58
59
60
61
62
63
64require "openai"

client = OpenAI::Client.new
search = client.responses.create(
  model: "gpt-6-astra",
  input: "Find the shipping ETA tool, then use it for order_42.",
  parallel_tool_calls: false,
  tools: [
    {
      type: :tool_search,
      execution: :client,
      description: "Find the project tools needed to continue the task.",
      parameters: {
        type: :object,
        properties: { goal: { type: :string } },
        required: ["goal"],
        additionalProperties: false
      }
    }
  ]
)
call = search.output.find do |item|
  item.is_a?(OpenAI::Models::Responses::ResponseToolSearchCall)
end
unless call.is_a?(OpenAI::Models::Responses::ResponseToolSearchCall)
  raise "No tool search call returned"
end

response = client.responses.create(
  model: "gpt-6-astra",
  previous_response_id: search.id,
  input: [
    {
      type: :tool_search_output,
      call_id: call.call_id,
      execution: :client,
      status: :completed,
      tools: [
        {
          type: :function,
          name: "get_shipping_eta",
          description: "Look up shipping details for an order.",
          defer_loading: true,
          strict: true,
          parameters: {
            type: :object,
            properties: { order_id: { type: :string } },
            required: ["order_id"],
            additionalProperties: false
          }
        }
      ]
    }
  ]
)

function_calls = response.output.grep(
  OpenAI::Models::Responses::ResponseFunctionToolCall
)
raise "No loaded function call returned" if function_calls.empty?

function_calls.each do |function_call|
  puts("#{function_call.name}(#{function_call.arguments})")
end

Au premier tour, le modèle émet un tool_search_call et s’arrête là :

Appel de recherche d’outils côté client

1
2
3
4
5
6
7
8
9
10
11[
  {
    "type": "tool_search_call",
    "execution": "client",
    "call_id": "call_abc123",
    "status": "completed",
    "arguments": {
      "goal": "Find the shipping ETA tool for order_42."
    }
  }
]

Votre application effectue ensuite la recherche et renvoie un tool_search_output contenant les outils qu’elle souhaite charger :

Renvoi de tool_search_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[
  {
    "type": "tool_search_output",
    "execution": "client",
    "call_id": "call_abc123",
    "status": "completed",
    "tools": [
      {
        "type": "function",
        "name": "get_shipping_eta",
        "description": "Look up shipping ETA details for an order.",
        "defer_loading": true,
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string" }
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    ]
  }
]

Au tour suivant, le modèle peut appeler l’outil chargé comme une fonction ordinaire :

Appel de la fonction chargée

1
2
3
4
5
6
7
8
9[
  {
    "type": "function_call",
    "name": "get_shipping_eta",
    "namespace": "get_shipping_eta",
    "call_id": "call_xyz456",
    "arguments": "{\"order_id\":\"order_42\"}"
  }
]

En mode client, execution vaut client et call_id a une valeur définie. Reprenez la valeur de call_id fournie par le tool_search_call dans votre tool_search_output.

Utilisation avancée

Rédigez des descriptions claires pour les espaces de noms

Décrivez clairement le cas d’usage de chaque espace de noms. Le modèle s’appuie sur cette description pour décider quand charger une partie des fonctions de l’espace de noms. Gardez la description concise. Réservez les détails aux descriptions des fonctions à chargement différé, que le modèle ne charge que lorsqu’il en a besoin.

Identifiez les outils chargés

tool_search_output.tools contient la liste des outils que le modèle a chargés dynamiquement. Le modèle peut appeler chacun de ces outils lors des tours suivants. En mode client, vous n’avez donc pas besoin de recharger le même outil d’un tour à l’autre. Le modèle n’a pas accès aux outils absents de ce tableau. Pour désactiver un outil chargé, vous pouvez le retirer de l’élément tool_search_output dans lequel vous définissez l’ensemble des outils chargés. Toute modification de cet ensemble invalide le cache du modèle à partir de ce point.

Injection avancée d’outils

La plupart des intégrations déclarent les outils dans le paramètre tools de la requête. La recherche d’outils côté client permet également à votre application de renvoyer des outils qui ne figuraient pas dans la requête initiale. Dans ce cas avancé, validez soigneusement les schémas renvoyés et ne rendez accessibles que des définitions d’outils de confiance.

Recherche d’outils et mise en cache

Tous les outils sont chargés à la fin de la fenêtre de contexte du modèle, aussi bien en mode hébergé qu’en mode client. Le modèle conserve ainsi son cache d’une requête à l’autre, ce qui réduit les coûts globaux et accélère le traitement.

Ajoutez des outils à un point précis de l’entrée

Dans les workflows avancés, vous pouvez utiliser un élément d’entrée additional_tools pour rendre des outils disponibles à un point précis de la conversation. C’est utile lorsque votre application charge des outils en dehors du processus habituel de recherche ou doit conserver l’ordre dans lequel les outils ont été ajoutés lors d’une réponse précédente.

Attribuez à role la valeur developer et placez les outils à ajouter dans le tableau tools de l’élément :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19{
    "type": "additional_tools",
    "role": "developer",
    "tools": [
      {
        "type": "function",
        "name": "get_customer",
        "description": "Look up a customer by ID.",
        "parameters": {
          "type": "object",
          "properties": {
            "customer_id": { "type": "string" }
          },
          "required": ["customer_id"],
          "additionalProperties": false
        }
      }
    ]
  }

Les outils d’un élément additional_tools ne deviennent disponibles qu’après l’apparition de cet élément dans l’entrée. Lorsque vous retransmettez manuellement les éléments de la conversation, conservez la position de cet élément pour que le modèle voie les mêmes outils au même point de la conversation.

API Agents

Par défaut, l’API Agents charge immédiatement les définitions des fonctions. Pour différer le chargement de certaines fonctions, ajoutez { "type": "tool_search" } dans agent.tools et indiquez defer_loading: true pour chaque fonction que l’agent doit découvrir à la demande. L’ajout de tool_search ne diffère pas automatiquement le chargement de toutes les fonctions.

La requête de session fournit toujours la définition complète de la fonction, y compris son nom, sa description et le schéma de ses arguments. La recherche d’outils change le moment où le modèle reçoit cette définition. Une fois la fonction découverte, votre application traite l’appel et renvoie le résultat comme d’habitude. Pour en savoir plus sur le traitement des résultats, consultez le guide Fonctions.

Définissez OPENAI_API_KEY avant d’exécuter cet exemple :

Chargement des fonctions à la demande

JavaScript

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

const result = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "tool_search",
      },
      {
        type: "function",
        name: "lookup_account",
        description: "Find an account by its account number.",
        parameters: {
          type: "object",
          properties: {
            account_id: {
              type: "string",
            },
          },
          required: ["account_id"],
          additionalProperties: false,
        },
        defer_loading: true,
      },
    ],
  },
  environment: {
    type: "none",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Look up account 42.",
        },
      ],
    },
  ],
});
console.log(result.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
32from openai import OpenAI

client = OpenAI()

result = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "tools": [
            {"type": "tool_search"},
            {
                "type": "function",
                "name": "lookup_account",
                "description": "Find an account by its account number.",
                "parameters": {
                    "type": "object",
                    "properties": {"account_id": {"type": "string"}},
                    "required": ["account_id"],
                    "additionalProperties": False,
                },
                "defer_loading": True,
            },
        ],
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "Look up account 42."}],
        }
    ],
)
print(result.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
36
37
38
39
40
41
42
43
44
45import (
	"context"
	"fmt"

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

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model: openai.String("gpt-6-astra"),
			Tools: []openai.AgentToolParamUnion{
				{OfParamToolSearch: &openai.AgentToolParamToolSearch{}},
				{
					OfParamFunction: &openai.AgentToolParamFunction{
						Name:        "lookup_account",
						Description: "Find an account by its account number.",
						Parameters: map[string]any{
							"type":                 "object",
							"properties":           map[string]any{"account_id": map[string]any{"type": "string"}},
							"required":             []any{"account_id"},
							"additionalProperties": false,
						},
						DeferLoading: openai.Bool(true),
					},
				},
			},
		},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{OfParamInputText: &openai.InputContentParamInputText{Text: "Look up account 42."}},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result.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
36
37
38
39
40
41
42
43import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;
import java.util.Map;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .addToolToolSearch()
                        .addTool(
                            AgentToolParam.Function.builder()
                                .name("lookup_account")
                                .description("Find an account by its account number.")
                                .parameters(
                                    AgentToolParam.Function.Parameters.builder()
                                        .putAdditionalProperty("type", JsonValue.from("object"))
                                        .putAdditionalProperty(
                                            "properties",
                                            JsonValue.from(
                                                Map.of("account_id", Map.of("type", "string"))))
                                        .putAdditionalProperty(
                                            "required", JsonValue.from(List.of("account_id")))
                                        .putAdditionalProperty(
                                            "additionalProperties", JsonValue.from(false))
                                        .build())
                                .deferLoading(true)
                                .build())
                        .build())
                .environmentNone()
                .input("Look up account 42.")
                .build());
System.out.println(result.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
36require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    tools: [
      { type: "tool_search" },
      {
        type: "function",
        name: "lookup_account",
        description: "Find an account by its account number.",
        parameters: {
          type: "object",
          properties: { account_id: { type: "string" } },
          required: ["account_id"],
          additionalProperties: false
        },
        defer_loading: true
      }
    ]
  },
  environment: { type: "none" },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Look up account 42."
        }
      ]
    }
  ]
)
puts result.id

Choisissez une stratégie de chargement des fonctions

Stratégie	Configuration	Cas d’usage	Compromis
Chargement immédiat	Omettez `defer_loading` ou attribuez-lui la valeur `false`.	Un petit nombre de fonctions, ou des fonctions nécessaires à la plupart des tâches.	Les définitions inutilisées occupent de la place dans le contexte. La modification d’une définition peut invalider un préfixe mis en cache.
Chargement différé	Indiquez `defer_loading: true` et ajoutez `tool_search`.	Un vaste catalogue dont seules quelques fonctions sont nécessaires pour chaque tâche.	La découverte ajoute une étape et suppose que la recherche trouve l’outil pertinent.

L’API Agents permet de combiner chargement immédiat et chargement différé dans une même session, mais cette approche est généralement déconseillée. Donnez aux fonctions à chargement différé des noms et des descriptions clairs. Avant de choisir une stratégie par défaut, utilisez des requêtes représentatives pour comparer la réussite des tâches, la consommation de tokens en entrée et la latence.

Outils MCP et outils fournis par des plugins

Dans l’API Agents, la découverte des outils MCP est automatique lorsque le modèle et le fournisseur prennent en charge la recherche d’outils. L’environnement d’exécution diffère le chargement des outils MCP et ajoute la recherche d’outils dès que des outils à chargement différé peuvent faire l’objet d’une recherche. Cela s’applique aux serveurs MCP distants, aux serveurs MCP des exécuteurs et aux outils MCP fournis par des plugins.

Pour les outils MCP seuls, vous n’avez pas besoin d’ajouter { "type": "tool_search" } ni de définir l’option defer_loading au niveau des fonctions sur un serveur MCP. Pour configurer le serveur, consultez le guide Connexions MCP. La configuration de l’API Responses décrite plus haut ne s’applique pas aux serveurs MCP de l’API Agents.

Guides associés

Utilisez l’appel de fonction pour définir des fonctions que le modèle peut appeler et des outils personnalisés.
Consultez le guide Utilisation des outils pour une vue d’ensemble des outils disponibles dans l’API Responses.

Suggestions

Premiers pas

Notions fondamentales

SDK et CLI

Fournisseurs de services cloud

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Rédaction de prompts

Raisonnement

Images

Temps réel et audio

Modèles spécialisés

API Agents

Agents SDK

ChatKit

Recherche et récupération d’informations

Connectez des outils et des sources de données

Créez des workflows qui font appel à des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Créer des applications vocales

Connexions

Traitement audio

Mise en production

Performances et qualité

Évaluation

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts clés

Planification

Développement

Tests et publication

Spécifications de conversion

Guides

Ressources

Identité

Utilisation du forfait ChatGPT

Guides

Envoi de fichiers

API

Mesure des performances

API pour les annonceurs

Référence de l’API

Premiers pas

Premiers pas

Notions de base

Explorer

Disponible sur

Versions

Workflows

Capacités

Sites

dots

Espace ChatGPT

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendre les fonctionnalités de ChatGPT et de Codex

Linux

Windows

Workflows de développement

Extensions et automatisation

Environnements

Codex Cloud

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Premiers pas

Configuration des fonctionnalités

Identité et accès