Chamada de função | OpenAI API

A chamada de função (também conhecida como chamada de ferramenta) oferece aos modelos da OpenAI uma maneira poderosa e flexível de interagir com sistemas externos e acessar dados que não fizeram parte do treinamento. Este guia mostra como conectar um modelo aos dados e às ações que seu aplicativo oferece. Você verá como usar ferramentas do tipo função (definidas por um schema JSON) e ferramentas personalizadas que recebem e retornam texto livre.

Em sessões da Agents API, use Funções para registrar funções e processar solicitações de ação da sessão. Os exemplos deste guia mostram integrações com a Responses API e com a API chat completions.

Se seu aplicativo tiver muitas funções ou schemas grandes, você pode combinar a chamada de função com a pesquisa de ferramentas para adiar o carregamento de ferramentas pouco usadas até que o modelo precise delas. Somente o gpt-5.4 e modelos posteriores oferecem suporte a tool_search.

O GPT-6 Astra e o GPT-6.1 Sol exigem a Responses API para chamadas de ferramenta. Os exemplos da API chat completions usam o GPT-5.6 Terra com o raciocínio desativado. Consulte o guia de migração para atualizar uma integração existente.

Como funciona

Antes de passar aos exemplos práticos, vamos conhecer alguns termos fundamentais para entender como funciona a chamada de ferramenta.

A saída de uma chamada de função ou saída de uma chamada de ferramenta é a resposta que a ferramenta gera a partir da entrada fornecida pelo modelo na chamada. Essa saída pode ser um JSON estruturado ou texto simples e deve incluir uma referência à chamada específica feita pelo modelo (identificada por call_id nos próximos exemplos). Para completar o exemplo do tempo:

O modelo tem acesso a get_weather, uma ferramenta que recebe location como argumento.
Em resposta a um prompt como “Como está o tempo em Paris?”, o modelo retorna uma chamada de ferramenta com o argumento location definido como Paris.
A saída da chamada de ferramenta pode conter um objeto JSON (por exemplo, {"temperature": "25", "unit": "C"}, que indica uma temperatura atual de 25 graus), o conteúdo de uma imagem ou o conteúdo de um arquivo.

Em seguida, enviamos ao modelo a definição da ferramenta, o prompt original, a chamada de ferramenta feita pelo modelo e a saída da chamada. Assim, recebemos uma resposta em texto como esta:

The weather in Paris today is 25C.

Fluxo de chamada de ferramenta

A chamada de ferramenta envolve uma conversa em várias etapas entre seu aplicativo e um modelo por meio da API da OpenAI. O fluxo tem cinco etapas principais:

Envie uma solicitação ao modelo com as ferramentas que ele pode chamar.
Receba uma chamada de ferramenta do modelo.
Execute o código no aplicativo com a entrada fornecida na chamada.
Envie uma segunda solicitação ao modelo com a saída da ferramenta.
Receba a resposta final do modelo (ou outras chamadas de ferramenta).

Diagrama das etapas da chamada de função

Com a Responses API, seu aplicativo pode continuar esse fluxo por quantas chamadas de ferramenta a tarefa exigir. Se quiser usar um framework que cuide das etapas recorrentes de orquestração desse ciclo, veja a comparação entre a Responses API e o Agents SDK.

Exemplo de ferramenta do tipo função

Veja o fluxo completo de chamada de ferramenta com uma função get_horoscope que consulta o horóscopo do dia para um signo.

Exemplo completo de chamada de ferramenta

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72import OpenAI from "openai";

const openai = new OpenAI();

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

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

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

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

// 2. Prompt the model with tools defined
let response = await openai.chat.completions.create({
  model: "gpt-5.6-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
69from 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
69package main

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

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

func main() {
	client := openai.NewClient()
	tool := horoscopeChatTool()
	messages := []openai.ChatCompletionMessageParamUnion{
		openai.UserMessage("What is my horoscope? I am an Aquarius."),
	}
	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6-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
61import 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
62require "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)

Exemplo completo de chamada de ferramenta

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

const openai = new OpenAI();

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

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

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69from 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-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-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
75package main

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;

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

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

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

record HoroscopeArguments(String sign) {}

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48require "json"
require "openai"

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

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

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

puts(response.output_text)

Ao usar modelos de raciocínio como o GPT-5 ou o o4-mini, envie de volta, junto com as saídas das chamadas de ferramenta, todos os itens de raciocínio que o modelo retornou nas respostas que continham essas chamadas. Para saber como preservar o histórico que deu origem a esses itens, consulte as boas práticas para alterar o prefixo.

Como definir funções

Normalmente, você declara as funções no parâmetro tools de cada solicitação à API. Com a pesquisa de ferramentas, seu aplicativo também pode adiar o carregamento de funções para um momento posterior da interação. Em ambos os casos, o schema de cada função que pode ser chamada segue a mesma estrutura. A definição de uma função tem as seguintes propriedades:

Campo	Descrição
`type`	Deve ser sempre `function`
`name`	Nome da função (por exemplo, `get_weather`)
`description`	Detalhes sobre quando e como usar a função
`parameters`	Schema JSON que define os argumentos de entrada da função
`strict`	Indica se o modo estrito deve ser aplicado à chamada de função

Veja um exemplo de definição da função get_weather:

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

Como parameters é definido por um schema JSON, você pode aproveitar recursos como tipos de propriedades, enumerações, descrições, objetos aninhados e objetos recursivos.

Como definir namespaces

Use namespaces para agrupar ferramentas relacionadas por domínio, como crm, billing ou shipping. Os namespaces ajudam a organizar ferramentas semelhantes e são especialmente úteis quando o modelo precisa escolher entre ferramentas destinadas a sistemas ou finalidades diferentes, como uma ferramenta de pesquisa para o CRM e outra para o sistema de chamados de suporte.

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

Pesquisa de ferramentas

Se precisar dar ao modelo acesso a muitas ferramentas, você pode adiar o carregamento de algumas ou de todas elas com tool_search. A ferramenta tool_search permite que o modelo procure ferramentas relevantes, adicione-as ao contexto e passe a usá-las. Somente o gpt-5.4 e modelos posteriores oferecem suporte a esse recurso. Saiba mais no guia de pesquisa de ferramentas.

Sempre que possível, defina os schemas das funções diretamente. As bibliotecas cliente para Python e JavaScript também oferecem utilitários para converter objetos pydantic e zod em schemas, mas esses utilitários não oferecem suporte a todos os recursos.

Definição de objetos para representar o schema da função

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import OpenAI from "openai";
import { z } from "zod";
import { zodFunction } from "openai/helpers/zod";

const openai = new OpenAI();

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

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

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

const response = await openai.chat.completions.create({
  model: "gpt-5.6-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
20from 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)

Boas práticas para definir funções

Escolha nomes claros e descritivos para as funções e escreva descrições de parâmetros e instruções detalhadas.
- Descreva explicitamente a finalidade da função e de cada parâmetro (incluindo seu formato), além do significado da saída.
- Use o prompt do sistema para descrever quando usar cada função e quando evitar seu uso. Em geral, diga ao modelo exatamente o que fazer.
- Inclua exemplos e casos extremos, especialmente para corrigir falhas recorrentes. (Observação: adicionar exemplos pode prejudicar o desempenho dos modelos de raciocínio.)
- Para ferramentas com carregamento adiado, inclua orientações detalhadas na descrição da função e mantenha a descrição do namespace concisa. O namespace ajuda o modelo a escolher o que carregar. A descrição da função o ajuda a usar a ferramenta corretamente após o carregamento.
Aplique boas práticas de engenharia de software.
- Crie funções previsíveis e intuitivas. (Princípio da menor surpresa)
- Use enumerações e a estrutura dos objetos para evitar estados inválidos. Por exemplo, toggle_light(on: bool, off: bool) permite chamadas inválidas.
- Faça o teste do estagiário. Uma pessoa em início de carreira conseguiria usar a função corretamente só com as informações que você deu ao modelo? (Se não conseguir, que perguntas ela faria? Inclua as respostas no prompt.)
Reduza o trabalho do modelo e use código sempre que possível.
- Evite pedir ao modelo que preencha argumentos cujos valores você já conhece. Por exemplo, se você já obteve um order_id em um menu anterior, não inclua um parâmetro order_id. Defina submit_refund() sem parâmetros e passe o order_id no seu código.
- Combine funções que são sempre chamadas em sequência. Por exemplo, se você sempre chama mark_location() depois de query_location(), incorpore a lógica de marcação à função de consulta.
Disponibilize poucas funções inicialmente para aumentar a precisão.
- Avalie o desempenho com diferentes quantidades de funções.
- Procure disponibilizar menos de 20 funções no início de cada turno, mas considere esse número apenas uma referência.
- Use a pesquisa de ferramentas para adiar o carregamento de grupos grandes de ferramentas ou de ferramentas pouco usadas, em vez de disponibilizar tudo de início.
Aproveite os recursos da OpenAI.
- Gere e refine schemas de funções no Playground.
- Considere usar o ajuste fino para aumentar a precisão da chamada de função quando houver muitas funções ou tarefas difíceis. (Exemplo no Cookbook)

Uso de tokens

Internamente, as funções são inseridas na mensagem do sistema com uma sintaxe que o modelo aprendeu durante o treinamento. Assim, as definições das funções disponíveis contam para o limite de contexto do modelo e são cobradas como tokens de entrada. Se atingir o limite de tokens, sugerimos reduzir o número de funções carregadas inicialmente, encurtar as descrições quando possível ou usar a pesquisa de ferramentas para carregar as ferramentas adiadas somente quando necessárias.

Se a especificação das ferramentas definir muitas funções, você também pode usar o ajuste fino para reduzir o número de tokens usados.

Como processar chamadas de função

Quando o modelo chama uma função, você precisa executá-la e retornar o resultado. Como as respostas do modelo podem incluir zero, uma ou várias chamadas, é uma boa prática preparar seu código para processar várias.

A resposta contém o array tool_calls. Cada chamada tem um id (usado posteriormente para enviar o resultado da função) e um objeto function que contém um name e os arguments codificados em JSON.

Exemplo de resposta com várias chamadas de função

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\"}"
        }
    }
]

Execução das chamadas de função e inclusão dos resultados

Python

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40import 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
18message = completion.choices.fetch(0).message
messages << message

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

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

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

O array output da resposta contém uma entrada cujo type tem o valor function_call. Cada entrada desse tipo contém um call_id (usado posteriormente para enviar o resultado da função), um name e os arguments codificados em JSON.

Exemplo de resposta com várias chamadas de função

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\"}"
    }
]

Se estiver usando a pesquisa de ferramentas, você também poderá ver itens tool_search_call e tool_search_output antes de um function_call. Após o carregamento da função, processe a chamada como neste exemplo.

Execução das chamadas de função e inclusão dos resultados

Python

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49import 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
14input.concat(response.output)

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

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

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

No exemplo acima, usamos uma função hipotética call_function para encaminhar cada chamada à função correspondente. Veja uma possível implementação:

Execução das chamadas de função e inclusão dos resultados

Python

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31import 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
22using 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
16def call_function(name, arguments)
  case name
  when "get_weather"
    FunctionCallingExample.get_weather(
      arguments.fetch("latitude"),
      arguments.fetch("longitude")
    )
  when "send_email"
    FunctionCallingExample.send_email(
      arguments.fetch("to"),
      arguments.fetch("body")
    )
  else
    raise ArgumentError, "Unknown function: #{name}"
  end
end

Formatação dos resultados

Em geral, o resultado que você passa na mensagem function_call_output deve ser uma string. Você escolhe o formato (JSON, códigos de erro, texto simples etc.). O modelo interpreta a string conforme necessário.

Para funções que retornam imagens ou arquivos, você pode passar um array de objetos de imagem ou arquivo em vez de uma string.

Se a função não tiver valor de retorno (por exemplo, send_email), retorne uma string que indique sucesso ou falha, como "success".

Inclusão dos resultados na resposta

Depois de adicionar os resultados a messages, envie a lista atualizada de volta ao modelo para obter a resposta final.

Envio dos resultados de volta ao modelo

Python

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

1
2
3
4
5
6completion = 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
9completion, 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
56import 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
49require "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)

Depois de adicionar os resultados a input, envie a entrada atualizada de volta ao modelo para obter a resposta final.

Envio dos resultados de volta ao modelo

Python

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

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

1
2
3
4
5
6
7
8response, err = client.Responses.New(context.Background(), responses.ResponseNewParams{
	Model: "gpt-6-astra",
	Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
	Tools: tools,
})
if err != nil {
	panic(err)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseFunctionToolCall;
import com.openai.models.responses.ResponseInputItem;
import java.util.List;
import java.util.Map;

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41require "openai"

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

puts(response.output_text)

Resposta final

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

Configurações adicionais

Escolha de ferramentas

Por padrão, o modelo decide quando usar ferramentas e quantas usar. Você pode impor um comportamento específico com o parâmetro tool_choice.

Automática: (Padrão) O modelo pode chamar zero, uma ou várias funções. tool_choice: "auto"
Obrigatória: O modelo deve chamar uma ou mais funções. tool_choice: "required"
Função imposta: O modelo deve chamar exatamente uma função específica. tool_choice: {"type": "function", "name": "get_weather"}
Ferramentas permitidas: Limite as chamadas do modelo a um subconjunto das ferramentas disponíveis.

Quando usar allowed_tools

Configure uma lista allowed_tools se quiser disponibilizar apenas um subconjunto de ferramentas nas solicitações ao modelo e manter a lista completa que você envia. Assim, você pode maximizar a economia com o cache de prompts.

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

Você também pode definir tool_choice como "none" para obter o mesmo comportamento que teria se não passasse nenhuma função.

Ao usar a pesquisa de ferramentas, tool_choice continua se aplicando às ferramentas que podem ser chamadas naquele momento do turno. Isso é especialmente útil depois de carregar um subconjunto de ferramentas, quando você quer limitar o modelo a esse subconjunto.

Chamada de função em paralelo

Nos modelos compatíveis a partir do GPT-5, as funções podem ser chamadas em paralelo mesmo quando há ferramentas integradas disponíveis. Ferramentas integradas não podem fazer parte de um lote de chamadas de função em paralelo.

O modelo pode optar por chamar várias funções em um único turno. Para impedir isso, defina parallel_tool_calls como false. Assim, o modelo fará no máximo uma chamada de ferramenta.

Observação: Atualmente, se um modelo com ajuste fino chamar várias funções no mesmo turno, o modo estrito será desativado para essas chamadas.

Observação sobre gpt-4.1-nano-2025-04-14: Essa versão do gpt-4.1-nano às vezes gera várias chamadas à mesma ferramenta quando as chamadas em paralelo estão ativadas. Recomendamos desativar esse recurso ao usar essa versão.

Modo estrito

Defina strict como true para garantir que as chamadas de função sigam o schema da função de forma confiável. Sem essa garantia, o modelo apenas tenta seguir o schema. Recomendamos sempre ativar o modo estrito.

Internamente, o modo estrito usa o recurso de saídas estruturadas, o que impõe dois requisitos:

additionalProperties deve ter o valor false em cada objeto de parameters.
Todos os campos de properties devem ser marcados como required.

Para indicar campos opcionais, adicione null como uma opção de type (veja o exemplo abaixo).

Se você enviar strict: true e o schema não atender aos requisitos acima, a API rejeitará a solicitação e indicará quais restrições faltam. Se você omitir strict, o comportamento padrão dependerá da API. A Responses API tenta normalizar o schema para o modo estrito. Se não for possível torná-lo compatível, a chamada de função passa a operar sem a garantia de conformidade do modo estrito. Nesse caso, a ferramenta na resposta exibirá strict: false. As solicitações à API chat completions usam o modo não estrito por padrão. Para desativar o modo estrito na Responses API e manter a chamada de função sem garantia de conformidade, defina explicitamente strict: false.

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

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

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

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

Todos os schemas gerados no Playground têm o modo estrito ativado.

Embora recomendemos ativar o modo estrito, ele tem algumas limitações:

O modo estrito não oferece suporte a todos os recursos de schema JSON. (Consulte os schemas compatíveis.)

Para modelos com ajuste fino, há limitações específicas:

Os schemas passam por processamento adicional na primeira solicitação e depois ficam em cache. Se os schemas variarem de uma solicitação para outra, a latência poderá aumentar.
Os schemas ficam em cache para melhorar o desempenho e não são elegíveis para zero retenção de dados.

Streaming

Com o streaming, você pode mostrar o progresso da chamada, indicando qual função o modelo está chamando enquanto ele preenche os argumentos. Também é possível exibir os argumentos em tempo real.

O streaming de chamadas de função funciona como o de respostas comuns: você define stream como true e recebe fragmentos com objetos delta.

Streaming de chamadas de função

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42import { OpenAI } from "openai";

const openai = new OpenAI();

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

const stream = await openai.chat.completions.create({
  model: "gpt-5.6-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
37from 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
40package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string", "description": "City and country e.g. Bogotá, Colombia"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
		Function: shared.FunctionDefinitionParam{Name: "get_weather", Parameters: parameters, Strict: openai.Bool(true)},
	}}
	stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6-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
42import 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
35require "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

Saída de delta.tool_calls

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

Nesse caso, em vez de reunir os fragmentos em uma única string content, você os reúne para formar o objeto JSON codificado em arguments.

Quando o modelo chama uma ou mais funções, o campo tool_calls de cada delta é preenchido. Cada tool_call contém os seguintes campos:

Campo	Descrição
`index`	Identifica a chamada de função à qual o `delta` corresponde
`id`	ID da chamada de ferramenta.
`function`	Delta da chamada de função (`name` e `arguments`)
`type`	Tipo de `tool_call` (sempre `function` para chamadas de função)

Muitos desses campos só são definidos no primeiro delta de cada chamada de ferramenta, como id, function.name e type.

O trecho de código abaixo mostra como reunir os objetos delta em um objeto tool_calls final.

Acúmulo dos deltas de tool_call

Python

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14final_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
53package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := openai.ChatCompletionToolUnionParam{OfFunction: &openai.ChatCompletionFunctionToolParam{
		Function: shared.FunctionDefinitionParam{Name: "get_weather", Parameters: parameters, Strict: openai.Bool(true)},
	}}
	stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5.6-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
61import 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
49require "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)

Resultado acumulado em final_tool_calls[0]

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

O streaming de chamadas de função funciona como o de respostas comuns: você define stream como true e recebe diferentes objetos event.

Streaming de chamadas de função

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34import { OpenAI } from "openai";

const openai = new OpenAI();

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

const stream = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{ role: "user", content: "What's the weather like in Paris today?" }],
  tools,
  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
33from 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-astra",
    input=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
    stream=True,
)

for event in stream:
    print(event)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string", "description": "City and country e.g. Bogotá, Colombia"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction("get_weather", parameters, true)
	stream := client.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What's the weather like in Paris today?")},
		Tools: []responses.ToolUnionParam{tool},
	})
	for stream.Next() {
		fmt.Println(stream.Current().Type)
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseStreamEvent;
import java.util.List;
import java.util.Map;

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

try (StreamResponse<ResponseStreamEvent> stream = client.responses().createStreaming(params)) {
  stream.stream().forEach(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
23require "openai"

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

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

Eventos de saída

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\"}"}}

Nesse caso, em vez de reunir os fragmentos em uma única string content, você os reúne para formar o objeto JSON codificado em arguments.

Quando o modelo chama uma ou mais funções, a API emite um evento do tipo response.output_item.added para cada chamada de função. O evento contém os seguintes campos:

Campo	Descrição
`response_id`	ID da resposta à qual pertence a chamada de função
`output_index`	Índice do item de saída na resposta. Identifica cada chamada de função na resposta.
`item`	Item da chamada de função em andamento, com os campos `name`, `arguments` e `id`

Em seguida, você recebe uma série de eventos do tipo response.function_call_arguments.delta com o delta do campo arguments. Esses eventos contêm os seguintes campos:

Campo	Descrição
`response_id`	ID da resposta à qual pertence a chamada de função
`item_id`	ID do item da chamada de função ao qual pertence o delta
`output_index`	Índice do item de saída na resposta. Identifica cada chamada de função na resposta.
`delta`	Delta do campo `arguments`.

O trecho de código abaixo mostra como reunir os objetos delta em um objeto tool_call final.

Acúmulo dos deltas de tool_call

Python

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13final_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
49package main

import (
	"context"
	"fmt"

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.core.http.StreamResponse;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseFunctionToolCall;
import com.openai.models.responses.ResponseStreamEvent;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36require "openai"

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

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

    final_tool_calls[event.output_index] = 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)

Resultado acumulado em final_tool_calls[0]

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

Quando o modelo termina de chamar as funções, a API emite um evento do tipo response.function_call_arguments.done. Esse evento contém a chamada de função completa, incluindo os seguintes campos:

Campo	Descrição
`response_id`	ID da resposta à qual pertence a chamada de função
`output_index`	Índice do item de saída na resposta. Identifica cada chamada de função na resposta.
`item`	Item da chamada de função, com os campos `name`, `arguments` e `id`.

Ferramentas personalizadas

As ferramentas personalizadas funcionam de maneira semelhante às ferramentas do tipo função definidas por schema JSON. A diferença é que, em vez de receber instruções explícitas sobre a entrada exigida pela ferramenta, o modelo pode passar uma string arbitrária como entrada. Isso permite evitar o uso desnecessário de JSON para encapsular uma resposta ou aplicar uma gramática personalizada à resposta (veja a seguir).

O exemplo de código a seguir cria uma ferramenta personalizada que espera receber como resposta uma string de texto com código Python.

Exemplo de chamada de ferramenta personalizada

Python

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

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

console.log(response.output);

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

client = OpenAI()

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

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

import (
	"context"
	"fmt"

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

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

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

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

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

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

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

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

puts(response.output)

Como nos exemplos anteriores, o array output contém uma chamada de ferramenta gerada pelo modelo. Desta vez, a entrada da chamada é fornecida em texto simples.

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

Gramáticas livres de contexto

Uma gramática livre de contexto (CFG) é um conjunto de regras que definem como produzir texto válido em determinado formato. Para ferramentas personalizadas, você pode fornecer uma CFG que restrinja o texto que o modelo envia como entrada à ferramenta.

Use o parâmetro grammar ao configurar uma ferramenta personalizada para fornecer sua própria CFG. Atualmente, há suporte a duas sintaxes para definir gramáticas: lark e regex.

CFG com Lark

Exemplo de gramática livre de contexto com Lark

Python

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

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

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

console.log(response.output);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34from openai import OpenAI

client = OpenAI()

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37package main

import (
	"context"
	"fmt"

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.CustomToolInputFormat;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;

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

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

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

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

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

puts(response.output)

A saída da ferramenta deve então seguir a CFG que você definiu com Lark:

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

As gramáticas são especificadas com uma variante de Lark. A LLGuidance restringe a amostragem do modelo. A API não oferece suporte aos seguintes recursos de Lark:

Asserções de contexto (lookarounds) nas expressões regulares do analisador léxico
Modificadores não gulosos (*?, +?, ??) nas expressões regulares do analisador léxico
Prioridades de terminais
Templates
Importações (exceto a importação integrada %import common)
Diretivas %declare

Recomendamos usar o IDE do Lark para experimentar gramáticas personalizadas.

Limite a complexidade da gramática

Restrinja a gramática às regras e aos padrões de que a ferramenta precisa. A API da OpenAI pode retornar um erro se a gramática for complexa demais. Verifique se a gramática é compatível antes de usá-la na API.

Pode ser difícil acertar todos os detalhes de uma gramática Lark. Gramáticas mais simples funcionam de forma mais confiável. Com gramáticas complexas, muitas vezes é preciso refinar a própria definição da gramática, o prompt e a descrição da ferramenta para evitar que o modelo gere saídas fora da distribuição esperada.

Padrões corretos e incorretos

Correto (um único terminal delimitado):

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, ]*\./

NÃO divida o padrão entre regras e terminais como no exemplo abaixo. Essa abordagem tenta usar regras para distribuir o texto livre entre os terminais. O analisador léxico consome os trechos de texto livre de forma gulosa, e você perde o controle sobre a divisão:

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

As regras em minúsculas não influenciam a divisão da entrada em terminais. Somente as definições dos terminais determinam essa divisão. Quando precisar de “texto livre entre âncoras”, represente todo o padrão em um único terminal de expressão regular para que o analisador léxico faça uma única correspondência com a estrutura pretendida.

Terminais e regras

O Lark usa terminais para representar os tokens do analisador léxico (por convenção, em UPPERCASE) e regras para as produções do analisador sintático (por convenção, em lowercase). Para usar apenas os recursos compatíveis e evitar surpresas, mantenha a gramática explícita, evite complexidade desnecessária e separe claramente as responsabilidades dos terminais e das regras.

Os terminais usam a sintaxe da biblioteca regex do Rust, que difere da sintaxe de re, o módulo de expressões regulares do Python.

Conceitos e boas práticas

O analisador léxico é executado antes do analisador sintático

Antes da aplicação de qualquer regra da CFG, o analisador léxico identifica os terminais de forma gulosa: prevalece a correspondência mais longa. Se você tentar delimitar um terminal dividindo-o entre várias regras, essas regras não orientarão o analisador léxico. Ele segue apenas as expressões regulares dos terminais.

Prefira um único terminal para extrair trechos de texto livre

Se precisar reconhecer um padrão em meio a texto arbitrário (por exemplo, linguagem natural com “qualquer conteúdo” entre âncoras), represente-o como um único terminal. Evite intercalar terminais de texto livre com regras do analisador sintático. A análise léxica gulosa não respeitará os limites pretendidos, e é muito provável que o modelo gere saídas fora da distribuição esperada.

Use regras para combinar tokens distintos

As regras são ideais para combinar terminais com limites explícitos (números, palavras-chave, pontuação) em estruturas maiores. Elas não são adequadas para restringir “o conteúdo entre” dois terminais.

Defina terminais específicos, delimitados e independentes

Prefira classes de caracteres explícitas e quantificadores limitados ({0,10}, em vez de usar * sem limite em toda parte). Se precisar de “qualquer texto até um ponto final”, prefira algo como /[^.\n]{0,10}*\./ a /.+\./ para evitar que o trecho capturado cresça sem controle.

Use regras para combinar tokens e deixe a correspondência interna a cargo das expressões regulares

Exemplo de uso adequado de regras:

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

Trate os espaços em branco de forma explícita

Evite depender de diretivas %ignore sem limites. Elas podem tornar a gramática complexa demais, levar o modelo a gerar saídas fora da distribuição esperada ou causar ambos os problemas. Prefira inserir terminais explícitos em cada ponto em que espaços em branco são permitidos.

Solução de problemas

Se a API rejeitar a gramática por excesso de complexidade, simplifique as regras e os terminais e remova as diretivas %ignore sem limites.
Se as ferramentas personalizadas receberem chamadas com tokens inesperados, verifique se há sobreposição entre os terminais e como o analisador léxico faz a correspondência gulosa.
Quando o modelo gerar saídas “fora da distribuição esperada” (excessivamente longas ou repetitivas, com sintaxe válida, mas significado incorreto):
- Torne a gramática mais restritiva.
- Refine o prompt (adicione exemplos few-shot) e a descrição da ferramenta (explique a gramática e instrua o modelo a raciocinar e a seguir suas regras).
- Experimente um esforço de raciocínio maior (por exemplo, passe de médio para alto).

CFG com expressão regular

Exemplo de gramática livre de contexto com expressão regular

Python

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

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

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

console.log(response.output);

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

client = OpenAI()

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

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

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

import (
	"context"
	"fmt"

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.CustomToolInputFormat;
import com.openai.models.responses.CustomTool;
import com.openai.models.responses.ResponseCreateParams;

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

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

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

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

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

puts(response.output)

A saída da ferramenta deve então seguir a CFG que você definiu com a expressão regular:

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

Assim como na sintaxe Lark, as expressões regulares usam a sintaxe da biblioteca regex do Rust, que difere da sintaxe de re, o módulo de expressões regulares do Python.

A API não oferece suporte aos seguintes recursos de expressões regulares:

Asserções de contexto (lookarounds)
Modificadores não gulosos (*?, +?, ??)

Conceitos e boas práticas

O padrão deve ocupar uma única linha

Se precisar reconhecer uma quebra de linha na entrada, use a sequência de escape \n. Não use o modo detalhado ou estendido, que permite escrever padrões em várias linhas.

Forneça a expressão regular como uma string que contenha apenas o padrão

Não delimite o padrão com //.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso