도구 검색을 사용하면 모델이 필요할 때 도구를 동적으로 검색해 컨텍스트에 로드할 수 있습니다. 모든 도구 정의를 미리 로드할 필요가 없어 전체 토큰 사용량과 비용을 줄이는 데 도움이 될 수 있습니다. 도구 검색은 비용과 지연 시간을 줄이기 위해 모델의 캐시를 유지하도록 설계되었습니다. 모델이 새 도구를 찾으면 해당 도구가 컨텍스트 윈도우 끝에 추가됩니다.
Responses API에서는 gpt-5.4 이상 모델만 tool_search를 지원합니다.
다음 설정과 예제에서는 Responses API를 사용합니다. 세션 단위 함수 로딩과 MCP 도구 자동 검색에 관해서는 Agents API를 참고하세요.
Responses API에서 도구 검색을 활성화하려면 다음 두 가지를 설정하세요.
tool_search를 tools 배열에 도구로 추가하세요.- 함수를 사용하는 경우 로딩을 미룰 함수에
defer_loading: true를 설정하세요. MCP 서버를 사용하는 경우 MCP 서버 도구 정의에 defer_loading: true를 설정하세요.
로딩을 미룬 함수, 네임스페이스, MCP 서버에 도구 검색을 사용할 수 있습니다. 가능하면 네임스페이스나 MCP 서버를 사용하는 것이 좋습니다. 모델이 주로 네임스페이스와 MCP 서버를 검색하도록 학습되었고, 일반적으로 이 둘을 사용할 때 토큰 절감 효과도 더 큽니다.
네임스페이스에서 defer_loading은 네임스페이스 객체 자체가 아니라 그 안에 있는 함수에 적용됩니다.
요청이 시작되면 모델에는 검색 대상의 이름과 설명이 표시됩니다. 네임스페이스나 MCP 서버의 경우 처음에는 네임스페이스나 서버의 이름과 설명만 표시됩니다. 그 안에 있는 개별 함수의 세부 정보는 도구 검색으로 해당 함수를 로드한 후에 표시됩니다. 개별 함수의 로딩을 미룬 경우에도 모델에는 함수 이름과 설명이 표시되므로, 실제로는 주로 매개변수 스키마의 로딩이 미뤄집니다.
토큰을 최대한 절약하려면 로딩을 미룰 함수를 네임스페이스나 MCP 서버로 묶고, 각각 어떤 기능을 제공하는지 명확하게 요약하세요. 그러면 모델이 효과적으로 검색해 필요한 함수만 로드할 수 있습니다. 토큰 효율과 모델 성능을 높이려면 네임스페이스당 함수 수를 10개 미만으로 유지하는 것이 좋습니다.
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"
}
]
}
하나의 네임스페이스에 즉시 로드할 도구와 로딩을 미룰 도구를 함께 둘 수 있습니다. defer_loading: true를 설정하지 않은 도구는 바로 호출할 수 있고, 같은 네임스페이스에서 로딩을 미룬 도구는 도구 검색을 통해 로드됩니다.
다음 두 가지 도구 검색 방식 중 하나를 선택하세요.
- 호스팅형 도구 검색: OpenAI가 요청에 선언된 지연 로딩 도구를 검색하고, 그중 로드한 도구를 같은 응답에 포함해 반환합니다.
- 클라이언트 실행형 도구 검색: 모델이
tool_search_call을 생성하면 애플리케이션이 검색을 수행하고 해당 호출에 대응하는 tool_search_output을 반환합니다.
요청을 만들 때 검색할 도구 후보를 이미 알고 있다면 호스팅형 도구 검색부터 사용하세요. 검색 대상이 프로젝트 상태, 테넌트 상태 또는 애플리케이션이 제어하는 다른 시스템에 따라 달라진다면 클라이언트 실행형 도구 검색을 사용하세요.
모델이 검색할 함수, 네임스페이스, MCP 서버의 전체 목록을 이미 알고 있다면 호스팅형 도구 검색이 가장 간단합니다. 검색 대상을 미리 선언하고 {"type": "tool_search"}를 추가하면 API가 어떤 도구를 로드할지 결정합니다.
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)
모델이 지연 로딩 도구가 필요하다고 판단하면 응답에서 실제 함수 호출 앞에 다음 두 출력 항목이 추가됩니다.
tool_search_call은 호스팅형 검색 단계를 기록합니다.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
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\"}"
}
]
호스팅 모드에서는 execution이 server로, call_id가 null로 설정됩니다.
더 복잡한 작업에서는 모델이 하나의 tool_search_call로 여러 네임스페이스나 MCP 서버를 로드할 수도 있습니다. 예를 들어 하나의 작업을 완료하는 데 서로 다른 네임스페이스의 함수가 필요하면, 모델은 해당 네임스페이스를 함께 검색해 로드한 뒤 함수를 호출할 수 있습니다.
클라이언트 실행형 도구 검색에서는 애플리케이션이 도구를 찾는 방식을 전적으로 제어합니다. 처음부터 tools 목록에 명시하기 어려운 정보에 따라 사용 가능한 도구가 달라질 때 유용합니다.
tool_search 도구에 execution: "client"를 설정하고 애플리케이션이 받을 검색 인수의 스키마를 지정하세요.
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
첫 번째 턴에서 모델은 tool_search_call을 생성하고 해당 턴을 종료합니다.
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."
}
}
]
이어서 애플리케이션이 검색을 수행하고 로드할 도구를 담은 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
}
}
]
}
]
다음 턴부터는 로드된 도구를 일반 함수처럼 호출할 수 있습니다.
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\"}"
}
]
클라이언트 모드에서는 execution이 client로 설정되고 call_id에 값이 지정됩니다. call_id는 tool_search_call에서 받은 값을 그대로 tool_search_output에 포함해 반환하세요.
모델은 네임스페이스 설명을 바탕으로 그 안에 있는 함수 중 일부를 언제 로드할지 결정합니다. 네임스페이스를 어떤 상황에 사용하는지 명확하게 설명하세요. 설명은 간결하게 유지하고, 자세한 내용은 필요할 때만 로드되는 개별 함수의 설명에 담으세요.
tool_search_output.tools에는 모델이 동적으로 로드한 도구 목록이 들어 있습니다. 모델은 이후 턴에서도 이 목록의 도구를 모두 호출할 수 있으므로 클라이언트 모드에서 같은 도구를 매 턴 다시 로드할 필요가 없습니다. 이 배열에 포함되지 않은 도구는 모델이 사용할 수 없습니다. 로드된 도구를 비활성화하려면 로드할 도구 목록을 정의한 tool_search_output 항목에서 해당 도구를 제거하세요. 단, 목록을 변경하면 그 지점부터 모델의 기존 캐시를 사용할 수 없습니다.
대부분의 통합에서는 요청의 tools 매개변수에 도구를 선언합니다. 클라이언트 실행형 도구 검색은 애플리케이션이 원래 요청에 없던 도구를 반환하는 방식도 지원합니다. 이 고급 워크플로우를 사용할 때는 반환되는 스키마를 꼼꼼히 검증하고 신뢰할 수 있는 도구 정의만 제공하세요.
모든 도구는 모델의 컨텍스트 윈도우 끝에 로드됩니다. 이는 호스팅형 도구 검색과 클라이언트 실행형 도구 검색에 모두 적용됩니다. 따라서 다음 요청에서도 모델의 캐시를 재사용할 수 있어 전체 비용이 줄고 처리 속도가 빨라집니다.
고급 워크플로우에서는 additional_tools 입력 항목을 사용해 대화의 특정 지점부터 도구를 사용할 수 있도록 설정할 수 있습니다. 애플리케이션이 일반적인 도구 검색 플로우 밖에서 도구를 로드하거나 이전 응답에서 도구가 추가된 순서를 유지해야 할 때 유용합니다.
role을 developer로 설정하고 항목의 tools 배열에 추가할 도구를 넣으세요.
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
}
}
]
}
additional_tools 항목에 포함된 도구는 입력에서 해당 항목이 나타난 이후에만 사용할 수 있습니다. 대화 항목을 직접 받아 다시 보낼 때는 모델이 대화의 같은 지점에서 같은 도구를 볼 수 있도록 항목의 위치를 유지하세요.
Agents API는 기본적으로 함수 정의를 즉시 로드합니다. 특정 함수의 로딩을 미루려면 { "type": "tool_search" }를 agent.tools에 포함하고 에이전트가 필요할 때 검색할 각 함수에 defer_loading: true를 설정하세요. tool_search를 추가하는 것만으로 모든 함수의 로딩이 미뤄지지는 않습니다.
세션 요청에는 여전히 이름, 설명, 인수 스키마를 포함한 전체 함수 정의를 제공해야 합니다. 도구 검색을 사용하면 모델이 해당 정의를 받는 시점이 달라집니다. 모델이 함수를 찾은 뒤에는 평소처럼 애플리케이션이 함수 호출을 처리하고 결과를 반환합니다. 결과 처리 방법은 함수를 참고하세요.
예제를 실행하기 전에 OPENAI_API_KEY를 설정하세요.
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
| 전략 |
설정 |
적합한 경우 |
고려 사항 |
| 즉시 로딩 |
defer_loading을 생략하거나 false로 설정합니다. |
함수 수가 적거나 대부분의 작업에 필요한 함수인 경우 |
사용하지 않는 함수 정의도 컨텍스트를 차지합니다. 정의를 변경하면 캐시된 접두부가 무효화될 수 있습니다. |
| 지연 로딩 |
defer_loading: true를 설정하고 tool_search를 포함합니다. |
함수 목록이 크지만 각 작업에는 몇 개의 함수만 필요한 경우 |
검색 단계가 추가되며, 필요한 도구를 찾아야 호출할 수 있습니다. |
Agents API 세션에서 즉시 로딩 함수와 지연 로딩 함수를 함께 사용할 수 있지만 일반적으로 권장하지 않습니다. 지연 로딩 함수에는 명확한 이름과 설명을 지정하세요. 기본 전략을 선택하기 전에 대표적인 요청으로 작업 완료 여부, 입력 토큰 사용량, 지연 시간을 비교하세요.
모델과 제공업체가 도구 검색을 지원하면 Agents API에서 MCP 도구를 자동으로 검색합니다. 런타임은 MCP 도구의 로딩을 미루고, 검색할 수 있는 지연 로딩 도구가 있으면 도구 검색을 추가합니다. 원격 MCP, 실행기 MCP, 플러그인이 제공하는 MCP 도구 모두에 이 방식이 적용됩니다.
MCP 도구를 사용하기 위해 별도로 { "type": "tool_search" }를 추가하거나 MCP 서버에 함수 수준의 defer_loading 플래그를 설정할 필요는 없습니다. MCP 연결을 사용해 서버를 설정하세요. 이 가이드 앞부분의 Responses API 설정은 Agents API의 MCP 서버에 적용되지 않습니다.
- 함수 호출을 사용해 호출 가능한 함수와 사용자 지정 도구를 정의하세요.
- Responses API에서 사용할 수 있는 도구 전반을 살펴보려면 도구 사용하기를 참고하세요.
