Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Agents SDK: Installazione e il tuo primo agente

Lezione 4 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Agents SDK: Installazione e il tuo primo agente
  2. Prerequisiti
  3. Installazione
  4. Il tuo primo agente
  5. Esecuzione asincrona
  6. Esecuzione in streaming
  7. Struttura del progetto agente
  8. Punti chiave

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_KEY come variabile d’ambiente
  • Usa Runner.run_sync() per lo sviluppo e Runner.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