Cheatsheet OpenAI Agents SDK
L’OpenAI Agents SDK è un piccolo framework Python orientato alla costruzione di app agentic. Espone quattro primitive core — Agents (un LLM più istruzioni e strumenti), Tools (funzioni Python o strumenti ospitati), Handoffs (delegare un’esecuzione a un altro agente), e Guardrails (convalidare input e output) — con Sessions per la memoria e Tracing integrati. È flessibile dal punto di vista del provider ma funziona subito con i modelli OpenAI.
Installation
| Passaggio | Comando |
|---|
| Installa | pip install openai-agents |
| Con uv | uv add openai-agents |
| Imposta la chiave | export OPENAI_API_KEY="sk-..." |
| Extras vocali | pip install "openai-agents[voice]" |
| Verifica | python -c "import agents; print(agents.__version__)" |
Agente minimo
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)
| Chiamata | Descrizione |
|---|
Runner.run_sync(agent, input) | Esegui in modo sincrono |
await Runner.run(agent, input) | Esegui in modo asincrono |
Runner.run_streamed(agent, input) | Esegui il flusso degli eventi mentre accadono |
result.final_output | La risposta finale dell’agente |
result.new_items | Elementi di esecuzione strutturati (messaggi, tool call, handoff) |
Strumenti
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])
| Concetto | Descrizione |
|---|
@function_tool | Trasforma una funzione Python tipizzata in uno strumento (schema auto-generato dalla firma/docstring) |
| Hosted tools | Built-in come web search e file search |
tool_use_behavior | Controlla se l’output dello strumento termina il turno |
| Agenti come strumenti | agent.as_tool(...) espone un agente come strumento richiamabile di un altro |
Handoff
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, ...)
)
Gli handoff trasferiscono la conversazione completa all’agente ricevente all’interno di una singola esecuzione; i guardrail di input si applicano al primo agente e quelli di output all’agente che produce l’output finale.
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])
| Tipo | Esecuzioni | Scopo |
|---|
@input_guardrail | Prima dell’agente | Convalida/schermatura input utente |
@output_guardrail | Dopo l’output finale | Convalida la risposta dell’agente |
| Tool guardrails | Attorno a ogni tool call | Controlla input/output dei singoli strumenti |
| Tripwire | All’attivazione | Solleva un’eccezione per interrompere l’esecuzione |
Sessions (Memory)
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
| Session | Utilizzo |
|---|
SQLiteSession | Memoria di conversazione locale/persistente |
| In-memory session | Contesto effimero all’interno di un processo |
| Custom session | Implementa il protocollo di sessione per il tuo store |
Tracing
| Funzione | Descrizione |
|---|
| Automatic traces | Ogni Runner.run registra chiamate di modelli, tool call, handoff, risultati di guardrail, e timing |
| Dashboard | Le tracce appaiono nel tuo progetto sulla piattaforma OpenAI |
trace(...) | Raggruppa più esecuzioni in una traccia di workflow |
| External processors | Esporta span a strumenti di osservabilità di terze parti |
Workflow comuni
# Streaming tokens a un'interfaccia utente
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())
Risorse
