Recherche d’outils

La recherche d’outils permet au modèle de rechercher et de charger dynamiquement des outils dans son contexte selon ses besoins. Vous évitez ainsi de charger toutes les définitions d’outils dans le contexte du modèle dès le départ, ce qui peut contribuer à réduire la consommation globale de tokens et les coûts. Pour optimiser les coûts et la latence, la recherche d’outils est conçue pour préserver le cache du modèle. Lorsque le modèle découvre de nouveaux outils, ceux-ci sont injectés à la fin de la 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 par session et la découverte automatique des outils MCP, consultez la section API Agents.

Pour activer la recherche d’outils dans l’API Responses, vous devez effectuer deux opérations :

Ajoutez tool_search comme outil dans votre tableau tools.
Si vous utilisez des fonctions, marquez celles dont vous souhaitez différer le chargement avec defer_loading: true. Si vous utilisez des serveurs MCP, définissez defer_loading: true dans la définition de l’outil du serveur MCP.

Utilisez des espaces de noms lorsque c’est possible

Vous pouvez utiliser la recherche d’outils avec des fonctions, des espaces de noms ou des serveurs MCP à chargement différé, mais nous 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 à effectuer des recherches dans ces ensembles, et les économies de tokens y sont généralement plus importantes.

Pour les espaces de noms, defer_loading s’applique aux fonctions qu’ils contiennent, et non à l’objet espace de noms lui-même.

Au début d’une requête, le modèle voit toujours le nom et la description de chaque élément dans lequel il peut effectuer une recherche. Pour un espace de noms ou un serveur MCP, cela signifie que le modèle ne voit initialement que son nom et sa description. Les détails des fonctions qu’il contient ne sont visibles qu’une fois ces fonctions chargées par l’outil de recherche. Pour une fonction individuelle à chargement différé, le modèle voit toujours son nom et sa description : en pratique, la recherche d’outils diffère donc surtout le chargement du schéma des paramètres.

Pour économiser un maximum de tokens, nous recommandons de regrouper les fonctions à chargement différé dans des espaces de noms ou des serveurs MCP. Donnez-leur des descriptions générales claires, qui offrent au modèle une bonne vue d’ensemble de leur contenu afin qu’il puisse rechercher et charger efficacement les seules fonctions pertinentes. Pour limiter la consommation de tokens et améliorer les performances du modèle, essayez de conserver moins de 10 fonctions par espace de noms.

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 même espace de noms peut contenir des outils à chargement différé et des outils à chargement immédiat. Les outils sans defer_loading: true peuvent être appelés immédiatement, tandis que les outils à chargement différé du même espace de noms sont chargés via la recherche d’outils.

Types de recherche d’outils

Choisissez entre deux types 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 le sous-ensemble chargé dans la même réponse.
Recherche d’outils exécutée côté client : le modèle émet un tool_search_call, votre application effectue la recherche et vous renvoyez le tool_search_output correspondant.

Commencez par la recherche d’outils hébergée si les outils à rechercher sont déjà connus au moment où vous créez la requête. Utilisez la recherche d’outils exécutée côté client lorsque la découverte des outils dépend de l’état du projet, de l’état du locataire ou d’un autre système contrôlé par votre application.

Recherche d’outils hébergée

La recherche d’outils hébergée est la solution la plus simple lorsque vous connaissez déjà l’ensemble des fonctions, des espaces de noms ou des serveurs MCP dans lesquels vous souhaitez que le modèle effectue ses recherches. Déclarez-les dès le départ, ajoutez {"type": "tool_search"} et laissez l’API décider des éléments à charger.

Configurez 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 inclut deux éléments de sortie supplémentaires avant l’appel de fonction qui suit :

tool_search_call, qui consigne l’étape de recherche hébergée.
tool_search_output, qui contient le sous-ensemble chargé d’outils désormais disponibles à l’appel.

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 est défini sur server et call_id sur 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, s’il a besoin de fonctions provenant de différents espaces de noms pour accomplir une tâche, il peut choisir de rechercher et de charger ces ensembles conjointement avant d’effectuer les appels de fonction suivants.

Recherche d’outils exécutée côté client

La recherche d’outils exécutée côté client donne à votre application un contrôle total sur le fonctionnement de la découverte des outils. Elle est utile lorsque les outils disponibles dépendent d’informations qu’il serait peu pratique 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 :

Configurez la recherche d’outils exécutée 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",
    input=[
        *first_response.output,
        {
            "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.ToolUnionParam{loadedTool})
	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 :

Renvoyez 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, l’outil chargé peut être appelé 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 est défini sur client et call_id est renseigné. Reprenez la même valeur call_id du 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, car le modèle s’appuie sur cette description pour décider quand charger un sous-ensemble de ses fonctions. Évitez les descriptions trop longues. Réservez les détails aux descriptions des fonctions à chargement différé, qui ne sont chargées qu’en cas de besoin.

Comprenez ce qui est chargé

tool_search_output.tools contient la liste des outils chargés dynamiquement par le modèle. Celui-ci pourra appeler n’importe lequel 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. Les outils absents de ce tableau ne seront pas disponibles pour le modèle. 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. Notez toutefois que toute modification de cet ensemble invalide le cache du modèle à partir de ce point.

Techniques d’injection avancées

La plupart des intégrations déclarent les outils dans le paramètre tools de la requête. La recherche d’outils exécutée côté client prend également en charge des techniques plus avancées, dans lesquelles votre application renvoie des outils absents de la requête initiale. Il s’agit d’un workflow avancé : validez soigneusement les schémas renvoyés et n’exposez 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 pour la recherche d’outils hébergée que pour celle exécutée côté client. Le cache du modèle peut ainsi être préservé d’une requête à l’autre, ce qui réduit les coûts globaux et améliore la vitesse.

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

Pour les workflows avancés, vous pouvez utiliser un élément d’entrée additional_tools afin de rendre des outils disponibles à un moment précis de la conversation. C’est utile lorsque votre application charge des outils en dehors du processus normal de recherche d’outils ou doit préserver l’ordre des outils ajoutés lors d’une réponse précédente.

Définissez role sur developer et incluez 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 afin que le modèle voie les mêmes outils au même moment dans la conversation.

API Agents

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

Votre 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 modifie le moment où cette définition est transmise au modèle. Une fois la fonction découverte, votre application traite l’appel de fonction et renvoie son résultat comme d’habitude. Pour le traitement des résultats, consultez la section Fonctions.

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

Chargez les outils de type fonction uniquement lorsque nécessaire

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’utilisation	Compromis
Chargement immédiat	Omettez `defer_loading` ou définissez sa valeur sur `false`.	Un petit ensemble de fonctions, ou des fonctions nécessaires à la plupart des tâches.	Les définitions inutilisées occupent de la place dans le contexte. Modifier une définition peut invalider un préfixe mis en cache.
Chargement différé	Définissez `defer_loading: true` et ajoutez `tool_search`.	Un vaste catalogue dont chaque tâche ne nécessite que quelques fonctions.	La découverte ajoute une étape et dépend de la capacité à trouver l’outil pertinent.

Combiner des fonctions à chargement immédiat et différé dans une session de l’API Agents est possible, mais généralement déconseillé. Donnez aux fonctions à chargement différé des noms et des descriptions clairs. Comparez la réussite des tâches, la consommation de tokens d’entrée et la latence sur des requêtes représentatives avant de choisir une stratégie par défaut.

Outils MCP et outils de plugins

Les outils MCP utilisent la découverte automatique dans l’API Agents 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 lorsque des outils à chargement différé peuvent être découverts par recherche. Ce fonctionnement s’applique aux serveurs MCP distants, aux serveurs MCP des exécuteurs et aux outils MCP fournis par des plugins.

Vous n’avez pas besoin d’ajouter { "type": "tool_search" } uniquement pour les outils MCP, ni de définir sur un serveur MCP le paramètre defer_loading prévu pour les fonctions. Configurez le serveur à l’aide des Connexions MCP. La configuration de l’API Responses présentée plus haut dans ce guide ne s’applique pas aux serveurs MCP de l’API Agents.

Utilisez l’appel de fonction pour définir des fonctions appelables et des outils personnalisés.
Consultez le guide Utilisation des outils pour une vue d’ensemble des outils disponibles dans Responses.

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