Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

SDK-Anatomie: Agent, Runner, Tool, Guardrail

Lektion 5 von 25 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. SDK-Anatomie: Agent, Runner, Tool, Guardrail
  2. Agent: Konfiguration
  3. Runner: Ausführung
  4. Tool: Fähigkeiten
  5. Guardrail: Sicherheit
  6. Wie diese Bausteine interagieren
  7. Wichtige Erkenntnisse

SDK-Anatomie: Agent, Runner, Tool, Guardrail

Das Agents SDK basiert auf vier Kernkonzepten: Agent, Runner, Tool und Guardrail. Jedes Konzept hat eine einzige Verantwortung. Ihre Wechselwirkung – wer entscheidet, wer ausführt, wer handelt und wer kontrolliert – macht das SDK erst lesbar, sobald Sie diese Dynamik verinnerlicht haben.

1

Agent — Das Gehirn

Definiert Anweisungen, Modell, Tools und Guardrails. Dies ist die Konfiguration Ihres Agents.

2

Runner — Die Ausführungsengine

Orchestriert den Denkzyklus: Sendet Anfragen, führt Tools aus und übernimmt Übergaben.

3

Tool — Fähigkeiten

Funktionen, die der Agent aufrufen kann: Websuche, Codeausführung, API-Aufrufe und mehr.

4

Guardrail — Sicherheit

Validiert Eingaben und Ausgaben des Agents. Blockiert gefährliche oder vom Thema abweichende Anfragen.

Agent: Konfiguration

Die Agent-Klasse ist rein deklarativ: Sie führt nichts aus, sie beschreibt lediglich. Alles, was das Verhalten Ihres Agents definiert, befindet sich an einer einzigen Stelle.

from agents import Agent, function_tool, WebSearchTool

@function_tool
def get_price(product: str) -> str:
    """Ruft den Preis eines Produkts ab."""
    prices = {"widget": "€29.99", "gadget": "€49.99"}
    return prices.get(product, "Unbekanntes Produkt")

agent = Agent(
    name="Sales Agent",
    instructions="""Sie sind ein Verkaufsagent für einen Online-Shop.
    Helfen Sie Kunden, Produkte zu finden und deren Preise zu ermitteln.
    Antworten Sie stets auf Französisch in einem professionellen Ton.""",
    model="gpt-5.6-terra",
    tools=[get_price, WebSearchTool()],
    handoff_description="Agent, der sich auf den Verkauf von Produkten spezialisiert hat",
    output_type=None,  # oder ein Pydantic-Typ, um ein Ausgabeformat durchzusetzen
)

Wichtige Agent-Parameter:

  • name: Menschlich lesbare Kennzeichnung für den Agenten
  • instructions: Der Systemprompt, der das Verhalten definiert
  • model: Das zu verwendende Modell (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: Die Liste der verfügbaren Tools
  • handoff_description: Beschreibung, die für Übergaben zwischen Agents verwendet wird
  • output_type: Pydantic-Typ, um die Ausgabe zu strukturieren

Runner: Ausführung

Der Runner ist die Engine, die Ihren Agenten ausführt. Er verwaltet den gesamten Zyklus und bietet je nach Aufrufkontext drei Modi.

from agents import Runner

# Synchroner Modus (Entwicklung)
result = Runner.run_sync(agent, "Was kostet das Widget?")

# Asynchroner Modus (Produktion)
result = await Runner.run(agent, "Was kostet das Widget?")

# Streaming-Modus (Echtzeit)
result = Runner.run_streamed(agent, "Was kostet das Widget?")

Unabhängig vom Modus erhalten Sie ein RunResult zurück, das weit mehr als die anzeigbare Antwort enthält. Die vollständige Historie ermöglicht es, einen Gesprächsverlauf fortzusetzen, und last_agent wird essenziell, sobald mehrere Agents untereinander Übergaben vornehmen.

result = Runner.run_sync(agent, "Was kostet das Widget?")

# Die finale Antwort des Agents
print(result.final_output)

# Die vollständige Gesprächshistorie
print(result.to_input_list())

# Der zuletzt aktive Agent (nützlich bei Übergaben)
print(result.last_agent.name)

Tool: Fähigkeiten

Das SDK unterstützt drei Möglichkeiten, Tools zu deklarieren, sortiert von der häufigsten zur architektonischsten Variante.

1. Funktionstools (häufigste Variante)

Eine mit einem Dekorator versehene Python-Funktion wird zu einem Tool; das SDK leitet das Schema aus der Signatur und der Docstring ab.

from agents import function_tool

@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
    """Sendet eine E-Mail an einen Empfänger."""
    # Ihre Logik zum Senden hier
    return f"E-Mail an {recipient} gesendet"

2. Von OpenAI gehostete Tools

Diese Tools werden auf der Seite von OpenAI ausgeführt: Sie schreiben keine Suchlogik oder keinen Python-Sandbox.

from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool

tools = [
    WebSearchTool(),                               # Websuche
    FileSearchTool(vector_store_ids=["vs_123"]),   # Dateisuche
    CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),                          # Codeausführung
]

3. Agents als Tools

Ein Agent kann einen anderen Agenten als Tool verwenden. Der Koordinator unten delegiert die Recherche, ohne jemals die Kontrolle über das Gespräch abzugeben, was dies von einer Übergabe unterscheidet.

search_agent = Agent(
    name="Researcher",
    instructions="Sie ermitteln präzise Informationen.",
    tools=[WebSearchTool()],
)

primary_agent = Agent(
    name="Coordinator",
    instructions="Sie koordinieren die Recherche.",
    tools=[search_agent.as_tool(
        tool_name="search",
        tool_description="Führt vertiefte Recherchen durch"
    )],
)

Guardrail: Sicherheit

Ein Guardrail ist ein Kontrollagent, der vor Ihrem Business-Agenten platziert wird. Hier prüft ein Verifizierer, ob die Anfrage in den Bereich des Verkaufs fällt, bevor der Verkaufsagent antwortet.

from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner

guardrail_agent = Agent(
    name="Verifier",
    instructions="Bestimmen Sie, ob die Anfrage den Verkauf betrifft. Antworten Sie mit true oder false.",
    output_type=bool,
)

async def verify_topic(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=not result.final_output,
    )

protected_agent = Agent(
    name="Protected Sales Agent",
    instructions="Sie sind ein Verkaufsagent.",
    input_guardrails=[
        InputGuardrail(guardrail_function=verify_topic),
    ],
)

Wenn der Guardrail auslöst (tripwire_triggered=True), wird die Ausführung gestoppt und eine InputGuardrailTripwireTriggered-Ausnahme geworfen. Planen Sie vor, dies in Ihrer Anwendung abzufangen; andernfalls geben Sie einem Benutzer, der einfach eine vom Thema abweichende Frage stellt, einen 500-Fehler zurück.

Wie diese Bausteine interagieren

Der vollständige Ablauf läuft wie folgt ab:

  1. Sie rufen Runner.run(agent, message) auf
  2. Der Runner prüft die Eingabe-Guardrails
  3. Der Runner sendet die Nachricht an das Modell des Agents
  4. Wenn das Modell ein Tool anfordert, führt der Runner es aus
  5. Der Runner gibt das Ergebnis an das Modell zurück (zurück zu Schritt 3)
  6. Wenn das Modell eine finale Antwort erzeugt, prüft der Runner die Ausgabe-Guardrails
  7. Das RunResult wird zurückgegeben

Wichtige Erkenntnisse

  • Agent definiert das Verhalten (Anweisungen, Modell, Tools)
  • Runner orchestriert die Ausführung des Agentenzyklus
  • Tools deklarieren Sie mit @function_tool, eingebaute Klassen oder .as_tool()
  • Guardrails validieren Eingaben und Ausgaben für die Sicherheit
  • RunResult enthält die finale Antwort und die vollständige Historie