Agents SDK: Installazione e il tuo primo agente
In questa pagina
Agents SDK: Installazione e il tuo primo agente
Passiamo al codice. Installerai l’SDK ufficiale Agents di OpenAI, costruirai un agente Python funzionante ed esplorerai le tre modalità di esecuzione che utilizzerai durante tutto questo corso.
Prerequisiti
Ti servono solo tre cose: Python 3.10+ installato sulla tua macchina, un account OpenAI con una chiave API attiva e un editor di codice. Consigliamo VS Code, ma qualsiasi editor con evidenziazione della sintassi Python va bene.
Installazione
Il pacchetto si chiama openai-agents. Attenzione: installare solo openai ti fornisce il client API classico, non l’SDK Agents.
pip install openai-agents
Questo pacchetto installa automaticamente le dipendenze richieste, incluso l’SDK Python di OpenAI. Successivamente, imposta la tua chiave API come variabile d’ambiente. L’SDK la legge automaticamente, quindi non è necessaria alcuna configurazione aggiuntiva.
export OPENAI_API_KEY="sk-proj-your-api-key"
Questo comando scompare quando chiudi il terminale e certamente non vuoi hard-codare la tua chiave nei file sorgente. Per una configurazione corretta del progetto, usa un file .env con python-dotenv e aggiungi quel file al tuo .gitignore prima del primo commit.
pip install python-dotenv
# .env
OPENAI_API_KEY=sk-proj-your-api-key
Il tuo primo agente
Crea un file chiamato my_first_agent.py:
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant. Respond in English concisely.",
model="gpt-5.6-terra",
)
result = Runner.run_sync(agent, "Explain what an AI agent is in three sentences.")
print(result.final_output)
Eseguilo:
python my_first_agent.py
Hai appena creato ed eseguito il tuo primo agente. È semplice: niente strumenti, niente guardrail, ma costituisce la base per tutto il resto. Il resto di questo corso si basa semplicemente su questi due oggetti: Agent e Runner.
Esecuzione asincrona
run_sync blocca il thread corrente fino all’arrivo della risposta. Va bene per uno script di test, ma è inaccettabile per un server web che gestisce centinaia di richieste concorrenti. In produzione, utilizzerai la modalità asincrona.
import asyncio
from agents import Agent, Runner
agent = Agent(
name="Async Assistant",
instructions="You are a helpful assistant. Respond in English.",
model="gpt-5.6-terra",
)
async def main():
result = await Runner.run(agent, "What are the advantages of Python for AI?")
print(result.final_output)
asyncio.run(main())
Runner.run() è la versione asincrona; Runner.run_sync() è un wrapper sincrono che la chiama per te. Quando usi FastAPI o qualsiasi altro framework asincrono, usa sempre Runner.run().
Esecuzione in streaming
Esiste una terza modalità, essenziale ogni volta che un umano aspetta davanti allo schermo. Lo streaming visualizza la risposta man mano che viene generata, token per token.
import asyncio
from agents import Agent, Runner
agent = Agent(
name="Streaming Assistant",
instructions="You are a helpful assistant. Respond in English.",
model="gpt-5.6-terra",
)
async def main():
result = Runner.run_streamed(agent, "Tell a short story about AI.")
async for event in result.stream_events():
if event.type == "raw_response_event":
if hasattr(event.data, "delta") and event.data.delta:
print(event.data.delta, end="", flush=True)
print() # New line at the end
asyncio.run(main())
Il ciclo async for consuma un flusso di eventi. Qui filtriamo gli eventi di risposta grezza del modello e stampiamo solo i frammenti di testo. Lo streaming è fondamentale per l’esperienza utente: nessuno vuole fissare uno schermo vuoto per 10 secondi.
Struttura del progetto agente
Un agente di produzione non sta in un singolo file. Separa le definizioni degli agenti, gli strumenti e i test fin dall’inizio, altrimenti il tuo main.py diventerà rapidamente illeggibile.
my-agent-project/
├── .env # API key
├── requirements.txt # Dependencies
├── agents/
│ ├── __init__.py
│ ├── assistant.py # Agent definition
│ └── tools.py # Tool definitions
├── main.py # Entry point
└── tests/
└── test_agent.py # Tests
# requirements.txt
openai-agents>=0.1.0
python-dotenv>=1.0.0
Punti chiave
- Installa l’SDK con
pip install openai-agents - Imposta
OPENAI_API_KEYcome variabile d’ambiente - Usa
Runner.run_sync()per lo sviluppo eRunner.run()per la produzione asincrona - Usa
Runner.run_streamed()per lo streaming in tempo reale - Struttura il tuo progetto con cartelle separate per agenti, strumenti e test