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.
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_tokensAnnidamento 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à.
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
- Perché il tracing è necessario per gli agenti
- Registrare chiamate agli strumenti e input/output
- Latenza e costi per passaggio
- Visualizzare le esecuzioni degli agenti (Langfuse, LangSmith)