Lista de verificación del despliegue de la API

Contenido	Impacto esperado
Usa la API Responses	Calidad, costo, latencia, confiabilidad
Elige un modelo GPT-5.6	Calidad, costo, latencia
Configura `reasoning.effort`	Calidad, costo, latencia
Configura `text.verbosity`	Calidad, costo, latencia
Configura el parámetro `phase` del asistente	Calidad, costo
Usa `tool_search`	Costo, latencia
Usa la llamada programática a herramientas	Calidad, costo, latencia
Usa Multiagente para trabajar en paralelo	Calidad, costo, latencia
Aprovecha las herramientas integradas	Calidad
Aprovecha la compactación	Costo
Optimiza el almacenamiento de prompts en caché	Latencia, costo
Usa `reasoning.encrypted_content`	Calidad, latencia
Elige el nivel de detalle de las imágenes de forma deliberada	Calidad, costo, latencia
Envía un identificador de seguridad	Seguridad, confiabilidad
Usa `background=True`	Reanudar el trabajo
Usa el modo WebSocket	Latencia

Usa la API Responses

Empieza siempre con la API Responses. Es la API insignia de OpenAI y la mejor opción para acceder a los comportamientos más recientes de los modelos, las herramientas integradas, los flujos de trabajo con estado y las funciones para agentes.

Elige un modelo GPT-5.6

Elige un modelo GPT-5.6 adecuado para la carga de trabajo en lugar de dirigir todas las solicitudes al nivel de mayor capacidad. Usa gpt-5.6 o gpt-5.6-sol para obtener las capacidades de un modelo insignia, gpt-5.6-terra para obtener un buen rendimiento a un precio menor y gpt-5.6-luna para procesar con eficiencia cargas de trabajo de gran volumen.

Al migrar, conserva la función del modelo actual en la carga de trabajo y su esfuerzo de razonamiento efectivo para la primera comparación. Ejecuta evaluaciones representativas antes de cambiar los prompts o agregar nuevas capacidades. Compara el éxito de las tareas, la latencia, los tokens de entrada, de salida, de razonamiento y de escritura en caché, y el costo por tarea completada con éxito.

Configura `reasoning.effort`

Usa reasoning.effort para decidir cuánto debe razonar el modelo antes de responder.

Para los modelos GPT-5.6, los valores admitidos son none, low, medium, high, xhigh y max. El valor predeterminado es medium. Un esfuerzo menor es más rápido y usa menos tokens de razonamiento. Un esfuerzo mayor le da al modelo más tiempo para planificar, depurar, sintetizar y evaluar ventajas y desventajas en varios pasos.

Usa low cuando la tarea consista principalmente en extracción, enrutamiento, clasificación o una reescritura rutinaria. Usa medium o high cuando el modelo necesite diagnosticar un problema, comparar opciones, elaborar un plan o razonar sobre código. Usa xhigh o max solo cuando las evaluaciones representativas demuestren que la mejora de calidad justifica la latencia y el costo adicionales. Al migrar desde GPT-5.5 o GPT-5.4, empieza con el esfuerzo actual y compara ese ajuste con uno de un nivel inferior. GPT-5.6 a menudo puede mantener o mejorar la calidad con menos tokens de razonamiento, por lo que el ajuste inferior también puede reducir la latencia y el costo.

Para las cargas de trabajo más difíciles que priorizan la calidad, compara también reasoning.mode: "pro" con el modo estándar al mismo nivel de esfuerzo. El modo y el esfuerzo de razonamiento son independientes. El modo Pro puede mejorar la confiabilidad al hacer que el modelo trabaje más antes de devolver una única respuesta final, pero aumenta la latencia y el uso de tokens.

Ajusta el esfuerzo de razonamiento según la tarea

Python

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

const openai = new OpenAI();

const prompt = [
  "Our CI job started failing after a dependency bump.",
  "",
  "Error:",
  "TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'",
  "",
  "Identify the likeliest root cause and the smallest safe fix.",
].join("\n");

const response = await openai.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "xhigh", mode: "pro" },
  input: prompt,
});

console.log(response.output_text);

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

client = OpenAI()

prompt = """
Our CI job started failing after a dependency bump.

Error:
TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'

Identify the likeliest root cause and the smallest safe fix.
"""

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "xhigh", "mode": "pro"},
    input=prompt,
)

print(response.output_text)

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

import (
	"context"
	"fmt"
	"strings"

	"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()
	prompt := strings.Join([]string{
		"Our CI job started failing after a dependency bump.",
		"",
		"Error:",
		"TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'",
		"",
		"Identify the likeliest root cause and the smallest safe fix.",
	}, "\n")
	reasoning := shared.ReasoningParam{Effort: shared.ReasoningEffortXhigh}
	reasoning.SetExtraFields(map[string]any{"mode": "pro"})
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-6-astra",
		Reasoning: reasoning,
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String(prompt)},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

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

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Our CI job started failing after a dependency bump. Error: TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'. Identify the likeliest root cause and the smallest safe fix.")
        .reasoning(
            Reasoning.builder()
                .effort(ReasoningEffort.XHIGH)
                .putAdditionalProperty("mode", JsonValue.from("pro"))
                .build())
        .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
22require "openai"

client = OpenAI::Client.new
prompt = <<~PROMPT
  Our CI job started failing after a dependency bump.

  Error:
  TypeError: Timeout.__init__() got an unexpected keyword argument 'connect'

  Identify the likeliest root cause and the smallest safe fix.
PROMPT

response = client.responses.create(
  model: "gpt-6-astra",
  reasoning: {
    effort: :xhigh,
    mode: :pro
  },
  input: prompt
)

puts(response.output_text)

Configura `text.verbosity`

text.verbosity es el principal control para equilibrar la brevedad y la exhaustividad. Usa un nivel de detalle menor cuando el producto necesite una respuesta rápida y compacta, y uno mayor cuando la respuesta requiera una explicación más amplia, una estructura más clara o todo el contexto. Un nivel de detalle menor implica menos tokens de salida, por lo que el modelo genera menos texto y devuelve el resultado más rápido.

Para programar, medium y high suelen producir resultados más extensos y organizados, con una estructura más clara. low mantiene la respuesta más concisa y reducida a lo esencial.

GPT-5.6 suele ser más conciso de forma predeterminada que GPT-5.5. Al migrar, verifica si las instrucciones generales como “Sé conciso” siguen siendo útiles. En algunos casos, pueden hacer que las respuestas sean demasiado breves. Consérvalas solo si siguen siendo útiles y prioriza el uso de text.verbosity para controlar el nivel de detalle predeterminado; luego usa el prompt para especificar el contenido requerido, la estructura y una extensión más concreta, si corresponde.

Configura un nivel de detalle menor para obtener resultados compactos

Python

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

const openai = new OpenAI();

const incident = [
  "Summarize this incident for the next on-call engineer.",
  "- checkout latency spiked from 220 ms to 4.8 s",
  "- only us-east-1 was affected",
  "- rollback is complete",
  "- likely trigger: cache stampede after deploy",
].join("\n");

const response = await openai.responses.create({
  model: "gpt-6-astra",
  text: { verbosity: "low" },
  input: incident,
});

console.log(response.output_text);

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

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    text={"verbosity": "low"},
    input="""
    Summarize this incident for the next on-call engineer.
    - checkout latency spiked from 220 ms to 4.8 s
    - only us-east-1 was affected
    - rollback is complete
    - likely trigger: cache stampede after deploy
    """,
)

print(response.output_text)

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

import (
	"context"
	"fmt"
	"strings"

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

func main() {
	client := openai.NewClient()
	incident := strings.Join([]string{
		"Summarize this incident for the next on-call engineer.",
		"- checkout latency spiked from 220 ms to 4.8 s",
		"- only us-east-1 was affected",
		"- rollback is complete",
		"- likely trigger: cache stampede after deploy",
	}, "\n")
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Text:  responses.ResponseTextConfigParam{Verbosity: "low"},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(incident)},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

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

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Summarize this incident for the next on-call engineer: checkout latency spiked from 220 ms to 4.8 s, only us-east-1 was affected, rollback is complete, and the likely trigger was a cache stampede.")
        .text(ResponseTextConfig.builder().verbosity(ResponseTextConfig.Verbosity.LOW).build())
        .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
18require "openai"

client = OpenAI::Client.new
incident = <<~INCIDENT
  Summarize this incident for the next on-call engineer.
  - checkout latency spiked from 220 ms to 4.8 s
  - only us-east-1 was affected
  - rollback is complete
  - likely trigger: cache stampede after deploy
INCIDENT

response = client.responses.create(
  model: "gpt-6-astra",
  text: { verbosity: :low },
  input: incident
)

puts(response.output_text)

Configura el parámetro `phase` del asistente

phase es una etiqueta de los mensajes del asistente en el historial de la conversación. Le indica al modelo si un mensaje anterior del asistente era un comentario intermedio sobre el trabajo en curso o la respuesta final. Usa phase: "commentary" para las actualizaciones de progreso, las notas previas a las llamadas a herramientas y otros mensajes intermedios. Usa phase: "final_answer" para la respuesta terminada.

El asistente podría decir algo como:

Mensaje de comentario del asistente

1
2
3
4
5{
  "role": "assistant",
  "phase": "commentary",
  "content": "I'm checking the logs and comparing them to the last successful deploy."
}

Esa no es la respuesta. Es una nota de progreso. Más adelante, el asistente podría decir:

Mensaje de respuesta final del asistente

1
2
3
4
5{
  "role": "assistant",
  "phase": "final_answer",
  "content": "The deploy failed because the migration referenced a column that does not exist in production."
}

Esto es útil en flujos de trabajo de larga duración o con uso intensivo de herramientas, donde el asistente puede mostrar actualizaciones de progreso antes de terminar. Cuando vuelvas a enviar ese historial en solicitudes de seguimiento a gpt-5.3-codex y modelos posteriores, conserva y reenvía phase en los mensajes del asistente para que el modelo pueda distinguir las actualizaciones de progreso del resultado final. Esto ayuda a reducir las interrupciones prematuras y aumenta la probabilidad de que el agente continúe hasta llegar a la respuesta final.

Usa `tool_search`

En lugar de cargar el catálogo completo de herramientas en cada solicitud, usa la búsqueda de herramientas: agrega {"type": "tool_search"} y marca las definiciones de herramientas costosas con defer_loading: true. Así, el modelo puede cargar el subconjunto que necesita en tiempo de ejecución. Al inicio de la solicitud, el modelo solo ve el nombre y la descripción de la herramienta de búsqueda. Si decide que necesita una herramienta de carga diferida, ejecuta la búsqueda de herramientas y, solo entonces, se cargan las definiciones de esas herramientas en el contexto. Solo a partir de ese momento el modelo las llama. Esto ahorra tokens y mantiene el rendimiento de la caché.

La búsqueda de herramientas tiene dos modos:

La búsqueda de herramientas alojada es la opción más sencilla. Úsala cuando ya sepas qué herramientas podrían estar disponibles para la solicitud.
La búsqueda de herramientas ejecutada por el cliente sirve para los casos en que tu aplicación debe decidir qué herramientas están disponibles, por ejemplo, según el tenant, el proyecto, los permisos o el registro interno del usuario.

Empieza con la búsqueda de herramientas alojada a menos que tu aplicación realmente necesite controlar por sí misma la detección de herramientas.

Agrupa tus herramientas según la intención del usuario. Usa espacios de nombres o servidores MCP cuando puedas. Al modelo le resulta más fácil elegir entre unos pocos grupos claros que entre una larga lista de funciones sin agrupar. Recomendamos mantener cada espacio de nombres por debajo de unas 10 funciones para optimizar el uso de tokens y el rendimiento del modelo.

Mantén las descripciones de los espacios de nombres breves y fáciles de distinguir entre sí. Coloca las instrucciones detalladas en las definiciones de las herramientas de carga diferida. Evita crear un único espacio de nombres enorme para todo.

Usa la búsqueda de herramientas alojada con herramientas de carga diferida

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
61import OpenAI from "openai";

const openai = new OpenAI();

const billingNamespace = {
  type: "namespace",
  name: "billing",
  description: "Billing tools for invoices, payments, taxes, and credits.",
  tools: [
    {
      type: "function",
      name: "lookup_invoice",
      description:
        "Look up invoice state, taxes, credits, and payment attempts.",
      parameters: {
        type: "object",
        properties: {
          invoice_id: { type: "string" },
        },
        required: ["invoice_id"],
        additionalProperties: false,
      },
      strict: true,
      defer_loading: true,
    },
  ],
};

const crmNamespace = {
  type: "namespace",
  name: "crm",
  description:
    "CRM tools for account ownership, plans, health, and payment history.",
  tools: [
    {
      type: "function",
      name: "get_account",
      description: "Fetch account owner, plan, health, and payment history.",
      parameters: {
        type: "object",
        properties: {
          account_id: { type: "string" },
        },
        required: ["account_id"],
        additionalProperties: false,
      },
      strict: true,
      defer_loading: true,
    },
  ],
};

const response = await openai.responses.create({
  model: "gpt-6-astra",
  input:
    "Find the right billing tool and explain why invoice INV-1043 still " +
    "shows overdue after a payment yesterday.",
  tools: [billingNamespace, crmNamespace, { type: "tool_search" }],
});

console.log(response.output);

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

client = OpenAI()

billing_namespace = {
    "type": "namespace",
    "name": "billing",
    "description": "Billing tools for invoices, payments, taxes, and credits.",
    "tools": [
        {
            "type": "function",
            "name": "lookup_invoice",
            "description": "Look up invoice state, taxes, credits, and payment attempts.",
            "parameters": {
                "type": "object",
                "properties": {
                    "invoice_id": {"type": "string"},
                },
                "required": ["invoice_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

crm_namespace = {
    "type": "namespace",
    "name": "crm",
    "description": "CRM tools for account ownership, plans, health, and payment history.",
    "tools": [
        {
            "type": "function",
            "name": "get_account",
            "description": "Fetch account owner, plan, health, and payment history.",
            "parameters": {
                "type": "object",
                "properties": {
                    "account_id": {"type": "string"},
                },
                "required": ["account_id"],
                "additionalProperties": False,
            },
            "strict": True,
            "defer_loading": True,
        }
    ],
}

response = client.responses.create(
    model="gpt-6-astra",
    input=(
        "Find the right billing tool and explain why invoice INV-1043 still "
        "shows overdue after a payment yesterday."
    ),
    tools=[billing_namespace, crm_namespace, {"type": "tool_search"}],
)

print(response.output)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58package main

import (
	"context"
	"fmt"

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

func main() {
	client := openai.NewClient()
	billing := namespaceTool(
		"billing",
		"Billing tools for invoices, payments, taxes, and credits.",
		"lookup_invoice",
		"Look up invoice state, taxes, credits, and payment attempts.",
		"invoice_id",
	)
	crm := namespaceTool(
		"crm",
		"CRM tools for account ownership, plans, health, and payment history.",
		"get_account",
		"Fetch account owner, plan, health, and payment history.",
		"account_id",
	)
	toolSearch := responses.ToolUnionParam{OfToolSearch: &responses.ToolSearchToolParam{}}
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(
			"Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.",
		)},
		Tools: []responses.ToolUnionParam{billing, crm, toolSearch},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

func namespaceTool(namespace, namespaceDescription, name, description, argument string) responses.ToolUnionParam {
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			argument: map[string]any{"type": "string"},
		},
		"required":             []string{argument},
		"additionalProperties": false,
	}
	function := responses.NamespaceToolToolFunctionParam{
		Name: name, Description: openai.String(description), Parameters: parameters, Strict: openai.Bool(true), DeferLoading: openai.Bool(true),
	}
	return responses.ToolParamOfNamespace(
		namespaceDescription,
		namespace,
		[]responses.NamespaceToolToolUnionParam{{OfFunction: &function}},
	)
}

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
62import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.NamespaceTool;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ToolSearchTool;
import java.util.List;
import java.util.Map;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.")
        .addTool(
            namespace(
                "billing",
                "Billing tools for invoices, payments, taxes, and credits.",
                "lookup_invoice",
                "Look up invoice state, taxes, credits, and payment attempts.",
                "invoice_id"))
        .addTool(
            namespace(
                "crm",
                "CRM tools for account ownership, plans, health, and payment history.",
                "get_account",
                "Fetch account owner, plan, health, and payment history.",
                "account_id"))
        .addTool(ToolSearchTool.builder().execution(ToolSearchTool.Execution.SERVER).build())
        .build();

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

private static NamespaceTool namespace(
    String name,
    String description,
    String function,
    String functionDescription,
    String argument) {
  return NamespaceTool.builder()
      .name(name)
      .description(description)
      .addTool(
          NamespaceTool.Tool.Function.builder()
              .name(function)
              .description(functionDescription)
              .deferLoading(true)
              .strict(true)
              .parameters(
                  JsonValue.from(
                      Map.of(
                          "type",
                          "object",
                          "properties",
                          Map.of(argument, Map.of("type", "string")),
                          "required",
                          List.of(argument),
                          "additionalProperties",
                          false)))
              .build())
      .build();
}

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"

def namespace_tool(name, description, function_name, function_description, argument)
  {
    type: :namespace,
    name: name,
    description: description,
    tools: [
      {
        type: :function,
        name: function_name,
        description: function_description,
        defer_loading: true,
        strict: true,
        parameters: {
          type: "object",
          properties: { argument => { type: "string" } },
          required: [argument],
          additionalProperties: false
        }
      }
    ]
  }
end

client = OpenAI::Client.new
billing = namespace_tool(
  "billing",
  "Billing tools for invoices, payments, taxes, and credits.",
  "lookup_invoice",
  "Look up invoice state, taxes, credits, and payment attempts.",
  "invoice_id"
)
crm = namespace_tool(
  "crm",
  "CRM tools for account ownership, plans, health, and payment history.",
  "get_account",
  "Fetch account owner, plan, health, and payment history.",
  "account_id"
)

response = client.responses.create(
  model: "gpt-6-astra",
  input: "Find the right billing tool and explain why invoice INV-1043 still shows overdue after a payment yesterday.",
  tools: [billing, crm, { type: :tool_search }]
)

puts(response.output)

Usa la llamada programática a herramientas

La llamada programática a herramientas permite que GPT-5.6 escriba JavaScript que llame a herramientas compatibles y reduzca sus resultados intermedios dentro de un entorno de ejecución alojado. Úsala en etapas acotadas en las que el código pueda filtrar, unir, ordenar, eliminar duplicados, combinar o verificar resultados extensos de herramientas antes de devolver al modelo un resultado estructurado más pequeño.

Agrega la herramienta programmatic_tool_calling y habilita cada herramienta compatible. Usa allowed_callers: ["programmatic"] para las herramientas que solo pueden llamarse desde programas, o usa allowed_callers: ["direct", "programmatic"] cuando el modelo también pueda llamar a la herramienta directamente. Mantén las llamadas directas cuando cada resultado pueda cambiar la siguiente decisión del modelo, una acción requiera aprobación o la respuesta final deba conservar citas o artefactos nativos. Documenta los campos que devuelven las herramientas y su comportamiento ante errores para que el modelo pueda escribir un programa correcto sin tener que inspeccionar primero un resultado.

Tu bucle de herramientas debe manejar los elementos program y program_output, así como los elementos function_call emitidos por el programa y sus elementos function_call_output. Conserva cada call_id y copia el valor de caller de la llamada a función en su salida para que el servicio pueda reanudar el programa correcto.

Prueba tanto program_output como el mensaje final del asistente. Un resultado correcto del programa puede aun así dar lugar a una respuesta final incompleta. Compara el éxito de la tarea, la evidencia requerida, el total de tokens, la latencia y el costo con los del mismo flujo de trabajo usando llamadas directas a herramientas.

Usa Multiagente para trabajar en paralelo

Multiagente es una función de GPT-5.6 que permite que un agente raíz delegue líneas de trabajo independientes a subagentes y sintetice sus resultados. Úsala cuando puedas dividir la investigación, el análisis o la implementación en tareas concretas y acotadas que usen contextos separados y se ejecuten en paralelo.

Establece multi_agent.enabled en true en la solicitud. Para HTTP, usa el SDK beta de Responses con client.beta.responses y pasa responses_multi_agent=v1 en betas. Para conexiones HTTP directas o WebSocket, envía OpenAI-Beta: responses_multi_agent=v1. Los esquemas de los elementos pueden cambiar mientras Multiagente esté en versión beta.

Prefiere un solo agente para tareas cortas, secuencias ordenadas en las que cada paso depende del anterior o trabajos que escriben en el mismo recurso mutable. Los subagentes pueden aumentar el uso de tokens, así que empieza con el valor predeterminado de max_concurrent_subagents, que es 3, y mide la calidad, la latencia y el costo de principio a fin. Para flujos de trabajo de Multiagente de larga duración o con uso intensivo de herramientas, el modo WebSocket puede reducir la sobrecarga de las continuaciones.

Antes de habilitar Multiagente, ten en cuenta sus limitaciones actuales: /responses/compact, reasoning.summary y max_tool_calls no se admiten. El servidor compacta automáticamente el contexto raíz y el contexto de cada subagente.

Aprovecha las herramientas integradas

Las herramientas integradas son capacidades nativas de la API. En lugar de crear cada herramienta por tu cuenta, puedes darle al modelo acceso a herramientas que ya funcionan dentro de la API Responses. Así, el modelo puede decidir cuándo usarlas.

OpenAI sigue agregando herramientas nativas, así que empieza con las herramientas integradas cuando se ajusten a tu flujo de trabajo. Crea herramientas personalizadas cuando las opciones nativas no cubran la tarea. Las herramientas integradas y las opciones relacionadas disponibles actualmente incluyen:

Búsqueda web: busca información actualizada en la web
Búsqueda de archivos: busca en archivos cargados o almacenes vectoriales
Intérprete de código: ejecuta Python para análisis, cálculos matemáticos, gráficos y procesamiento de archivos
Shell: ejecuta comandos de shell en un contenedor alojado o en tu propio entorno de ejecución
Uso de la computadora: opera una interfaz de usuario mediante capturas de pantalla, clics, escritura y desplazamiento
Generación de imágenes: genera o edita imágenes
MCP/conectores: conecta el modelo a servicios y herramientas externos
Habilidades: adjunta paquetes de instrucciones reutilizables y archivos de flujos de trabajo
Aplicar parches: realiza ediciones estructuradas de código

La calidad del modelo es otra razón para preferirlas. Las herramientas integradas forman parte de la distribución de datos de nuestro posentrenamiento, lo que significa que los modelos se entrenan y evalúan con los formatos, comportamientos y salidas de estas herramientas. Con las herramientas integradas, los modelos de OpenAI seleccionan mejor las herramientas, las ejecutan de forma más limpia y presentan menos fallos que con herramientas nuevas.

Aprovecha la compactación

La compactación es una herramienta de ingeniería de contexto: decide qué información conserva el modelo a lo largo de muchos turnos. En los agentes de larga duración, el problema no es solo “¿Alcanzaré el límite de contexto?”. También ocurre que los mensajes antiguos, los registros de herramientas, los reintentos y los detalles desactualizados desplazan el estado que el modelo necesita.

La compactación te permite reducir el tamaño del contexto de forma controlada y conservar el estado necesario para los turnos posteriores. Después de un hito significativo, como terminar una fase de depuración o acotar una causa raíz, puedes compactar la ventana anterior y continuar a partir de la salida compactada. Esto mantiene al modelo enfocado porque el siguiente turno se construye en torno al estado importante, no a cada razonamiento intermedio, comando fallido y línea de razonamiento obsoleta.

Puedes usar la compactación de dos maneras:

Deja que el servidor se encargue: si usas previous_response_id, activa context_management con un valor de compact_threshold. El servidor compactará automáticamente la conversación cuando sea demasiado grande. Tú sigues enviando solo el mensaje más reciente del usuario.
Hazlo por tu cuenta: si administras todo el arreglo de entrada, llama a client.responses.compact(). Devuelve una ventana de contexto más pequeña. Usa esa salida directamente en la siguiente llamada a responses.create().

No edites la salida compactada. No es un resumen para personas, sino el estado de la máquina que ayuda al modelo a continuar. Pásala tal como está y luego agrega el siguiente mensaje del usuario.

Continúa a partir del estado compactado de la respuesta

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
31import OpenAI from "openai";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

const openai = new OpenAI();

// Full window collected from a long debugging session:
// user messages, assistant outputs, tool calls, and tool outputs.
const longWindow = sessionItems;

const compacted = await openai.responses.compact({
  model: "gpt-6-astra",
  input: longWindow,
});

const nextResponse = await openai.responses.create({
  model: "gpt-6-astra",
  store: false,
  input: [
    // Preserve replayable compacted items.
    ...toResponseInputItems(compacted.output),
    {
      type: "message",
      role: "user",
      content:
        "We found the bad cache invalidation path. Write the fix plan " +
        "and the verification checklist.",
    },
  ],
});

console.log(nextResponse.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
30from openai import OpenAI

client = OpenAI()

# Full window collected from a long debugging session:
# user messages, assistant outputs, tool calls, and tool outputs.
long_window = session_items

compacted = client.responses.compact(
    model="gpt-6-astra",
    input=long_window,
)

next_response = client.responses.create(
    model="gpt-6-astra",
    store=False,
    input=[
        *compacted.output,  # Use compact output as-is.
        {
            "type": "message",
            "role": "user",
            "content": (
                "We found the bad cache invalidation path. Write the fix plan "
                "and the verification checklist."
            ),
        },
    ],
)

print(next_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
51package main

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

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

func main() {
	client := openai.NewClient()
	longWindow := []responses.ResponseInputItemUnionParam{
		responses.ResponseInputItemParamOfMessage("Find the cache invalidation bug in this debugging session.", responses.EasyInputMessageRoleUser),
	}
	compacted, err := client.Responses.Compact(context.Background(), responses.ResponseCompactParams{
		Model: "gpt-6-astra",
		Input: responses.ResponseCompactParamsInputUnion{OfResponseInputItemArray: longWindow},
	})
	if err != nil {
		panic(err)
	}
	input := append(outputAsInput(compacted.Output),
		responses.ResponseInputItemParamOfMessage(
			"We found the bad cache invalidation path. Write the fix plan and the verification checklist.",
			responses.EasyInputMessageRoleUser,
		),
	)
	nextResponse, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Store: openai.Bool(false),
		Input: responses.ResponseNewParamsInputUnion{OfInputItemList: input},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(nextResponse.OutputText())
}

func outputAsInput(output []responses.ResponseOutputItemUnion) []responses.ResponseInputItemUnionParam {
	input := make([]responses.ResponseInputItemUnionParam, 0, len(output))
	for _, item := range output {
		var converted responses.ResponseInputItemUnion
		if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
			panic(err)
		}
		input = append(input, converted.ToParam())
	}
	return input
}

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
53import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseCompactParams;
import com.openai.models.responses.ResponseCompactionItemParam;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseInputItem;
import java.util.ArrayList;

var compacted =
    client
        .responses()
        .compact(
            ResponseCompactParams.builder()
                .model("gpt-6-astra")
                .input("Find the cache invalidation bug in this debugging session.")
                .build());
var input = new ArrayList<ResponseInputItem>();
for (var item : compacted.output()) {
  item.message().map(ResponseInputItem::ofResponseOutputMessage).ifPresent(input::add);
  item.reasoning().map(ResponseInputItem::ofReasoning).ifPresent(input::add);
  item.compaction()
      .map(
          value ->
              ResponseInputItem.ofCompaction(
                  ResponseCompactionItemParam.builder()
                      .id(value.id())
                      .encryptedContent(value.encryptedContent())
                      .build()))
      .ifPresent(input::add);
}
input.add(
    ResponseInputItem.ofEasyInputMessage(
        EasyInputMessage.builder()
            .role(EasyInputMessage.Role.USER)
            .content(
                "We found the bad cache invalidation path. Write the fix plan and the verification checklist.")
            .build()));

client
    .responses()
    .create(
        ResponseCreateParams.builder()
            .model("gpt-6-astra")
            .inputOfResponse(input)
            .store(false)
            .build())
    .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
27require "openai"

client = OpenAI::Client.new
long_window = [
  {
    role: :user,
    content: "Find the cache invalidation bug in this debugging session."
  }
]

compacted = client.responses.compact(
  model: "gpt-6-astra",
  input: long_window
)
input = compacted.output.dup
input << {
  role: :user,
  content: "We found the bad cache invalidation path. Write the fix plan and the verification checklist."
}

response = client.responses.create(
  model: "gpt-6-astra",
  store: false,
  input: input
)

puts(response.output_text)

Optimiza el almacenamiento de prompts en caché

El almacenamiento de prompts en caché reduce automáticamente la latencia y el costo cuando las solicitudes reutilizan el mismo prefijo largo. Coloca primero las instrucciones, los ejemplos y el material de referencia que no cambian, seguidos del contenido dinámico específico del usuario. Mantén estables las definiciones de herramientas y su orden, y agrega nuevos turnos de conversación sin reescribir el contexto anterior.

GPT-5.6 introdujo el almacenamiento explícito de prompts en caché. El almacenamiento implícito sigue siendo la opción predeterminada, pero los modelos GPT-5.6 y las familias de modelos posteriores también admiten puntos de corte explícitos de caché y una política de caché para toda la solicitud. Si un sufijo que cambia aparece después de un prefijo estable, agrega un prompt_cache_breakpoint explícito al final de la parte reutilizable. Establece prompt_cache_options.mode en explicit solo cuando la solicitud deba usar únicamente los puntos de corte que proporciones y ninguno implícito. Los modelos anteriores siguen usando únicamente el almacenamiento automático de prompts en caché.

En los modelos GPT-5.6 y las familias de modelos posteriores, las escrituras en caché cuestan 1,25× la tarifa de los tokens de entrada sin caché. Registra cached_tokens y cache_write_tokens, y luego compara el volumen de escritura con las lecturas posteriores de caché para medir el costo neto y ajustar la ubicación de los puntos de corte.

Usa un valor estable de prompt_cache_key para las solicitudes que compartan un prefijo reutilizable para ayudar a dirigir las solicitudes relacionadas a la misma caché y optimizar las tasas de aciertos de caché en modelos anteriores a GPT-5.6. Para los grupos con mucho tráfico, sigue las recomendaciones para distribuir el tráfico entre más claves.

En GPT-5.6 y versiones posteriores, prompt_cache_key es opcional: puedes lograr tasas óptimas de aciertos de caché sin usarlo. Puedes usarlo para llevar una contabilidad de caché separada por cliente, usuario o espacio de trabajo. Esto puede facilitar la explicación del uso de tokens en caché y la facturación para cada grupo. Asigna una clave distinta a cada cliente y mantenla estable en todas las solicitudes relacionadas de ese cliente. Las claves separadas también ayudan a evitar sondeos de aciertos de caché entre clientes. Consulta Contabilidad de caché separada mediante claves.

Lleva una contabilidad de caché separada para un cliente

Python

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

const openai = new OpenAI();

const instructions = [
  "You are the support agent for Acme.",
  "Follow the Acme support policy and escalation rubric.",
  "Use the same tone, safety rules, and tool plan for each ticket.",
].join("\n");

const response = await openai.responses.create({
  model: "gpt-6-astra",
  prompt_cache_key: "tenant-acme-support-agent",
  instructions,
  input: "Summarize the current escalation for the on-call lead.",
});

console.log(response.output_text);

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

client = OpenAI()

instructions = """
You are the support agent for Acme.
Follow the Acme support policy and escalation rubric.
Use the same tone, safety rules, and tool plan for each ticket.
"""

response = client.responses.create(
    model="gpt-6-astra",
    prompt_cache_key="tenant-acme-support-agent",
    instructions=instructions,
    input="Summarize the current escalation for the on-call lead.",
)

print(response.output_text)

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

import (
	"context"
	"fmt"
	"strings"

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

func main() {
	client := openai.NewClient()
	instructions := strings.Join([]string{
		"You are the support agent for Acme.",
		"Follow the Acme support policy and escalation rubric.",
		"Use the same tone, safety rules, and tool plan for each ticket.",
	}, "\n")
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:          "gpt-6-astra",
		PromptCacheKey: openai.String("tenant-acme-support-agent"),
		Instructions:   openai.String(instructions),
		Input:          responses.ResponseNewParamsInputUnion{OfString: openai.String("Summarize the current escalation for the on-call lead.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

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

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .instructions(
            "You are the support agent for Acme.\n"
                + "Follow the Acme support policy and escalation rubric.\n"
                + "Use the same tone, safety rules, and tool plan for each ticket.")
        .input("Summarize the current escalation for the on-call lead.")
        .promptCacheKey("tenant-acme-support-agent")
        .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
18using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new()
{
    Model = "gpt-6-astra",
    PromptCacheKey = "tenant-acme-support-agent",
    Instructions = "Follow the Acme support policy and escalation rubric.",
};
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("Summarize the current escalation for the on-call lead.")
);

ResponseResult response = await client.CreateResponseAsync(options);
Console.WriteLine(response.GetOutputText());

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

client = OpenAI::Client.new
instructions = <<~INSTRUCTIONS
  You are the support agent for Acme.
  Follow the Acme support policy and escalation rubric.
  Use the same tone, safety rules, and tool plan for each ticket.
INSTRUCTIONS

response = client.responses.create(
  model: "gpt-6-astra",
  prompt_cache_key: "tenant-acme-support-agent",
  instructions: instructions,
  input: "Summarize the current escalation for the on-call lead."
)

puts(response.output_text)

Usa `reasoning.encrypted_content`

GPT-5.6 puede conservar el razonamiento entre llamadas. Usa reasoning.context: "all_turns" cuando los objetivos, los supuestos y las prioridades de la tarea se mantengan estables. Usa current_turn cuando el razonamiento anterior ya no sea relevante y pueda aferrar al modelo a un enfoque desactualizado. Si omites reasoning.context o lo estableces en auto, inspecciona el campo reasoning.context de la respuesta para confirmar el modo efectivo.

El razonamiento persistente solo funciona cuando los elementos de razonamiento anteriores están disponibles. Usa previous_response_id para las respuestas almacenadas. Si tus requisitos de retención cero de datos (ZDR) no permiten almacenar datos de respuesta, el contenido de razonamiento cifrado permite transferirlos sin mantener estado.

Los elementos de razonamiento en la salida de la respuesta incluyen contenido de razonamiento cifrado de forma predeterminada. Puedes acceder a ese contenido mediante la propiedad encrypted_content de cada elemento de razonamiento. Tu aplicación no necesita interpretar ese valor. Solo conserva cada elemento de razonamiento exactamente como se devuelve y lo reenvía en el siguiente turno, para que el modelo pueda usarlo y continuar el flujo de trabajo.

Pasa el razonamiento cifrado entre turnos sin estado

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";
import { toResponseInputItems } from "openai/lib/responses/ResponseInputItems";

const openai = new OpenAI();

const history = [
  {
    role: "user",
    content: "Investigate why invoice INV-1043 has mismatched tax totals.",
  },
];

const first = await openai.responses.create({
  model: "gpt-6-astra",
  store: false,
  reasoning: { effort: "medium", context: "current_turn" },
  input: history,
});

history.push(...toResponseInputItems(first.output));
history.push({
  role: "user",
  content: "Now write the customer-facing explanation in plain English.",
});

const second = await openai.responses.create({
  model: "gpt-6-astra",
  store: false,
  reasoning: { effort: "medium", context: "all_turns" },
  input: history,
});

console.log(second.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
34from openai import OpenAI

client = OpenAI()

history = [
    {
        "role": "user",
        "content": "Investigate why invoice INV-1043 has mismatched tax totals.",
    }
]

first = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "current_turn"},
    input=history,
)

history.extend(item.model_dump(exclude={"status"}) for item in first.output)
history.append(
    {
        "role": "user",
        "content": "Now write the customer-facing explanation in plain English.",
    }
)

second = client.responses.create(
    model="gpt-6-astra",
    store=False,
    reasoning={"effort": "medium", "context": "all_turns"},
    input=history,
)

print(second.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
55package main

import (
	"context"
	"encoding/json"
	"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()
	history := []responses.ResponseInputItemUnionParam{
		responses.ResponseInputItemParamOfMessage("Investigate why invoice INV-1043 has mismatched tax totals.", responses.EasyInputMessageRoleUser),
	}
	first, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-6-astra",
		Store:     openai.Bool(false),
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortMedium, Context: shared.ReasoningContextCurrentTurn},
		Include:   []responses.ResponseIncludable{responses.ResponseIncludableReasoningEncryptedContent},
		Input:     responses.ResponseNewParamsInputUnion{OfInputItemList: history},
	})
	if err != nil {
		panic(err)
	}
	history = append(history, outputAsInput(first.Output)...)
	history = append(history, responses.ResponseInputItemParamOfMessage(
		"Now write the customer-facing explanation in plain English.",
		responses.EasyInputMessageRoleUser,
	))
	second, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-6-astra",
		Store:     openai.Bool(false),
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortMedium, Context: shared.ReasoningContextAllTurns},
		Input:     responses.ResponseNewParamsInputUnion{OfInputItemList: history},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(second.OutputText())
}

func outputAsInput(output []responses.ResponseOutputItemUnion) []responses.ResponseInputItemUnionParam {
	input := make([]responses.ResponseInputItemUnionParam, 0, len(output))
	for _, item := range output {
		var converted responses.ResponseInputItemUnion
		if err := json.Unmarshal([]byte(item.RawJSON()), &converted); err != nil {
			panic(err)
		}
		input = append(input, converted.ToParam())
	}
	return input
}

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
62import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.Reasoning;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseIncludable;
import com.openai.models.responses.ResponseInputItem;
import java.util.ArrayList;

var history = new ArrayList<ResponseInputItem>();
history.add(
    ResponseInputItem.ofEasyInputMessage(
        EasyInputMessage.builder()
            .role(EasyInputMessage.Role.USER)
            .content("Investigate why invoice INV-1043 has mismatched tax totals.")
            .build()));

var first =
    client
        .responses()
        .create(
            ResponseCreateParams.builder()
                .model("gpt-6-astra")
                .inputOfResponse(history)
                .store(false)
                .reasoning(
                    Reasoning.builder()
                        .effort(com.openai.models.ReasoningEffort.MEDIUM)
                        .putAdditionalProperty("context", JsonValue.from("current_turn"))
                        .build())
                .addInclude(ResponseIncludable.of("reasoning.encrypted_content"))
                .build());
first.output().stream()
    .map(item -> JsonValue.from(item).convert(ResponseInputItem.class))
    .forEach(history::add);
history.add(
    ResponseInputItem.ofEasyInputMessage(
        EasyInputMessage.builder()
            .role(EasyInputMessage.Role.USER)
            .content("Now write the customer-facing explanation in plain English.")
            .build()));

client
    .responses()
    .create(
        ResponseCreateParams.builder()
            .model("gpt-6-astra")
            .inputOfResponse(history)
            .store(false)
            .reasoning(
                Reasoning.builder()
                    .effort(com.openai.models.ReasoningEffort.MEDIUM)
                    .putAdditionalProperty("context", JsonValue.from("all_turns"))
                    .build())
            .build())
    .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
37require "openai"

client = OpenAI::Client.new
history = [
  {
    role: :user,
    content: "Investigate why invoice INV-1043 has mismatched tax totals."
  }
]

first = client.responses.create(
  model: "gpt-6-astra",
  store: false,
  reasoning: {
    effort: :medium,
    context: :current_turn
  },
  include: ["reasoning.encrypted_content"],
  input: history
)
history.concat(first.output)
history << {
  role: :user,
  content: "Now write the customer-facing explanation in plain English."
}

second = client.responses.create(
  model: "gpt-6-astra",
  store: false,
  reasoning: {
    effort: :medium,
    context: :all_turns
  },
  input: history
)

puts(second.output_text)

Elige el nivel de detalle de las imágenes de forma deliberada

En los modelos GPT-5.6, omitir detail de la imagen o usar detail: "auto" produce el mismo comportamiento de dimensionamiento que original. El servicio conserva las dimensiones de entrada, excepto cuando las imágenes superan los 65 535 píxeles en cualquiera de sus lados: en ese caso, las reduce para ajustarlas a ese límite. La API rechaza las imágenes que aún superan el límite de 30 000 parches, en lugar de redimensionarlas para ajustarlas. Las imágenes grandes pueden consumir más tokens de entrada y, como resultado, aumentar la latencia.

Elige detail según la tarea. Redimensiona la imagen, usa low cuando los detalles visuales finos no sean importantes o usa high para una comprensión de imágenes estándar de alta fidelidad. Reserva original para tareas con imágenes grandes o con mucha información, sensibles a las coordenadas, de OCR, de localización o de inspección visual en las que el detalle adicional mejore la calidad. Mide el consumo de tokens de imagen y la latencia en el peor de los casos antes del despliegue.

Envía un identificador de seguridad

Si tu aplicación atiende a usuarios finales individuales, envía en cada solicitud un identificador safety_identifier estable que preserve la privacidad. Ayuda a OpenAI a detectar usos indebidos y le ofrece a tu equipo una forma estable de rastrear infracciones de las políticas. También reduce la probabilidad de que el uso indebido por parte de un usuario interrumpa el acceso del resto de tu organización.

Aplica una función hash al nombre de usuario o a la dirección de correo electrónico del usuario en lugar de enviar información que permita identificarlo. Para experiencias sin inicio de sesión, usa un ID de sesión estable.

Usa `background=True`

Usa background=True para solicitudes que puedan tardar mucho tiempo. En lugar de mantener abierta la conexión del cliente, la API inicia una tarea y devuelve un ID. Tu aplicación puede consultar periódicamente esa tarea hasta que termine, falle o se cancele. Úsalo para análisis de gran escala, ejecuciones prolongadas de herramientas o trabajos que necesiten seguimiento del estado y reintentos.

Ejecuta una respuesta en segundo plano y consulta su estado periódicamente

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// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";

const openai = new OpenAI();
const logBundleFileId = "file_123";

let job = await openai.responses.create({
  model: "gpt-6-astra",
  background: true,
  store: false,
  input: "Analyze this large log bundle and cluster the primary failure modes.",
  tools: [
    {
      type: "code_interpreter",
      container: {
        type: "auto",
        file_ids: [logBundleFileId],
      },
    },
  ],
});

while (["queued", "in_progress"].includes(job.status)) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  job = await openai.responses.retrieve(job.id);
}

console.log(job.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# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
import time

client = OpenAI()
log_bundle_file_id = "file_123"

job = client.responses.create(
    model="gpt-6-astra",
    background=True,
    store=False,
    input="Analyze this large log bundle and cluster the primary failure modes.",
    tools=[
        {
            "type": "code_interpreter",
            "container": {
                "type": "auto",
                "file_ids": [log_bundle_file_id],
            },
        }
    ],
)

while job.status in {"queued", "in_progress"}:
    time.sleep(2)
    job = client.responses.retrieve(job.id)

print(job.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
35package main

import (
	"context"
	"fmt"
	"time"

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

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfCodeInterpreter(responses.ToolCodeInterpreterContainerCodeInterpreterContainerAutoParam{
		FileIDs: []string{"file_abc123"},
	})
	job, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:      "gpt-6-astra",
		Background: openai.Bool(true),
		Store:      openai.Bool(false),
		Input:      responses.ResponseNewParamsInputUnion{OfString: openai.String("Analyze this large log bundle and cluster the primary failure modes.")},
		Tools:      []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}
	for job.Status == responses.ResponseStatusQueued || job.Status == responses.ResponseStatusInProgress {
		time.Sleep(2 * time.Second)
		job, err = client.Responses.Get(context.Background(), job.ID, responses.ResponseGetParams{})
		if err != nil {
			panic(err)
		}
	}
	fmt.Println(job.OutputText())
}

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.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseStatus;
import com.openai.models.responses.Tool;

String fileId = "file_abc123";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Analyze this large log bundle and cluster the primary failure modes.")
        .background(true)
        .store(false)
        .addCodeInterpreterTool(
            Tool.CodeInterpreter.Container.CodeInterpreterToolAuto.builder()
                .addFileId(fileId)
                .build())
        .build();

var response = client.responses().create(params);
while (response.status().filter(ResponseStatus.QUEUED::equals).isPresent()
    || response.status().filter(ResponseStatus.IN_PROGRESS::equals).isPresent()) {
  Thread.sleep(1000);
  response = client.responses().retrieve(response.id());
}
if (response.status().filter(ResponseStatus.COMPLETED::equals).isEmpty()) {
  throw new IllegalStateException(
      "Research ended with status: " + response.status().orElseThrow());
}

response.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
26require "openai"

client = OpenAI::Client.new

job = client.responses.create(
  model: "gpt-6-astra",
  background: true,
  store: false,
  input: "Analyze this large log bundle and cluster the primary failure modes.",
  tools: [
    {
      type: :code_interpreter,
      container: {
        type: :auto,
        file_ids: ["file_abc123"]
      }
    }
  ]
)

while [:queued, :in_progress].include?(job.status)
  sleep(2)
  job = client.responses.retrieve(job.id)
end

puts(job.output_text)

Puedes combinarlo con stream=True para recibir eventos de progreso, pero el primer evento puede tardar más que en una solicitud normal.

Desde la perspectiva de la interfaz, el modo en segundo plano indica: “Esto está en ejecución; este es el estado; el resultado aparecerá aquí cuando esté listo”.

Usa el modo WebSocket

El modo WebSocket está diseñado para flujos de trabajo de larga duración con muchas llamadas a herramientas, en los que mantienes abierta una conexión persistente y continúas enviando solo los nuevos elementos de entrada junto con previous_response_id. Para ejecuciones con 20 o más llamadas a herramientas, este enfoque es aproximadamente un 40 % más rápido de principio a fin.

Cómo funciona: el primer mensaje se verá como una solicitud normal de Responses: modelo, instrucciones, herramientas y entrada del usuario. El servidor devuelve eventos en streaming. Si el modelo solicita una herramienta, tu aplicación la ejecuta. Luego, en lugar de enviar una nueva solicitud HTTP, envías otro evento response.create por el mismo socket con el previous_response_id anterior y el nuevo elemento. De ahí proviene la reducción de latencia. Con HTTP convencional, cada interacción posterior es una solicitud nueva. En el modo WebSocket, la conexión permanece abierta y el estado de la respuesta más reciente se mantiene listo en la memoria de esa conexión. Cuando el siguiente turno continúa a partir de esa respuesta, el backend necesita menos trabajo de preparación.

Si tu flujo de trabajo consiste en una solicitud y una respuesta, sigue usando HTTP. Si tu flujo de trabajo se comporta como un agente de larga duración, prueba el modo WebSocket.

Una sola conexión WebSocket maneja una respuesta en curso a la vez, por lo que el trabajo en paralelo requiere varias conexiones. Actualmente, las conexiones tienen una duración máxima de 60 minutos. La continuación usa la misma semántica de previous_response_id que el modo HTTP, con una caché local de la conexión para la respuesta más reciente.

Nota: el modo WebSocket funciona con ZDR porque tus datos no se almacenan en disco, sino únicamente en memoria.

El ejemplo de Python usa pip install "openai[realtime]>=3.8.0". El ejemplo de JavaScript usa npm install openai@^7.10.0 ws. El ejemplo de Ruby usa gem install openai async-websocket.

Inicia una sesión WebSocket de la API Responses

Python

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

const openai = new OpenAI();

const ws = new ResponsesWS(openai);

ws.on("event", (event) => {
  console.log(event.type);
  if (
    event.type === "response.completed" ||
    event.type === "response.failed" ||
    event.type === "response.incomplete"
  ) {
    ws.close();
  }
});
ws.on("error", (error) => {
  console.error(error);
  ws.close();
});

ws.send({
  type: "response.create",
  model: "gpt-6-astra",
  store: false,
  input: [
    {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text:
            "Find the flaky test in this run, call the tools you need, " +
            "and keep going until you can explain the root cause.",
        },
      ],
    },
  ],
  tools: [testLogTool, codeSearchTool],
});

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
29from openai import OpenAI

client = OpenAI()

with client.responses.connect() as connection:
    # Use the same typed parameters as client.responses.create(...).
    connection.response.create(
        model="gpt-6-astra",
        store=False,
        input=[
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Find the flaky test in this run, call the tools "
                            "you need, and keep going until you can explain "
                            "the root cause."
                        ),
                    }
                ],
            }
        ],
        tools=[test_log_tool, code_search_tool],
    )
    first_event = connection.recv()
    print(first_event.type)

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
58require "async"
require "openai"
require "json"

def wait_for_response(connection)
  while (event = connection.receive)
    case event.type.to_s
    when "response.completed" then return event.response
    when "response.failed", "response.incomplete", "error"
      raise "Response failed: #{event.to_json}"
    end
  end
  raise "Connection closed before the response finished"
end

test_log_tool = {
  type: "function",
  name: "search_test_logs",
  description: "Search test logs.",
  parameters: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
    additionalProperties: false
  },
  strict: true
}
code_search_tool = {
  type: "function",
  name: "search_code",
  description: "Search source code.",
  parameters: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
    additionalProperties: false
  },
  strict: true
}

client = OpenAI::Client.new
Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      connection.response.create(
        stream_id: "main", model: "gpt-6-astra", store: false,
        input: [
          {
            role: "user",
            content: "Find the flaky test in this run, call the tools you need, and keep going until you can explain the root cause."
          }
        ],
        tools: [test_log_tool, code_search_tool]
      )
      puts(JSON.pretty_generate(wait_for_response(connection).output.map(&:to_h)))
    end
  end
end

Conclusión

La API Responses es la base para crear aplicaciones de OpenAI más inteligentes y con mayores capacidades. Su principal ventaja es que permite a los desarrolladores pasar de prompts puntuales a flujos de trabajo persistentes que usan herramientas, tienen en cuenta el contexto y se adaptan a la complejidad de la tarea. Sigue esta guía para mejorar el rendimiento en despliegues reales.

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

Configura `reasoning.effort`

Configura `text.verbosity`

Configura el parámetro `phase` del asistente

Usa `tool_search`

Usa `reasoning.encrypted_content`

Usa `background=True`