Wie man das OpenAI Agents SDK verwendet?

```html

Das OpenAI Agents SDK ist eine Python-Bibliothek, die entwickelt wurde, um die Entwicklung von KI-Agenten, die von OpenAIs Sprachmodellen angetrieben werden, zu vereinfachen. Es stattet Entwickler mit Werkzeugen aus, um aufgabenspezifische Agenten zu erstellen, externe Funktionalitäten zu integrieren, die Aufgabenverteilung zwischen Agenten zu verwalten, die Eingabe-/Ausgabevalidierung durchzusetzen und Ausführungsabläufe zu überwachen. Dieser Leitfaden liefert eine detaillierte, technische Anleitung zur effektiven Installation, Konfiguration und Nutzung des SDK, wobei mindestens 2000 Wörter mit Schwerpunkt auf Präzision und praktischer Anwendung sichergestellt werden.

Einführung

Das OpenAI Agents SDK bietet einen strukturierten Rahmen für den Aufbau von Multi-Agenten-Systemen, bei denen jeder Agent auf die Ausführung bestimmter Aufgaben zugeschnitten ist. Diese Agenten können mit Benutzern interagieren, Aktionen über integrierte Tools ausführen und zusammenarbeiten, indem sie Aufgaben an andere Agenten weiterleiten. Zu den Hauptkomponenten des SDK gehören:

• Agenten: Instanzen von Sprachmodellen, die mit spezifischen Anweisungen und Rollen konfiguriert sind.
• Tools: Funktionen oder Dienste (z. B. Websuche, benutzerdefinierter Python-Code), die die Fähigkeiten der Agenten erweitern.
• Handoffs: Mechanismen, die es Agenten ermöglichen, Aufgaben nahtlos an andere Agenten zu delegieren.
• Guardrails: Validierungsebenen, um sicherzustellen, dass Eingaben und Ausgaben definierte Kriterien erfüllen.
• Tracing: Ausführungsprotokolle für das Debuggen und die Leistungsanalyse.

Dieser Leitfaden ist für Entwickler mit grundlegendem Verständnis von Python und API-Interaktionen konzipiert und bietet detaillierte Erklärungen, Codebeispiele und Best Practices, um eine robuste und umfassende Ressource zu erstellen.

Installation und Konfiguration

Die richtige Einrichtung ist entscheidend für die effektive Nutzung des OpenAI Agents SDK. Dieser Abschnitt behandelt Voraussetzungen, Umgebungseinrichtung, Installation und Verifizierung.

Voraussetzungen

Stellen Sie vor dem Fortfahren Folgendes sicher:

• Python 3.8+: Überprüfen Sie Ihre Python-Version mit python --version. Installieren Sie es bei Bedarf von python.org.

• OpenAI API Key: Erhalten Sie Ihren Schlüssel von platform.openai.com unter Ihren Kontoeinstellungen. Dieser Schlüssel authentifiziert Anfragen an die Server von OpenAI.

Schritt 1: Einrichten einer virtuellen Umgebung

Eine virtuelle Umgebung isoliert Projektabhängigkeiten und verhindert Konflikte mit anderen Python-Projekten. So erstellen und aktivieren Sie eine:

• Linux/macOS:

python -m venv agents_env
source agents_env/bin/activate

• Windows:

python -m venv agents_env
agents_env\Scripts\activate

Nach der Aktivierung sollte Ihre Eingabeaufforderung die Umgebung widerspiegeln (z. B. (agents_env)). Dieser Schritt ist eine Best Practice für die Python-Entwicklung und gewährleistet einen sauberen Arbeitsbereich.

Schritt 2: Installieren des SDK

Installieren Sie das SDK mit der aktiven virtuellen Umgebung mit pip:

pip install openai-agents

Dieser Befehl ruft die neueste Version des SDK und seine Abhängigkeiten von PyPI ab. Um die Installation zu bestätigen, führen Sie Folgendes aus:

pip show openai-agents-python

Dadurch werden Metadaten angezeigt, einschließlich der Versionsnummer, wodurch bestätigt wird, dass das Paket installiert ist.

Schritt 3: Konfigurieren des API-Schlüssels

Das SDK benötigt einen OpenAI API-Schlüssel, um zu funktionieren. Legen Sie ihn als Umgebungsvariable fest, um zu vermeiden, dass er in Ihren Code eingebettet wird, was die Sicherheit erhöht:

• Linux/macOS:

export OPENAI_API_KEY='your-api-key'

• Windows:

set OPENAI_API_KEY='your-api-key'

Um dies sitzungsübergreifend persistent zu machen, fügen Sie den Befehl zu Ihrer Shell-Konfigurationsdatei (z. B. .bashrc oder .zshrc auf Unix-Systemen) hinzu. Alternativ können Sie ihn programmgesteuert in Python festlegen, obwohl dies weniger sicher ist:

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

Schritt 4: Installation überprüfen

Testen Sie die Einrichtung mit einem minimalen Agenten, um sicherzustellen, dass alles funktioniert:

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # Expected output: "Setup successful"

Wenn dies "Setup successful" ausgibt, ist Ihre Installation funktionsfähig. Häufige Probleme sind:

• Ungültiger API-Schlüssel: Überprüfen Sie den Schlüssel noch einmal und stellen Sie sicher, dass keine zusätzlichen Leerzeichen oder Tippfehler vorhanden sind.
• Netzwerkfehler: Überprüfen Sie Ihre Internetverbindung und den Serverstatus von OpenAI.

Erstellen von Agenten

Agenten sind die grundlegenden Bausteine des SDK, die jeweils durch eine eindeutige Rolle und ein eindeutiges Verhalten definiert sind.

Agenteninitialisierung

Die Agent-Klasse wird verwendet, um Agenten zu instanziieren. Zu den wichtigsten Parametern gehören:

• name: Ein Zeichenfolgenbezeichner (z. B. "MathAgent").
• instructions: Eine Zeichenfolge, die den Zweck des Agenten angibt (z. B. "Mathematische Probleme lösen").
• model: Das zu verwendende OpenAI-Modell (Standard: gpt-4).
• temperature: Eine Gleitkommazahl zwischen 0 und 1, die die Ausgabezufälligkeit steuert (Standard: 0,7).

Beispiel: Einfacher Agent

Hier ist ein einfacher Agent für Arithmetik:

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # Output: "20"

Die Methode Runner.run_sync führt den Agenten synchron aus und gibt ein Ergebnisobjekt mit dem Attribut final_output zurück.

Erweiterte Konfiguration

Passen Sie Agenten für bestimmte Anforderungen an, indem Sie Parameter anpassen:

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # Output: A creative story

• Modell: gpt-4 bietet überlegenes Reasoning, während gpt-3.5-turbo für einfachere Aufgaben schneller und günstiger ist.
• Temperatur: Niedrigere Werte (z. B. 0,2) ergeben vorhersagbare Ausgaben; höhere Werte (z. B. 0,9) erhöhen die Kreativität.

Beispiel für mehrere Agenten

Erstellen Sie separate Agenten für verschiedene Aufgaben:

support_agent = Agent(
    name="SupportBot",
    instructions="Answer technical support questions."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Generate Python code snippets."
)

support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output)  # Output: Installation instructions
print(code_result.final_output)     # Output: "def add(a, b): return a + b"

Dies demonstriert die Flexibilität des SDK bei der Handhabung verschiedener Rollen.

Integrieren von Tools

Tools erweitern Agenten, indem sie ihnen ermöglichen, externe Aktionen auszuführen. Das SDK unterstützt gehostete Tools, benutzerdefinierte Funktions-Tools und agentenbasierte Tools.

Verwenden von gehosteten Tools

Gehostete Tools, wie z. B. web_search, sind vorgefertigt und einsatzbereit:

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using web search.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # Output: "The capital of France is Paris."

Der Agent ruft automatisch web_search auf, um Echtzeitdaten abzurufen.

Erstellen von benutzerdefinierten Funktions-Tools

Definieren Sie benutzerdefinierte Tools mit dem Dekorator @function_tool. Tools müssen Zeichenfolgen akzeptieren und zurückgeben.

Beispiel: Datenabruf-Tool

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Return data for the given ID."""
    # Simulated database lookup
    return f"Data for ID {id}: active"

agent = Agent(
    name="DataAgent",
    instructions="Retrieve data using the tool.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output)  # Output: "Data for ID 123: active"

Integrieren externer APIs

Tools können sich mit externen Diensten verbinden. Hier ist ein Wetter-Tool-Beispiel:

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    api_key = "your-weather-api-key"  # Replace with a real key
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"The weather in {city} is {data['current']['condition']['text']}."
    return "Weather data unavailable."

agent = Agent(
    name="WeatherAgent",
    instructions="Provide weather updates using the tool.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)  # Output: "The weather in Tokyo is Sunny." (example)

Melden Sie sich für einen kostenlosen API-Schlüssel unter weatherapi.com an, um dies zu testen.

Kombinieren mehrerer Tools

Agenten können mehrere Tools gleichzeitig verwenden:

@function_tool
def log_entry(text: str) -> str:
    """Log a message."""
    return f"Logged: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use tools to search and log.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output)  # Output includes search results and log confirmation

Agenten-Handoffs

Handoffs ermöglichen es Agenten, Aufgaben zu delegieren, wodurch komplexe Workflows ermöglicht werden.

Einrichten von Handoffs

Definieren Sie einen primären Agenten mit Zugriff auf sekundäre Agenten über den Parameter handoffs:

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Respond in English only."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Respond in Spanish only."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detect the language and hand off to the appropriate agent.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # Output: "¡Bien, gracias!" (or similar)

Der triage_agent analysiert die Eingabe und delegiert an den entsprechenden sprachspezifischen Agenten.

Handoff-Logik

Die Handoff-Entscheidung basiert auf den Anweisungen des primären Agenten. Zum Beispiel:

• "Wenn die Eingabe spanische Wörter enthält, übergeben Sie an SpanishHelper."
• "Verwenden Sie für englische Eingaben EnglishHelper."

Testen Sie mit einer englischen Eingabe:

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # Output: "I'm good, thanks!"

Geschachtelte Handoffs

Für tiefere Workflows können Agenten an andere Agenten mit Handoffs übergeben:

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Generate a report from analysis."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Start with analysis.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output)  # Output: A generated report

Implementieren von Guardrails

Guardrails erzwingen Einschränkungen für Eingaben und Ausgaben mithilfe von Pydantic-Modellen.

Definieren eines Guardrails

Erstellen Sie ein Modell, um die Ausgabestruktur zu validieren:

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine if the input is a question.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output)  # Output: {"is_question": true, "reason": "Ends with a question mark"}

Workflow-Integration

Verwenden Sie Guardrails, um Eingaben zu filtern:

task_agent = Agent(
    name="TaskProcessor",
    instructions="Process questions only.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output)  # Output indicates it’s not a question

Tracing und Debugging

Tracing protokolliert Agentenausführungsdetails, auf die über das OpenAI Dashboard zugegriffen werden kann.

Aktivieren des Tracings

Tracing erfolgt automatisch. Jeder Lauf generiert eine Trace mit:

• Eingabe-/Ausgabedaten
• Tool-Aufrufe
• Handoff-Ereignisse
• Fehler

Debugging-Beispiel

Wenn ein Agent fehlschlägt, überprüfen Sie die Trace, um Folgendes zu identifizieren:

• Falsche Tool-Parameter
• Handoff-Fehlleitung
• API-Fehler

Best Practices

Leistungsoptimierung

• Modellauswahl: Verwenden Sie gpt-3.5-turbo für Geschwindigkeit, gpt-4 für komplexes Reasoning.
• Temperatur: 0,2 für Präzision, 0,9 für Kreativität.
• Asynchrone Ausführung: Verwenden Sie Runner.run_async für parallele Aufgaben.

Fehlerbehandlung

• Tools: Geben Sie klare Fehlermeldungen zurück (z. B. "Ungültige ID").
• Handoffs: Fügen Sie einen Fallback-Agenten für Fehler ein.

Workflow-Design

• Modularität: Teilen Sie Aufgaben auf Agenten auf.
• Klarheit: Schreiben Sie eindeutige Anweisungen.
• Validierung: Wenden Sie Guardrails in wichtigen Phasen an.

Fazit

Das OpenAI Agents SDK ermöglicht es Entwicklern, anspruchsvolle KI-Systeme mit spezialisierten Agenten, integrierten Tools und kollaborativen Workflows zu erstellen. Dieser Leitfaden bietet eine technische Grundlage, um sein volles Potenzial auszuschöpfen, komplett mit Beispielen und Best Practices.

Was kommt also als Nächstes? Beginnen Sie mit dem Experimentieren! Spielen Sie mit verschiedenen Anweisungen, Tools und Workflows. Und wenn Sie auf ein Problem stoßen, können Tools wie Apidog beim API-Testen helfen – holen Sie es sich kostenlos.

```