Llamada a funciones | OpenAI API

La llamada a funciones (también conocida como llamada a herramientas) ofrece una forma potente y flexible para que los modelos de OpenAI interactúen con sistemas externos y accedan a datos que no forman parte de sus datos de entrenamiento. Esta guía muestra cómo conectar un modelo con los datos y las acciones que ofrece tu aplicación. Mostraremos cómo usar herramientas de función (definidas mediante un esquema JSON) y herramientas personalizadas que trabajan con entradas y salidas de texto libre.

Para las sesiones de la API de agentes, usa Funciones para registrar funciones y gestionar las solicitudes de acciones de la sesión. Los ejemplos de esta guía muestran las integraciones con la API Responses y Chat Completions.

Si tu aplicación tiene muchas funciones o esquemas grandes, puedes combinar la llamada a funciones con la búsqueda de herramientas para diferir la carga de las herramientas que se usan con poca frecuencia y cargarlas solo cuando el modelo las necesite. Solo gpt-5.4 y los modelos posteriores admiten tool_search.

GPT-6 Astra requiere la API Responses para la llamada a herramientas. Los ejemplos de Chat Completions usan GPT-5.6 por compatibilidad. Consulta la guía de migración para actualizar una integración existente.

Cómo funciona

Comencemos por entender algunos términos clave sobre la llamada a herramientas. Una vez que tengamos un vocabulario común, te mostraremos cómo se hace con algunos ejemplos prácticos.

El resultado de una llamada a una función o resultado de una llamada a una herramienta se refiere a la respuesta que genera una herramienta con los datos de entrada de una llamada del modelo. Este resultado puede ser JSON estructurado o texto sin formato, y debe contener una referencia a una llamada específica del modelo a una herramienta (identificada mediante call_id en los ejemplos que siguen). Para completar nuestro ejemplo del clima:

El modelo tiene acceso a una herramienta get_weather que recibe location como argumento.
En respuesta a un prompt como “¿Cómo está el clima en París?”, el modelo devuelve una llamada a una herramienta que contiene un argumento location con el valor Paris
El resultado de la llamada a la herramienta podría devolver un objeto JSON (por ejemplo, {"temperature": "25", "unit": "C"}, que indica una temperatura actual de 25 grados), contenido de imágenes o contenido de archivos.

Luego, enviamos de vuelta al modelo la definición completa de la herramienta, el prompt original, la llamada del modelo a la herramienta y su resultado para recibir finalmente una respuesta de texto como esta:

The weather in Paris today is 25C.

El flujo de llamada a herramientas

La llamada a herramientas es una conversación de varios pasos entre tu aplicación y un modelo a través de la API de OpenAI. Este flujo consta de cinco pasos generales:

Envía una solicitud al modelo con las herramientas a las que podría llamar
Recibe una llamada a una herramienta del modelo
Ejecuta código en la aplicación con los datos de entrada de la llamada a la herramienta
Envía una segunda solicitud al modelo con el resultado de la herramienta
Recibe una respuesta final del modelo (o más llamadas a herramientas)

Diagrama de los pasos de la llamada a funciones

Con Responses, tu aplicación puede continuar este flujo durante tantas llamadas a herramientas como requiera la tarea. Si quieres un framework que encapsule la orquestación recurrente de ese ciclo, consulta la comparación entre la API Responses y el Agents SDK.

Ejemplo de una herramienta de función

Veamos un flujo completo de llamada a herramientas para una función get_horoscope que obtiene el horóscopo diario de un signo del zodiaco.

Ejemplo completo de llamada a herramientas

Python

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

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",
  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",
  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
67from 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",
    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",
    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", 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", 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
59import 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.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")
        .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
60require "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",
  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",
  messages: messages,
  tools: tools
)
puts(final_completion.choices.fetch(0).message.content)

Ejemplo completo de llamada a herramientas

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
69
70
71
72from openai import OpenAI
import json

client = OpenAI()

# 1. Define a list of callable tools for the model
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"],
        },
    },
]


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,
                }
            )

print("Final input:")
print(input_list)

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("Final output:")
print(response.model_dump_json(indent=2))
print("\n" + 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)

Ten en cuenta que, en los modelos de razonamiento como GPT-5 u o4-mini, todos los elementos de razonamiento que se devuelvan en las respuestas del modelo con llamadas a herramientas también deben enviarse de vuelta junto con los resultados de esas llamadas.

Definir funciones

Las funciones suelen declararse en el parámetro tools de cada solicitud a la API. Con la búsqueda de herramientas, tu aplicación también puede cargar funciones diferidas más adelante en la interacción. En ambos casos, cada función a la que se puede llamar usa la misma estructura de esquema. La definición de una función tiene las siguientes propiedades:

Campo	Descripción
`type`	Siempre debe ser `function`
`name`	El nombre de la función (por ejemplo, `get_weather`)
`description`	Detalles sobre cuándo y cómo usar la función
`parameters`	Esquema JSON que define los argumentos de entrada de la función
`strict`	Indica si se debe aplicar el modo estricto a la llamada a la función

Aquí tienes un ejemplo de definición de una función 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
}

Al definir parameters mediante un esquema JSON, puedes aprovechar muchas de sus funciones avanzadas, como tipos de propiedades, enumeraciones, descripciones, objetos anidados y objetos recursivos.

Definir espacios de nombres

Usa espacios de nombres para agrupar herramientas relacionadas por dominio, como crm, billing o shipping. Los espacios de nombres ayudan a organizar herramientas similares y son especialmente útiles cuando el modelo debe elegir entre herramientas que sirven a distintos sistemas o propósitos, como una herramienta de búsqueda para tu CRM y otra para tu sistema de tickets de soporte.

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

Búsqueda de herramientas

Si necesitas darle al modelo acceso a un amplio ecosistema de herramientas, puedes diferir la carga de algunas o de todas ellas con tool_search. La herramienta tool_search permite que el modelo busque herramientas relevantes, las agregue a su contexto y luego las use. Solo gpt-5.4 y los modelos posteriores la admiten. Lee la guía de búsqueda de herramientas para obtener más información.

Aunque recomendamos que definas directamente los esquemas de tus funciones, nuestros SDK incluyen funciones auxiliares para convertir objetos de pydantic y zod en esquemas. No se admiten todas las características de pydantic y zod.

Define objetos para representar el esquema de la función

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
26import 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",
  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
19from 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",
    messages=[{"role": "user", "content": "What's the weather like in Paris today?"}],
    tools=tools,
)

print(completion.choices[0].message.tool_calls)

Prácticas recomendadas para definir funciones

Escribe nombres de funciones, descripciones de parámetros e instrucciones que sean claros y detallados.
- Describe explícitamente el propósito de la función y de cada parámetro (y su formato), así como lo que representa la salida.
- Usa el prompt del sistema para describir cuándo usar cada función y cuándo no. En general, dile al modelo exactamente qué hacer.
- Incluye ejemplos y casos límite, especialmente para corregir fallas recurrentes. (Nota: agregar ejemplos puede perjudicar el desempeño de los modelos de razonamiento.)
- Para las herramientas de carga diferida, incluye instrucciones detalladas en la descripción de la función y mantén concisa la descripción del espacio de nombres. El espacio de nombres ayuda al modelo a elegir qué cargar; la descripción de la función lo ayuda a usar correctamente la herramienta cargada.
Aplica las prácticas recomendadas de ingeniería de software.
- Haz que las funciones sean predecibles e intuitivas. (principio de mínima sorpresa)
- Usa enumeraciones y la estructura de los objetos para evitar estados no válidos. Por ejemplo, toggle_light(on: bool, off: bool) permite llamadas no válidas.
- Supera la prueba del pasante. ¿Puede un pasante u otra persona usar correctamente la función con solo la información que le diste al modelo? (Si no, ¿qué preguntas te hace? Agrega las respuestas al prompt.)
Reduce la carga del modelo y usa código cuando sea posible.
- No hagas que el modelo complete argumentos cuyos valores ya conoces. Por ejemplo, si ya tienes un order_id a partir de un menú anterior, no incluyas un parámetro order_id. En su lugar, define submit_refund() sin parámetros y pasa el order_id en tu código.
- Combina las funciones que siempre se llaman en secuencia. Por ejemplo, si siempre llamas a mark_location() después de query_location(), simplemente mueve la lógica de marcado a la llamada a la función de consulta.
Mantén un número reducido de funciones disponibles al inicio para lograr mayor precisión.
- Evalúa el desempeño con distintas cantidades de funciones.
- Procura que haya menos de 20 funciones disponibles al inicio de cada turno , aunque esto es solo una recomendación orientativa.
- Usa la búsqueda de herramientas para diferir la carga de grupos grandes de herramientas o de herramientas que se usan con poca frecuencia, en lugar de exponerlas todas desde el principio.
Aprovecha los recursos de OpenAI.
- Genera esquemas de funciones y mejóralos de forma iterativa en el Playground.
- Considera el ajuste fino para aumentar la precisión de las llamadas a funciones cuando haya muchas funciones o tareas difíciles. (Cookbook)

Uso de tokens

Internamente, las funciones se insertan en el mensaje del sistema con una sintaxis con la que se entrenó al modelo. Esto significa que las definiciones de las funciones que se pueden llamar cuentan para el límite de contexto del modelo y se facturan como tokens de entrada. Si alcanzas los límites de tokens, te sugerimos limitar la cantidad de funciones que se cargan al inicio, acortar las descripciones cuando sea posible o usar la búsqueda de herramientas para que las herramientas de carga diferida solo se carguen cuando se necesiten.

También puedes usar el ajuste fino para reducir la cantidad de tokens utilizados si tienes muchas funciones definidas en tu especificación de herramientas.

Manejo de llamadas a funciones

Cuando el modelo llama a una función, debes ejecutarla y devolver el resultado. Como las respuestas del modelo pueden incluir cero, una o varias llamadas, la práctica recomendada es asumir que habrá varias.

La respuesta contiene un arreglo de tool_calls, cada una con un id (que se usa después para enviar el resultado de la función) y una function que contiene un name y arguments codificados en JSON.

Ejemplo de respuesta con varias llamadas a funciones

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

Ejecuta las llamadas a funciones y agrega los 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
36import 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.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().orElseThrow()) {
  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 =
        JsonValue.from(
                Map.of(
                    "latitude", coordinates.latitude(),
                    "longitude", coordinates.longitude(),
                    "temperature_c", 18))
            .toString();
  } else if (call.function().name().equals("send_email")) {
    record Email(String to, String body) {}
    Email message = call.function().arguments(Email.class);
    output = JsonValue.from(Map.of("to", message.to(), "status", "sent")).toString();
  } else {
    throw new IllegalArgumentException("Unknown function: " + call.function().name());
  }
  history.addMessage(
      ChatCompletionToolMessageParam.builder().toolCallId(call.id()).content(output).build());
  System.out.println(call.id() + " " + output);
}

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

El arreglo output de la respuesta contiene una entrada cuyo type tiene el valor function_call. Cada entrada incluye un call_id (que se usa después para enviar el resultado de la función), un name y arguments codificados en JSON.

Ejemplo de respuesta con varias llamadas a funciones

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

Si usas la búsqueda de herramientas, también puedes ver elementos tool_search_call y tool_search_output antes de un function_call. Una vez cargada la función, maneja la llamada a la función de la misma manera que se muestra aquí.

Ejecuta las llamadas a funciones y agrega los 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
47import 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.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);
response.output().stream()
    .flatMap(item -> item.functionCall().stream())
    .forEach(
        call -> {
          String result;
          if (call.name().equals("get_weather")) {
            record Coordinates(double latitude, double longitude) {}

            Coordinates coordinates = call.arguments(Coordinates.class);
            result =
                JsonValue.from(
                        Map.of(
                            "latitude", coordinates.latitude(),
                            "longitude", coordinates.longitude(),
                            "temperature_c", 18))
                    .toString();
          } else if (call.name().equals("send_email")) {
            record Email(String to, String body) {}

            Email message = call.arguments(Email.class);
            result = JsonValue.from(Map.of("to", message.to(), "status", "sent")).toString();
          } 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(call.callId() + " " + result);
        });

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

En el ejemplo anterior, usamos una función hipotética call_function para dirigir cada llamada. Esta es una posible implementación:

Ejecuta las llamadas a funciones y agrega los 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
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

Formato de los resultados

Por lo general, el resultado que pases en el mensaje function_call_output debe ser una cadena de texto cuyo formato puedes elegir (JSON, códigos de error, texto sin formato, etc.). El modelo interpretará esa cadena según sea necesario.

Para las funciones que devuelven imágenes o archivos, puedes pasar un arreglo de objetos de imagen o archivo en lugar de una cadena de texto.

Si tu función no tiene un valor de retorno (por ejemplo, send_email), devuelve una cadena de texto que indique si la operación tuvo éxito o falló, como "success".

Incorporación de los resultados en la respuesta

Después de agregar los resultados a messages, puedes enviarlos de vuelta al modelo para obtener una respuesta final.

Envía los resultados de vuelta al modelo

Python

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

1
2
3
4
5
6
7completion = client.chat.completions.create(
    model="gpt-5.6",
    messages=messages,
    tools=chat_tools,
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9completion, err = client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
	Model:           "gpt-5.6",
	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
54import 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.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")
        .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
48require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-5.6",
  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)

Después de agregar los resultados a input, puedes enviarlos de vuelta al modelo para obtener una respuesta final.

Envía los resultados de vuelta al modelo

Python

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

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

print(response.output_text)

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)

Respuesta final

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

Configuraciones adicionales

Selección de herramientas

De forma predeterminada, el modelo determinará cuándo usar herramientas y cuántas usar. Puedes forzar un comportamiento específico con el parámetro tool_choice.

Automática: (Predeterminada) llamar a cero, una o varias funciones. tool_choice: "auto"
Obligatoria: llamar a una o más funciones. tool_choice: "required"
Función forzada: llamar exactamente a una función específica. tool_choice: {"type": "function", "name": "get_weather"}
Herramientas permitidas: restringir las llamadas a herramientas que puede hacer el modelo a un subconjunto de las herramientas disponibles para el modelo.

Cuándo usar allowed_tools

Puedes configurar una lista allowed_tools si quieres que solo esté disponible un subconjunto de herramientas en las solicitudes al modelo, sin modificar la lista de herramientas que envías, para maximizar el ahorro del almacenamiento de prompts en caché.

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

También puedes establecer tool_choice en "none" para simular el comportamiento de no pasar ninguna función.

Cuando usas la búsqueda de herramientas, tool_choice sigue aplicándose a las herramientas que se pueden llamar en ese momento del turno. Esto resulta especialmente útil después de cargar un subconjunto de herramientas, cuando quieres limitar al modelo a ese subconjunto.

Llamadas a funciones en paralelo

En los modelos compatibles a partir de GPT-5, se puede llamar a funciones en paralelo cuando también hay herramientas integradas disponibles. Las herramientas integradas no pueden incluirse en un lote de llamadas a funciones en paralelo.

El modelo puede optar por llamar a varias funciones en un solo turno. Puedes evitarlo estableciendo parallel_tool_calls en false, lo que garantiza que se llame a una sola herramienta o a ninguna.

Nota: actualmente, si usas un modelo con ajuste fino y este llama a varias funciones en un turno, el modo estricto se desactivará para esas llamadas.

Nota sobre gpt-4.1-nano-2025-04-14: esta versión de gpt-4.1-nano a veces puede incluir varias llamadas a la misma herramienta si las llamadas a herramientas en paralelo están habilitadas. Se recomienda desactivar esta función al usar esta versión.

Modo estricto

Establecer strict en true garantiza que las llamadas a funciones cumplan de manera confiable el esquema de la función, en lugar de solo intentar cumplirlo sin garantías. Recomendamos activar siempre el modo estricto.

Internamente, el modo estricto utiliza nuestra función de resultados estructurados y, por lo tanto, introduce un par de requisitos:

additionalProperties debe establecerse en false para cada objeto de parameters.
Todos los campos de properties deben marcarse como required.

Puedes indicar que un campo es opcional agregando null como opción de type (consulta el ejemplo a continuación).

Si envías strict: true y tu esquema no cumple con los requisitos anteriores, la solicitud se rechazará con detalles sobre las restricciones faltantes. Si omites strict, el comportamiento predeterminado depende de la API: las solicitudes a Responses intentarán normalizar tu esquema para usar el modo estricto cuando sea posible y recurrirán a llamadas a funciones no estrictas, que intentan cumplir el esquema sin garantizarlo, si este no puede hacerse compatible con el modo estricto. Cuando esto ocurra, la herramienta en la respuesta mostrará strict: false. Las solicitudes a Chat Completions siguen siendo no estrictas de forma predeterminada. Para desactivar el modo estricto en Responses y mantener las llamadas a funciones no estrictas, que intentan cumplir el esquema sin garantizarlo, establece explícitamente 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 los esquemas generados en el Playground tienen el modo estricto activado.

Aunque recomendamos activar el modo estricto, tiene algunas limitaciones:

Algunas características de los esquemas JSON no son compatibles. (Consulta los esquemas compatibles.)

Específicamente para los modelos con ajuste fino:

Los esquemas pasan por un procesamiento adicional en la primera solicitud (y luego se almacenan en caché). Si tus esquemas varían entre solicitudes, esto puede generar latencias más altas.
Los esquemas se almacenan en caché para mejorar el rendimiento y no pueden acogerse a la retención cero de datos.

Streaming

El streaming permite mostrar el progreso indicando a qué función se llama mientras el modelo completa sus argumentos, e incluso mostrando los argumentos en tiempo real.

El streaming de llamadas a funciones es muy similar al de las respuestas normales: estableces stream en true y recibes fragmentos con objetos delta.

Streaming de llamadas a funciones

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
40import { 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",
  messages: [
    { role: "user", content: "What's the weather like in Paris today?" },
  ],
  tools,
  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
36from 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",
    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",
		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
40import 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.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")
        .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
34require "openai"

client = OpenAI::Client.new
stream = client.chat.completions.stream(
  model: "gpt-5.6",
  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

Salida 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

Sin embargo, en lugar de combinar los fragmentos en una sola cadena content, los combinas en un objeto JSON codificado de arguments.

Cuando el modelo llama a una o más funciones, se completa el campo tool_calls de cada delta. Cada tool_call contiene los siguientes campos:

Campo	Descripción
`index`	Identifica a qué llamada a función corresponde el `delta`
`id`	ID de la llamada a herramienta.
`function`	Delta de la llamada a función (`name` y `arguments`)
`type`	Tipo de `tool_call` (siempre `function` para las llamadas a funciones)

Muchos de estos campos, como id, function.name y type, solo se establecen en el primer delta de cada llamada a herramienta.

El siguiente fragmento de código muestra cómo combinar los delta en un objeto tool_calls final.

Acumulación de 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
10final_tool_calls = {}

for chunk in stream:
    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

        final_tool_calls[index].function.arguments += tool_call.function.arguments

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
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",
		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
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.FunctionDefinition;
import com.openai.models.FunctionParameters;
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")
        .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
48require "openai"

client = OpenAI::Client.new
stream = client.chat.completions.stream(
  model: "gpt-5.6",
  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)

final_tool_calls[0] acumulado

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

El streaming permite mostrar el progreso indicando qué función se llama mientras el modelo completa sus argumentos, e incluso mostrar los argumentos en tiempo real.

El streaming de llamadas a funciones es muy similar al de respuestas normales: estableces stream en true y recibes distintos objetos event.

Streaming de llamadas a funciones

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
33import { 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,
  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
32from openai import OpenAI

client = OpenAI()

tools = [
    {
        "type": "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,
        },
    }
]

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
34
35
36
37
38
39
40
41
42
43
44
45
46import 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(
          event -> {
            System.out.println(event);
            event
                .outputItemAdded()
                .ifPresent(added -> System.out.println("response.output_item.added: " + added));
            event
                .functionCallArgumentsDelta()
                .ifPresent(
                    delta ->
                        System.out.println("response.function_call_arguments.delta: " + delta));
          });
}

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 salida

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

Sin embargo, en lugar de combinar los fragmentos en una sola cadena content, los combinas en un objeto JSON arguments codificado.

Cuando el modelo llama a una o más funciones, se emite un evento de tipo response.output_item.added por cada llamada a función. Este evento contiene los siguientes campos:

Campo	Descripción
`response_id`	El identificador de la respuesta a la que pertenece la llamada a función
`output_index`	El índice del elemento de salida en la respuesta. Representa las llamadas a funciones individuales de la respuesta.
`item`	El elemento de llamada a función en curso que incluye los campos `name`, `arguments` y `id`

Después recibirás una serie de eventos de tipo response.function_call_arguments.delta que contendrán el delta del campo arguments. Estos eventos contienen los siguientes campos:

Campo	Descripción
`response_id`	El identificador de la respuesta a la que pertenece la llamada a función
`item_id`	El identificador del elemento de llamada a función al que pertenece el delta
`output_index`	El índice del elemento de salida en la respuesta. Representa las llamadas a funciones individuales de la respuesta.
`delta`	El delta del campo `arguments`.

El siguiente fragmento de código muestra cómo combinar los delta en un objeto tool_call final.

Acumulación de 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
10final_tool_calls = {}

for event in stream:
    if event.type == "response.output_item.added":
        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
36
37
38
39
40
41
42require "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] = {
      id: item.id,
      call_id: item.call_id,
      name: item.name,
      type: item.type,
      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)

final_tool_calls[0] acumulado

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

Cuando el modelo termine de llamar a las funciones, se emitirá un evento de tipo response.function_call_arguments.done. Este evento contiene la llamada a función completa, incluidos los siguientes campos:

Campo	Descripción
`response_id`	El identificador de la respuesta a la que pertenece la llamada a función
`output_index`	El índice del elemento de salida en la respuesta. Representa las llamadas a funciones individuales de la respuesta.
`item`	El elemento de llamada a función que incluye los campos `name`, `arguments` y `id`.

Herramientas personalizadas

Las herramientas personalizadas funcionan de forma muy similar a las herramientas de función basadas en esquemas JSON. Sin embargo, en lugar de darle al modelo instrucciones explícitas sobre la entrada que requiere tu herramienta, el modelo puede pasarle una cadena arbitraria como entrada. Esto permite evitar envolver innecesariamente una respuesta en JSON o aplicar una gramática personalizada a la respuesta (más detalles a continuación).

El siguiente ejemplo de código muestra cómo crear una herramienta personalizada que espera recibir como respuesta una cadena de texto con código Python.

Ejemplo de llamada a una herramienta 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 antes, el arreglo output contendrá una llamada a herramienta generada por el modelo. La diferencia es que esta vez la entrada de la llamada a herramienta se proporciona como texto sin formato.

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 libres de contexto

Una gramática libre de contexto (CFG) es un conjunto de reglas que definen cómo producir texto válido en un formato determinado. Para las herramientas personalizadas, puedes proporcionar una CFG que restrinja el texto que el modelo envía como entrada a una herramienta personalizada.

Puedes proporcionar una CFG personalizada mediante el parámetro grammar al configurar una herramienta personalizada. Actualmente, admitimos dos formas de sintaxis de CFG para definir gramáticas: lark y regex.

CFG de Lark

Ejemplo de gramática libre de contexto de 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)

La salida de la herramienta debería ajustarse entonces a la CFG de Lark que definiste:

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

Las gramáticas se especifican mediante una variante de Lark. El muestreo del modelo se restringe mediante LLGuidance. Algunas funciones de Lark no son compatibles:

Aserciones de anticipación y retrospección en las expresiones regulares del analizador léxico
Modificadores no codiciosos (*?, +?, ??) en las expresiones regulares del analizador léxico
Prioridades de los terminales
Plantillas
Importaciones (excepto la instrucción integrada %import common)
Directivas %declare

Recomendamos usar el Lark IDE para experimentar con gramáticas personalizadas.

Limitar la complejidad de la gramática

Limita tu gramática a las reglas y los patrones que necesita tu herramienta. La API de OpenAI puede devolver un error si la gramática es demasiado compleja, por lo que debes asegurarte de que la gramática que quieres usar sea compatible antes de utilizarla en la API.

Perfeccionar las gramáticas de Lark puede ser difícil. Las gramáticas menos complejas funcionan con mayor fiabilidad, mientras que las complejas suelen requerir ajustes sucesivos en la propia definición de la gramática, el prompt y la descripción de la herramienta para garantizar que el modelo no se salga de la distribución.

Patrones correctos e incorrectos

Correcto (un solo terminal acotado):

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

NO hagas esto (dividir entre reglas o terminales). Este enfoque intenta que las reglas repartan el texto libre entre terminales. El analizador léxico buscará coincidencias de forma voraz en los fragmentos de texto libre y perderás el control:

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

Las reglas en minúsculas no influyen en cómo se extraen los terminales de la entrada; solo lo hacen las definiciones de los terminales. Cuando necesites “texto libre entre anclas”, exprésalo como un único terminal con una gran expresión regular para que el analizador léxico lo reconozca exactamente una vez con la estructura que buscas.

Terminales y reglas

Lark usa terminales para los tokens del analizador léxico (por convención, UPPERCASE) y reglas para las producciones del analizador sintáctico (por convención, lowercase). La forma más práctica de mantenerse dentro del subconjunto admitido y evitar sorpresas es definir la gramática de forma explícita, evitar la complejidad innecesaria y usar terminales y reglas con una clara separación de responsabilidades.

La sintaxis de expresiones regulares que usan los terminales es la sintaxis del crate regex de Rust, no la del módulo re de Python.

Conceptos clave y prácticas recomendadas

El analizador léxico se ejecuta antes que el analizador sintáctico

El analizador léxico reconoce los terminales de forma voraz (prevalece la coincidencia más larga) antes de que se aplique la lógica de cualquier regla de la CFG. Si intentas “dar forma” a un terminal dividiéndolo entre varias reglas, esas reglas no pueden guiar al analizador léxico; solo pueden hacerlo las expresiones regulares de los terminales.

Prefiere un solo terminal para extraer texto de fragmentos de formato libre

Si necesitas reconocer un patrón dentro de un texto arbitrario (por ejemplo, lenguaje natural con “cualquier cosa” entre anclas), exprésalo como un solo terminal. No intentes intercalar terminales de texto libre con reglas del analizador sintáctico; el analizador léxico voraz no respetará los límites que pretendes establecer y es muy probable que el modelo se salga de la distribución.

Usa reglas para combinar tokens discretos

Las reglas son ideales para combinar terminales delimitados explícitamente (números, palabras clave, signos de puntuación) en estructuras más grandes. No son la herramienta adecuada para restringir “lo que hay entre” dos terminales.

Mantén los terminales específicos, acotados y autocontenidos

Prioriza las clases de caracteres explícitas y los cuantificadores acotados ({0,10}, en lugar de usar * sin límites en todas partes). Si necesitas “cualquier texto hasta un punto”, usa algo como /[^.\n]{0,10}*\./ en lugar de /.+\./ para evitar un crecimiento descontrolado.

Usa reglas para combinar tokens, no para controlar el funcionamiento interno de las expresiones regulares

Ejemplo de uso adecuado de reglas:

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

Maneja los espacios en blanco de forma explícita

No dependas de directivas %ignore sin límites. Usar directivas de omisión sin límites puede hacer que la gramática sea demasiado compleja o que el modelo se salga de la distribución, o ambas cosas. Prefiere insertar terminales explícitos en cada lugar donde se permitan espacios en blanco.

Solución de problemas

Si la API rechaza la gramática porque es demasiado compleja, simplifica las reglas y los terminales y elimina las directivas %ignore sin límites.
Si se llama a las herramientas personalizadas con tokens inesperados, confirma que los terminales no se superpongan; revisa el comportamiento voraz del analizador léxico.
Cuando el modelo se desvía “fuera de la distribución” (esto se manifiesta en salidas excesivamente largas o repetitivas, sintácticamente válidas pero semánticamente incorrectas):
- Restringe más la gramática.
- Ajusta de forma iterativa el prompt (agrega unos pocos ejemplos) y la descripción de la herramienta (explica la gramática e indica al modelo que razone y se ajuste a ella).
- Prueba un mayor esfuerzo de razonamiento (por ejemplo, pasa de Media a Alta).

CFG con expresiones regulares

Ejemplo de gramática libre de contexto con expresiones regulares

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)

La salida de la herramienta debería ajustarse entonces a la CFG con expresiones regulares que definiste:

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

Al igual que con la sintaxis de Lark, las expresiones regulares usan la sintaxis del crate regex de Rust, no la del módulo re de Python.

Algunas funciones de las expresiones regulares no son compatibles:

Aserciones de anticipación y retrospección
Modificadores no voraces (*?, +?, ??)

Conceptos clave y prácticas recomendadas

El patrón debe estar en una sola línea

Si necesitas reconocer un salto de línea en la entrada, usa la secuencia de escape \n. No uses el modo detallado o extendido, que permite que los patrones abarquen varias líneas.

Proporciona la expresión regular como una cadena que contenga solo el patrón

No encierres el patrón entre //.

Sugerencias

Primeros pasos

Conceptos fundamentales

SDK y CLI

Recursos

API heredadas

Elige un modelo

Texto y código

Diseño de prompts

Razonamiento

Imágenes y video

Tiempo real y audio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Búsqueda y recuperación

Conecta herramientas y datos

Crea flujos de trabajo con herramientas

Computadora y código

Contenido multimedia

GPT-Live

Realtime API

Desarrollar con voz

Conexiones

Procesamiento de audio

Pasa a producción

Rendimiento y calidad

Costo y rendimiento

Seguridad y gobernanza

Infraestructura y acceso

Operaciones

Conceptos fundamentales

Plan

Build

Test and publish

Conversion specs

Guías

Recursos

Primeros pasos

Guías

File Upload

API

Measurement

Advertiser API

Referencia de la API

Primeros pasos

Fundamentos

Explorar

Disponible en

Versiones

Flujos de trabajo

Capacidades

Referencia

Personalización

Archivo de configuración

Configuración de agentes

Ampliar las capacidades de ChatGPT y Codex

Linux

Windows

Flujos de trabajo de desarrollo

Extender y automatizar

Entornos

Crear con Codex

Integraciones de terceros

Referencia

Permisos

Codex Security

Seguridad cibernética

Primeros pasos

ChatGPT Work

Identidad y autenticación

Acceso, políticas y modelos del espacio de trabajo

Controles de complementos y conectores

Uso, gobernanza y cumplimiento

Implementación y proveedores de modelos

Comunidad

Blog

Comunidad

Blog