Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Integrationen und Observability

Binde Funktionen über MCP ein und untersuche einzelne Durchläufe, bevor du den Workflow optimierst.

Sobald der Aufbau deines Workflows feststeht, kannst du entscheiden, welche externen Schnittstellen du in die Agentenschleife einbindest und wie du später nachvollziehst, was zur Laufzeit passiert ist.

Welche Funktionen gehören ins SDK?

Ziel Einstieg Warum?
Einem Agenten Zugriff auf öffentliche, remote gehostete MCP-Tools geben Gehostete MCP-Tools im SDK Das Modell kann den Remote-MCP-Server über die gehostete Schnittstelle aufrufen
Lokale oder private MCP-Server aus deiner Laufzeitumgebung anbinden Vom SDK verwaltete MCP-Server über stdio oder Streamable HTTP Deine Laufzeitumgebung verwaltet die Verbindung und die Genehmigungen und legt die Netzwerkgrenzen fest
Fehler in Prompts, Tools, Übergaben oder Genehmigungen finden Integriertes Tracing Mit Traces kannst du den gesamten Ablauf nachvollziehen, bevor du formale Evaluationen einführst

Welche Funktionen die einzelnen Tools bieten und wie sie sich verhalten, beschreibt der Leitfaden Tools verwenden. Hier erfährst du, wie du MCP im SDK anbindest und die Ausführung deines Workflows nachvollziehst.

MCP

Verwende gehostete MCP-Tools, wenn das Modell über seine Schnittstelle auf den Remote-Server zugreifen soll.

Einen gehosteten MCP-Server anbinden
import { Agent, hostedMcpTool } from "@openai/agents";

const agent = new Agent({
  name: "MCP assistant",
  instructions: "Use the MCP tools to answer questions.",
  tools: [
    hostedMcpTool({
      serverLabel: "gitmcp",
      serverUrl: "https://gitmcp.io/openai/codex",
    }),
  ],
});

Verwende lokale Transportmechanismen, wenn deine Anwendung die Verbindung zum MCP-Server direkt herstellen soll.

Verbindung zu einem lokalen MCP-Server herstellen
import { Agent, MCPServerStdio, run } from "@openai/agents";

const server = new MCPServerStdio({
  name: "Filesystem MCP Server",
  fullCommand:
    "npx -y @modelcontextprotocol/server-filesystem fixtures/sample_files",
});

await server.connect();

try {
  const agent = new Agent({
    name: "Filesystem assistant",
    instructions: "Read files with the MCP tools before answering.",
    mcpServers: [server],
  });

  const result = await run(agent, "Read the files and list them.");
  console.log(result.finalOutput);
} finally {
  await server.close();
}

Für die Auswahl gelten folgende Kriterien:

  • Verwende gehostetes MCP für öffentliche Remote-Server, die zum Vertrauensmodell der Plattform passen.
  • Verwende lokales oder privates MCP, wenn deine Laufzeitumgebung Verbindungen, Filterung oder Genehmigungen steuern soll.

Der Leitfaden MCP-Server ist die maßgebliche Referenz für das plattformweite MCP-Konzept, das Vertrauensmodell und die Unterstützung von MCP in den einzelnen Produkten.

Tracing

Tracing ist im Agents SDK integriert und bei der üblichen serverseitigen Ausführung standardmäßig aktiviert. Bei jedem Durchlauf kann das SDK Modellaufrufe, Tool-Aufrufe, Übergaben, Guardrails und benutzerdefinierte Spans strukturiert aufzeichnen. Diese Aufzeichnung kannst du im Traces-Dashboard einsehen.

Mit den Standardeinstellungen zeigt dir ein Trace in der Regel:

  • den gesamten Durchlauf oder Workflow
  • jeden einzelnen Modellaufruf
  • Tool-Aufrufe und ihre Ausgaben
  • Übergaben und Guardrails
  • alle benutzerdefinierten Spans, mit denen du den Workflow umschließt

Wenn du weniger Tracing benötigst, passe die Tracing-Einstellungen für das SDK oder für einzelne Durchläufe an. So kannst du den Workflow weiterhin beobachten.

Mehrere Durchläufe in einem Trace zusammenfassen
import { Agent, run, withTrace } from "@openai/agents";

const agent = new Agent({
  name: "Joke generator",
  instructions: "Tell funny jokes.",
});

await withTrace("Joke workflow", async () => {
  const first = await run(agent, "Tell me a joke");
  const second = await run(agent, `Rate this joke: ${first.finalOutput}`);
  console.log(first.finalOutput);
  console.log(second.finalOutput);
});

Traces helfen dir bei zwei Aufgaben:

  • Untersuche einen einzelnen Workflow-Durchlauf, um Fehler zu finden und nachzuvollziehen, was passiert ist.
  • Nutze besonders aussagekräftige Beispiele für die Evaluation von Agenten-Workflows, sobald du das Verhalten systematisch bewerten möchtest.

Nächste Schritte

Sobald du die externen Schnittstellen angebunden hast, wähle den passenden Leitfaden. Je nach Ziel kannst du Funktionen gestalten, festlegen, wann eine Prüfung erforderlich ist, oder deinen Workflow evaluieren.