PricingLoginStart free
AI Agents · Lezione

Restituire i risultati al modello

Formatti gli output degli strumenti come messaggi con ruolo tool, così che il modello possa leggerli e proseguire la conversazione.

Lezione 4 di 413 passaggi

Restituire i risultati al modello è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Il messaggio del risultato dello strumento

Dopo aver eseguito uno strumento, comunichi al modello l'esito con un messaggio dello strumento:

messages.append({
    'role': 'tool',
    'tool_call_id': tool_call.id,    # MUST match the assistant's tool_call.id
    'content': json.dumps(result)
})

Il contenuto deve essere una stringa

OpenAI si aspetta che content sia una stringa. Serializzi gli oggetti con json.dumps:

# Bad — will error
messages.append({'role': 'tool', 'tool_call_id': id, 'content': {'temp': 18}})

# Good
messages.append({'role': 'tool', 'tool_call_id': id, 'content': '{"temp": 18}'})

Formato Anthropic

Anthropic usa un blocco di contenuto all'interno di un messaggio dell'utente:

messages.append({
    'role': 'user',
    'content': [{
        'type': 'tool_result',
        'tool_use_id': 'toolu_abc',
        'content': json.dumps(result)
    }]
})

Restituzione degli errori

Se lo strumento non è riuscito, restituisca l'errore: non finga che abbia avuto successo. Il modello può recuperare:

try:
    result = run_tool(...)
    content = json.dumps({'ok': True, 'data': result})
except Exception as e:
    content = json.dumps({'ok': False, 'error': str(e)})

messages.append({'role': 'tool', 'tool_call_id': id, 'content': content})

Pattern multi-risultato

Per le chiamate parallele agli strumenti, aggiunga ogni risultato con l'ID corrispondente:

for tc in message.tool_calls:
    result = dispatch(tc)
    messages.append({
        'role': 'tool',
        'tool_call_id': tc.id,
        'content': json.dumps(result)
    })

Output di grandi dimensioni: riepilogare

Se uno strumento restituisce 100 KB di HTML, inviarlo tutto al modello spreca token e diluisce l'attenzione. Prima lo riepiloghi o lo tronchi:

def truncate(text, max_chars=4000):
    if len(text) <= max_chars:
        return text
    return text[:max_chars] + f'\n...[truncated, {len(text)-max_chars} more chars]'

sample = "x" * 4500
result = truncate(sample, max_chars=50)
print(result)

Schema sempre uguale

Anche quando i risultati variano (successo / errore / non trovato), mantenga stabile lo schema dell'output. Il modello è più affidabile con strutture coerenti:

from typing import TypedDict, Literal, Optional, Any

class ToolResult(TypedDict):
    status: Literal['ok', 'not_found', 'error']
    data: Optional[Any]
    error: Optional[str]

def make_result(status, data=None, error=None) -> ToolResult:
    return {'status': status, 'data': data, 'error': error}

print(make_result('ok', data={'temp': 72}))
print(make_result('not_found', error='city not found'))

Includere suggerimenti nei metadati

Aiuti il modello a interpretare i risultati includendo suggerimenti nel contenuto:

content = json.dumps({
    'data': rows,
    'note': 'Returned 50 rows (most recent first). There may be more matches.'
})

Dati binari

Non inserisca grandi blocchi binari codificati in base64 nei messaggi degli strumenti. Li salvi invece nell'archiviazione e restituisca un URL o un ID:

result = {
    'image_path': '/tmp/chart-abc.png',
    'thumbnail_url': 'https://...',
    'caption': 'Sales by quarter, 2024'
}
for k, v in result.items():
    print(f"{k}: {v}")

Richiamare nuovamente il modello nel ciclo

Dopo aver aggiunto tutti i risultati degli strumenti, richiami il modello: produrrà una risposta finale oppure chiamerà altri strumenti:

class Msg:
    def __init__(self, tool_calls=None, content=None):
        self.tool_calls = tool_calls or []
        self.content = content

class ToolCall:
    def __init__(self, name, args):
        self.name = name
        self.args = args

def call_model(messages, tools):
    if len(messages) < 4:
        return Msg(tool_calls=[ToolCall('get_weather', {'city': 'Paris'})])
    return Msg(content='It is sunny in Paris.')

messages = [{'role': 'user', 'content': 'Weather in Paris?'}]
tools = ['get_weather']
message = call_model(messages, tools)

while message.tool_calls:
    for tc in message.tool_calls:
        result = f'Result of {tc.name}({tc.args})'
        messages.append({'role': 'tool', 'name': tc.name, 'content': result})
        print('Tool call:', tc.name, '->', result)
    message = call_model(messages, tools)

print('Final answer:', message.content)

Verifica degli output degli strumenti

Registri ogni coppia (tool_call_id, args, result) per il debugging. Quando un agente fa qualcosa di strano, il log dei risultati degli strumenti è il primo posto da controllare.

Formato del risultato dello strumento

A cosa si riferisce tool_call_id in un messaggio dello strumento?

Rispondi nella lezione interattiva

Riepilogo

Ora conosce l'intero ciclo completo delle chiamate agli strumenti. Prossimo corso: la memoria, il terzo pilastro degli agenti.

Gratis per iniziare

Impara AI Agents con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi
60
Lezioni
239
Inizia a imparare gratisVisualizza il corso completo

Domande Frequenti

La lezione «Restituire i risultati al modello» è gratuita?

Sì — il testo completo di «Restituire i risultati al modello» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Restituire i risultati al modello»?

Formatti gli output degli strumenti come messaggi con ruolo tool, così che il modello possa leggerli e proseguire la conversazione. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Restituire i risultati al modello»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Come funziona il function calling
  2. Definire gli schemi degli strumenti (JSON Schema)
  3. Scegliere gli strumenti a runtime
  4. Restituire i risultati al modello
← Torna a AI Agents