Erweitertes Funktionsaufrufen: Schemata und Validierung
Auf dieser Seite
Erweitertes Funktionsaufrufen: Schemata und Validierung
Funktionsaufrufe sind der Kernmechanismus, der einem Agenten ermöglicht, zu entscheiden, wann und wie er Ihre Tools aufruft. Die Deklaration eines Tools reicht für einen Prototypen aus, doch der Übergang in die Produktion erfordert, dass Sie Aufrufe einschränken, geschäftliche Werte validieren und Fehler behandeln, ohne den Agenten zum Absturz zu bringen. Genau das behandelt diese Lektion.
JSON-Schemata und strikter Modus
Die Responses API verwendet JSON-Schemata, um die Parameter für jedes Tool zu beschreiben, und der strikte Modus garantiert, dass das Modell dem Schema exakt folgt. Konkret schließt die Verwendung eines Enum oder eines Literal die Tür für erfundene Werte.
from agents import function_tool
from pydantic import BaseModel, Field
from typing import Literal
from enum import Enum
class Priority(str, Enum):
LOW = "low"
MEDIUM = "medium"
HIGH = "high"
CRITICAL = "critical"
class CreateTicket(BaseModel):
title: str = Field(description="Kurze Ticket-Überschrift (max. 100 Zeichen)")
description: str = Field(description="Ausführliche Problembeschreibung")
priority: Priority = Field(description="Prioritätsstufe des Tickets")
component: Literal["frontend", "backend", "infra", "data"] = Field(
description="Betroffene technische Komponente"
)
tags: list[str] = Field(
default_factory=list,
description="Optionale Tags zur Kategorisierung des Tickets"
)
@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
"""Erstellt ein neues technisches Support-Ticket."""
# In der Produktion: Aufruf von Jira, Linear, GitHub Issues usw.
return f"Ticket erstellt: [{ticket.priority.value}] {ticket.title} ({ticket.component})"
Mit dem standardmäßig aktivierten strikten Modus kann das Modell niemals einen ungültigen Prioritätswert oder eine Komponente außerhalb der erlaubten Liste senden. Sie müssen keinen defensiven Backend-Code schreiben, um Begriffe wie “urgent” oder “P1” in einen Wert zu übersetzen, den Ihr Ticketing-System erkennt.
Benutzerdefinierte Validierung mit Pydantic
Typüberprüfung verhindert unmögliche Werte, nicht aber absurde. Eine IBAN mit fünfzehn Zeichen ist ein völlig gültiger String; Ihre Geschäftslogik lehnt sie ab. Mit Pydantic können Sie diese Regeln direkt in das Schema einbetten.
from pydantic import BaseModel, Field, field_validator
class MoneyTransfer(BaseModel):
source_account: str = Field(description="IBAN des Quellkontos")
destination_account: str = Field(description="IBAN des Zielkontos")
amount: float = Field(gt=0, le=50000, description="Betrag in Euro (max. 50.000)")
reason: str = Field(min_length=5, max_length=200, description="Grund für die Überweisung")
@field_validator("source_account", "destination_account")
@classmethod
def validate_iban(cls, v):
if not v.startswith("FR"):
raise ValueError("Nur französische IBANs werden akzeptiert")
if len(v) != 27:
raise ValueError("IBAN muss 27 Zeichen enthalten")
return v
@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
"""Führt eine Banküberweisung zwischen zwei Konten aus."""
return f"Überweisung von €{transfer.amount} initiiert von {transfer.source_account[:8]}... zu {transfer.destination_account[:8]}..."
Die Einschränkungen gt=0 und le=50000 für den Betrag spielen auf einer anderen Ebene eine ähnliche Rolle: Sie machen eine negative Überweisung oder eine Überweisung, die das Limit überschreitet, strukturell unmöglich, unabhängig davon, wie der Nutzer die Anfrage formuliert.
Fehlerbehandlung in Tools
Was ist, wenn ein Tool ausgeführt wird, aber fehlschlägt? Die Versuchung besteht darin, die Ausnahme aufsteigen zu lassen; das ist ein Fehler, da dies den Agenten-Loop unterbricht. Stattdessen sollten Sie eine klare Fehlermeldung zurückgeben, die das Modell lesen und interpretieren kann.
import json
from agents import function_tool
@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
"""Abfragt eine externe API mit den angegebenen Parametern."""
try:
# In der Produktion: echter HTTP-Aufruf
import httpx
response = httpx.get(f"https://api.example.com/{endpoint}", params=parameters, timeout=10)
response.raise_for_status()
return json.dumps(response.json(), ensure_ascii=False)
except httpx.TimeoutException:
return json.dumps({
"error": True,
"message": f"Timeout beim Aufruf von {endpoint}. Bitte in einigen Momenten erneut versuchen."
})
except httpx.HTTPStatusError as e:
return json.dumps({
"error": True,
"message": f"HTTP-Fehler {e.response.status_code} bei {endpoint}.",
"details": str(e)
})
except Exception as e:
return json.dumps({
"error": True,
"message": f"Unerwarteter Fehler: {str(e)}"
})
Jeder Zweig formatiert die Nachricht in einer Sprache, die das Modell versteht. Bei einem Timeout wird der Agent einen weiteren Aufruf versuchen; bei einem HTTP 404-Fehler wird er den Benutzer informieren oder den Ansatz ändern, anstatt blind weiterzumachen.
Strukturierte Ausgabe für Tools
Diese Einschränkung gilt auch für die finale Ausgabe. Mit output_type ist final_output kein Text mehr zum Parsen, sondern ein typisiertes Objekt, das direkt vom aufrufenden Code verwendet werden kann.
from pydantic import BaseModel
from agents import Agent, Runner
class AnalysisResponse(BaseModel):
summary: str
key_points: list[str]
recommendation: str
confidence_score: float
agent = Agent(
name="Analyst",
instructions="Analysieren Sie die bereitgestellten Daten und erstellen Sie einen strukturierten Bericht.",
model="gpt-5.6-terra",
output_type=AnalysisResponse,
)
result = Runner.run_sync(agent, "Analysieren Sie die Umsatzentwicklungen des ersten Quartals 2026.")
# result.final_output ist vom Typ AnalysisResponse
print(f"Zusammenfassung: {result.final_output.summary}")
print(f"Punktzahl: {result.final_output.confidence_score}")
Muster: Tools mit gemeinsamem Kontext
Ein letztes wiederkehrendes Problem: Ihre Tools benötigen oft einen gemeinsamen Zustand – Benutzer-Sitzung, Datenbankverbindung, API-Schlüssel –, den es absurd wäre, über das Modell zu übergeben. Kontext löst dies, indem er diesen Zustand zusammen mit dem Gespräch übergeben wird.
from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool
@dataclass
class AppContext:
user_id: str
db_connection: object # Ihre Datenbankverbindung
api_key: str
@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
"""Ruft das Profil des aktuellen Benutzers ab."""
user_id = ctx.context.user_id
# Verwenden Sie ctx.context.db_connection für die Abfrage
return f"Benutzerprofil {user_id}: Premium, aktiv seit 2024"
agent = Agent(
name="Personalisierter Agent",
instructions="Sie unterstützen den angemeldeten Benutzer.",
tools=[get_user_profile],
)
context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "Was ist mein Profil?", context=context)
Das Tool hat keine geschäftlichen Parameter: Die Identität des Benutzers stammt aus dem Kontext, nicht aus dem Modell. Dies ist auch eine Sicherheitsmaßnahme, da der Agent das Profil einer anderen Person nicht durch Ändern eines Arguments einsehen kann.
Kernaussagen
- Pydantic-Schemata mit Enums und Literals garantieren die Gültigkeit von Aufrufen
- Feldvalidatoren fügen eine geschäftliche Validierung über die Typüberprüfung hinaus hinzu
- Geben Sie JSON-Fehlermeldungen zurück, anstatt in Tools Ausnahmen zu werfen
output_typezwingt den Agenten, seine finale Antwort zu strukturieren- Gemeinsamer Kontext (
RunContextWrapper) ermöglicht es Tools, auf den Anwendungszustand zuzugreifen