Checkliste für die API-Bereitstellung

Inhalt	Erwartete Auswirkungen
Die Responses API verwenden	Qualität, Kosten, Latenz, Zuverlässigkeit
Ein GPT-5.6-Modell auswählen	Qualität, Kosten, Latenz
`reasoning.effort` konfigurieren	Qualität, Kosten, Latenz
`text.verbosity` konfigurieren	Qualität, Kosten, Latenz
Den Parameter `phase` für den Assistenten konfigurieren	Qualität, Kosten
`tool_search` verwenden	Kosten, Latenz
Programmatische Tool-Aufrufe verwenden	Qualität, Kosten, Latenz
Mehrere Agenten für parallele Arbeit einsetzen	Qualität, Kosten, Latenz
Integrierte Werkzeuge nutzen	Qualität
Compaction (Kontextverdichtung) nutzen	Kosten
Prompt-Caching optimieren	Latenz, Kosten
`reasoning.encrypted_content` verwenden	Qualität, Latenz
Den Detailgrad von Bildern bewusst festlegen	Qualität, Kosten, Latenz
Eine Sicherheitskennung senden	Sicherheit, Zuverlässigkeit
`background=True` verwenden	Arbeit fortsetzen
Den WebSocket-Modus verwenden	Latenz

Die Responses API verwenden

Starte immer mit der Responses API. Sie ist die führende API von OpenAI und die beste Wahl, um das neueste Modellverhalten, integrierte Werkzeuge, zustandsbehaftete Arbeitsabläufe und Agentenfunktionen zu nutzen.

Ein GPT-5.6-Modell auswählen

Wähle ein GPT-5.6-Modell passend zur Aufgabe, statt jede Anfrage an die leistungsfähigste Modellstufe zu leiten. Verwende gpt-5.6 oder gpt-5.6-sol für höchste Leistungsfähigkeit, gpt-5.6-terra für starke Leistung zu einem niedrigeren Preis und gpt-5.6-luna für die effiziente Verarbeitung großer Anfragevolumen.

Behalte bei der Migration für den ersten Vergleich die bisherige Rolle des Modells im Arbeitsablauf und seinen tatsächlichen Reasoning-Aufwand bei. Führe repräsentative Evaluationen durch, bevor du Prompts änderst oder neue Funktionen hinzufügst. Vergleiche den Aufgabenerfolg, die Latenz, die Anzahl der Eingabe-, Ausgabe- und Reasoning-Token sowie der in den Cache geschriebenen Token und die Kosten pro erfolgreich abgeschlossener Aufgabe.

`reasoning.effort` konfigurieren

Mit reasoning.effort legst du fest, wie viel das Modell nachdenken soll, bevor es antwortet.

GPT-5.6-Modelle unterstützen die Werte none, low, medium, high, xhigh und max. Der Standardwert ist medium. Ein geringerer Reasoning-Aufwand führt schneller zu Ergebnissen und verbraucht weniger Reasoning-Token. Ein höherer Reasoning-Aufwand gibt dem Modell mehr Zeit für Planung, Debugging, das Zusammenführen von Informationen und mehrstufige Abwägungen.

Verwende low, wenn es hauptsächlich um Extraktion, Routing, Klassifizierung oder einfache Textüberarbeitungen geht. Verwende medium oder high, wenn das Modell ein Problem diagnostizieren, Optionen vergleichen, einen Plan erstellen oder Code durchdenken muss. Verwende xhigh oder max nur, wenn repräsentative Evaluationen zeigen, dass der Qualitätsgewinn die zusätzliche Latenz und die höheren Kosten rechtfertigt. Beginne beim Wechsel von GPT-5.5 oder GPT-5.4 mit dem bisherigen Reasoning-Aufwand und vergleiche diese Einstellung mit der nächstniedrigeren Stufe. GPT-5.6 kann die Qualität oft mit weniger Reasoning-Token halten oder verbessern. Die niedrigere Einstellung kann daher auch Latenz und Kosten senken.

Vergleiche bei den anspruchsvollsten Aufgaben, bei denen Qualität an erster Stelle steht, auch reasoning.mode: "pro" mit dem Standardmodus bei gleichem Reasoning-Aufwand. Reasoning-Modus und Reasoning-Aufwand sind voneinander unabhängig. Der Pro-Modus kann die Zuverlässigkeit verbessern, indem das Modell vor der Ausgabe einer einzigen abschließenden Antwort mehr Arbeit leistet. Allerdings steigen dadurch Latenz und Token-Verbrauch.

Den Reasoning-Aufwand an die Aufgabe anpassen

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)

`text.verbosity` konfigurieren

Mit text.verbosity steuerst du vor allem das Verhältnis zwischen Kürze und Vollständigkeit. Wähle eine geringere Ausführlichkeit, wenn das Produkt eine schnelle, kompakte Antwort benötigt, und eine höhere Ausführlichkeit, wenn die Antwort detailliertere Erklärungen, eine klarere Struktur oder vollständigen Kontext enthalten soll. Eine geringere Ausführlichkeit bedeutet weniger Ausgabe-Token. Das Modell generiert also weniger Text und liefert die Ausgabe schneller.

Beim Programmieren führen medium und high meist zu längeren, besser gegliederten Ausgaben mit klarerer Struktur. Mit low bleibt die Antwort knapper und auf das Wesentliche beschränkt.

GPT-5.6 antwortet standardmäßig meist knapper als GPT-5.5. Prüfe bei der Migration, ob allgemeine Anweisungen wie „Fasse dich kurz“ noch hilfreich sind. In manchen Fällen können sie zu allzu knappen Antworten führen. Behalte sie nur bei, wenn sie weiterhin helfen, und steuere den standardmäßigen Detailgrad vorzugsweise mit text.verbosity. Lege dann im Prompt die erforderlichen Inhalte, die Struktur und gegebenenfalls eine genauere Länge fest.

Für kompakte Ausgaben eine geringere Ausführlichkeit einstellen

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)

Den Parameter `phase` für den Assistenten konfigurieren

phase kennzeichnet Nachrichten des Assistenten im Gesprächsverlauf. Daran erkennt das Modell, ob eine frühere Nachricht des Assistenten ein Kommentar während der Bearbeitung oder die abschließende Antwort war. Verwende phase: "commentary" für Fortschrittsmeldungen, Hinweise vor Tool-Aufrufen und andere Zwischenmeldungen. Verwende phase: "final_answer" für die fertige Antwort.

Der Assistent könnte zum Beispiel Folgendes sagen:

Kommentar des Assistenten

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

Das ist noch nicht die Antwort, sondern eine Fortschrittsmeldung. Später könnte der Assistent Folgendes sagen:

Nachricht mit der abschließenden Antwort des Assistenten

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

Das ist bei lang andauernden Arbeitsabläufen oder solchen mit vielen Tool-Aufrufen nützlich, bei denen der Assistent vor dem Abschluss sichtbare Fortschrittsmeldungen ausgeben kann. Wenn du diesen Verlauf bei Folgeanfragen an gpt-5.3-codex und spätere Modelle erneut sendest, behalte phase in den Nachrichten des Assistenten bei und sende den Wert erneut mit , damit das Modell Fortschrittsmeldungen vom Endergebnis unterscheiden kann. Dadurch bricht der Agent seltener vorzeitig ab und arbeitet eher weiter, bis er die abschließende Antwort erreicht.

Verwende `tool_search`

Statt bei jeder Anfrage den gesamten Tool-Katalog zu laden, verwende die Tool-Suche: Füge {"type": "tool_search"} hinzu und kennzeichne umfangreiche Tool-Definitionen mit defer_loading: true. Das Modell kann dann zur Laufzeit die benötigte Teilmenge laden. Zu Beginn der Anfrage sieht das Modell nur den Namen und die Beschreibung des Suchwerkzeugs. Wenn es entscheidet, dass es ein nachzuladendes Werkzeug benötigt, führt es die Tool-Suche aus. Erst dann werden die entsprechenden Tool-Definitionen in den Kontext geladen. Anschließend kann das Modell diese Werkzeuge aufrufen. Das spart Token und erhält die Cache-Leistung.

Die Tool-Suche bietet zwei Modi:

Die gehostete Tool-Suche ist die einfachere Option. Verwende sie, wenn du bereits weißt, welche Werkzeuge für die Anfrage verfügbar sein könnten.
Die clientseitig ausgeführte Tool-Suche eignet sich für Fälle, in denen deine App entscheiden muss, welche Werkzeuge verfügbar sind, etwa anhand des Mandanten, des Projekts, der Berechtigungen oder der internen Registry der jeweiligen Person.

Beginne mit der gehosteten Tool-Suche , sofern deine App die Suche nach Werkzeugen nicht tatsächlich selbst steuern muss.

Gruppiere deine Werkzeuge danach, was die Nutzenden erreichen wollen. Verwende nach Möglichkeit Namespaces oder MCP-Server. Dem Modell fällt die Auswahl zwischen wenigen klaren Gruppen leichter als aus einer langen, flachen Liste von Funktionen. Für eine optimale Token-Effizienz und Modellleistung empfehlen wir, jeden Namespace auf weniger als etwa 10 Funktionen zu beschränken.

Halte die Beschreibungen der Namespaces kurz und grenze sie klar voneinander ab. Hinterlege ausführliche Anweisungen in den nachzuladenden Tool-Definitionen. Vermeide einen einzigen riesigen Namespace für alles.

Verwende die gehostete Tool-Suche mit nachzuladenden Werkzeugen

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)

Verwende programmatische Tool-Aufrufe

Mit programmatischen Tool-Aufrufen kann GPT-5.6 JavaScript schreiben, das geeignete Werkzeuge aufruft und deren Zwischenergebnisse in einer gehosteten Laufzeitumgebung reduziert. Nutze diese Funktion für klar abgegrenzte Schritte, in denen Code umfangreiche Tool-Ergebnisse filtern, verknüpfen, nach Rang ordnen, von Duplikaten bereinigen, kombinieren oder prüfen kann, bevor er ein kleineres, strukturiertes Ergebnis an das Modell zurückgibt.

Füge das Werkzeug programmatic_tool_calling hinzu und aktiviere die Funktion für jedes geeignete Werkzeug. Verwende allowed_callers: ["programmatic"] für Werkzeuge, die nur über Programme aufgerufen werden sollen, oder allowed_callers: ["direct", "programmatic"], wenn das Modell das Werkzeug auch direkt aufrufen darf. Behalte direkte Aufrufe bei, wenn jedes Ergebnis die nächste Entscheidung des Modells beeinflussen kann, eine Aktion eine Genehmigung erfordert oder die abschließende Antwort Quellenangaben oder native Artefakte beibehalten muss. Dokumentiere die Rückgabefelder und das Fehlerverhalten der Werkzeuge, damit das Modell ein korrektes Programm schreiben kann, ohne zuvor ein Ergebnis prüfen zu müssen.

Deine Tool-Schleife muss Elemente vom Typ program und program_output sowie vom Programm erzeugte function_call-Elemente und deren function_call_output-Elemente verarbeiten. Behalte jede call_id bei und kopiere den caller-Wert des Funktionsaufrufs in dessen Ausgabe, damit der Dienst das richtige Programm fortsetzen kann.

Teste sowohl program_output als auch die abschließende Nachricht des Assistenten. Selbst ein korrektes Programmergebnis kann zu einer unvollständigen abschließenden Antwort führen. Vergleiche Aufgabenerfolg, erforderliche Belege, gesamten Token-Verbrauch, Latenz und Kosten mit demselben Arbeitsablauf bei direkten Tool-Aufrufen.

Nutze mehrere Agenten für parallele Arbeit

Mit der GPT-5.6-Funktion Mehrere Agenten kann ein Hauptagent unabhängige Arbeitsstränge an Subagenten delegieren und deren Ergebnisse zusammenführen. Nutze sie, wenn du Recherche, Analyse oder Implementierung in konkrete, klar abgegrenzte Aufgaben aufteilen kannst, die jeweils einen eigenen Kontext nutzen und parallel laufen.

Setze multi_agent.enabled in der Anfrage auf true. Verwende für HTTP das Responses SDK in der Betaversion mit client.beta.responses und übergib responses_multi_agent=v1 in betas. Sende bei direkten HTTP- oder WebSocket-Verbindungen OpenAI-Beta: responses_multi_agent=v1. Die Schemas der Elemente können sich ändern, solange die Funktion „Mehrere Agenten“ in der Betaphase ist.

Verwende vorzugsweise einen einzelnen Agenten für kurze Aufgaben, Abläufe, in denen jeder Schritt vom vorherigen abhängt, oder Arbeiten, die in dieselbe veränderbare Ressource schreiben. Subagenten können den Token-Verbrauch erhöhen. Beginne daher mit dem Standardwert 3 für max_concurrent_subagents und miss Qualität, Latenz und Kosten über den gesamten Ablauf. Bei Arbeitsabläufen mit mehreren Agenten, die lange dauern oder viele Tool-Aufrufe nutzen, kann der WebSocket-Modus den Aufwand für die Fortsetzung reduzieren.

Berücksichtige vor dem Aktivieren der Funktion „Mehrere Agenten“ ihre aktuellen Einschränkungen: /responses/compact, reasoning.summary und max_tool_calls werden nicht unterstützt. Der Server verdichtet automatisch den Kontext des Hauptagenten sowie den Kontext jedes Subagenten.

Nutze integrierte Werkzeuge

Integrierte Werkzeuge sind native Funktionen der API. Statt jedes Werkzeug selbst zu entwickeln, kannst du dem Modell Zugriff auf Werkzeuge geben, die bereits innerhalb der Responses API funktionieren. Das Modell kann dann selbst entscheiden, wann es sie verwendet.

OpenAI ergänzt laufend weitere native Werkzeuge. Beginne daher mit integrierten Werkzeugen, wenn sie zu deinem Arbeitsablauf passen. Entwickle eigene Werkzeuge, wenn die nativen Optionen die Aufgabe nicht abdecken. Zu den aktuellen integrierten Werkzeugen und verwandten Optionen gehören:

Websuche: Durchsuche das Web nach aktuellen Informationen
Dateisuche: Durchsuche hochgeladene Dateien oder Vektorspeicher
Code Interpreter: Führe Python für Analysen, Berechnungen, Diagramme und Dateiverarbeitung aus
Shell: Führe Shell-Befehle in einem gehosteten Container oder deiner eigenen Laufzeitumgebung aus
Computernutzung: Bediene eine Benutzeroberfläche mithilfe von Screenshots, Klicks, Texteingaben und Scrollen
Bildgenerierung: Generiere oder bearbeite Bilder
MCP/Konnektoren: Verbinde das Modell mit externen Diensten und Werkzeugen
Skills: Füge wiederverwendbare Anweisungspakete und Dateien für Arbeitsabläufe hinzu
Patch anwenden: Nimm strukturierte Codeänderungen vor

Auch die Qualität der Modellergebnisse spricht für integrierte Werkzeuge. Sie entsprechen der Datenverteilung unseres Nachtrainings: Die Modelle werden anhand der Formate, Verhaltensweisen und Ausgaben dieser Werkzeuge trainiert und evaluiert. Mit integrierten Werkzeugen wählen OpenAI-Modelle die passenden Werkzeuge besser aus, führen sie sauberer aus und verursachen weniger Fehler als mit neuen Werkzeugen.

Nutze Compaction (Kontextverdichtung)

Compaction (Kontextverdichtung) ist ein Werkzeug zur Kontextgestaltung: Es bestimmt, welche Informationen das Modell über viele Gesprächsrunden hinweg beibehält. Bei lang laufenden Agenten geht es nicht nur um die Frage: „Erreiche ich das Kontextlimit?“ Alte Nachrichten, Tool-Protokolle, Wiederholungsversuche und veraltete Details verdrängen zudem die Zustandsinformationen, die das Modell benötigt.

Mit Compaction (Kontextverdichtung) kannst du den Kontext kontrolliert verkleinern und dabei die Zustandsinformationen erhalten, die für nachfolgende Gesprächsrunden benötigt werden. Nach einem wichtigen Meilenstein, etwa dem Abschluss einer Debugging-Phase oder dem Eingrenzen einer Fehlerursache, kannst du das bisherige Kontextfenster verdichten und mit der verdichteten Ausgabe fortfahren. So bleibt das Modell fokussiert: Die nächste Gesprächsrunde baut auf den wichtigen Zustandsinformationen auf, statt auf jeder Zwischenüberlegung, jedem fehlgeschlagenen Befehl und jedem überholten Gedankengang.

Du kannst Compaction (Kontextverdichtung) auf zwei Arten nutzen:

Überlasse es dem Server: Wenn du previous_response_id verwendest, aktiviere context_management und lege einen compact_threshold fest. Der Server verdichtet die Unterhaltung automatisch, wenn sie zu groß wird. Du sendest weiterhin nur die neueste Nachricht der nutzenden Person.
Übernimm es selbst: Wenn du das gesamte Eingabearray selbst verwaltest, rufe client.responses.compact() auf. Du erhältst ein kleineres Kontextfenster zurück. Verwende diese zurückgegebene Ausgabe direkt beim nächsten Aufruf von responses.create().

Bearbeite die verdichtete Ausgabe nicht. Sie ist keine Zusammenfassung für Menschen, sondern enthält den Maschinenzustand, mit dem das Modell fortfahren kann. Übernimm sie unverändert und füge dann die nächste Nachricht der nutzenden Person hinzu.

Mit dem verdichteten Antwortzustand fortfahren

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)

Optimiere das Prompt-Caching

Prompt-Caching reduziert automatisch Latenz und Kosten, wenn Anfragen dasselbe lange Präfix wiederverwenden. Platziere unveränderliche Anweisungen, Beispiele und Referenzmaterial zuerst, gefolgt von dynamischen, benutzerspezifischen Inhalten. Halte Tool-Definitionen und deren Reihenfolge stabil und hänge neue Gesprächsrunden an, ohne den bisherigen Kontext umzuschreiben.

Mit GPT-5.6 wurde explizites Prompt-Caching eingeführt. Implizites Caching bleibt der Standard, aber GPT-5.6-Modelle und spätere Modellfamilien unterstützen auch explizite Cache-Breakpoints und eine Cache-Richtlinie für die gesamte Anfrage. Wenn auf ein unveränderliches Präfix ein veränderliches Suffix folgt, füge am Ende des wiederverwendbaren Abschnitts einen expliziten prompt_cache_breakpoint hinzu. Setze prompt_cache_options.mode nur dann auf explicit, wenn die Anfrage ausschließlich die von dir angegebenen Breakpoints und keinen impliziten Breakpoint verwenden soll. Frühere Modelle nutzen weiterhin nur automatisches Prompt-Caching.

Bei GPT-5.6-Modellen und späteren Modellfamilien kosten Cache-Schreibvorgänge das 1,25-Fache des Preises für nicht gecachte Eingabetoken. Protokolliere cached_tokens und cache_write_tokens und vergleiche dann das Schreibvolumen mit späteren Cache-Lesevorgängen, um die Nettokosten zu ermitteln und die Platzierung der Breakpoints zu optimieren.

Verwende einen gleichbleibenden Wert für prompt_cache_key bei Anfragen mit einem gemeinsamen, wiederverwendbaren Präfix. So lassen sich zusammengehörige Anfragen leichter an denselben Cache weiterleiten und die Cache-Trefferraten bei Modellen vor GPT-5.6 optimieren. Beachte bei Gruppen mit hohem Anfrageaufkommen die Empfehlungen zur Verteilung des Datenverkehrs auf mehr Schlüssel.

Ab GPT-5.6 ist prompt_cache_key optional: Du kannst auch ohne diesen Schlüssel optimale Cache-Trefferraten erzielen. Mit ihm kannst du die Cache-Nutzung getrennt nach Kundenkonten, nutzenden Personen oder Workspaces erfassen. Dadurch lassen sich die Nutzung gecachter Token und deren Abrechnung für jede Gruppe leichter nachvollziehen. Weise jedem Kundenkonto einen eigenen Schlüssel zu und behalte ihn für alle zusammengehörigen Anfragen dieses Kontos bei. Getrennte Schlüssel helfen außerdem, das gezielte Ausforschen von Cache-Treffern anderer Kundenkonten zu verhindern. Siehe Cache-Nutzung mit Schlüsseln getrennt erfassen.

Cache-Nutzung für ein Kundenkonto getrennt erfassen

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)

Verwende `reasoning.encrypted_content`

GPT-5.6 kann Überlegungen über mehrere Aufrufe hinweg beibehalten. Verwende reasoning.context: "all_turns", wenn Ziele, Annahmen und Prioritäten der Aufgabe unverändert bleiben. Verwende current_turn, wenn frühere Überlegungen nicht mehr relevant sind und das Modell auf einen veralteten Ansatz festlegen könnten. Wenn du reasoning.context weglässt oder auf auto setzt, prüfe in der Antwort das Feld reasoning.context, um den tatsächlich verwendeten Modus zu bestätigen.

Das Beibehalten von Überlegungen funktioniert nur, wenn frühere Reasoning-Elemente verfügbar sind. Verwende previous_response_id für gespeicherte Antworten. Wenn deine Anforderungen an keine Datenaufbewahrung (ZDR) das Speichern von Antwortdaten nicht zulassen, ermöglichen verschlüsselte Reasoning-Inhalte eine zustandslose Übergabe.

Reasoning-Elemente in der Antwortausgabe enthalten standardmäßig verschlüsselte Reasoning-Inhalte. Auf diese Inhalte kannst du über die Eigenschaft encrypted_content des jeweiligen Reasoning-Elements zugreifen. Deine App muss diesen Wert nicht interpretieren. Sie behält jedes Reasoning-Element genau so bei, wie es zurückgegeben wurde, und sendet es in der nächsten Gesprächsrunde erneut, damit das Modell den Arbeitsablauf damit fortsetzen kann.

Verschlüsselte Reasoning-Inhalte zwischen zustandslosen Gesprächsrunden weitergeben

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)

Lege den Bilddetailgrad gezielt fest

Bei GPT-5.6-Modellen werden Bildgrößen bei fehlendem detail und bei detail: "auto" genauso behandelt wie bei original. Der Dienst behält die Eingabeabmessungen bei. Nur Bilder, deren Breite oder Höhe 65.535 Pixel überschreitet, werden so verkleinert, dass sie diese Grenze einhalten. Bilder, die weiterhin das Limit von 30.000 Patches überschreiten, lehnt die API ab, statt sie entsprechend zu verkleinern. Große Bilder können mehr Eingabetokens verbrauchen und dadurch die Latenz erhöhen.

Wähle detail passend zur Aufgabe. Passe die Bildgröße an, verwende low, wenn feine Bilddetails nicht wichtig sind, oder high für ein standardmäßiges, detailgetreues Bildverständnis. Verwende original für Aufgaben mit großen oder detailreichen Bildern, bei denen es auf genaue Koordinaten ankommt, sowie für OCR, Lokalisierung oder visuelle Inspektion, wenn die zusätzlichen Details die Qualität verbessern. Miss vor der Bereitstellung den Tokenverbrauch der Bilder und die Latenz im ungünstigsten Fall.

Sende eine Sicherheitskennung

Wenn deine Anwendung von einzelnen Personen genutzt wird, sende bei jeder Anfrage einen stabilen, datenschutzfreundlichen safety_identifier mit. Er hilft OpenAI, Missbrauch zu erkennen, und bietet deinem Team eine verlässliche Möglichkeit, Richtlinienverstöße nachzuverfolgen. Außerdem verringert er das Risiko, dass der Missbrauch durch eine einzelne Person den Zugriff für deine gesamte Organisation beeinträchtigt.

Bilde einen Hash aus dem Benutzernamen oder der E-Mail-Adresse der jeweiligen Person, statt identifizierende Informationen zu senden. Verwende bei einer Nutzung ohne Anmeldung eine stabile Sitzungs-ID.

Verwende `background=True`

Verwende background=True für Anfragen, die möglicherweise lange dauern. Die API startet einen Auftrag und gibt eine ID zurück, statt die Clientverbindung offen zu halten. Deine App kann den Status dieses Auftrags regelmäßig abfragen, bis er abgeschlossen ist, fehlschlägt oder abgebrochen wird. Nutze diese Option für umfangreiche Analysen, lange Werkzeugausführungen oder Aufgaben, die Statusabfragen und Wiederholungsversuche benötigen.

Eine Antwort im Hintergrund ausführen und ihren Status abfragen

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)

Du kannst die Option mit stream=True kombinieren, um Fortschrittsereignisse zu erhalten. Bis zum ersten Ereignis kann es allerdings länger dauern als bei einer normalen Anfrage.

Aus Sicht der Benutzeroberfläche signalisiert der Hintergrundmodus: „Die Aufgabe läuft. Hier siehst du den Status. Das Ergebnis erscheint hier, sobald es fertig ist.“

Verwende den WebSocket-Modus

Der WebSocket-Modus ist für lang andauernde Arbeitsabläufe mit vielen Werkzeugaufrufen ausgelegt. Dabei hältst du eine dauerhafte Verbindung offen und sendest zum Fortsetzen nur neue Eingabeelemente zusammen mit previous_response_id. Bei Durchläufen mit 20 oder mehr Werkzeugaufrufen ist dieser Ansatz über den gesamten Ablauf hinweg etwa 40 % schneller.

So funktioniert es: Die erste Nachricht sieht wie eine normale Responses-Anfrage aus: Modell, Anweisungen, Werkzeuge und Benutzereingabe. Der Server sendet Ereignisse als Stream zurück. Wenn das Modell ein Werkzeug anfordert, führt deine App es aus. Anschließend sendest du keine neue HTTP-Anfrage, sondern ein weiteres response.create-Ereignis über denselben Socket, mit dem bisherigen Wert für previous_response_id und dem neuen Element. Dadurch sinkt die Latenz. Bei reinem HTTP ist jede Folgeanfrage eine neue Anfrage. Im WebSocket-Modus bleibt die Verbindung offen, und der Zustand der letzten Antwort bleibt für diese Verbindung im Arbeitsspeicher verfügbar. Wenn der nächste Dialogschritt auf dieser Antwort aufbaut, muss das Backend weniger Vorbereitungsarbeit leisten.

Wenn dein Arbeitsablauf aus einer Anfrage und einer Antwort besteht, bleib bei HTTP. Wenn dein Arbeitsablauf wie ein über längere Zeit laufender Agent funktioniert, probiere den WebSocket-Modus aus.

Eine einzelne WebSocket-Verbindung verarbeitet jeweils nur eine laufende Antwort. Für parallele Arbeit sind daher mehrere Verbindungen erforderlich. Die Verbindungsdauer ist derzeit auf 60 Minuten begrenzt. Für das Fortsetzen gilt dieselbe Semantik für previous_response_id wie im HTTP-Modus, mit einem verbindungslokalen Cache für die letzte Antwort.

Hinweis: Der WebSocket-Modus ist mit ZDR kompatibel, da deine Daten nur im Arbeitsspeicher und nicht auf einem Datenträger gespeichert werden.

Das Python-Beispiel verwendet pip install "openai[realtime]>=3.8.0". Das JavaScript-Beispiel verwendet npm install openai@^7.10.0 ws. Das Ruby-Beispiel verwendet gem install openai async-websocket.

Eine WebSocket-Sitzung mit der Responses API starten

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

Fazit

Die Responses API ist die Grundlage für die Entwicklung intelligenterer, leistungsfähigerer OpenAI-Anwendungen. Ihr entscheidender Vorteil: Sie ermöglicht Entwickelnden den Übergang von einzelnen Prompts zu beständigen Arbeitsabläufen, die Werkzeuge nutzen, den Kontext berücksichtigen und sich an die Komplexität der Aufgabe anpassen können. Befolge diesen Leitfaden, um bei tatsächlichen Bereitstellungen eine höhere Leistung zu erzielen.

Vorschläge

Erste Schritte

Grundlegende Konzepte

SDKs und CLI

Ressourcen

Ältere APIs

Modell auswählen

Text und Code

Prompts formulieren

Reasoning-Aufwand

Bilder und Video

Echtzeit und Audio

Spezialisierte Modelle

Agents API

Agents SDK

ChatKit

Suche und Informationsabruf

Tools und Daten anbinden

Arbeitsabläufe mit Tools erstellen

Computer und Code

Medien

GPT-Live

Realtime API

Anwendungen mit Sprachfunktionen entwickeln

Verbindungen

Audioverarbeitung

In Produktion gehen

Leistung und Qualität

Kosten und Durchsatz

Sicherheit und Governance

Infrastruktur und Zugriff

Betrieb

Grundlegende Konzepte

Plan

Build

Test and publish

Conversion specs

Leitfäden

Ressourcen

Erste Schritte

Leitfäden

File Upload

API

Measurement

Advertiser API

API-Referenz

Erste Schritte

Grundlagen

Entdecken

Verfügbar auf

Versionen

Arbeitsabläufe

Funktionen

Referenz

Anpassung

Konfigurationsdatei

Agentenkonfiguration

ChatGPT und Codex erweitern

Linux

Windows

Arbeitsabläufe für die Entwicklung

Erweitern und automatisieren

Umgebungen

Mit Codex entwickeln

Integrationen von Drittanbietern

Referenz

Berechtigungen

Codex Security

Cybersicherheit

Erste Schritte

ChatGPT Work

Identität und Authentifizierung

Workspace-Zugriff, Richtlinien und Modelle

Kontrollen für Plug-ins und Konnektoren

Nutzung, Governance und Compliance

Bereitstellung und Modellanbieter

Community

Blog

Community

Blog

`reasoning.effort` konfigurieren

`text.verbosity` konfigurieren

Den Parameter `phase` für den Assistenten konfigurieren

Verwende `tool_search`

Verwende `reasoning.encrypted_content`

Verwende `background=True`