函数调用 (也称为工具调用 )让 OpenAI 模型能够灵活地与外部系统交互,访问训练数据以外的数据。本指南介绍如何让模型访问应用提供的数据并执行应用支持的操作。您将了解如何使用由 JSON 模式定义的函数工具,以及支持自由格式文本输入和输出的自定义工具。
在 Agents API 会话中,请使用函数 注册函数并处理会话中的操作请求。本指南中的示例展示了如何与 Responses API 和 Chat Completions 集成。
如果您的应用包含大量函数或较大的模式,可以将函数调用与工具搜索 结合使用,推迟加载不常用的工具,直到模型需要时才加载。只有 gpt-5.4 及后续模型支持 tool_search。
GPT-6 Astra 和 GPT-6.1 Sol 必须通过 Responses API 调用工具。Chat Completions 示例使用 GPT-5.6 Terra,并关闭了推理。要更新现有集成,请参阅迁移指南 。
先来了解工具调用中的几个关键术语,再通过实际示例看看如何调用工具。
工具:提供给模型的功能 函数 或工具 泛指您告知模型可以使用的某项功能。模型根据提示词生成响应时,可能会判断自己需要工具提供的数据或功能才能执行提示词中的指令。
您可以向模型提供能执行以下操作的工具:
查询某个地点今天的天气
根据用户 ID 查询账户详情
为丢失的订单办理退款
您也可以提供其他工具,让模型在回应提示词时获取所需信息或执行您希望它执行的操作。
通过 API 向模型发送提示词时,可以在请求中附上可供模型选用的工具列表。例如,如果您希望模型能回答关于世界各地当前天气的问题,可以为它提供一个 get_weather 工具,该工具接受 location 参数。
工具调用:模型发出的工具使用请求 函数调用 或工具调用 是模型返回的一种特殊响应。模型分析提示词后,如果判断需要调用您提供的某个工具才能执行其中的指令,就可能返回这种响应。
如果模型在 API 请求中收到“巴黎的天气怎么样?”这样的提示词,它可能会请求调用 get_weather 工具,并将 Paris 作为 location 参数的值。
工具调用输出:为模型生成的结果 函数调用输出 或工具调用输出 是工具根据模型调用时提供的输入生成的响应。工具调用输出可以是结构化 JSON 或纯文本,并且应指明它对应模型的哪一次工具调用(后面的示例使用 call_id 标识调用)。
以查询天气为例,完整过程如下:
模型可以使用 get_weather 工具 ,该工具接受 location 参数。
收到“巴黎的天气怎么样?”这样的提示词后,模型返回一次工具调用 ,其中 location 参数的值为 Paris。
工具调用输出 可以是 JSON 对象(例如,{"temperature": "25", "unit": "C"} 表示当前气温为 25 摄氏度)、图像内容 或文件内容 。
然后,将工具定义、原始提示词、模型的工具调用和工具调用输出一起发回给模型,就可以得到如下文本响应:
The weather in Paris today is 25C.
函数与工具的区别
函数是一种由 JSON 模式定义的工具。通过函数定义,模型可以向您的应用传递数据,应用中的代码则可以访问数据或执行模型建议的操作。
除函数工具外,您还可以使用本指南介绍的自定义工具,以自由格式的文本作为输入和输出。
OpenAI 平台还提供内置工具 。通过这些工具,模型可以进行网页搜索 、运行代码 、使用 MCP 服务器 提供的功能等。
工具调用是您的应用通过 OpenAI API 与模型进行多步交互的过程。整个流程大致分为五步:
向模型发送请求,并提供可调用的工具
接收模型返回的工具调用
使用工具调用提供的输入,在应用端执行代码
将工具输出放入第二次请求中,发送给模型
接收模型的最终响应(或更多工具调用)
使用 Responses 时,应用可以按任务需要重复这一流程,直到完成所需的工具调用。如果您希望使用框架来处理这个循环中反复出现的编排工作,请参阅 Responses API 与 Agents SDK 的比较 。
下面以 get_horoscope 函数为例,展示完整的工具调用流程。该函数可以查询指定星座的每日运势。
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 import OpenAI from "openai";
const openai = new OpenAI();
// 1. Define a list of callable tools for the model
const tools: OpenAI.Chat.Completions.ChatCompletionTool[] = [
{
type: "function",
function: {
name: "get_horoscope",
description: "Get today's horoscope for an astrological sign.",
parameters: {
type: "object",
properties: {
sign: {
type: "string",
description: "An astrological sign like Taurus or Aquarius",
},
},
required: ["sign"],
additionalProperties: false,
},
strict: true,
},
},
];
function getHoroscope(sign: string) {
return `${sign}: Next Tuesday you will befriend a baby otter.`;
}
const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
{ role: "user", content: "What is my horoscope? I am an Aquarius." },
];
// 2. Prompt the model with tools defined
let response = await openai.chat.completions.create({
model: "gpt-5.6-terra",
reasoning_effort: "none",
messages,
tools,
});
messages.push(response.choices[0].message);
for (const toolCall of response.choices[0].message.tool_calls ?? []) {
if (toolCall.type !== "function") continue;
if (toolCall.function.name === "get_horoscope") {
// 3. Execute the function logic for get_horoscope
const args = JSON.parse(toolCall.function.arguments);
const horoscope = getHoroscope(args.sign);
// 4. Provide function call results to the model
messages.push({
role: "tool",
tool_call_id: toolCall.id,
content: JSON.stringify({ horoscope }),
});
}
}
response = await openai.chat.completions.create({
model: "gpt-5.6-terra",
reasoning_effort: "none",
messages,
tools,
});
// 5. The model should be able to give a response!
console.log(response.choices[0].message.content); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69 from openai import OpenAI
import json
client = OpenAI()
# 1. Define a list of callable tools for the model
tools = [
{
"type" : "function" ,
"function" : {
"name" : "get_horoscope" ,
"description" : "Get today's horoscope for an astrological sign." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"sign" : {
"type" : "string" ,
"description" : "An astrological sign like Taurus or Aquarius" ,
},
},
"required" : [ "sign" ],
"additionalProperties" : False ,
},
"strict" : True ,
},
},
]
def get_horoscope (sign):
return f " { sign } : Next Tuesday you will befriend a baby otter."
messages = [{ "role" : "user" , "content" : "What is my horoscope? I am an Aquarius." }]
# 2. Prompt the model with tools defined
response = client.chat.completions.create(
model = "gpt-5.6-terra" ,
reasoning_effort = "none" ,
messages = messages,
tools = tools,
)
messages.append(response.choices[ 0 ].message)
for tool_call in response.choices[ 0 ].message.tool_calls or []:
if tool_call.function.name == "get_horoscope" :
# 3. Execute the function logic for get_horoscope
args = json.loads(tool_call.function.arguments)
horoscope = get_horoscope(args[ "sign" ])
# 4. Provide function call results to the model
messages.append(
{
"role" : "tool" ,
"tool_call_id" : tool_call.id,
"content" : json.dumps({ "horoscope" : horoscope}),
}
)
response = client.chat.completions.create(
model = "gpt-5.6-terra" ,
reasoning_effort = "none" ,
messages = messages,
tools = tools,
)
# 5. The model should be able to give a response!
print (response.choices[ 0 ].message.content) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
tool := horoscopeChatTool()
messages := []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("What is my horoscope? I am an Aquarius."),
}
completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
Model: "gpt-5.6-terra", Messages: messages, Tools: []openai.ChatCompletionToolUnionParam{tool},
ReasoningEffort: shared.ReasoningEffortNone,
})
if err != nil {
panic(err)
}
messages = append(messages, completion.Choices[0].Message.ToParam())
for _, call := range completion.Choices[0].Message.ToolCalls {
if call.Type != "function" || call.Function.Name != "get_horoscope" {
continue
}
var arguments struct {
Sign string `json:"sign"`
}
if err := json.Unmarshal([]byte(call.Function.Arguments), &arguments); err != nil {
panic(err)
}
horoscope := getHoroscope(arguments.Sign)
messages = append(messages, openai.ToolMessage(horoscope, call.ID))
}
completion, err = client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
Model: "gpt-5.6-terra", Messages: messages, Tools: []openai.ChatCompletionToolUnionParam{tool},
ReasoningEffort: shared.ReasoningEffortNone,
})
if err != nil {
panic(err)
}
fmt.Println(completion.Choices[0].Message.Content)
}
func horoscopeChatTool() openai.ChatCompletionToolUnionParam {
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"sign": map[string]any{"type": "string", "description": "An astrological sign like Taurus or Aquarius"},
},
"required": []string{"sign"},
"additionalProperties": false,
}
return openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
Function: shared.FunctionDefinitionParam{
Name: "get_horoscope", Description: openai.String("Get today's horoscope for an astrological sign."), Parameters: parameters, Strict: openai.Bool(true),
},
}}
}
func getHoroscope(sign string) string {
return fmt.Sprintf("%s: Next Tuesday you will befriend a baby otter.", sign)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.ReasoningEffort;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionToolMessageParam;
import java.util.List;
import java.util.Map;
FunctionDefinition horoscope =
FunctionDefinition.builder()
.name("get_horoscope")
.description("Get today's horoscope for an astrological sign.")
.parameters(
FunctionParameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties",
JsonValue.from(
Map.of(
"sign",
Map.of(
"type", "string",
"description",
"An astrological sign like Taurus or Aquarius"))))
.putAdditionalProperty("required", JsonValue.from(List.of("sign")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ChatCompletionCreateParams params =
ChatCompletionCreateParams.builder()
.model("gpt-5.6-terra")
.reasoningEffort(ReasoningEffort.NONE)
.addUserMessage("What is my horoscope? I am an Aquarius.")
.addFunctionTool(horoscope)
.build();
var assistant = client.chat().completions().create(params).choices().get(0).message();
var calls = assistant.toolCalls().orElseThrow(() -> new IllegalStateException("No tool calls"));
var followUp = params.toBuilder().addMessage(assistant);
record HoroscopeArguments(String sign) {}
for (var toolCall : calls) {
var function = toolCall.asFunction();
if (function.function().name().equals("get_horoscope")) {
String sign = function.function().arguments(HoroscopeArguments.class).sign();
followUp.addMessage(
ChatCompletionToolMessageParam.builder()
.toolCallId(function.id())
.content(sign + ": Embrace an unexpected opportunity today.")
.build());
}
}
client.chat().completions().create(followUp.build()).choices().stream()
.flatMap(choice -> choice.message().content().stream())
.forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62 require "json"
require "openai"
client = OpenAI::Client.new
messages = [
{
role: :user,
content: "What is my horoscope? I am an Aquarius."
}
]
tools = [
{
type: :function,
function: {
name: "get_horoscope",
description: "Get today's horoscope for an astrological sign.",
parameters: {
type: :object,
properties: { sign: { type: :string } },
required: ["sign"],
additionalProperties: false
},
strict: true
}
}
]
first_completion = client.chat.completions.create(
model: "gpt-5.6-terra",
reasoning_effort: :none,
messages: messages,
tools: tools
)
assistant_message = first_completion.choices.fetch(0).message
tool_calls = assistant_message.tool_calls || []
raise "The model did not call get_horoscope" if tool_calls.empty?
messages << {
role: :assistant,
content: assistant_message.content,
tool_calls: tool_calls.map(&:to_h)
}
tool_calls.each do |tool_call|
next unless tool_call.is_a?(OpenAI::Models::Chat::ChatCompletionMessageFunctionToolCall)
next unless tool_call.function.name == "get_horoscope"
arguments = JSON.parse(tool_call.function.arguments, symbolize_names: true)
sign = arguments.fetch(:sign)
messages << {
role: :tool,
tool_call_id: tool_call.id,
content: "#{sign}: Embrace an unexpected opportunity today."
}
end
final_completion = client.chat.completions.create(
model: "gpt-5.6-terra",
reasoning_effort: :none,
messages: messages,
tools: tools
)
puts(final_completion.choices.fetch(0).message.content)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77 import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";
const openai = new OpenAI();
// 1. Define a list of callable tools for the model
const tools: OpenAI.Responses.Tool[] = [
{
type: "function",
name: "get_horoscope",
description: "Get today's horoscope for an astrological sign.",
parameters: {
type: "object",
properties: {
sign: {
type: "string",
description: "An astrological sign like Taurus or Aquarius",
},
},
required: ["sign"],
additionalProperties: false,
},
strict: true,
},
];
function getHoroscope(sign: string) {
return `${sign}: Next Tuesday you will befriend a baby otter.`;
}
// Create a running input list we will add to over time
let input: OpenAI.Responses.ResponseInput = [
{ role: "user", content: "What is my horoscope? I am an Aquarius." },
];
// 2. Prompt the model with tools defined
let response = await openai.responses.create({
model: "gpt-6.2-astra",
tools,
input,
});
// Preserve model output for the next turn
input.push(...toResponseInputItems(response.output));
for (const item of response.output) {
if (item.type !== "function_call") continue;
if (item.name === "get_horoscope") {
// 3. Execute the function logic for get_horoscope
const { sign } = JSON.parse(item.arguments);
const horoscope = getHoroscope(sign);
// 4. Provide function call results to the model
input.push({
type: "function_call_output",
call_id: item.call_id,
output: horoscope,
});
}
}
console.log("Final input:");
console.log(JSON.stringify(input, null, 2));
response = await openai.responses.create({
model: "gpt-6.2-astra",
instructions: "Respond only with a horoscope generated by a tool.",
tools,
input,
});
// 5. The model should be able to give a response!
console.log("Final output:");
console.log(response.output_text); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69 from openai import OpenAI
import json
client = OpenAI()
# 1. Define a list of callable tools for the model
tools = [
{
"type" : "function" ,
"name" : "get_horoscope" ,
"strict" : True ,
"description" : "Get today's horoscope for an astrological sign." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"sign" : {
"type" : "string" ,
"description" : "An astrological sign like Taurus or Aquarius" ,
},
},
"required" : [ "sign" ],
"additionalProperties" : False ,
},
},
]
def get_horoscope (sign):
return f " { sign } : Next Tuesday you will befriend a baby otter."
# Create a running input list we will add to over time
input_list = [{ "role" : "user" , "content" : "What is my horoscope? I am an Aquarius." }]
# 2. Prompt the model with tools defined
response = client.responses.create(
model = "gpt-6.2-astra" ,
tools = tools,
input = input_list,
)
# Save function call outputs for subsequent requests
input_list += response.output
for item in response.output:
if item.type == "function_call" :
if item.name == "get_horoscope" :
# 3. Execute the function logic for get_horoscope
sign = json.loads(item.arguments)[ "sign" ]
horoscope = get_horoscope(sign)
# 4. Provide function call results to the model
input_list.append(
{
"type" : "function_call_output" ,
"call_id" : item.call_id,
"output" : horoscope,
}
)
response = client.responses.create(
model = "gpt-6.2-astra" ,
instructions = "Respond only with a horoscope generated by a tool." ,
tools = tools,
input = input_list,
)
# 5. The model should be able to give a response!
print (response.output_text) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := horoscopeResponseTool()
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is my horoscope? I am an Aquarius.")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
var functionOutput responses.ResponseInputItemUnionParam
for _, output := range response.Output {
if output.Type != "function_call" {
continue
}
call := output.AsFunctionCall()
if call.Name != "get_horoscope" {
continue
}
var arguments struct {
Sign string `json:"sign"`
}
if err := json.Unmarshal([]byte(call.Arguments), &arguments); err != nil {
panic(err)
}
functionOutput = responses.ResponseInputItemParamOfFunctionCallOutput(getHoroscope(arguments.Sign))
functionOutput.OfFunctionCallOutput.CallID = openai.String(call.CallID)
}
if functionOutput.OfFunctionCallOutput == nil {
panic("the model did not call get_horoscope")
}
response, err = client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
PreviousResponseID: openai.String(response.ID),
Instructions: openai.String("Respond only with a horoscope generated by a tool."),
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{functionOutput}},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(response.OutputText())
}
func horoscopeResponseTool() responses.ToolUnionParam {
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"sign": map[string]any{"type": "string", "description": "An astrological sign like Taurus or Aquarius"},
},
"required": []string{"sign"},
"additionalProperties": false,
}
tool := responses.ToolParamOfFunction("get_horoscope", parameters, true)
tool.OfFunction.Description = openai.String("Get today's horoscope for an astrological sign.")
return tool
}
func getHoroscope(sign string) string {
return fmt.Sprintf("%s: Next Tuesday you will befriend a baby otter.", sign)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;
FunctionTool horoscope =
FunctionTool.builder()
.name("get_horoscope")
.description("Get today's horoscope for an astrological sign.")
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties",
JsonValue.from(
Map.of(
"sign",
Map.of(
"type", "string",
"description",
"An astrological sign like Taurus or Aquarius"))))
.putAdditionalProperty("required", JsonValue.from(List.of("sign")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
var firstResponse =
client
.responses()
.create(
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.input("What is my horoscope? I am an Aquarius.")
.addTool(horoscope)
.build());
var functionCall =
firstResponse.output().stream()
.flatMap(item -> item.functionCall().stream())
.filter(call -> call.name().equals("get_horoscope"))
.findFirst()
.orElseThrow(() -> new IllegalStateException("The model did not call get_horoscope"));
record HoroscopeArguments(String sign) {}
String sign = functionCall.arguments(HoroscopeArguments.class).sign();
ResponseCreateParams followUp =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.instructions("Respond only with a horoscope generated by a tool.")
.previousResponseId(firstResponse.id())
.inputOfResponse(
List.of(
ResponseInputItem.ofFunctionCallOutput(
ResponseInputItem.FunctionCallOutput.builder()
.callId(functionCall.callId())
.output(sign + ": Embrace an unexpected opportunity today.")
.build())))
.addTool(horoscope)
.build();
client.responses().create(followUp).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48 require "json"
require "openai"
client = OpenAI::Client.new
tools = [
{
type: :function,
name: "get_horoscope",
description: "Get today's horoscope for an astrological sign.",
parameters: {
type: :object,
properties: { sign: { type: :string } },
required: ["sign"],
additionalProperties: false
},
strict: true
}
]
first_response = client.responses.create(
model: "gpt-6.2-astra",
input: "What is my horoscope? I am an Aquarius.",
tools: tools
)
function_call = first_response.output.find do |item|
item.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall) &&
item.name == "get_horoscope"
end
unless function_call.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)
raise "The model did not call get_horoscope"
end
arguments = JSON.parse(function_call.arguments, symbolize_names: true)
sign = arguments.fetch(:sign)
response = client.responses.create(
model: "gpt-6.2-astra",
previous_response_id: first_response.id,
input: [
{
type: :function_call_output,
call_id: function_call.call_id,
output: "#{sign}: Embrace an unexpected opportunity today."
}
],
tools: tools
)
puts(response.output_text)
对于 GPT-5 或 o4-mini 等推理模型,如果模型的响应中包含工具调用,您必须将该响应中的所有推理项与工具调用输出一起发回给模型。有关如何保留模型生成这些推理项时所依据的对话历史,请参阅更改前缀的最佳实践 。
通常在每个 API 请求的 tools 参数中声明函数。使用工具搜索 时,应用也可以在交互过程中按需加载先前推迟加载的函数。无论采用哪种方式,每个可调用函数的模式结构都相同。函数定义包含以下属性:
字段
说明
type
应始终为 function
name
函数名称(例如 get_weather)
description
详细说明何时以及如何使用函数
parameters
定义函数输入参数的 JSON 模式
strict
是否对函数调用强制使用严格模式
下面是 get_weather 函数的定义示例:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 {
"type" : "function" ,
"name" : "get_weather" ,
"description" : "Retrieves current weather for the given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia"
},
"units" : {
"type" : "string" ,
"enum" : [ "celsius" , "fahrenheit" ],
"description" : "Units the temperature will be returned in."
}
},
"required" : [ "location" , "units" ],
"additionalProperties" : false
},
"strict" : true
}
由于 parameters 由 JSON 模式 定义,您可以使用属性类型、枚举、描述、嵌套对象和递归对象等多种特性。
使用命名空间可以按业务领域对相关工具进行分组,例如 crm、billing 或 shipping。命名空间便于组织相似的工具。当模型需要在服务于不同系统或用途的工具之间做选择时,命名空间尤其有用,例如一个搜索工具用于 CRM,另一个用于支持工单系统。
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 {
"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
}
}
]
}
如果需要让模型使用大量工具,可以通过 tool_search 推迟加载部分或全部工具。模型可以使用 tool_search 工具搜索相关工具,将其添加到模型上下文中,再加以使用。只有 gpt-5.4 及后续模型支持此功能。详情请参阅工具搜索指南 。
(可选)根据类型生成函数模式 请尽可能直接定义函数模式。Python 和 TypeScript 客户端库也提供了辅助函数,可以将 pydantic 和 zod 对象转换为模式,但这些辅助函数仅支持部分特性。
如果使用 Go,请安装 github.com/google/jsonschema-go@v0.4.3。该库根据 Go 结构体生成模式,OpenAI SDK 会将生成的模式随请求一起发送。
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 import OpenAI from "openai";
import { z } from "zod";
import { zodFunction } from "openai/helpers/zod";
const openai = new OpenAI();
const GetWeatherParameters = z.object({
location: z.string().describe("City and country e.g. Bogotá, Colombia"),
});
const tools = [
zodFunction({ name: "getWeather", parameters: GetWeatherParameters }),
];
const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
{ role: "user", content: "What's the weather like in Paris today?" },
];
const response = await openai.chat.completions.create({
model: "gpt-5.6-terra",
reasoning_effort: "none",
messages,
tools,
store: true,
});
console.log(response.choices[0].message.tool_calls); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 from openai import OpenAI, pydantic_function_tool
from pydantic import BaseModel, Field
client = OpenAI()
class GetWeather ( BaseModel ):
location: str = Field( ... , description = "City and country e.g. Bogotá, Colombia" )
tools = [pydantic_function_tool(GetWeather)]
completion = client.chat.completions.create(
model = "gpt-5.6-terra" ,
reasoning_effort = "none" ,
messages = [{ "role" : "user" , "content" : "What's the weather like in Paris today?" }],
tools = tools,
)
print (completion.choices[ 0 ].message.tool_calls) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53 package main
import (
"context"
"encoding/json"
"fmt"
"github.com/google/jsonschema-go/jsonschema"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/shared"
)
type GetWeather struct {
Location string `json:"location" jsonschema:"City and country, such as Paris, France"`
}
func main() {
client := openai.NewClient()
schema, err := jsonschema.For[GetWeather](nil)
if err != nil {
panic(err)
}
data, err := json.Marshal(schema)
if err != nil {
panic(err)
}
var parameters shared.FunctionParameters
if err := json.Unmarshal(data, ¶meters); err != nil {
panic(err)
}
tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
Function: shared.FunctionDefinitionParam{
Name: "get_weather", Description: openai.String("Get the current weather for a location."), Parameters: parameters, Strict: openai.Bool(true),
},
}}
completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
Model: "gpt-5.6-terra",
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("What's the weather like in Paris today?"),
},
Tools: []openai.ChatCompletionToolUnionParam{tool},
ReasoningEffort: shared.ReasoningEffortNone,
})
if err != nil {
panic(err)
}
if len(completion.Choices) == 0 {
panic("Response has no choices")
}
fmt.Println(completion.Choices[0].Message.ToolCalls)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 require "openai"
class GetWeather < OpenAI::BaseModel
required :location, String
end
client = OpenAI::Client.new
completion = client.chat.completions.create(
model: "gpt-5.6-terra",
reasoning_effort: :none,
messages: [
{
role: :user,
content: "What's the weather like in Paris today?"
}
],
tools: [GetWeather]
)
puts(completion.choices.fetch(0).message.tool_calls)
给函数起一个清楚具体的名称,并详细说明参数和用法。
明确说明函数和每个参数的用途 ,注明参数格式,并解释输出的含义。
在系统提示词中说明何时应使用每个函数,以及何时不应使用。 通常应当_明确_告诉模型具体要做什么。
提供示例并涵盖边界情况 ,尤其是针对反复出现的错误。(**注意:**添加示例可能会降低推理模型 的表现。)
对于推迟加载的工具,请在函数描述中提供详细指引,并保持命名空间描述简洁。 命名空间帮助模型选择要加载的工具,函数描述则帮助模型正确使用已加载的工具。
遵循软件工程最佳实践。
让函数易于理解,行为符合预期 。(参见最小惊讶原则 )
使用枚举 和对象结构来避免无效状态。例如,toggle_light(on: bool, off: bool) 允许传入无效的参数组合。
请实习生试用。 只看您提供给模型的信息,实习生或其他人能否正确使用这个函数?(如果不能,他们会问哪些问题?请把答案补充到提示词中。)
减轻模型的负担,尽可能用代码处理。
对于您已经知道的参数值,无需让模型填写。 例如,如果您已从上一步的菜单中获得 order_id,就不要再设置 order_id 参数。请将 submit_refund() 定义为无参数函数,并在代码中传递 order_id。
合并总是按顺序调用的函数。 例如,如果 mark_location() 总是在 query_location() 之后调用,就可以把标记逻辑移到查询函数中。
减少初始可用的函数数量,以提高准确率。
评估调用效果 ,比较函数数量不同时的表现。
尽量让每一轮开始时可用的函数少于 20 个 ,这个数量仅供参考。
使用工具搜索 推迟加载规模较大或不常用的工具组,无需一开始就提供全部工具。
利用 OpenAI 资源。
在底层实现中,函数会以模型训练时学过的语法注入系统消息。因此,可调用函数的定义会占用模型的上下文空间,并按输入 Token 计费。如果遇到 Token 数量限制,建议减少预先加载的函数数量,尽可能缩短描述,或使用工具搜索 ,仅在需要时加载其余工具。
如果工具规范中定义了大量函数,也可以通过微调 减少 Token 用量。
当模型调用函数时,您必须执行函数并返回结果。模型的响应可能不包含调用,也可能包含一次或多次调用,因此最好按可能有多次调用来处理。
响应中包含 tool_calls 数组。每一项都有一个 id(稍后提交函数结果时使用)和一个 function 对象,后者包含 name 和经过 JSON 编码的 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 [
{
"id" : "call_12345xyz" ,
"type" : "function" ,
"function" : {
"name" : "get_weather" ,
"arguments" : "{ \" location \" : \" Paris, France \" }"
}
},
{
"id" : "call_67890abc" ,
"type" : "function" ,
"function" : {
"name" : "get_weather" ,
"arguments" : "{ \" location \" : \" Bogotá, Colombia \" }"
}
},
{
"id" : "call_99999def" ,
"type" : "function" ,
"function" : {
"name" : "send_email" ,
"arguments" : "{ \" to \" : \" bob@email.com \" , \" body \" : \" Hi bob \" }"
}
}
] 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 messages.push(completion.choices[0].message);
for (const toolCall of completion.choices[0].message.tool_calls ?? []) {
if (toolCall.type !== "function") continue;
const name = toolCall.function.name;
const args = JSON.parse(toolCall.function.arguments);
const result = await callFunction(name, args);
messages.push({
role: "tool",
tool_call_id: toolCall.id,
content: result.toString(),
});
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14 messages.append(completion.choices[ 0 ].message)
for tool_call in completion.choices[ 0 ].message.tool_calls or []:
name = tool_call.function.name
args = json.loads(tool_call.function.arguments)
result = call_function(name, args)
messages.append(
{
"role" : "tool" ,
"tool_call_id" : tool_call.id,
"content" : json.dumps(result),
}
) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 messages = append(messages, completion.Choices[0].Message.ToParam())
for _, toolCall := range completion.Choices[0].Message.ToolCalls {
if toolCall.Type != "function" {
continue
}
var arguments functionArguments
if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &arguments); err != nil {
panic(err)
}
result, err := callFunction(toolCall.Function.Name, arguments)
if err != nil {
panic(err)
}
messages = append(messages, openai.ToolMessage(result, toolCall.ID))
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.ObjectMappers;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.ReasoningEffort;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionToolMessageParam;
import java.util.List;
import java.util.Map;
var assistant = client.chat().completions().create(params).choices().get(0).message();
var history = params.toBuilder().addMessage(assistant);
for (var item : assistant.toolCalls().orElse(List.of())) {
var call = item.asFunction();
String output;
if (call.function().name().equals("get_weather")) {
record Coordinates(double latitude, double longitude) {}
Coordinates coordinates = call.function().arguments(Coordinates.class);
output =
ObjectMappers.jsonMapper()
.writeValueAsString(
Map.of(
"latitude", coordinates.latitude(),
"longitude", coordinates.longitude(),
"temperature_c", 18));
} else if (call.function().name().equals("send_email")) {
record Email(String to, String body) {}
Email message = call.function().arguments(Email.class);
output =
ObjectMappers.jsonMapper()
.writeValueAsString(Map.of("to", message.to(), "status", "sent"));
} else {
throw new IllegalArgumentException("Unknown function: " + call.function().name());
}
history.addMessage(
ChatCompletionToolMessageParam.builder().toolCallId(call.id()).content(output).build());
}
System.out.println(ObjectMappers.jsonMapper().writeValueAsString(history.build().messages())); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 message = completion.choices.fetch(0).message
messages << message
Array(message.tool_calls).each do |tool_call|
next unless tool_call.is_a?(
OpenAI::Models::Chat::ChatCompletionMessageFunctionToolCall
)
name = tool_call.function.name
arguments = JSON.parse(tool_call.function.arguments)
result = call_function(name, arguments)
messages << {
role: :tool,
tool_call_id: tool_call.id,
content: JSON.generate(result)
}
end
响应的 output 数组中包含 type 值为 function_call 的项。每个这样的项都有一个 call_id(稍后提交函数结果时使用)、一个 name 和经过 JSON 编码的 arguments。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 [
{
"id" : "fc_12345xyz" ,
"call_id" : "call_12345xyz" ,
"type" : "function_call" ,
"name" : "get_weather" ,
"arguments" : "{ \" location \" : \" Paris, France \" }"
},
{
"id" : "fc_67890abc" ,
"call_id" : "call_67890abc" ,
"type" : "function_call" ,
"name" : "get_weather" ,
"arguments" : "{ \" location \" : \" Bogotá, Colombia \" }"
},
{
"id" : "fc_99999def" ,
"call_id" : "call_99999def" ,
"type" : "function_call" ,
"name" : "send_email" ,
"arguments" : "{ \" to \" : \" bob@email.com \" , \" body \" : \" Hi bob \" }"
}
] 如果您使用工具搜索 ,还可能看到 tool_search_call 和 tool_search_output 项出现在 function_call 之前。函数加载后,按此处所示的方式处理函数调用即可。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";
input.push(...toResponseInputItems(response.output));
for (const toolCall of response.output) {
if (toolCall.type !== "function_call") {
continue;
}
const name = toolCall.name;
const args = JSON.parse(toolCall.arguments);
const result = await callFunction(name, args);
input.push({
type: "function_call_output",
call_id: toolCall.call_id,
output: result.toString(),
});
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 input_messages += response.output
for tool_call in response.output:
if tool_call.type != "function_call" :
continue
name = tool_call.name
args = json.loads(tool_call.arguments)
result = call_function(name, args)
input_messages.append(
{
"type" : "function_call_output" ,
"call_id" : tool_call.call_id,
"output" : json.dumps(result),
}
) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 input = append(input, responseOutputAsInput(response.Output)...)
for _, output := range response.Output {
if output.Type != "function_call" {
continue
}
toolCall := output.AsFunctionCall()
var arguments functionArguments
if err := json.Unmarshal([]byte(toolCall.Arguments), &arguments); err != nil {
panic(err)
}
result, err := callFunction(toolCall.Name, arguments)
if err != nil {
panic(err)
}
toolOutput := responses.ResponseInputItemParamOfFunctionCallOutput(result)
toolOutput.OfFunctionCallOutput.CallID = openai.String(toolCall.CallID)
input = append(input, toolOutput)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.ObjectMappers;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
response.output().stream()
.map(item -> JsonValue.from(item).convert(ResponseInputItem.class))
.forEach(input::add);
for (var item : response.output()) {
if (item.functionCall().isEmpty()) continue;
var call = item.functionCall().get();
String result;
if (call.name().equals("get_weather")) {
record Coordinates(double latitude, double longitude) {}
Coordinates coordinates = call.arguments(Coordinates.class);
result =
ObjectMappers.jsonMapper()
.writeValueAsString(
Map.of(
"latitude", coordinates.latitude(),
"longitude", coordinates.longitude(),
"temperature_c", 18));
} else if (call.name().equals("send_email")) {
record Email(String to, String body) {}
Email message = call.arguments(Email.class);
result =
ObjectMappers.jsonMapper()
.writeValueAsString(Map.of("to", message.to(), "status", "sent"));
} else {
throw new IllegalArgumentException("Unknown function: " + call.name());
}
var output =
ResponseInputItem.ofFunctionCallOutput(
ResponseInputItem.FunctionCallOutput.builder()
.callId(call.callId())
.output(result)
.build());
input.add(output);
}
System.out.println(ObjectMappers.jsonMapper().writeValueAsString(input)); 1
2
3
4
5
6
7
8
9
10
11
12
13
14 input.concat(response.output)
response.output.each do |tool_call|
next unless tool_call.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)
arguments = JSON.parse(tool_call.arguments)
result = call_function(tool_call.name, arguments)
input << {
type: :function_call_output,
call_id: tool_call.call_id,
output: JSON.generate(result)
}
end
上例使用一个假设的 call_function 函数将每次调用分派给相应的函数。下面是一种可能的实现:
1
2
3
4
5
6
7
8
9 const callFunction = async (name: string, args: Record<string, unknown>) => {
if (name === "get_weather") {
return getWeather(args.latitude, args.longitude);
}
if (name === "send_email") {
return sendEmail(args.to, args.body);
}
throw new Error(`Unknown function: ${name}`);
}; 1
2
3
4
5
6 def call_function (name, args):
if name == "get_weather" :
return get_weather( ** args)
if name == "send_email" :
return send_email( ** args)
raise ValueError ( f "Unknown function: { name } " ) 1
2
3
4
5
6
7
8
9
10 func callFunction(name string, arguments functionArguments) (string, error) {
switch name {
case "get_weather":
return getWeather(arguments.Location), nil
case "send_email":
return sendEmail(arguments.To, arguments.Body), nil
default:
return "", fmt.Errorf("unknown function: %s", name)
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31 import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
var argsJson = new ObjectMapper().readTree("{\"location\":\"Paris, France\"}");
System.out.println(callFunction("get_weather", argsJson));
// These local fixtures demonstrate dispatch; replace them with your application services.
// The email fixture prints its inputs and does not send a message.
static Map<String, Object> callFunction(String name, JsonNode arguments) {
return switch (name) {
case "get_weather" -> getWeather(arguments.get("location").asText());
case "send_email" -> sendEmail(arguments.get("to").asText(), arguments.get("body").asText());
default -> throw new IllegalArgumentException("Unknown function: " + name);
};
}
private static Map<String, Object> getWeather(String location) {
int temperature =
switch (location) {
case "Bogotá, Colombia" -> 18;
case "Paris, France" -> 15;
default -> 20;
};
return Map.of("location", location, "temperature_celsius", temperature);
}
private static Map<String, Object> sendEmail(String to, String body) {
System.out.println("Sending email to " + to + ": " + body);
return Map.of("status", "sent");
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 using System.Text.Json;
using JsonDocument arguments = JsonDocument.Parse("{\"location\":\"Paris, France\"}");
Console.WriteLine(FunctionDispatcher.CallFunction("get_weather", arguments.RootElement));
internal static class FunctionDispatcher
{
// These local fixtures demonstrate dispatch; replace them with your application services.
// The email fixture prints its inputs and does not send a message.
internal static string CallFunction(string name, JsonElement arguments) => name switch
{
"get_weather" => GetWeather(arguments.GetProperty("location").GetString()!),
"send_email" => SendEmail(arguments.GetProperty("to").GetString()!, arguments.GetProperty("body").GetString()!),
_ => throw new ArgumentException($"Unknown function: {name}", nameof(name))
};
private static string GetWeather(string location) => JsonSerializer.Serialize(new { location, temperature_celsius = location switch { "Bogotá, Colombia" => 18, "Paris, France" => 15, _ => 20 } });
private static string SendEmail(string to, string body)
{
Console.WriteLine($"Sending email to {to}: {body}");
return "{\"status\":\"sent\"}";
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 def call_function(name, arguments)
case name
when "get_weather"
FunctionCallingExample.get_weather(
arguments.fetch("latitude"),
arguments.fetch("longitude")
)
when "send_email"
FunctionCallingExample.send_email(
arguments.fetch("to"),
arguments.fetch("body")
)
else
raise ArgumentError, "Unknown function: #{name}"
end
end
在 function_call_output 消息中传递的结果通常应为字符串,具体格式由您决定,可以是 JSON、错误码、纯文本等。模型会根据需要解读该字符串。
对于返回图像或文件的函数,可以传递由图像或文件对象组成的数组 来代替字符串。
如果函数没有返回值(例如 send_email),请返回一个表示成功或失败的字符串,例如 "success"。
将结果追加到 messages 后,即可将更新后的消息发回给模型,以获取最终响应。
1
2
3
4
5
6
7 const completion = await openai.chat.completions.create({
model: "gpt-5.6-terra",
reasoning_effort: "none",
messages,
tools,
store: true,
}); 1
2
3
4
5
6 completion = client.chat.completions.create(
model = "gpt-5.6-terra" ,
reasoning_effort = "none" ,
messages = messages,
tools = chat_tools,
) 1
2
3
4
5
6
7
8
9 completion, err = client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
Model: "gpt-5.6-terra",
Messages: messages,
Tools: tools,
ReasoningEffort: shared.ReasoningEffortNone,
})
if err != nil {
panic(err)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.ReasoningEffort;
import com.openai.models.chat.completions.ChatCompletionAssistantMessageParam;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionMessageFunctionToolCall;
import com.openai.models.chat.completions.ChatCompletionToolMessageParam;
import java.util.List;
import java.util.Map;
FunctionDefinition weather =
FunctionDefinition.builder()
.name("get_weather")
.description("Get the weather for a city.")
.parameters(
FunctionParameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("city")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ChatCompletionCreateParams params =
ChatCompletionCreateParams.builder()
.model("gpt-5.6-terra")
.reasoningEffort(ReasoningEffort.NONE)
.addUserMessage("What is the weather in Paris?")
.addMessage(
ChatCompletionAssistantMessageParam.builder()
.addToolCall(
ChatCompletionMessageFunctionToolCall.builder()
.id("call_weather")
.function(
ChatCompletionMessageFunctionToolCall.Function.builder()
.name("get_weather")
.arguments("{\"city\":\"Paris\"}")
.build())
.build())
.build())
.addMessage(
ChatCompletionToolMessageParam.builder()
.toolCallId("call_weather")
.content("{\"city\":\"Paris\",\"temperature_c\":18}")
.build())
.addFunctionTool(weather)
.build();
client.chat().completions().create(params).choices().stream()
.flatMap(choice -> choice.message().content().stream())
.forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49 require "openai"
client = OpenAI::Client.new
completion = client.chat.completions.create(
model: "gpt-5.6-terra",
reasoning_effort: :none,
messages: [
{
role: :user,
content: "What is the weather in Paris?"
},
{
role: :assistant,
tool_calls: [
{
id: "call_weather",
type: :function,
function: {
name: "get_weather",
arguments: '{"city":"Paris"}'
}
}
]
},
{
role: :tool,
tool_call_id: "call_weather",
content: '{"city":"Paris","temperature_c":18}'
}
],
tools: [
{
type: :function,
function: {
name: "get_weather",
description: "Get the weather for a city",
parameters: {
type: :object,
properties: { city: { type: :string } },
required: ["city"],
additionalProperties: false
},
strict: true
}
}
]
)
puts(completion.choices.fetch(0).message.content)
将结果追加到 input 后,即可将更新后的输入发回给模型,以获取最终响应。
1
2
3
4
5 const response = await openai.responses.create({
model: "gpt-6.2-astra",
input,
tools,
}); 1
2
3
4
5 response = client.responses.create(
model = "gpt-6.2-astra" ,
input = input_messages,
tools = responses_tools,
) 1
2
3
4
5
6
7
8 response, err = client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
Tools: tools,
})
if err != nil {
panic(err)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseFunctionToolCall;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;
FunctionTool weather =
FunctionTool.builder()
.name("get_weather")
.description("Get the weather for a city.")
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("city")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.inputOfResponse(
List.of(
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("What is the weather like in Paris?")
.build()),
ResponseInputItem.ofFunctionCall(
ResponseFunctionToolCall.builder()
.callId("call_weather")
.name("get_weather")
.arguments("{\"city\":\"Paris\"}")
.build()),
ResponseInputItem.ofFunctionCallOutput(
ResponseInputItem.FunctionCallOutput.builder()
.callId("call_weather")
.output("{\"city\":\"Paris\",\"temperature_c\":18}")
.build())))
.addTool(weather)
.build();
client.responses().create(params).output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text())); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41 require "openai"
client = OpenAI::Client.new
input = [
{
role: :user,
content: "What is the weather like in Paris?"
},
{
type: :function_call,
call_id: "call_weather",
name: "get_weather",
arguments: '{"city":"Paris"}'
},
{
type: :function_call_output,
call_id: "call_weather",
output: '{"city":"Paris","temperature_c":18}'
}
]
tools = [
{
type: :function,
name: "get_weather",
description: "Get the weather for a city",
parameters: {
type: :object,
properties: { city: { type: :string } },
required: ["city"],
additionalProperties: false
},
strict: true
}
]
response = client.responses.create(
model: "gpt-6.2-astra",
input: input,
tools: tools
)
puts(response.output_text)
"It's about 15°C in Paris, 18°C in Bogotá, and I've sent that email to Bob."
默认情况下,模型自行决定何时使用工具以及使用多少个工具。您可以使用 tool_choice 参数指定调用行为。
自动: (默认 )可以不调用函数,也可以调用一个或多个函数。tool_choice: "auto"
**必须调用:**调用一个或多个函数。
tool_choice: "required"
**强制调用指定函数:**仅调用指定的函数一次。
tool_choice: {"type": "function", "name": "get_weather"}
**允许使用的工具:**将模型可以调用的工具限制在可用工具的一个子集内。
何时使用 allowed_tools
您可以配置 allowed_tools 列表,让模型在不同请求中只能调用部分工具,同时保持传入的工具列表不变,以充分利用提示词缓存 节省成本。
1 2 3 4 5 6 7 8 9 "tool_choice" : {
"type" : "allowed_tools" ,
"mode" : "auto" ,
"tools" : [
{ "type" : "function" , "name" : "get_weather" },
{ "type" : "function" , "name" : "search_docs" }
]
}
}
也可以将 tool_choice 设置为 "none",效果与不传入任何函数相同。
使用工具搜索时,tool_choice 仍适用于当前轮次可调用的工具。如果您已经加载了一部分工具,并希望模型仅使用这些工具,这一设置尤其有用。
从 GPT-5 开始,在支持此功能的模型上,即使同时提供了内置工具 ,也可以并行调用函数。内置工具不能包含在同一批并行函数调用中。
模型可能会选择在一轮中调用多个函数。您可以将 parallel_tool_calls 设置为 false 来阻止这种行为,确保每轮最多发起一次工具调用。
**注意:**目前,如果您使用微调后的模型,并且模型在一轮中调用了多个函数,这些调用的严格模式 将被禁用。
**关于 gpt-4.1-nano-2025-04-14 的说明:**启用并行工具调用时,这个 gpt-4.1-nano 快照有时会对同一工具发起多次调用。使用该快照时,建议禁用此功能。
将 strict 设置为 true 后,函数调用会严格遵循函数模式。我们建议始终启用严格模式。
严格模式在底层使用结构化输出 功能,因此有两项要求:
additionalProperties 必须设置为 false,且 parameters 中的每个对象都必须如此设置。
properties 中的所有字段都必须标记为 required。
对于可选字段,可以将 null 添加为 type 的一个选项(见下例)。
如果您发送 strict: true,但模式不符合上述要求,请求将被拒绝,错误信息会指出缺少哪些约束。如果省略 strict,默认行为取决于所用的 API。对于 Responses 请求,API 会尽可能将您提供的模式规范化,使其符合严格模式的要求。如果无法做到这一点,API 会回退到非严格模式,尽力按函数定义进行调用。发生回退时,响应中的工具定义会显示 strict: false。Chat Completions 请求默认使用非严格模式。如果希望 Responses 始终以非严格模式尽力调用函数,请显式设置 strict: false。
Strict mode enabled Strict mode disabled 已启用严格模式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24 {
"type" : "function" ,
"function" : {
"name" : "get_weather" ,
"description" : "Retrieves current weather for the given location." ,
"strict" : true ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia"
},
"units" : {
"type" : [ "string" , "null" ],
"enum" : [ "celsius" , "fahrenheit" ],
"description" : "Units the temperature will be returned in."
}
},
"required" : [ "location" , "units" ],
"additionalProperties" : false
}
}
} 已禁用严格模式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 {
"type" : "function" ,
"function" : {
"name" : "get_weather" ,
"description" : "Retrieves current weather for the given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia"
},
"units" : {
"type" : "string" ,
"enum" : [ "celsius" , "fahrenheit" ],
"description" : "Units the temperature will be returned in."
}
},
"required" : [ "location" ],
}
}
}
Strict mode enabled Strict mode disabled 已启用严格模式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 {
"type" : "function" ,
"name" : "get_weather" ,
"description" : "Retrieves current weather for the given location." ,
"strict" : true ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia"
},
"units" : {
"type" : [ "string" , "null" ],
"enum" : [ "celsius" , "fahrenheit" ],
"description" : "Units the temperature will be returned in."
}
},
"required" : [ "location" , "units" ],
"additionalProperties" : false
}
} 已禁用严格模式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 {
"type" : "function" ,
"name" : "get_weather" ,
"description" : "Retrieves current weather for the given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia"
},
"units" : {
"type" : "string" ,
"enum" : [ "celsius" , "fahrenheit" ],
"description" : "Units the temperature will be returned in."
}
},
"required" : [ "location" ],
}
}
我们建议启用严格模式,但它有以下限制:
部分 JSON 模式特性尚不受支持。(参见支持的模式 。)
对于微调后的模型,还需注意:
首次请求时,模式需要经过额外处理,之后会被缓存。如果每次请求使用的模式都不同,可能会增加延迟。
为提高性能,系统会缓存模式,因此模式不适用零数据保留 。
通过流式传输,您可以在模型填写参数时显示正在调用哪个函数,甚至可以实时显示参数,让用户看到调用进度。
流式传输函数调用的方式与流式传输普通响应类似。将 stream 设置为 true,即可接收包含 delta 对象的数据块。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42 import { OpenAI } from "openai";
const openai = new OpenAI();
const tools: OpenAI.Chat.Completions.ChatCompletionTool[] = [
{
type: "function",
function: {
name: "get_weather",
description: "Get current temperature for a given location.",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "City and country e.g. Bogotá, Colombia",
},
},
required: ["location"],
additionalProperties: false,
},
strict: true,
},
},
];
const stream = await openai.chat.completions.create({
model: "gpt-5.6-terra",
reasoning_effort: "none",
messages: [
{ role: "user", content: "What's the weather like in Paris today?" },
],
tools,
tool_choice: "required",
stream: true,
store: true,
});
for await (const chunk of stream) {
const delta = chunk.choices[0].delta;
console.log(delta.tool_calls);
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37 from openai import OpenAI
client = OpenAI()
tools = [
{
"type" : "function" ,
"function" : {
"name" : "get_weather" ,
"description" : "Get current temperature for a given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia" ,
}
},
"required" : [ "location" ],
"additionalProperties" : False ,
},
"strict" : True ,
},
}
]
stream = client.chat.completions.create(
model = "gpt-5.6-terra" ,
reasoning_effort = "none" ,
messages = [{ "role" : "user" , "content" : "What's the weather like in Paris today?" }],
tools = tools,
stream = True ,
)
for chunk in stream:
delta = chunk.choices[ 0 ].delta
print (delta.tool_calls) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{"type": "string", "description": "City and country e.g. Bogotá, Colombia"},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
Function: shared.FunctionDefinitionParam{Name: "get_weather", Parameters: parameters, Strict: openai.Bool(true)},
}}
stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
Model: "gpt-5.6-terra",
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("What's the weather like in Paris today?"),
},
Tools: []openai.ChatCompletionToolUnionParam{tool},
ReasoningEffort: shared.ReasoningEffortNone,
})
for stream.Next() {
if len(stream.Current().Choices) > 0 {
fmt.Println(stream.Current().Choices[0].Delta.ToolCalls)
}
}
if err := stream.Err(); err != nil {
panic(err)
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.ReasoningEffort;
import com.openai.models.chat.completions.ChatCompletionChunk;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import java.util.List;
import java.util.Map;
FunctionDefinition weather =
FunctionDefinition.builder()
.name("get_weather")
.description("Get the weather for a city.")
.parameters(
FunctionParameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("city")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ChatCompletionCreateParams params =
ChatCompletionCreateParams.builder()
.model("gpt-5.6-terra")
.reasoningEffort(ReasoningEffort.NONE)
.addUserMessage("What is the weather in Paris?")
.addFunctionTool(weather)
.build();
try (StreamResponse<ChatCompletionChunk> stream =
client.chat().completions().createStreaming(params)) {
stream.stream()
.flatMap(chunk -> chunk.choices().stream())
.flatMap(choice -> choice.delta().toolCalls().stream())
.flatMap(List::stream)
.forEach(System.out::println);
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35 require "openai"
client = OpenAI::Client.new
stream = client.chat.completions.stream(
model: "gpt-5.6-terra",
reasoning_effort: :none,
messages: [
{
role: :user,
content: "What is the weather in Paris?"
}
],
tools: [
{
type: :function,
function: {
name: "get_weather",
description: "Get the weather for a city",
parameters: {
type: :object,
properties: { city: { type: :string } },
required: ["city"],
additionalProperties: false
},
strict: true
}
}
]
)
stream.each do |event|
next unless event.is_a?(OpenAI::Helpers::Streaming::ChatChunkEvent)
puts(event.chunk.choices.first&.delta&.tool_calls)
end 1
2
3
4
5
6
7
8
9 [{ "index" : 0 , "id" : "call_DdmO9pD3xa9XTPNJ32zg2hcA" , "function" : { "arguments" : "" , "name" : "get_weather" }, "type" : "function" }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : "{ \" " , "name" : null }, "type" : null }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : "location" , "name" : null }, "type" : null }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : " \" : \" " , "name" : null }, "type" : null }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : "Paris" , "name" : null }, "type" : null }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : "," , "name" : null }, "type" : null }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : " France" , "name" : null }, "type" : null }]
[{ "index" : 0 , "id" : null , "function" : { "arguments" : " \" }" , "name" : null }, "type" : null }]
null 处理普通响应时,需要将数据块拼接成一个 content 字符串。处理函数调用时,则需要将参数片段拼接起来,得到经过 JSON 编码的 arguments 对象。
当模型调用一个或多个函数时,每个 delta 的 tool_calls 字段都会填入数据。每个 tool_call 包含以下字段:
字段
说明
index
标识 delta 对应的函数调用
id
工具调用的 ID
function
函数调用的增量(name 和 arguments)
type
tool_call 的类型(对于函数调用,始终为 function)
其中许多字段仅在每次工具调用的第一个 delta 中设置,例如 id、function.name 和 type。
下面的代码片段演示如何将多个 delta 汇总为最终的 tool_calls 对象。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 const finalToolCalls: Record<
number,
{
id?: string;
type?: "function" | "custom";
function: { name?: string; arguments: string };
}
> = {};
for await (const chunk of stream) {
const toolCalls = chunk.choices[0].delta.tool_calls || [];
for (const toolCall of toolCalls) {
const { index } = toolCall;
const accumulated = (finalToolCalls[index] ??= {
id: toolCall.id,
type: toolCall.type,
function: { name: toolCall.function?.name, arguments: "" },
});
accumulated.id ??= toolCall.id;
accumulated.type ??= toolCall.type;
accumulated.function.name ??= toolCall.function?.name;
accumulated.function.arguments += toolCall.function?.arguments ?? "";
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14 final_tool_calls = {}
for chunk in stream:
if not chunk.choices:
continue
for tool_call in chunk.choices[ 0 ].delta.tool_calls or []:
index = tool_call.index
if index not in final_tool_calls:
final_tool_calls[index] = tool_call
elif tool_call.function:
final_tool_calls[index].function.arguments += (
tool_call.function.arguments or ""
) 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 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{"type": "string"},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
Function: shared.FunctionDefinitionParam{Name: "get_weather", Parameters: parameters, Strict: openai.Bool(true)},
}}
stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
Model: "gpt-5.6-terra",
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("What's the weather like in Paris today?"),
},
Tools: []openai.ChatCompletionToolUnionParam{tool},
ReasoningEffort: shared.ReasoningEffortNone,
})
finalToolCalls := map[int64]openai.ChatCompletionChunkChoiceDeltaToolCall{}
for stream.Next() {
chunk := stream.Current()
if len(chunk.Choices) == 0 {
continue
}
for _, toolCall := range chunk.Choices[0].Delta.ToolCalls {
finalToolCall, ok := finalToolCalls[toolCall.Index]
if !ok {
finalToolCalls[toolCall.Index] = toolCall
continue
}
finalToolCall.Function.Arguments += toolCall.Function.Arguments
finalToolCalls[toolCall.Index] = finalToolCall
}
}
if err := stream.Err(); err != nil {
panic(err)
}
fmt.Println(finalToolCalls)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.FunctionDefinition;
import com.openai.models.FunctionParameters;
import com.openai.models.ReasoningEffort;
import com.openai.models.chat.completions.ChatCompletionChunk;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
FunctionDefinition weather =
FunctionDefinition.builder()
.name("get_weather")
.description("Get the weather for a city.")
.parameters(
FunctionParameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties", JsonValue.from(Map.of("location", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ChatCompletionCreateParams params =
ChatCompletionCreateParams.builder()
.model("gpt-5.6-terra")
.reasoningEffort(ReasoningEffort.NONE)
.addUserMessage("What is the weather in Paris?")
.addFunctionTool(weather)
.build();
record ToolCall(String id, String type, String name, StringBuilder arguments) {}
Map<Long, ToolCall> toolCalls = new LinkedHashMap<>();
try (StreamResponse<ChatCompletionChunk> stream =
client.chat().completions().createStreaming(params)) {
stream.stream()
.flatMap(chunk -> chunk.choices().stream())
.flatMap(choice -> choice.delta().toolCalls().stream())
.flatMap(List::stream)
.forEach(
delta -> {
ToolCall toolCall =
toolCalls.computeIfAbsent(
delta.index(),
ignored ->
new ToolCall(
delta.id().orElseThrow(),
delta.type().orElseThrow().asString(),
delta.function().flatMap(function -> function.name()).orElseThrow(),
new StringBuilder()));
delta
.function()
.flatMap(function -> function.arguments())
.ifPresent(toolCall.arguments()::append);
});
}
toolCalls.values().forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49 require "openai"
client = OpenAI::Client.new
stream = client.chat.completions.stream(
model: "gpt-5.6-terra",
reasoning_effort: :none,
messages: [
{
role: :user,
content: "What is the weather in Paris?"
}
],
tools: [
{
type: :function,
function: {
name: "get_weather",
parameters: {
type: :object,
properties: { location: { type: :string } },
required: ["location"],
additionalProperties: false
},
strict: true
}
}
]
)
tool_calls = {}
stream.each do |event|
next unless event.is_a?(OpenAI::Helpers::Streaming::ChatChunkEvent)
(event.chunk.choices.first&.delta&.tool_calls || []).each do |delta|
tool_call = tool_calls[delta.index] ||= {
id: nil,
type: nil,
function: {
name: nil,
arguments: +""
}
}
tool_call[:id] ||= delta.id
tool_call[:type] ||= delta.type
tool_call[:function][:name] ||= delta.function&.name
tool_call[:function][:arguments] << delta.function&.arguments.to_s
end
end
puts(tool_calls.sort.to_h.values) 1
2
3
4
5
6
7
8 {
"index" : 0 ,
"id" : "call_RzfkBpJgzeR0S242qfvjadNe" ,
"function" : {
"name" : "get_weather" ,
"arguments" : "{ \" location \" : \" Paris, France \" }"
}
}
通过流式传输,您可以在模型填写参数时显示正在调用哪个函数,甚至可以实时显示参数,让用户看到调用进度。
流式传输函数调用的方式与流式传输普通响应类似。将 stream 设置为 true,即可接收不同的 event 对象。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34 import { OpenAI } from "openai";
const openai = new OpenAI();
const tools: OpenAI.Responses.Tool[] = [
{
type: "function",
name: "get_weather",
description: "Get current temperature for provided coordinates in celsius.",
parameters: {
type: "object",
properties: {
latitude: { type: "number" },
longitude: { type: "number" },
},
required: ["latitude", "longitude"],
additionalProperties: false,
},
strict: true,
},
];
const stream = await openai.responses.create({
model: "gpt-6.2-astra",
input: [{ role: "user", content: "What's the weather like in Paris today?" }],
tools,
tool_choice: "required",
stream: true,
store: true,
});
for await (const event of stream) {
console.log(event);
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33 from openai import OpenAI
client = OpenAI()
tools = [
{
"type" : "function" ,
"name" : "get_weather" ,
"strict" : True ,
"description" : "Get current temperature for a given location." ,
"parameters" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "City and country e.g. Bogotá, Colombia" ,
}
},
"required" : [ "location" ],
"additionalProperties" : False ,
},
}
]
stream = client.responses.create(
model = "gpt-6.2-astra" ,
input = [{ "role" : "user" , "content" : "What's the weather like in Paris today?" }],
tools = tools,
stream = True ,
)
for event in stream:
print (event) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{"type": "string", "description": "City and country e.g. Bogotá, Colombia"},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := responses.ToolParamOfFunction("get_weather", parameters, true)
stream := client.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What's the weather like in Paris today?")},
Tools: []responses.ToolUnionParam{tool},
})
for stream.Next() {
fmt.Println(stream.Current().Type)
}
if err := stream.Err(); err != nil {
panic(err)
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseStreamEvent;
import java.util.List;
import java.util.Map;
FunctionTool weather =
FunctionTool.builder()
.name("get_weather")
.description("Get the weather for a city.")
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties", JsonValue.from(Map.of("city", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("city")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.input("What is the weather in Paris?")
.addTool(weather)
.build();
try (StreamResponse<ResponseStreamEvent> stream = client.responses().createStreaming(params)) {
stream.stream().forEach(System.out::println);
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 require "openai"
client = OpenAI::Client.new
stream = client.responses.stream(
model: "gpt-6.2-astra",
input: "What is the weather in Paris?",
tools: [
{
type: :function,
name: "get_weather",
description: "Get the weather for a city",
parameters: {
type: :object,
properties: { city: { type: :string } },
required: ["city"],
additionalProperties: false
},
strict: true
}
]
)
stream.each { |event| puts(event.type) } 1
2
3
4
5
6
7
8
9
10 { "type" : "response.output_item.added" , "response_id" : "resp_1234xyz" , "output_index" : 0 , "item" :{ "type" : "function_call" , "id" : "fc_1234xyz" , "call_id" : "call_1234xyz" , "name" : "get_weather" , "arguments" : "" }}
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : "{ \" " }
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : "location" }
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : " \" : \" " }
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : "Paris" }
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : "," }
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : " France" }
{ "type" : "response.function_call_arguments.delta" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "delta" : " \" }" }
{ "type" : "response.function_call_arguments.done" , "response_id" : "resp_1234xyz" , "item_id" : "fc_1234xyz" , "output_index" : 0 , "arguments" : "{ \" location \" : \" Paris, France \" }" }
{ "type" : "response.output_item.done" , "response_id" : "resp_1234xyz" , "output_index" : 0 , "item" :{ "type" : "function_call" , "id" : "fc_1234xyz" , "call_id" : "call_1234xyz" , "name" : "get_weather" , "arguments" : "{ \" location \" : \" Paris, France \" }" }} 处理普通响应时,需要将数据块拼接成一个 content 字符串。处理函数调用时,则需要将参数片段拼接起来,得到经过 JSON 编码的 arguments 对象。
当模型调用一个或多个函数时,每次函数调用都会触发一个 response.output_item.added 类型的事件,其中包含以下字段:
字段
说明
response_id
函数调用所属响应的 ID
output_index
输出项在响应中的索引,用于区分响应中的各次函数调用。
item
正在进行的函数调用项,包含 name、arguments 和 id 字段
随后,您会收到一系列 response.function_call_arguments.delta 类型的事件。每个事件都包含一个 delta,表示 arguments 字段的增量。这些事件包含以下字段:
字段
说明
response_id
函数调用所属响应的 ID
item_id
增量所属函数调用项的 ID
output_index
输出项在响应中的索引,用于区分响应中的各次函数调用。
delta
arguments 字段的增量
下面的代码片段演示如何将多个 delta 汇总为最终的 tool_call 对象。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 const finalToolCalls: Record<
number,
import("openai").OpenAI.Responses.ResponseFunctionToolCall
> = {};
for await (const event of stream) {
if (
event.type === "response.output_item.added" &&
event.item.type === "function_call"
) {
finalToolCalls[event.output_index] = event.item;
} else if (event.type === "response.function_call_arguments.delta") {
const index = event.output_index;
if (finalToolCalls[index]) {
finalToolCalls[index].arguments += event.delta;
}
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13 final_tool_calls = {}
for event in stream:
if (
event.type == "response.output_item.added"
and event.item.type == "function_call"
):
final_tool_calls[event.output_index] = event.item
elif event.type == "response.function_call_arguments.delta" :
index = event.output_index
if final_tool_calls[index]:
final_tool_calls[index].arguments += event.delta 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{"type": "string"},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := responses.ToolParamOfFunction("get_weather", parameters, true)
stream := client.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{
OfString: openai.String("What's the weather like in Paris today?"),
},
Tools: []responses.ToolUnionParam{tool},
})
finalToolCalls := map[int64]responses.ResponseFunctionToolCall{}
for stream.Next() {
event := stream.Current()
if event.Type == "response.output_item.added" && event.Item.Type == "function_call" {
finalToolCalls[event.OutputIndex] = event.Item.AsFunctionCall()
}
if event.Type == "response.function_call_arguments.delta" {
finalToolCall, ok := finalToolCalls[event.OutputIndex]
if !ok {
continue
}
finalToolCall.Arguments += event.Delta
finalToolCalls[event.OutputIndex] = finalToolCall
}
}
if err := stream.Err(); err != nil {
panic(err)
}
fmt.Println(finalToolCalls)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseFunctionToolCall;
import com.openai.models.responses.ResponseStreamEvent;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
FunctionTool weather =
FunctionTool.builder()
.name("get_weather")
.description("Get the weather for a city.")
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties", JsonValue.from(Map.of("location", Map.of("type", "string"))))
.putAdditionalProperty("required", JsonValue.from(List.of("location")))
.putAdditionalProperty("additionalProperties", JsonValue.from(false))
.build())
.strict(true)
.build();
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.input("What is the weather in Paris?")
.addTool(weather)
.build();
Map<Long, ResponseFunctionToolCall> toolCalls = new LinkedHashMap<>();
try (StreamResponse<ResponseStreamEvent> stream = client.responses().createStreaming(params)) {
stream.stream()
.forEach(
event -> {
event
.outputItemAdded()
.ifPresent(
added ->
added
.item()
.functionCall()
.ifPresent(call -> toolCalls.put(added.outputIndex(), call)));
event
.functionCallArgumentsDelta()
.ifPresent(
delta ->
toolCalls.computeIfPresent(
delta.outputIndex(),
(ignored, call) ->
call.toBuilder()
.arguments(call.arguments() + delta.delta())
.build()));
});
}
toolCalls.values().forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36 require "openai"
client = OpenAI::Client.new
stream = client.responses.stream(
model: "gpt-6.2-astra",
input: "What is the weather in Paris?",
tools: [
{
type: :function,
name: "get_weather",
parameters: {
type: :object,
properties: { location: { type: :string } },
required: ["location"],
additionalProperties: false
},
strict: true
}
]
)
final_tool_calls = {}
stream.each do |event|
case event
when OpenAI::Models::Responses::ResponseOutputItemAddedEvent
item = event.item
next unless item.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall)
final_tool_calls[event.output_index] = item.to_h.merge(arguments: item.arguments.dup)
when OpenAI::Models::Responses::ResponseFunctionCallArgumentsDeltaEvent
tool_call = final_tool_calls[event.output_index]
tool_call[:arguments] << event.delta if tool_call
end
end
puts(final_tool_calls.sort.to_h.values) 1
2
3
4
5
6
7 {
"type" : "function_call" ,
"id" : "fc_1234xyz" ,
"call_id" : "call_2345abc" ,
"name" : "get_weather" ,
"arguments" : "{ \" location \" : \" Paris, France \" }"
} 当模型完成函数调用时,会触发一个 response.function_call_arguments.done 类型的事件。该事件包含完整的函数调用,字段如下:
字段
说明
response_id
函数调用所属响应的 ID
output_index
输出项在响应中的索引,用于区分响应中的各次函数调用。
item
函数调用项,包含 name、arguments 和 id 字段。
自定义工具的工作方式与使用 JSON 模式定义的函数工具大致相同。使用自定义工具时,模型可以将任意字符串作为输入传给工具,无需预先指定输入结构。这样可以省去不必要的 JSON 封装,也可以使用下文介绍的自定义文法约束响应。
以下代码示例展示了如何创建一个自定义工具,用于接收模型返回的包含 Python 代码的字符串。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6.2-astra",
input: "Use the code_exec tool to print hello world to the console.",
tools: [
{
type: "custom",
name: "code_exec",
description: "Executes arbitrary Python code.",
},
],
});
console.log(response.output); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model = "gpt-6.2-astra" ,
input = "Use the code_exec tool to print hello world to the console." ,
tools = [
{
"type" : "custom" ,
"name" : "code_exec" ,
"description" : "Executes arbitrary Python code." ,
}
],
)
print (response.output) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
tool := responses.ToolParamOfCustom("code_exec")
tool.OfCustom.Description = openai.String("Executes arbitrary Python code.")
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the code_exec tool to print hello world to the console.")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(response.Output)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.input("Use code_exec to print hello world.")
.addTool(
CustomTool.builder()
.name("code_exec")
.description("Executes arbitrary Python code.")
.build())
.build();
client.responses().create(params).output().forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 require "openai"
client = OpenAI::Client.new
response = client.responses.create(
model: "gpt-6.2-astra",
input: "Use code_exec to print hello world.",
tools: [
{
type: :custom,
name: "code_exec",
description: "Executes arbitrary Python code."
}
]
)
puts(response.output)
与前面的示例一样,output 数组中包含模型生成的工具调用。这一次,工具调用的输入是纯文本。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 [
{
"id" : "rs_6890e972fa7c819ca8bc561526b989170694874912ae0ea6" ,
"type" : "reasoning" ,
"content" : [],
"summary" : []
},
{
"id" : "ctc_6890e975e86c819c9338825b3e1994810694874912ae0ea6" ,
"type" : "custom_tool_call" ,
"status" : "completed" ,
"call_id" : "call_aGiFQkRWSWAIsMQ19fKqxUgb" ,
"input" : "print( \" hello world \" )" ,
"name" : "code_exec"
}
]
上下文无关文法 (CFG)是一组规则,规定如何生成符合特定格式的有效文本。对于自定义工具,您可以提供 CFG 来约束模型传给工具的文本输入。
配置自定义工具时,可以通过 grammar 参数提供自定义 CFG。目前支持两种 CFG 语法:lark 和 regex。
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 import OpenAI from "openai";
const client = new OpenAI();
const grammar = `
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT
`;
const response = await client.responses.create({
model: "gpt-6.2-astra",
input: "Use the math_exp tool to add four plus four.",
tools: [
{
type: "custom",
name: "math_exp",
description: "Creates valid mathematical expressions",
format: {
type: "grammar",
syntax: "lark",
definition: grammar,
},
},
],
});
console.log(response.output); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34 from openai import OpenAI
client = OpenAI()
grammar = """
start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%i mport common.INT
"""
response = client.responses.create(
model = "gpt-6.2-astra" ,
input = "Use the math_exp tool to add four plus four." ,
tools = [
{
"type" : "custom" ,
"name" : "math_exp" ,
"description" : "Creates valid mathematical expressions" ,
"format" : {
"type" : "grammar" ,
"syntax" : "lark" ,
"definition" : grammar,
},
}
],
)
print (response.output) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
grammar := `start: expr
expr: term (SP ADD SP term)* -> add
| term
term: factor (SP MUL SP factor)* -> mul
| factor
factor: INT
SP: " "
ADD: "+"
MUL: "*"
%import common.INT`
tool := responses.ToolParamOfCustom("math_exp")
tool.OfCustom.Description = openai.String("Creates valid mathematical expressions")
tool.OfCustom.Format = shared.CustomToolInputFormatParamOfGrammar(grammar, "lark")
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the math_exp tool to add four plus four.")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(response.Output)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.CustomToolInputFormat;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;
String grammar =
"""
start: expr
expr: term (SP ADD SP term)*
term: INT
SP: " "
ADD: "+"
%import common.INT
""";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.input("Use math_exp to add four plus four.")
.addTool(
CustomTool.builder()
.name("math_exp")
.description("Creates valid mathematical expressions.")
.format(
CustomToolInputFormat.Grammar.builder()
.syntax(CustomToolInputFormat.Grammar.Syntax.LARK)
.definition(grammar)
.build())
.build())
.build();
client.responses().create(params).output().forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29 require "openai"
client = OpenAI::Client.new
grammar = <<~LARK
start: expr
expr: term (SP ADD SP term)*
term: INT
SP: " "
ADD: "+"
%import common.INT
LARK
response = client.responses.create(
model: "gpt-6.2-astra",
input: "Use math_exp to add four plus four.",
tools: [
{
type: :custom,
name: "math_exp",
description: "Creates valid mathematical expressions.",
format: {
type: :grammar,
syntax: :lark,
definition: grammar
}
}
]
)
puts(response.output)
此时,模型在工具调用中生成的输入应符合您定义的 Lark CFG:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 [
{
"id" : "rs_6890ed2b6374819dbbff5353e6664ef103f4db9848be4829" ,
"type" : "reasoning" ,
"content" : [],
"summary" : []
},
{
"id" : "ctc_6890ed2f32e8819daa62bef772b8c15503f4db9848be4829" ,
"type" : "custom_tool_call" ,
"status" : "completed" ,
"call_id" : "call_pmlLjmvG33KJdyVdC4MVdk5N" ,
"input" : "4 + 4" ,
"name" : "math_exp"
}
]
文法使用 Lark 的一种变体来定义。模型采样由 LLGuidance 约束。以下 Lark 特性不受支持:
词法分析器正则表达式中的环视断言
词法分析器正则表达式中的惰性修饰符(*?、+?、??)
终结符优先级
模板
导入(使用内置 %import 导入 common 中的定义除外)
%declare 声明
建议使用 Lark IDE 试验自定义文法。
请只保留工具需要的规则和匹配模式。如果文法过于复杂,OpenAI API 可能会返回错误,因此在 API 中使用文法前,应先确认它与 API 兼容。
要把 Lark 文法调整到理想状态并不容易。简单的文法通常最可靠,而复杂的文法往往需要反复调整文法定义、提示词和工具描述,才能确保模型的输出不偏离其训练分布。
正确写法(使用一个边界明确的终结符):
start: SENTENCE
SENTENCE: /[A-Za-z, ]*(the hero|a dragon|an old man|the princess)[A-Za-z, ]*(fought|saved|found|lost)[A-Za-z, ]*(a treasure|the kingdom|a secret|his way)[A-Za-z, ]*\./
切勿采用以下写法(拆分成多个规则或终结符)。这种写法试图通过规则将自由文本分配给不同的终结符。词法分析器会贪婪地匹配自由文本片段,您将无法控制匹配边界:
start: sentence
sentence: /[A-Za-z, ]+/ subject /[A-Za-z, ]+/ verb /[A-Za-z, ]+/ object /[A-Za-z, ]+/
词法分析器只根据终结符的定义切分输入,以小写字母命名的规则不会影响这一过程。如果需要匹配“锚点之间的自由文本”,请用一个完整的正则表达式终结符表示整个结构,让词法分析器按预期结构一次完成匹配。
Lark 使用终结符表示词法分析器识别的词法单元(按惯例使用 UPPERCASE 命名),使用规则表示语法分析器的产生式(按惯例使用 lowercase 命名)。要确保文法仅使用受支持的特性并避免意外行为,最实用的做法是明确定义文法,避免不必要的复杂性,并让终结符与规则各司其职。
终结符使用 Rust regex 库的正则表达式语法 ,与 Python 的 re 模块 所用的语法不同。
词法分析先于语法分析
在应用任何 CFG 规则之前,词法分析器就已经匹配了终结符(采用贪婪匹配,以最长匹配为准)。如果您试图把一个终结符拆分到多个规则中来控制它的匹配范围,这些规则无法指导词法分析器。词法分析器只依据终结符的正则表达式进行匹配。
从自由文本中匹配片段时,优先使用单个终结符
如果需要识别嵌在任意文本中的特定模式(例如在自然语言中,锚点之间可以出现任意内容),请用单个终结符表示该模式。不要将自由文本终结符与语法分析规则交错使用。贪婪匹配的词法分析器不会按您预期的边界切分,模型的输出也很可能偏离训练分布。
使用规则组合独立的词法单元
规则适合将边界明确的终结符(数字、关键字、标点符号等)组合成更大的结构。要约束两个终结符之间的内容,不宜使用规则。
让终结符职责单一、边界明确且定义完整
优先使用明确的字符类和有界量词(例如 {0,10},避免到处使用无界的 *)。如果需要匹配“直到句点为止的任意文本”,优先采用 /[^.\n]{0,10}*\./ 这样的写法,避免使用 /.+\./,以防匹配范围不断扩大。
用规则组合词法单元,避免用规则控制正则表达式的内部匹配过程
合理使用规则的示例:
start: expr
NUMBER: /[0-9]+/
PLUS: "+"
MINUS: "-"
expr: term (("+"|"-") term)*
term: NUMBER
显式处理空白字符
不要依赖范围不受限制的 %ignore 指令。无界的忽略指令可能会使文法过于复杂,也可能导致模型输出偏离训练分布。建议在每个允许出现空白字符的位置显式加入相应的终结符。
如果 API 因文法过于复杂而拒绝请求,请简化规则和终结符,并移除无界的 %ignore 指令。
如果调用自定义工具时出现意外的词法单元,请确认各终结符的匹配范围没有重叠,并检查词法分析器的贪婪匹配行为。
如果模型输出偏离训练分布(例如输出过长或不断重复,语法有效但语义错误):
收紧文法约束。
调整提示词(添加少样本示例)和工具描述(解释文法,并指示模型进行推理并遵循文法)。
尝试提高推理强度(例如从“中”调至“高”)。
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 import OpenAI from "openai";
const client = new OpenAI();
const grammar =
"^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\\s+(?P<day>\\d{1,2})(?:st|nd|rd|th)?\\s+(?P<year>\\d{4})\\s+at\\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$";
const response = await client.responses.create({
model: "gpt-6.2-astra",
input:
"Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.",
tools: [
{
type: "custom",
name: "timestamp",
description: "Saves a timestamp in date + time in 24-hr format.",
format: {
type: "grammar",
syntax: "regex",
definition: grammar,
},
},
],
});
console.log(response.output); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 from openai import OpenAI
client = OpenAI()
grammar = r " ^( ?P<month> January | February | March | April | May | June | July | August | September | October | November | December )\s + ( ?P<day> \d {1,2} )(?: st | nd | rd | th ) ? \s + ( ?P<year> \d {4} )\s + at \s + ( ?P<hour> 0 ? [1-9] | 1 [0-2])( ?P<ampm> AM | PM )$ "
response = client.responses.create(
model = "gpt-6.2-astra" ,
input = "Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM." ,
tools = [
{
"type" : "custom" ,
"name" : "timestamp" ,
"description" : "Saves a timestamp in date + time in 24-hr format." ,
"format" : {
"type" : "grammar" ,
"syntax" : "regex" ,
"definition" : grammar,
},
}
],
)
print (response.output) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
"github.com/openai/openai-go/v3/shared"
)
func main() {
client := openai.NewClient()
grammar := `^(?P<month>January|February|March|April|May|June|July|August|September|October|November|December)\s+(?P<day>\d{1,2})(?:st|nd|rd|th)?\s+(?P<year>\d{4})\s+at\s+(?P<hour>0?[1-9]|1[0-2])(?P<ampm>AM|PM)$`
tool := responses.ToolParamOfCustom("timestamp")
tool.OfCustom.Description = openai.String("Saves a timestamp in date and time format.")
tool.OfCustom.Format = shared.CustomToolInputFormatParamOfGrammar(grammar, "regex")
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6.2-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the timestamp tool to save a timestamp for August 7th 2025 at 10AM.")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(response.Output)
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.CustomToolInputFormat;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;
String grammar =
"^(January|February|March|April|May|June|July|August|September|October|November|December) "
+ "\\d{1,2}(st|nd|rd|th)? \\d{4} at (0?[1-9]|1[0-2])(AM|PM)$";
ResponseCreateParams params =
ResponseCreateParams.builder()
.model("gpt-6.2-astra")
.input("Use timestamp to save August 7th 2025 at 10AM.")
.addTool(
CustomTool.builder()
.name("timestamp")
.description("Saves a timestamp in date and time format.")
.format(
CustomToolInputFormat.Grammar.builder()
.syntax(CustomToolInputFormat.Grammar.Syntax.REGEX)
.definition(grammar)
.build())
.build())
.build();
client.responses().create(params).output().forEach(System.out::println); 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 require "openai"
client = OpenAI::Client.new
grammar = "^(January|February|March|April|May|June|July|August|September|October|November|December) \\d{1,2}(st|nd|rd|th)? \\d{4} at (0?[1-9]|1[0-2])(AM|PM)$"
response = client.responses.create(
model: "gpt-6.2-astra",
input: "Use timestamp to save August 7th 2025 at 10AM.",
tools: [
{
type: :custom,
name: "timestamp",
description: "Saves a timestamp in date and time format.",
format: {
type: :grammar,
syntax: :regex,
definition: grammar
}
}
]
)
puts(response.output)
此时,模型在工具调用中生成的输入应符合您定义的正则表达式 CFG:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 [
{
"id" : "rs_6894f7a3dd4c81a1823a723a00bfa8710d7962f622d1c260" ,
"type" : "reasoning" ,
"content" : [],
"summary" : []
},
{
"id" : "ctc_6894f7ad7fb881a1bffa1f377393b1a40d7962f622d1c260" ,
"type" : "custom_tool_call" ,
"status" : "completed" ,
"call_id" : "call_8m4XCnYvEmFlzHgDHbaOCFlK" ,
"input" : "August 7th 2025 at 10AM" ,
"name" : "timestamp"
}
]
与 Lark 语法一样,此处的正则表达式使用 Rust regex 库的语法 ,与 Python 的 re 模块 所用的语法不同。
以下正则表达式特性不受支持:
匹配模式必须写在一行内
如果需要匹配输入中的换行符,请使用转义序列 \n。不要使用允许匹配模式跨行书写的详细模式或扩展模式。
以普通模式字符串的形式提供正则表达式
不要将匹配模式包在 // 中。