SDK-Anatomie: Agent, Runner, Tool, Guardrail
Auf dieser Seite
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.
Agent — Das Gehirn
Definiert Anweisungen, Modell, Tools und Guardrails. Dies ist die Konfiguration Ihres Agents.
Runner — Die Ausführungsengine
Orchestriert den Denkzyklus: Sendet Anfragen, führt Tools aus und übernimmt Übergaben.
Tool — Fähigkeiten
Funktionen, die der Agent aufrufen kann: Websuche, Codeausführung, API-Aufrufe und mehr.
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 Agenteninstructions: Der Systemprompt, der das Verhalten definiertmodel: Das zu verwendende Modell (gpt-5.6-sol,gpt-5.6-terra,gpt-5.6-luna)tools: Die Liste der verfügbaren Toolshandoff_description: Beschreibung, die für Übergaben zwischen Agents verwendet wirdoutput_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:
- Sie rufen
Runner.run(agent, message)auf - Der Runner prüft die Eingabe-Guardrails
- Der Runner sendet die Nachricht an das Modell des Agents
- Wenn das Modell ein Tool anfordert, führt der Runner es aus
- Der Runner gibt das Ergebnis an das Modell zurück (zurück zu Schritt 3)
- Wenn das Modell eine finale Antwort erzeugt, prüft der Runner die Ausgabe-Guardrails
- Das
RunResultwird zurückgegeben
Wichtige Erkenntnisse
Agentdefiniert das Verhalten (Anweisungen, Modell, Tools)Runnerorchestriert 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
RunResultenthält die finale Antwort und die vollständige Historie