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.
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.
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.
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.
Erfahre, wie du neben MCP auch gehostete Tools, Funktionen und Agenten als Tools einsetzt.
Lege fest, wann sensible Funktionen eine Genehmigung oder Validierung erfordern.
Sobald sich das Verhalten stabilisiert hat, kannst du von einzelnen Traces zu wiederholbaren Bewertungen übergehen.