Agents API

Die Agents API gibt deiner Anwendung über eine von OpenAI verwaltete API Zugriff auf den Codex-Harness.

OpenAI übernimmt Sitzungen, Orchestrierung, Compaction (Kontextverdichtung) und Wiederherstellung. Deine Anwendung stellt Werkzeuge bereit und wählt ihre Ausführungsumgebung.

Agenten können in einer Sandbox arbeiten, in der sie Code ausführen, Dateien bearbeiten, sich mit MCP-Servern verbinden und Artefakte erstellen können.

Preise

Die Modellnutzung wird zu den API-Preisen des ausgewählten Modells abgerechnet. Für OpenAI-Werkzeuge gelten die jeweiligen Standardpreise, für von OpenAI gehostete Sandboxen die üblichen Containerpreise.

Ein Beispiel ausprobieren

Probiere diese vollständigen Beispiele aus:

Erstelle ein Skript zur Darstellung eines Verzeichnisbaums und führe es aus, und zwar in einer von OpenAI gehosteten Sandbox.
Vergleiche Versionshinweise mithilfe von Subagenten und fasse ihre Ergebnisse in einer Antwort zusammen.

Entdecke vollständige Anwendungen:

Agent zur Vorfallsbearbeitung: Warnmeldungen untersuchen und Genehmigungen für Wiederherstellungsmaßnahmen anfordern.
Slack-Bot: Anfragen mithilfe angebundener Werkzeuge für den Arbeitsplatz untersuchen.
Data Analyst: Fragen zum Data Warehouse mit SQL-Abfragen ohne Schreibzugriff beantworten.
Verwende das Tool zur Untersuchung von GitHub-Issues, um gemeldete Fehler zu reproduzieren und Erkenntnisse auf GitHub zu teilen.
Verwende das Tool zur Dokumentenprüfung, um Dokumente mithilfe von Skills zur Richtlinienprüfung und spezialisierten Agenten zu überprüfen.

Grundlegende Konzepte

Die Agents API basiert auf vier zentralen Konzepten:

Agent: Das Modell, die Anweisungen, Werkzeuge und MCP-Server, die dem Agenten zur Verfügung stehen.
Umgebung: Eine optionale Sandbox oder ein Computer, in der bzw. auf dem der Agent auf Dateien zugreift, Skills lädt und Befehle ausführt.
Sitzung: Eine persistente Instanz eines Agenten, die Aufgaben bearbeitet und auf Eingaben reagiert.
Ereignisse und Elemente: Die Eingaben, die an einen Agenten gesendet werden, und die Ausgaben, die während einer Sitzung entstehen.

Eine Sitzung von Anfang bis Ende

Beginne im Schnellstart mit einer von OpenAI gehosteten Sandbox:

Erstelle eine Sitzung. Konfiguriere den Agenten. OpenAI stellt seine Umgebung bereit.
Gib ihm eine Aufgabe. Sobald die Umgebung bereit ist, startet eine Nutzereingabe einen Bearbeitungsdurchlauf.
Verfolge den Fortschritt. Empfange Ausgaben als Stream oder nutze Webhooks, um zu erfahren, wann der Agent fertig ist oder eine Eingabe benötigt.
Setze die Arbeit fort oder greife steuernd ein. Sende eine weitere Aufgabe an dieselbe Sitzung oder leite den Agenten während seines aktuellen Bearbeitungsdurchlaufs an.

Bei einer von OpenAI gehosteten Sitzung sendet deine Anwendung Eingaben und empfängt Ereignisse. OpenAI führt den Agenten aus und stellt seine Sandbox bereit und verwaltet sie. Informationen zum Setup und zu Einschränkungen findest du unter Umgebungsoptionen.

Deine Anwendung startet Sitzungen und empfängt Ereignisse und Ausgaben von der Agents API. OpenAI führt den verwalteten Codex-Harness aus und stellt dessen Sandbox bereit und verwaltet sie.

Was der verwaltete Harness bietet

Der verwaltete Codex-Harness unterstützt Folgendes:

Befehle und Code in einer Sandbox ausführen.
Relevante Skills und Anweisungen anwenden.
Über Werkzeuge oder MCP auf externe Daten zugreifen.
Den Agenten während seiner Arbeit steuern.
Bisherige Arbeit zusammenfassen, um das Kontextfenster zu verwalten.
Arbeit in Teilaufgaben aufteilen und an Subagenten delegieren.
Eine Sitzung dort fortsetzen, wo sie aufgehört hat.

Informationen zu Berechtigungen für API-Schlüssel und zum SDK-Setup findest du unter Voraussetzungen im Schnellstart. Konfiguriere diese Funktionen beim Erstellen einer Sitzung:

Funktionen des verwalteten Harness konfigurieren

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

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp",
        },
      },
      { type: "web_search" },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 4 },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
        },
      ],
    },
  ],
});
console.log(session.id);

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

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {
                    "type": "http",
                    "server_url": "https://developers.openai.com/mcp",
                },
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
                }
            ],
        }
    ],
)
print(session.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"
	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra"),
	Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
	Tools: []openai.AgentToolParamUnion{openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
		openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs",
			Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},
		openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}}},
	MultiAgent: openai.MultiAgentConfigParam{Enabled: true,
		MaxConcurrentSubagents: openai.Int(4)}},
	Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace",
		CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},
	Input: openai.BetaAgentSessionNewParamsInputUnion{OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{openai.AgentSessionInputMessageParam{Content: []openai.InputContentParamUnion{openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}}}}}}})
if err != nil {
	panic(err)
}
fmt.Println(session.ID)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "Use the OpenAI documentation MCP and web search to answer"
                                + " technical questions accurately. Delegate independent"
                                + " research tasks to subagents when useful.")
                        .addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
                        .addTool(
                            AgentToolParam.Mcp.builder()
                                .serverLabel("openai_docs")
                                .transport(
                                    McpTransportParam.Http.builder()
                                        .serverUrl("https://developers.openai.com/mcp")
                                        .build())
                                .build())
                        .addTool(AgentToolParam.WebSearch.builder().build())
                        .multiAgent(
                            MultiAgentConfigParam.builder()
                                .enabled(true)
                                .maxConcurrentSubagents(4L)
                                .build())
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/capabilities/skills"))
                        .build())
                .input(
                    "Research how to connect an MCP server to an OpenAI agent, check for recent"
                        + " updates, and summarize the recommended setup.")
                .build());
System.out.println(session.id());

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

client = OpenAI::Client.new

session = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp"
        }
      },
      { type: "web_search" }
    ],
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 4
    }
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"]
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
        }
      ]
    }
  ]
)
puts session.id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46curl -sS -X POST "https://api.openai.com/v1/agents/sessions" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
      "tools": [
        {
          "type": "programmatic_tool_calling"
        },
        {
          "type": "mcp",
          "server_label": "openai_docs",
          "transport": {
            "type": "http",
            "server_url": "https://developers.openai.com/mcp"
          }
        },
        {
          "type": "web_search"
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 4
      }
    },
    "environment": {
      "type": "self_hosted",
      "workspace_directory": "/workspace",
      "capability_directories": ["/workspace/capabilities/skills"]
    },
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
          }
        ]
      }
    ]
  }'

Einen Vergleich der Laufzeitumgebungen findest du in der Agentenübersicht.

Die Agents API speichert den Sitzungszustand, damit du über mehrere Bearbeitungsdurchläufe hinweg weiterarbeiten kannst, ohne den Gesprächskontext neu aufzubauen. Du kannst Sitzungen und veröffentlichte Artefakte löschen, wenn du sie nicht mehr benötigst. Die Agents API unterstützt derzeit Datenresidenz nur in den Vereinigten Staaten und unterstützt die Option „keine Datenaufbewahrung“ (ZDR) nicht. Auch mit einer selbst gehosteten Sandbox ist die Agents API nicht für ZDR geeignet. Unter Datenkontrollen auf der OpenAI-Plattform findest du Details zur Datenresidenz und Datenaufbewahrung.

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