Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Anatomia dell'SDK: Agent, Runner, Tool, Guardrail

Lezione 5 di 25 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Anatomia dell’SDK: Agent, Runner, Tool, Guardrail
  2. Agent: Configurazione
  3. Runner: Esecuzione
  4. Tool: Capacità
  5. Guardrail: Sicurezza
  6. Come interagiscono questi componenti
  7. Punti chiave

Anatomia dell’SDK: Agent, Runner, Tool, Guardrail

L’SDK Agents si basa su quattro concetti fondamentali: Agent, Runner, Tool e Guardrail. Ognuno ha una singola responsabilità. È la loro interazione — chi decide, chi esegue, chi agisce, chi controlla — a rendere l’SDK leggibile una volta che l’hai interiorizzato.

1

Agent — Il cervello

Definisce istruzioni, modello, strumenti e guardrail. Questa è la configurazione del tuo agente.

2

Runner — Il motore di esecuzione

Orchestra il ciclo di ragionamento: invia richieste, esegue strumenti e gestisce i passaggi di consegne (handoff).

3

Tool — Le capacità

Funzioni che l'agente può chiamare: ricerca web, esecuzione di codice, chiamate API e altro.

4

Guardrail — Sicurezza

Convalida input e output dell'agente. Blocca richieste pericolose o fuori tema.

Agent: Configurazione

La classe Agent è puramente dichiarativa: non esegue nulla, ma descrive. Tutto ciò che definisce il comportamento del tuo agente risiede in un unico luogo.

from agents import Agent, function_tool, WebSearchTool

@function_tool
def get_price(product: str) -> str:
    """Retrieves the price of a product."""
    prices = {"widget": "€29.99", "gadget": "€49.99"}
    return prices.get(product, "Unknown product")

agent = Agent(
    name="Sales Agent",
    instructions="""You are a sales agent for an online store.
    Help customers find products and learn their prices.
    Always respond in French with a professional tone.""",
    model="gpt-5.6-terra",
    tools=[get_price, WebSearchTool()],
    handoff_description="Agent specialized in selling products",
    output_type=None,  # or a Pydantic type to enforce an output format
)

Parametri chiave di Agent:

  • name: Identificatore leggibile dall’uomo per l’agente
  • instructions: Il prompt di sistema che definisce il comportamento
  • model: Il modello da utilizzare (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna)
  • tools: L’elenco degli strumenti disponibili
  • handoff_description: Descrizione utilizzata per i passaggi di consegna tra agenti
  • output_type: Tipo Pydantic per strutturare l’output

Runner: Esecuzione

Il Runner è il motore che esegue il tuo agente. Gestisce l’intero ciclo e si presenta in tre modalità a seconda del contesto di chiamata.

from agents import Runner

# Modalità sincrona (sviluppo)
result = Runner.run_sync(agent, "What is the price of the widget?")

# Modalità asincrona (produzione)
result = await Runner.run(agent, "What is the price of the widget?")

# Modalità streaming (tempo reale)
result = Runner.run_streamed(agent, "What is the price of the widget?")

Indipendentemente dalla modalità, ottieni un oggetto RunResult, che contiene molto più della semplice risposta visualizzabile. La cronologia completa ti permette di riprendere una conversazione, e last_agent diventa essenziale non appena più agenti si passano il compito l’un l’altro.

result = Runner.run_sync(agent, "What is the price of the widget?")

# La risposta finale dell'agente
print(result.final_output)

# La cronologia completa della conversazione
print(result.to_input_list())

# L'ultimo agente attivo (utile con gli handoff)
print(result.last_agent.name)

Tool: Capacità

L’SDK supporta tre modi per dichiarare gli strumenti, dal più comune al più architetturale.

1. Strumenti funzione (più comuni)

Una funzione Python decorata diventa uno strumento; l’SDK deduce lo schema dalla firma e dal docstring.

from agents import function_tool

@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
    """Sends an email to a recipient."""
    # Your sending logic here
    return f"Email sent to {recipient}"

2. Strumenti ospitati da OpenAI

Questi strumenti vengono eseguiti lato OpenAI: non scrivi tu la logica di ricerca né la sandbox Python.

from agents import WebSearchTool, FileSearchTool, CodeInterpreterTool

tools = [
    WebSearchTool(),                               # Web search
    FileSearchTool(vector_store_ids=["vs_123"]),   # File search
    CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),                          # Code execution
]

3. Agenti come strumenti

Un agente può utilizzarne un altro come strumento. Il coordinatore sottostante delega la ricerca senza mai cedere il controllo della conversazione, il che distingue questo approccio da un handoff.

search_agent = Agent(
    name="Researcher",
    instructions="You look up precise information.",
    tools=[WebSearchTool()],
)

primary_agent = Agent(
    name="Coordinator",
    instructions="You coordinate research.",
    tools=[search_agent.as_tool(
        tool_name="search",
        tool_description="Performs in-depth research"
    )],
)

Guardrail: Sicurezza

Un guardrail è un agente di controllo posizionato davanti al tuo agente di business. Qui, un verificatore controlla se la richiesta rientra nell’ambito delle vendite prima che l’agente di vendita risponda.

from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner

guardrail_agent = Agent(
    name="Verifier",
    instructions="Determine whether the request concerns sales. Respond true or false.",
    output_type=bool,
)

async def verify_topic(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=not result.final_output,
    )

protected_agent = Agent(
    name="Protected Sales Agent",
    instructions="You are a sales agent.",
    input_guardrails=[
        InputGuardrail(guardrail_function=verify_topic),
    ],
)

Se il guardrail scatta (tripwire_triggered=True), l’esecuzione si interrompe e viene sollevata un’eccezione InputGuardrailTripwireTriggered. Pianifica di catturarla nella tua applicazione; altrimenti, restituirai un errore 500 a un utente che ha semplicemente posto una domanda fuori tema.

Come interagiscono questi componenti

Il flusso completo si svolge come segue:

  1. Chiami Runner.run(agent, message)
  2. Il Runner verifica i guardrail di input
  3. Il Runner invia il messaggio al modello dell’Agent
  4. Se il modello richiede uno strumento, il Runner lo esegue
  5. Il Runner restituisce il risultato al modello (torna al passaggio 3)
  6. Quando il modello produce una risposta finale, il Runner verifica i guardrail di output
  7. Viene restituito il RunResult

Punti chiave

  • Agent definisce il comportamento (istruzioni, modello, strumenti)
  • Runner orchestra l’esecuzione del ciclo dell’agente
  • Dichiara gli strumenti con @function_tool, classi integrate o .as_tool()
  • I Guardrail convalidano input e output per la sicurezza
  • RunResult contiene la risposta finale e la cronologia completa