Lista de verificação de implantação da API

Conteúdo	Impacto esperado
Use a API Responses	Qualidade, custo, latência, confiabilidade
Escolha um modelo GPT-5.6	Qualidade, custo, latência
Configure `reasoning.effort`	Qualidade, custo, latência
Configure `text.verbosity`	Qualidade, custo, latência
Configure o parâmetro `phase` do assistente	Qualidade, custo
Use `tool_search`	Custo, latência
Use a chamada programática de ferramentas	Qualidade, custo, latência
Use múltiplos agentes para trabalhar em paralelo	Qualidade, custo, latência
Aproveite as ferramentas integradas	Qualidade
Aproveite a compactação	Custo
Otimize o cache de prompts	Latência, custo
Use `reasoning.encrypted_content`	Qualidade, latência
Escolha o nível de detalhe das imagens com critério	Qualidade, custo, latência
Envie um identificador de segurança	Segurança, confiabilidade
Use `background=True`	Retomada do trabalho
Use o modo WebSocket	Latência

Use a API Responses

Comece sempre pela API Responses. Ela é a principal API da OpenAI e o melhor lugar para acessar os comportamentos mais recentes dos modelos, ferramentas integradas, fluxos de trabalho com estado e recursos de agentes.

Escolha um modelo GPT-5.6

Escolha um modelo GPT-5.6 adequado à carga de trabalho em vez de encaminhar todas as solicitações ao nível mais capaz. Use gpt-5.6 ou gpt-5.6-sol para obter a capacidade dos modelos principais, gpt-5.6-terra para um ótimo desempenho a um preço menor e gpt-5.6-luna para processar cargas de trabalho de alto volume com eficiência.

Ao migrar, preserve o papel do modelo atual na carga de trabalho e o esforço de raciocínio efetivo na primeira comparação. Execute avaliações representativas antes de alterar prompts ou adicionar novas capacidades. Compare o sucesso nas tarefas, a latência, os tokens de entrada, saída, raciocínio e gravação em cache e o custo por tarefa concluída com sucesso.

Configure `reasoning.effort`

Use reasoning.effort para definir quanto o modelo deve raciocinar antes de responder.

Para os modelos GPT-5.6, os valores aceitos são none, low, medium, high, xhigh e max. O padrão é medium. Um esforço menor é mais rápido e usa menos tokens de raciocínio. Um esforço maior dá ao modelo mais tempo para planejamento, depuração, síntese e ponderação de vantagens e desvantagens em várias etapas.

Use low quando a tarefa envolver principalmente extração, roteamento, classificação ou uma reescrita rotineira. Use medium ou high quando o modelo precisar diagnosticar um problema, comparar opções, elaborar um plano ou raciocinar sobre código. Use xhigh ou max somente quando avaliações representativas mostrarem que o ganho de qualidade justifica a latência e o custo adicionais. Ao migrar do GPT-5.5 ou GPT-5.4, comece com o esforço atual e compare essa configuração com um nível abaixo. O GPT-5.6 muitas vezes consegue manter ou melhorar a qualidade com menos tokens de raciocínio, então a configuração de menor esforço também pode reduzir a latência e o custo.

Para as cargas de trabalho mais difíceis que priorizam a qualidade, compare também reasoning.mode: "pro" com o modo padrão no mesmo nível de esforço. O modo e o esforço de raciocínio são independentes. O modo Pro pode melhorar a confiabilidade ao fazer o modelo trabalhar mais antes de retornar uma única resposta final, mas aumenta a latência e o uso de tokens.

Ajuste o esforço de raciocínio à tarefa

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)

Configure `text.verbosity`

text.verbosity é o principal controle para equilibrar concisão e completude. Use um nível de detalhamento menor quando o produto precisar de uma resposta rápida e compacta, e um nível maior quando a resposta precisar de uma explicação mais detalhada, uma estrutura mais clara ou contexto completo. Menos detalhamento significa menos tokens de saída, então o modelo gera menos conteúdo e retorna a saída mais rápido.

Para programação, medium e high tendem a produzir saídas mais longas e organizadas, com uma estrutura mais clara. low mantém a resposta mais enxuta e restrita ao essencial.

O GPT-5.6 tende a ser mais conciso por padrão do que o GPT-5.5. Ao migrar, verifique se instruções genéricas como "Seja conciso" ainda ajudam. Em alguns casos, elas podem deixar as respostas breves demais. Mantenha essas instruções apenas quando ainda ajudarem e prefira usar text.verbosity para controlar o nível de detalhamento padrão; depois, use o prompt para especificar o conteúdo obrigatório, a estrutura e uma extensão mais específica, se aplicável.

Defina um nível de detalhamento menor para obter saídas compactas

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)

Configure o parâmetro `phase` do assistente

phase é um rótulo nas mensagens do assistente no histórico da conversa. Ele indica ao modelo se uma mensagem anterior do assistente era um comentário intermediário sobre o trabalho em andamento ou a resposta final. Use phase: "commentary" para atualizações de progresso, observações antes de chamadas de ferramentas e outras mensagens intermediárias. Use phase: "final_answer" para a resposta concluída.

O assistente pode dizer algo como:

Mensagem de comentário do assistente

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

Essa não é a resposta. É uma atualização de progresso. Mais tarde, o assistente pode dizer:

Mensagem de resposta final do assistente

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

Isso é útil em fluxos de trabalho de longa duração ou com uso intensivo de ferramentas, nos quais o assistente pode gerar atualizações visíveis de progresso antes de terminar. Ao reenviar esse histórico em solicitações subsequentes para gpt-5.3-codex e modelos posteriores, preserve e reenvie phase nas mensagens do assistente para que o modelo possa distinguir as atualizações de progresso do resultado final. Isso ajuda a reduzir o encerramento prematuro, aumentando a probabilidade de o agente continuar até chegar à resposta final.

Use `tool_search`

Em vez de carregar o catálogo completo de ferramentas em cada solicitação, use a pesquisa de ferramentas: adicione {"type": "tool_search"} e marque as definições de ferramentas de alto custo com defer_loading: true. Assim, o modelo pode carregar apenas o subconjunto necessário durante a execução. No início da solicitação, o modelo vê apenas o nome e a descrição da ferramenta de pesquisa. Se decidir que precisa de uma ferramenta com carregamento adiado, ele executa a pesquisa de ferramentas, e só então as definições dessas ferramentas são carregadas no contexto. Somente depois disso o modelo as chama. Isso economiza tokens e preserva o desempenho do cache.

A pesquisa de ferramentas tem dois modos:

A pesquisa de ferramentas hospedada é a opção mais simples. Use-a quando você já souber quais ferramentas podem estar disponíveis para a solicitação.
A pesquisa de ferramentas executada pelo cliente serve para casos em que seu aplicativo precisa decidir quais ferramentas estão disponíveis, por exemplo, com base no locatário, no projeto, nas permissões ou no registro interno do usuário.

Comece pela pesquisa de ferramentas hospedada , a menos que seu aplicativo realmente precise controlar a descoberta por conta própria.

Agrupe suas ferramentas pela intenção do usuário. Use espaços de nomes ou servidores MCP sempre que possível. É mais fácil para o modelo escolher entre alguns grupos bem definidos do que entre as funções de uma longa lista sem agrupamento. Recomendamos manter cada espaço de nomes com menos de cerca de 10 funções para otimizar a eficiência no uso de tokens e o desempenho do modelo.

Mantenha as descrições dos espaços de nomes curtas e deixe claras as diferenças entre eles. Coloque as instruções detalhadas nas definições das ferramentas com carregamento adiado. Evite criar um único espaço de nomes enorme para tudo.

Use a pesquisa de ferramentas hospedada com ferramentas de carregamento adiado

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)

Use a chamada programática de ferramentas

A chamada programática de ferramentas permite que o GPT-5.6 escreva JavaScript que chama ferramentas elegíveis e reduz seus resultados intermediários em um ambiente de execução hospedado. Use-a em etapas de escopo delimitado nas quais o código possa filtrar, cruzar, classificar, remover duplicatas, combinar ou verificar resultados volumosos de ferramentas antes de retornar um resultado estruturado menor ao modelo.

Adicione a ferramenta programmatic_tool_calling e habilite cada ferramenta elegível. Use allowed_callers: ["programmatic"] para ferramentas que só podem ser chamadas por programas, ou use allowed_callers: ["direct", "programmatic"] quando o modelo também puder chamar a ferramenta diretamente. Mantenha as chamadas diretas quando cada resultado puder mudar a próxima decisão do modelo, uma ação exigir aprovação ou a resposta final precisar preservar citações ou artefatos nativos. Documente os campos de retorno das ferramentas e o comportamento em caso de erro para que o modelo possa escrever um programa correto sem precisar inspecionar um resultado primeiro.

Seu ciclo de chamadas de ferramentas deve lidar com itens program e program_output, assim como itens function_call emitidos pelo programa e seus itens function_call_output. Preserve cada call_id e copie o caller da chamada de função para a saída dela, para que o serviço possa retomar o programa correto.

Teste tanto o program_output quanto a mensagem final do assistente. Um resultado correto do programa ainda pode levar a uma resposta final incompleta. Compare o sucesso da tarefa, as evidências exigidas, o total de tokens, a latência e o custo com os do mesmo fluxo de trabalho usando chamadas diretas de ferramentas.

Use múltiplos agentes para trabalhar em paralelo

O recurso de múltiplos agentes do GPT-5.6 permite que um agente principal delegue frentes de trabalho independentes a subagentes e sintetize seus resultados. Use-o quando puder dividir a pesquisa, a análise ou a implementação em tarefas concretas, de escopo delimitado, que usem contextos separados e sejam executadas em paralelo.

Defina multi_agent.enabled como true na solicitação. Para HTTP, use o SDK beta da API Responses com client.beta.responses e passe responses_multi_agent=v1 em betas. Para conexões HTTP diretas ou WebSocket, envie OpenAI-Beta: responses_multi_agent=v1. Os esquemas dos itens podem mudar enquanto o recurso de múltiplos agentes estiver em beta.

Prefira um único agente para tarefas curtas, sequências em que cada etapa depende da anterior ou trabalhos que gravam no mesmo recurso mutável. Subagentes podem aumentar o uso de tokens, então comece com o valor padrão de max_concurrent_subagents, que é 3, e meça a qualidade, a latência e o custo de ponta a ponta. Para fluxos de trabalho com múltiplos agentes de longa duração ou com uso intensivo de ferramentas, o modo WebSocket pode reduzir a sobrecarga de continuação.

Antes de habilitar múltiplos agentes, considere as limitações atuais do recurso: /responses/compact, reasoning.summary e max_tool_calls não têm suporte. O servidor compacta automaticamente o contexto do agente principal e o contexto de cada subagente.

Aproveite as ferramentas integradas

As ferramentas integradas são capacidades nativas da API. Em vez de criar cada ferramenta por conta própria, você pode dar ao modelo acesso a ferramentas que já funcionam dentro da API Responses. Assim, o modelo pode decidir quando usá-las.

A OpenAI continua adicionando ferramentas nativas, então comece pelas ferramentas integradas quando elas atenderem ao seu fluxo de trabalho. Crie ferramentas personalizadas quando as opções nativas não atenderem à tarefa. As ferramentas integradas e as opções de ferramentas relacionadas disponíveis atualmente incluem:

Pesquisa na Web: Pesquise na Web para obter informações atualizadas
Pesquisa de arquivos: Pesquise em arquivos enviados ou armazenamentos vetoriais
Code Interpreter: Execute Python para análises, cálculos, gráficos e processamento de arquivos
Shell: Execute comandos de shell em um contêiner hospedado ou no seu próprio ambiente de execução
Uso do computador: Opere uma interface por meio de capturas de tela, cliques, digitação e rolagem
Geração de imagens: Gere ou edite imagens
MCP/conectores: Conecte o modelo a serviços e ferramentas externos
Habilidades: Anexe pacotes reutilizáveis de instruções e arquivos de fluxo de trabalho
Aplicar patch: Faça edições estruturadas no código

A qualidade do modelo é outro motivo para preferir essas ferramentas. As ferramentas integradas fazem parte da distribuição usada no nosso pós-treinamento, ou seja, os modelos são treinados e avaliados com base nos formatos, comportamentos e saídas dessas ferramentas. Com ferramentas integradas, os modelos da OpenAI selecionam melhor as ferramentas, executam as chamadas de forma mais consistente e apresentam menos falhas do que com ferramentas novas.

Aproveite a compactação

A compactação é uma ferramenta de engenharia de contexto: ela decide quais informações o modelo mantém ao longo de vários turnos. Em agentes de longa duração, o problema não é apenas: "Vou atingir o limite de contexto?" Mensagens antigas, logs de ferramentas, novas tentativas e detalhes desatualizados também acabam tomando o espaço do estado de que o modelo precisa.

A compactação permite reduzir o tamanho do contexto de forma controlada, preservando o estado necessário para os turnos seguintes. Após um marco significativo, como concluir uma etapa de depuração ou delimitar uma causa raiz, você pode compactar a janela anterior e continuar a partir da saída compactada. Isso mantém o modelo focado, pois o próximo turno se baseia no estado importante, e não em cada raciocínio intermediário, comando que falhou e linha de raciocínio obsoleta.

Você pode usar a compactação de duas formas:

Deixe o servidor cuidar disso: se você usa previous_response_id, ative context_management com um compact_threshold. O servidor compactará automaticamente a conversa quando ela ficar grande demais. Você continua enviando apenas a mensagem mais recente do usuário.
Faça por conta própria: se você gerencia todo o array de entrada, chame client.responses.compact(). Essa chamada retorna uma janela de contexto menor. Use a saída retornada diretamente na próxima chamada de responses.create().

Não edite a saída compactada. Ela não é um resumo para leitura humana, mas o estado da máquina que ajuda o modelo a continuar. Passe-a adiante sem alterações e depois adicione a próxima mensagem do usuário.

Continue a partir do estado compactado da resposta

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)

Otimize o cache de prompts

O cache de prompts reduz automaticamente a latência e o custo quando as solicitações reutilizam o mesmo prefixo longo. Coloque instruções estáveis, exemplos e material de referência primeiro, seguidos pelo conteúdo dinâmico específico do usuário. Mantenha as definições e a ordem das ferramentas estáveis e acrescente novos turnos à conversa sem reescrever o contexto anterior.

O GPT-5.6 introduziu o cache explícito de prompts. O cache implícito continua sendo o padrão, mas os modelos GPT-5.6 e as famílias de modelos posteriores também oferecem suporte a pontos de corte explícitos de cache e a uma política de cache para toda a solicitação. Se um sufixo variável vier após um prefixo estável, adicione um prompt_cache_breakpoint explícito no limite do trecho reutilizável. Defina prompt_cache_options.mode como explicit somente quando a solicitação deva usar apenas os pontos de corte que você fornecer, sem nenhum ponto de corte implícito. Os modelos anteriores continuam usando apenas o cache automático de prompts.

Nos modelos GPT-5.6 e nas famílias de modelos posteriores, as gravações em cache custam 1,25× o preço dos tokens de entrada sem cache. Registre cached_tokens e cache_write_tokens e, depois, compare o volume de gravações com as leituras posteriores do cache para medir o custo líquido e ajustar a posição dos pontos de corte.

Use um valor estável de prompt_cache_key nas solicitações que compartilham um prefixo reutilizável para ajudar a direcionar solicitações relacionadas ao mesmo cache e otimizar as taxas de acerto de cache nos modelos anteriores ao GPT-5.6. Para grupos com tráfego intenso, siga as orientações para distribuir o tráfego entre mais chaves.

No GPT-5.6 e nos modelos posteriores, prompt_cache_key é opcional: você pode alcançar taxas ideais de acerto de cache sem essa chave. Você pode usá-la para manter a contabilização do cache separada por cliente, usuário ou workspace. Isso pode facilitar a explicação do uso de tokens em cache e da cobrança para cada grupo. Atribua uma chave distinta a cada cliente e mantenha-a estável nas solicitações relacionadas desse cliente. Chaves separadas também ajudam a impedir a sondagem de acertos de cache entre clientes. Consulte Separe a contabilização do cache com chaves.

Mantenha a contabilização do cache separada para um 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)

Use `reasoning.encrypted_content`

O GPT-5.6 pode preservar o raciocínio entre chamadas. Use reasoning.context: "all_turns" quando as metas, as premissas e as prioridades da tarefa permanecerem estáveis. Use current_turn quando o raciocínio anterior já não for relevante e puder prender o modelo a uma abordagem desatualizada. Se você omitir reasoning.context ou definir seu valor como auto, inspecione o campo reasoning.context da resposta para confirmar o modo efetivo.

O raciocínio persistido só funciona quando os itens de raciocínio anteriores estão disponíveis. Use previous_response_id para respostas armazenadas. Se seus requisitos de zero retenção de dados (ZDR) não permitirem armazenar dados de resposta, o conteúdo de raciocínio criptografado permite uma transferência sem estado.

Os itens de raciocínio na saída da resposta incluem conteúdo de raciocínio criptografado por padrão. Você pode acessar esse conteúdo pela propriedade encrypted_content de cada item de raciocínio. Seu aplicativo não precisa entender esse valor. Basta manter cada item de raciocínio exatamente como foi retornado e reenviá-lo no próximo turno, para que o modelo possa usá-lo para continuar o fluxo de trabalho.

Passe o raciocínio criptografado entre turnos sem 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)

Defina o nível de detalhe da imagem de forma intencional

Nos modelos GPT-5.6, omitir detail da imagem ou usar detail: "auto" resulta no mesmo comportamento de dimensionamento de original. O serviço preserva as dimensões de entrada, exceto quando a imagem ultrapassa 65.535 pixels em qualquer um dos lados; nesse caso, ela é reduzida para respeitar esse limite. A API rejeita imagens que ainda excedam o limite de 30.000 patches, em vez de redimensioná-las para atender a esse limite. Imagens grandes podem consumir mais tokens de entrada e, por isso, aumentar a latência.

Escolha detail de acordo com a tarefa. Redimensione a imagem, use low quando detalhes visuais finos não forem importantes ou use high para a compreensão padrão de imagens com alta fidelidade. Reserve original para tarefas com imagens grandes ou densas, sensíveis a coordenadas, de OCR, localização ou inspeção visual nas quais o detalhe adicional melhora a qualidade. Meça o consumo de tokens de imagem e a latência no pior caso antes da implantação.

Envie um identificador de segurança

Se seu aplicativo atende usuários finais individuais, envie um identificador safety_identifier estável e que preserve a privacidade em cada requisição. Ele ajuda a OpenAI a detectar uso indevido e oferece à sua equipe uma forma consistente de rastrear violações de políticas. Também reduz a chance de que o uso indevido por um usuário prejudique o acesso de toda a organização.

Gere um hash do nome de usuário ou do endereço de e-mail em vez de enviar informações que identifiquem a pessoa. Para experiências sem login, use um ID de sessão estável.

Use `background=True`

Use background=True para requisições que possam levar muito tempo. Em vez de manter a conexão do cliente aberta, a API inicia uma tarefa e retorna um ID. Seu aplicativo pode consultar periodicamente essa tarefa até que ela termine, falhe ou seja cancelada. Use esse recurso para análises extensas, execuções demoradas de ferramentas ou trabalhos que precisem de acompanhamento de status e novas tentativas.

Execute uma resposta em segundo plano e consulte seu status periodicamente

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)

Você pode combinar esse recurso com stream=True para receber eventos de progresso, mas o primeiro evento pode demorar mais do que em uma requisição normal.

Do ponto de vista da interface, o modo em segundo plano indica: "Está em execução; este é o status; o resultado aparecerá aqui quando estiver pronto."

Use o modo WebSocket

O modo WebSocket foi desenvolvido para fluxos de trabalho de longa duração com muitas chamadas de ferramentas, nos quais você mantém uma conexão persistente aberta e continua enviando apenas novos itens de entrada junto com previous_response_id. Para execuções com 20 ou mais chamadas de ferramentas, essa abordagem é cerca de 40% mais rápida de ponta a ponta.

Como funciona: a primeira mensagem será semelhante a uma requisição normal à API Responses: modelo, instruções, ferramentas e entrada do usuário. O servidor retorna eventos por streaming. Se o modelo solicitar uma ferramenta, seu aplicativo a executa. Em seguida, em vez de enviar uma nova requisição HTTP, você envia outro evento response.create pelo mesmo socket com o previous_response_id anterior e o novo item. É daí que vem a redução de latência. No HTTP convencional, cada continuação é uma nova requisição. No modo WebSocket, a conexão permanece aberta, e o estado da resposta mais recente fica pronto para reutilização na memória dessa conexão. Quando o próximo turno continua a partir dessa resposta, o backend precisa fazer menos trabalho de preparação.

Se seu fluxo de trabalho consiste em uma requisição e uma resposta, continue usando HTTP. Se seu fluxo de trabalho se comporta como um agente de longa duração, experimente o modo WebSocket.

Uma única conexão WebSocket processa uma resposta em andamento por vez, portanto o trabalho em paralelo exige várias conexões. Atualmente, as conexões têm duração máxima de 60 minutos. A continuação usa a mesma semântica de previous_response_id do modo HTTP, com um cache local da conexão para a resposta mais recente.

Observação: o modo WebSocket funciona com ZDR porque seus dados não são armazenados em disco, apenas na memória.

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

Inicie uma sessão WebSocket da 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

Conclusão

A API Responses é a base para criar aplicativos mais inteligentes e capazes com a OpenAI. A principal vantagem é permitir que desenvolvedores passem de prompts isolados para fluxos de trabalho duradouros, que usam ferramentas, levam o contexto em conta e se adaptam à complexidade da tarefa. Siga este guia para obter melhor desempenho em implantações reais.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog

Configure `reasoning.effort`

Configure `text.verbosity`

Configure o parâmetro `phase` do assistente

Use `tool_search`

Use `reasoning.encrypted_content`

Use `background=True`