Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Tools im SDK deklarieren

Lektion 6 von 25 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Tools im SDK deklarieren
  2. Der @function_tool-Decorator
  3. Name und Beschreibung anpassen
  4. Unterstützte Parametertypen
  5. Strukturierte Ergebnisse zurückgeben
  6. Von OpenAI gehostete Tools
  7. Kombination aus benutzerdefinierten und gehosteten Tools
  8. Kernaussagen

Tools im SDK deklarieren

Tools sind die konkreten Fähigkeiten Ihres Agenten. Ohne Tools kann ein Agent lediglich Text generieren; mit Tools kann er Datenbanken abfragen, APIs aufrufen und E-Mails versenden. Sie müssen diese Tools jedoch korrekt deklarieren, da die Qualität eines Tools nicht nur von seinem Code abhängt, sondern auch davon, wie gut das Modell ihn versteht.

Der @function_tool-Decorator

Der einfachste Weg, ein Tool zu erstellen, ist der @function_tool-Decorator, der eine Standard-Python-Funktion in eine Fähigkeit verwandelt, die der Agent aufrufen kann.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Sucht einen Kunden nach E-Mail-Adresse in der Datenbank.

    Args:
        email: Die E-Mail-Adresse des Kunden, nach der gesucht wird.
    """
    # In der Produktion: Ihre Datenbank aufrufen
    customers = {
        "[email protected]": {"name": "Alice Dupont", "plan": "Pro", "since": "2024"},
        "[email protected]": {"name": "Bob Martin", "plan": "Starter", "since": "2025"},
    }
    customer = customers.get(email)
    if customer:
        return f"Kunde gefunden: {customer['name']}, Plan {customer['plan']}, Kunde seit {customer['since']}"
    return f"Kein Kunde mit der E-Mail {email} gefunden"

Nichts wird doppelt deklariert: Das SDK verwendet den Funktionsnamen als Tool-Namen, den Docstring als Beschreibung und die Typ-Hinweise, um das JSON-Schema für die Parameter zu generieren. Mit anderen Worten: Ihr Docstring ist nicht mehr nur ein Kommentar für Ihre Kollegen; er ist der Text, den das Modell liest, um zu entscheiden, ob es diese Funktion aufrufen soll. Ein vager Docstring führt zu unpräzisen Aufrufen.

Name und Beschreibung anpassen

Wenn Ihr Funktionsname internen Konventionen folgt und nicht der Geschäftslogik, können Sie überschreiben, was das Modell sieht.

@function_tool(
    name_override="search_crm",
    description_override="Sucht einen Kunden im CRM nach E-Mail, Name oder Kontonummer."
)
def search_customer(identifier: str) -> str:
    """Sucht einen Kunden."""
    # ...
    return "Ergebnis"

Unterstützte Parametertypen

Neben nativen Python-Typen akzeptiert das SDK Pydantic-Modelle. Sobald ein Tool drei oder mehr Parameter annimmt, sollten Sie diese gruppieren: Das Schema wird für das Modell lesbarer, und die Validierung schützt Sie vor Ausreißerwerten.

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class SearchFilter(BaseModel):
    category: str = Field(description="Produktkategorie")
    max_price: Optional[float] = Field(None, description="Maximaler Preis in Euro")
    in_stock: bool = Field(True, description="Nur Produkte auf Lager")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Sucht Produkte basierend auf den angegebenen Kriterien."""
    results = []
    # Suchlogik unter Verwendung von filter.category, filter.max_price usw.
    return f"Es wurden {len(results)} Produkte in {filter.category} gefunden"

Pydantic-Modelle validieren Eingaben automatisch und liefern dem Modell reichhaltige, feldweise Beschreibungen.

Strukturierte Ergebnisse zurückgeben

Ein Tool gibt immer einen String zurück. Wenn Ihre Daten eine Struktur aufweisen – mehrere Metriken, eine Liste, gemischte Typen – sollten Sie diese als JSON serialisieren, anstatt einen Satz zu komponieren: Das Modell liest die Schlüssel deutlich zuverlässiger als freien Text.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Ruft Verkaufsstatistiken für einen bestimmten Monat ab."""
    stats = {
        "month": month,
        "year": year,
        "revenue": 145000,
        "sales_count": 342,
        "avg_basket": 423.98,
        "top_products": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
    }
    return json.dumps(stats, ensure_ascii=False, indent=2)

Von OpenAI gehostete Tools

Neben Ihren benutzerdefinierten Funktionen bietet das SDK Zugriff auf von OpenAI verwaltete Tools, die auf der Plattformseite ausgeführt werden.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="Allgemeiner Assistent",
    instructions="Sie sind ein Assistent, der in der Lage ist, im Internet zu suchen, Dateien zu analysieren und Code auszuführen.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool ermöglicht es dem Agenten, das Internet in Echtzeit zu durchsuchen und erfordert keine Konfiguration. FileSearchTool führt eine semantische Suche über Ihre Dateien durch, setzt jedoch eine vorherige Einrichtung voraus: Sie müssen einen Vektorspeicher über die OpenAI-API erstellen und Ihre Dokumente darin hochladen – daher wird vs_abc123 als Parameter übergeben. CodeInterpreterTool ermöglicht es dem Agenten, Python-Code in einer isolierten Container-Umgebung zu schreiben und auszuführen, was ihn zur ersten Wahl für Datenanalyse und Diagrammgenerierung macht. Es erfordert eine tool_config, die diesen Container spezifiziert: {"type": "auto"} erstellt ihn auf Abruf (das openai-agents-SDK lehnt CodeInterpreterTool() ohne diese Konfiguration ab).

Kombination aus benutzerdefinierten und gehosteten Tools

Die wahre Stärke liegt in der Kombination. Ein Finanzanalyst benötigt Ihre internen Daten, Berechnungsfähigkeiten und Marktkontext: drei Quellen, die kein einzelnes Tool abdeckt.

agent = Agent(
    name="Finanzanalyst",
    instructions="""Sie sind ein Finanzanalyst.
    Verwenden Sie interne Tools, um Daten abzurufen,
    den Code-Interpreter, um diese zu analysieren,
    und die Websuche für den Marktkontext.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Beachten Sie, wie die Anweisungen festlegen, wofür jede Tool-Familie dient. Ohne diese Klarheit zögert ein Agent mit vier Tools, versucht unnötigerweise zwei davon und erhöht die Latenz ohne Grund.

Kernaussagen

  • @function_tool verwandelt eine Python-Funktion in ein Agenten-Tool
  • Der Docstring und die Typ-Hinweise generieren automatisch das JSON-Schema
  • Verwenden Sie Pydantic für komplexe Parameter mit Validierung
  • Tools geben immer Strings zurück (JSON, wenn strukturiert)
  • Kombinieren Sie Ihre benutzerdefinierten Tools mit WebSearchTool, FileSearchTool und CodeInterpreterTool