Die neue OpenAI Agents API lässt sich als «Codex als Service» verstehen. Sie macht die Agentensteuerung hinter Codex über eine API für eigene Anwendungen nutzbar. OpenAI betreibt diese Steuerung; Ihre Anwendung liefert Aufgaben, Werkzeuge und den Zugang zu den benötigten Daten. OpenAI bezeichnet den technischen Kern als «managed Codex harness». «Codex als Service» ist hier eine Erklärung des Prinzips, kein offizieller Produktname. OpenAI Agents API

Zum Beispiel könnte ein Benutzer in Ihrem Serviceportal «Supportbericht erstellen» wählen. Ihr Backend startet einen Auftrag. Der Agent analysiert Daten, schreibt ein Prüfskript, führt es in einer Sandbox aus und erstellt den Bericht. Das Portal zeigt Fortschritt und Ergebnis. So wird die Agentenausführung Teil Ihres eigenen Produkts.

Der Vergleich bezieht sich auf die programmierbare Agentenausführung. Er verspricht keine vollständige Funktionsgleichheit mit der Codex-App oder deren Benutzeroberfläche. In diesem Artikel bauen wir damit einen technischen Prüfagenten und verbinden ihn über MCP mit einem Spezialisten in Microsoft Foundry. OpenAI führt den Hauptagenten aus; Foundry liefert in dieser Architektur eine abgegrenzte Fachauskunft.

Was die neue API übernimmt

Die zentrale Ressource ist eine Session. Sie hält die Agentenkonfiguration, den Gesprächsverlauf und gespeicherte Arbeit zusammen. Eine neue Nachricht startet einen Arbeitsdurchlauf oder steuert den laufenden Durchlauf. Die Anwendung kann später in derselben Session weiterarbeiten. Sessions und Turns

Die Anwendung muss dadurch weniger Agentenmechanik selbst implementieren. Sie bleibt verantwortlich für die fachlichen Grenzen: Welche Aufgaben sind erlaubt? Welche Daten darf ein Werkzeug liefern? Woran erkennen wir ein brauchbares Ergebnis? Die technische Aufteilung beschreibt OpenAI in seiner API-Übersicht.

Unser Beispiel: Ein technischer Prüfbericht

Als erste Aufgabe soll der Agent synthetische Supportdaten analysieren. Er erstellt ein Python-Skript, führt es aus und schreibt einen Markdown-Bericht mit den tatsächlich berechneten Kennzahlen. Eine Folgeaufgabe ergänzt einen Vergleich mit einer betrieblichen Richtlinie.

Dafür schlagen wir folgende Architektur vor:

Anwendung mit Benutzeranmeldung
        |
        | Aufgabe, Session-ID, Events
        v
OpenAI Agents API
        |
        +--- Sandbox: Python ausführen und Bericht erstellen
        |
        +--- MCP-Werkzeug: ask_foundry_specialist
                    |
                    v
             Eigener MCP-Dienst
                    |
                    | Microsoft Entra ID
                    v
             Microsoft Foundry Agent
             mit freigegebenem Fachwissen

Die Verbindung über den MCP-Dienst ist unser Integrationsentwurf auf Basis der dokumentierten Schnittstellen. OpenAI unterstützt MCP-Werkzeuge, Microsoft dokumentiert den Aufruf bestehender Foundry-Agenten. Daraus ergibt sich die hier gezeigte Brücke. Eine native Bereitstellung der OpenAI Agents API innerhalb von Foundry setzen wir nicht voraus. OpenAI MCP-Verbindungen, Foundry-Agenten aufrufen

1. Zugang und Python vorbereiten

Erstellen Sie im OpenAI-Projekt einen Application API Key mit api.agents.read, api.agents.write und api.responses.write. Letzteres wird für die Modellinferenz benötigt. Der Schlüssel bleibt im Anwendungsbackend ausserhalb der Sandbox. Die dokumentierte API verwendet den Beta-Namensraum; das SDK setzt den erforderlichen Header OpenAI-Beta: agents=v1 automatisch. Voraussetzungen im Quickstart

Installieren Sie das aktuelle OpenAI SDK in einer virtuellen Umgebung:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade openai

Stellen Sie OPENAI_API_KEY über Ihre lokale Secret-Verwaltung oder die Umgebung des Backend-Prozesses bereit. Für den Einstieg verwendet das Beispiel gpt-6-astra, entsprechend dem offiziellen Quickstart. Prüfen Sie den Zugriff in Ihrem OpenAI-Projekt.

2. Eine Aufgabe starten und den Fortschritt verfolgen

Speichern Sie folgenden Code als technical_agent.py:

from openai import OpenAI

TASK = """
Erstelle demo_tickets.csv mit diesen synthetischen Daten:
ticket_id,resolution_hours
DEMO-1,2
DEMO-2,4
DEMO-3,6

Schreibe analyse.py, das die CSV liest und Ticketanzahl sowie
mittlere Lösungszeit berechnet. Führe das Skript aus.
Erstelle report.md mit den tatsächlichen Ergebnissen.
Antworte auf Deutsch mit Schweizer Rechtschreibung.
"""

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": (
                "Prüfe technische Aufgaben mit ausführbarem Code. "
                "Berichte nur Ergebnisse, die du tatsächlich geprüft hast."
            ),
        },
        environment={"type": "openai_hosted"},
        input=TASK,
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

Starten Sie das Beispiel:

.\.venv\Scripts\python.exe technical_agent.py

Der Aufruf erstellt eine Session und startet den Auftrag. OpenAI stellt die Sandbox bereit. Die Konsole zeigt den Event-Stream; übernehmen Sie die darin enthaltene session_id in den Auftragsdatensatz Ihrer Anwendung. Agents-API-Quickstart

Das fachliche Prüfergebnis ist eindeutig: drei Tickets und eine mittlere Lösungszeit von vier Stunden. Vergleichen Sie damit den Bericht und die tatsächliche Skriptausgabe. Eine überzeugend formulierte Antwort allein genügt für diesen Test nicht.

3. Abschluss und Fehler unterscheiden

In einer Benutzeroberfläche sollten Events den Arbeitsstatus aktualisieren. Ein Server-Sent-Events-Stream ist dabei ein Transport für Fortschritt, kein Beleg für einen erfolgreichen Auftrag.

Wenn Subagenten aktiviert sind, unterscheiden Sie deren Turn-Events vom Abschluss des Hauptagenten über event.turn.subagent_id. Nach einer unterbrochenen Verbindung lesen Sie die Session und ihre gespeicherten Items erneut. Der Stream spielt verpasste Events nicht nach. Events und Wiederherstellung

Das ist für den Betrieb relevant: Startet Ihre Anwendung nach jedem Verbindungsabbruch eine neue Session, kann sie dieselbe Aufgabe mehrfach ausführen. Speichern Sie deshalb die Session-ID früh und stellen Sie zuerst den vorhandenen Zustand wieder her.

4. In derselben Session weiterarbeiten

Eine Folgeaufgabe kann den vorhandenen Bericht ergänzen. Dafür senden Sie ein Input-Event an dieselbe Session:

from openai import OpenAI


def send_follow_up(client: OpenAI, session_id: str, text: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id,
        events=[{
            "type": "agent.session.input.message",
            "input": [{
                "role": "user",
                "content": [{"type": "input_text", "text": text}],
            }],
        }],
    )

Abonnieren Sie im aufrufenden Code zuerst client.beta.agents.sessions.events.stream(session_id). Rufen Sie dann die Funktion auf, etwa mit: «Ergänze report.md um Median und maximale Lösungszeit. Führe das Skript erneut aus.» So empfangen Sie auch frühe Events der Folgeaufgabe. Die erwarteten zusätzlichen Kennzahlen sind vier und sechs Stunden. Session fortsetzen

5. Microsoft Foundry als Spezialisten anbinden

Nun soll der Prüfagent eine interne Support-Richtlinie berücksichtigen. Ein bestehender Foundry-Agent kann diese fachliche Aufgabe übernehmen. Unser MCP-Dienst veröffentlicht dafür genau ein Werkzeug, ask_foundry_specialist.

Die folgende Datei foundry_bridge.py zeigt den lokalen Kern des Dienstes. Sie setzt einen bereits konfigurierten Foundry-Agenten voraus, der seine Quellen nennt und nur lesende Werkzeuge verwendet:

import os

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from mcp.server.fastmcp import FastMCP
from openai import OpenAI

server = FastMCP(
    "foundry-specialist",
    host="127.0.0.1",
    port=8765,
    stateless_http=True,
)

foundry = OpenAI(
    base_url=(
        os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/") + "/openai/v1"
    ),
    api_key=get_bearer_token_provider(
        DefaultAzureCredential(),
        "https://ai.azure.com/.default",
    ),
    timeout=60.0,
)


@server.tool()
def ask_foundry_specialist(question: str) -> str:
    """Fragt den konfigurierten Foundry-Spezialisten nach Fachinformationen."""
    response = foundry.responses.create(
        input=question,
        extra_body={
            "agent_reference": {
                "type": "agent_reference",
                "name": os.environ["FOUNDRY_AGENT_NAME"],
            }
        },
    )
    if response.status != "completed" or not response.output_text:
        raise RuntimeError("Der Foundry-Spezialist lieferte keine vollständige Antwort.")
    return response.output_text


if __name__ == "__main__":
    server.run(transport="streamable-http")

Installieren Sie für diesen Dienst openai, azure-identity und mcp. Konfigurieren Sie FOUNDRY_PROJECT_ENDPOINT sowie FOUNDRY_AGENT_NAME. Die Identität des Dienstes benötigt Zugriff auf das Foundry-Projekt. Microsoft dokumentiert das Entra-Clientmuster und die Agentenreferenz; der MCP-Wrapper ist die Ergänzung für unsere Architektur. Entra-Clientkonfiguration, Foundry-Agentenreferenz

Der lokale Dienst bindet bewusst nur an Loopback. Für eine Verbindung aus OpenAI stellen Sie ihn hinter einem authentifizierten HTTPS-Endpunkt bereit. Dieser muss MCP-Anfragen an den Dienst weiterleiten und den Zugriff auf Benutzer beziehungsweise Mandanten begrenzen. Eine lokale Adresse wie 127.0.0.1 ist von OpenAI aus nicht erreichbar.

Nach dieser Bereitstellung ergänzen Sie in der Agentenkonfiguration des ersten Beispiels das Feld tools. Importieren Sie dort zusätzlich os:

"tools": [{
    "type": "mcp",
    "server_label": "foundry_specialist",
    "transport": {
        "type": "http",
        "server_url": os.environ["FOUNDRY_BRIDGE_MCP_URL"],
        "authorization": "Bearer " + os.environ["FOUNDRY_BRIDGE_TOKEN"],
    },
    "connection_origin": "service",
    "required": True,
}],

Dieses Fragment gehört in das agent-Dictionary. FOUNDRY_BRIDGE_TOKEN authentifiziert am eigenen MCP-Endpunkt; es ist kein OpenAI API Key. Der Dienst verwendet seinerseits Entra ID für Foundry. Mit required: True scheitert der Turn, wenn die MCP-Verbindung nicht initialisiert werden kann. MCP-Verbindungen und Authentifizierung

Erweitern Sie den Auftrag um: «Frage den Foundry-Spezialisten nach der freigegebenen Support-Richtlinie. Vergleiche die Kennzahlen damit und übernimm seine Quellen. Wenn keine belastbare Richtlinie vorliegt, kennzeichne den Vergleich als offen.»

Damit erledigt die Agents API die mehrstufige Arbeit und die Berichtserstellung. Foundry liefert eine abgegrenzte Fachauskunft. Prüfen Sie im Integrationstest beide Seiten: Hat der MCP-Aufruf stattgefunden, und enthält der Bericht die richtige Richtlinie mit nachvollziehbarer Quelle?

Wenn die Werkzeuge im privaten Azure-Netz bleiben sollen

Die Agents API unterstützt auch eigene Ausführungsumgebungen. Dort läuft codex exec-server und verbindet sich ausgehend mit OpenAI. MCP-Verbindungen können mit connection_origin: "environment" aus dieser Umgebung heraus aufgebaut werden. So lässt sich ein privater MCP-Dienst erreichen, sofern die Umgebung den passenden Netzwerkzugriff besitzt. Eigene Sandboxes, MCP-Verbindungswege

Eine solche Umgebung könnten Sie als eigenen Azure-Container betreiben. Das ist eine Architekturentscheidung, keine hier nachgewiesene native Foundry-Integration. OpenAI führt weiterhin die Agentensteuerung aus. Ein selbst gehosteter Executor bedeutet daher nicht, dass der gesamte Ablauf oder alle verarbeiteten Inhalte innerhalb Ihres Azure-Tenants bleiben.

Was vor dem produktiven Einsatz dazugehört

Die wichtigste fachliche Grenze liegt am Werkzeug. Unser Beispiel verwendet eine Dienstidentität. Diese übernimmt nicht automatisch die Rechte der Person, die den Auftrag gestellt hat. Für mandantenbezogene Daten muss der MCP-Dienst den authentifizierten Auftrag prüfen und die zulässige Datenmenge begrenzen.

Legen Sie ausserdem fest, welche Ergebnisse von Foundry zu OpenAI gelangen dürfen. Ein Quellenverweis ersetzt diese Entscheidung nicht. Für den ersten Pilot eignen sich freigegebene technische Richtlinien und synthetische Betriebsdaten.

Zu einem belastbaren Betriebsmodell gehören eine Auftrags-ID mit zugeordneter Session-ID, Fehlerbehandlung bei unterbrochenen Streams und eine Aufbewahrungsregel für Ergebnisse. Sichern Sie benötigte Dateien vor dem Löschen einer Session. Session-Verwaltung im Quickstart

Planen Sie die Kosten für beide Seiten der Architektur. OpenAI berechnet Modellnutzung, verwendete Tools und gegebenenfalls gehostete Sandboxes nach den jeweiligen Tarifen. Die Foundry-Aufrufe und der eigene MCP-Dienst kommen in diesem Entwurf hinzu. Messen Sie deshalb die Kosten pro abgeschlossenem Prüfauftrag. OpenAI-Abrechnungsmodell

Die neue Agents API ist besonders interessant für Aufgaben, die mehrere Schritte und überprüfbare Arbeitsergebnisse benötigen. Unser Beispiel lässt sich schrittweise ausbauen: zuerst ein reproduzierbarer Prüfbericht, dann eine klar begrenzte Fachauskunft aus Foundry und anschliessend die Einbindung in einen bestehenden Geschäftsprozess.

CNEXT unterstützt Sie dabei, einen passenden Anwendungsfall auszuwählen und die Verbindung zu Ihrer Microsoft-Umgebung umzusetzen. Kontakt mit CNEXT aufnehmen