Zum Inhalt springen
1337skills 1337skills - Referenzen

OpenAI Agents SDK Cheatsheet

OpenAI Agents SDK Cheatsheet

Das OpenAI Agents SDK ist ein kleines, eigensinniges Python-Framework zum Erstellen von Agent-Apps. Es stellt vier Kernprimitiven zur Verfügung — Agents (ein LLM plus Anweisungen und Tools), Tools (Python-Funktionen oder gehostete Tools), Handoffs (Delegierung eines Laufs an einen anderen Agent) und Guardrails (Validierung von Ein- und Ausgaben) — mit Sessions für Speicher und Tracing integriert. Es ist Provider-flexibel, funktioniert aber standardmäßig mit OpenAI-Modellen.

Installation

SchrittBefehl
Installierenpip install openai-agents
Mit uvuv add openai-agents
Legen Sie den Schlüssel festexport OPENAI_API_KEY="sk-..."
Voice-Extraspip install "openai-agents[voice]"
Verifizierenpython -c "import agents; print(agents.__version__)"

Minimaler Agent

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a concise, helpful assistant.",
)

result = Runner.run_sync(agent, "Summarize the Unix philosophy in one line.")
print(result.final_output)
AufrufBeschreibung
Runner.run_sync(agent, input)Synchron ausführen
await Runner.run(agent, input)Asynchron ausführen
Runner.run_streamed(agent, input)Ereignisse streamen, während sie auftreten
result.final_outputDie endgültige Antwort des Agenten
result.new_itemsStrukturierte Laufelemente (Nachrichten, Tool-Aufrufe, Handoffs)

Tools

from agents import Agent, function_tool

@function_tool
def get_weather(city: str) -> str:
    """Return the weather for a city."""
    return f"Sunny in {city}"

agent = Agent(name="Weather", tools=[get_weather])
KonzeptBeschreibung
@function_toolVerwandle eine typisierte Python-Funktion in ein Tool (Schema wird automatisch aus der Signatur/Dokumentation generiert)
Gehostete ToolsIntegrierte Tools wie Web-Suche und Datei-Suche
tool_use_behaviorKontrollieren Sie, ob die Tool-Ausgabe den Zug beendet
Agents als Toolsagent.as_tool(...) macht einen Agent als aufrufbares Tool eines anderen Agenten verfügbar

Handoffs

from agents import Agent, handoff

billing = Agent(name="Billing", instructions="Handle billing questions.")
triage = Agent(
    name="Triage",
    instructions="Route the user to the right specialist.",
    handoffs=[billing],          # or handoff(billing, ...)
)

Handoffs übertragen das gesamte Gespräch an den empfangenden Agent innerhalb eines einzelnen Laufs; Eingabe-Guardrails gelten für den ersten Agent und Ausgabe-Guardrails für den Agent, der die endgültige Ausgabe produziert.

Guardrails

from agents import Agent, input_guardrail, GuardrailFunctionOutput

@input_guardrail
async def no_secrets(ctx, agent, user_input):
    tripped = "password" in user_input.lower()
    return GuardrailFunctionOutput(output_info={}, tripwire_triggered=tripped)

agent = Agent(name="Safe", input_guardrails=[no_secrets])
TypLäuftZweck
@input_guardrailVor dem AgentBenutzer-Eingabe validieren/filtern
@output_guardrailNach der endgültigen AusgabeValidiere die Antwort des Agenten
Tool-GuardrailsUm jeden Tool-AufrufÜberprüfe Eingaben/Ausgaben einzelner Tools
TripwireBei AuslösungWirft eine Exception, um den Lauf zu unterbrechen

Sessions (Speicher)

from agents import Agent, Runner, SQLiteSession

session = SQLiteSession("user-123", "conversations.db")
Runner.run_sync(agent, "My name is Nick.", session=session)
Runner.run_sync(agent, "What's my name?", session=session)  # remembers
SessionVerwendung
SQLiteSessionLokales/persistentes Gesprächsspeicher
In-Memory-SessionFlüchtiger Kontext innerhalb eines Prozesses
Benutzerdefinierte SessionImplementiere das Session-Protokoll für deinen eigenen Store

Tracing

FunktionBeschreibung
Automatische TracesJeder Runner.run erfasst Modellaufrufe, Tool-Aufrufe, Handoffs, Guardrail-Ergebnisse und Timing
DashboardTraces erscheinen unter Ihrem Projekt auf der OpenAI-Plattform
trace(...)Gruppiere mehrere Läufe in ein Workflow-Trace
Externe ProzessorenExportiere Spans zu Drittanbieter-Observability-Tools

Häufige Workflows

# Streaming von Token zu einer UI
import asyncio
from agents import Agent, Runner

async def main():
    agent = Agent(name="Writer", instructions="Write vividly.")
    streamed = Runner.run_streamed(agent, "Describe a thunderstorm.")
    async for event in streamed.stream_events():
        print(event)

asyncio.run(main())

Ressourcen