AI Agents · Lezione

Registrare chiamate agli strumenti e input/output

Scopra cosa acquisire a ogni passaggio: nome dello strumento, argomenti di input, output, latenza, errore e parent span id.

Lezione 2 di 413 passaggi

Registrare chiamate agli strumenti e input/output è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 2 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.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Che cosa registrare per ogni passaggio

Per ogni span, acquisisca:

  • Nome del passaggio (llm_call, tool_call, retrieve)
  • Input (messaggi, argomenti dello strumento, query)
  • Output (risposta, risultato dello strumento)
  • Metadati (modello, latenza, conteggio dei token, costo)
  • Informazioni sull'errore, se il passaggio non riesce

Helper per span scritto a mano

Senza un framework, un helper minimo:

from contextlib import contextmanager
import time, uuid

@contextmanager
def span(name, trace_id, parent_id=None):
    span_id = str(uuid.uuid4())
    start = time.time()
    record = {'trace_id': trace_id, 'span_id': span_id, 'parent_id': parent_id, 'name': name, 'start': start}
    try:
        yield record
    except Exception as e:
        record['error'] = str(e)
        raise
    finally:
        record['duration_ms'] = (time.time() - start) * 1000
        save_span(record)

Using It

trace_id = str(uuid.uuid4())
with span('llm_call_planner', trace_id) as s:
    s['model'] = 'gpt-4o-mini'
    s['messages_in'] = messages
    response = client.chat.completions.create(model='gpt-4o-mini', messages=messages)
    s['response'] = response.choices[0].message.content
    s['tokens_in'] = response.usage.prompt_tokens
    s['tokens_out'] = response.usage.completion_tokens

Annidamento degli span

Passi parent_id in modo ricorsivo affinché gli span formino un albero:

with span('agent_step', trace_id) as parent:
    with span('llm_call', trace_id, parent_id=parent['span_id']):
        ...
    with span('tool_call:search', trace_id, parent_id=parent['span_id']):
        ...

Registrazione delle chiamate agli strumenti

In particolare, per le chiamate agli strumenti registri:

  • Nome dello strumento
  • Argomenti (JSON)
  • Risultato (JSON, eventualmente troncato)
  • Latenza
  • Errore, se presente

Troncamento dei payload di grandi dimensioni

Alcuni risultati degli strumenti sono enormi (200 KB di HTML). Li tronchi prima di archiviarli:

def safe_payload(obj, max_chars=8000):
    s = json.dumps(obj)
    return s if len(s) <= max_chars else s[:max_chars] + '...[truncated]'

Redazione dei dati PII

Rimuova le informazioni personali prima di archiviarle:

import re
EMAIL_RE = re.compile(r'[\w\.-]+@[\w\.-]+')

def redact(text):
    return EMAIL_RE.sub('[email]', text)

print(redact("Contact me at alice@example.com for details."))

Output di log strutturato

Generi un record JSON per ogni span e lo inoltri a ELK, Loki, Datadog o BigQuery:

import json
import sys

def save_span(record):
    print(json.dumps(record), file=sys.stderr, flush=True)

demo_record = {'span': 'call_llm', 'duration_ms': 120, 'ok': True}
save_span(demo_record)
print("Logged span:", json.dumps(demo_record))

Correlare con le sessioni utente

Includa un session_id e un user_id in ogni span, così potrà filtrare in seguito le tracce per utente.

Campionamento

Per gli agenti ad alto volume, utilizzi il campionamento:

import random

def should_trace(user_id):
    return random.random() < 0.10  # 10% of traces
# Always trace errors and slow runs.

random.seed(42)
sampled = sum(should_trace(i) for i in range(1000))
print(f"Traced {sampled} out of 1000 calls (~10% target)")

Rieseguire dalle tracce

Salvi tutti gli input (messaggi, strumenti, argomenti), così potrà rieseguire una traccia con un nuovo prompt per testare i miglioramenti. Questa è la base dello sviluppo guidato dalle eval.

Troncare i payload voluminosi?

Perché troncare gli output voluminosi degli strumenti nei log?

Riepilogo

Ogni passaggio, ogni input, ogni output: strutturati, annidati e campionati. Questa è la materia prima per tutto il resto dell'osservabilità.

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

Domande Frequenti

La lezione «Registrare chiamate agli strumenti e input/output» è gratuita?

Sì — il testo completo di «Registrare chiamate agli strumenti e input/output» è 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 «Registrare chiamate agli strumenti e input/output»?

Scopra cosa acquisire a ogni passaggio: nome dello strumento, argomenti di input, output, latenza, errore e parent span id. 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 2 di 4.

Quanto tempo richiede la lezione «Registrare chiamate agli strumenti e input/output»?

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. Perché il tracing è necessario per gli agenti
  2. Registrare chiamate agli strumenti e input/output
  3. Latenza e costi per passaggio
  4. Visualizzare le esecuzioni degli agenti (Langfuse, LangSmith)
← Torna a AI Agents