Analyser les traces avec LangSmith et Langfuse
Lire les traces : identifier les outils lents, les mauvaises décisions et les schémas d’erreur.
Analyser les traces avec LangSmith et Langfuse est une leçon AI Agents gratuite sur CoddyKit. Ceci est la leçon 1 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage AI Agents, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours AI Agents comprend 4 leçons au total.
Pourquoi tracer votre agent ?
Les agents effectuent plusieurs appels au LLM et invocations d’outils à chaque exécution. Sans traçage, le débogage repose sur des suppositions. Le traçage enregistre chaque étape : entrées, sorties, utilisation de jetons, latence et erreurs — ce qui vous donne une vue complète de chaque exécution.
Configuration de LangSmith
LangSmith est la plateforme de traçage d’Anthropic pour LangChain. Activez-la en définissant deux variables d’environnement. Chaque appel LangChain est automatiquement tracé et visible dans l’interface LangSmith.
import os
from dotenv import load_dotenv
load_dotenv()
# LangSmith tracing configuration
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_API_KEY'] = os.environ.get('LANGSMITH_API_KEY', 'ls__...')
os.environ['LANGCHAIN_PROJECT'] = 'my-agent-project'
# Now any LangChain code is automatically traced
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
llm = ChatOpenAI(model='gpt-4o-mini', api_key=os.environ.get('OPENAI_API_KEY', 'sk-...'))
# This call is traced automatically
response = llm.invoke([HumanMessage(content='What is 2+2?')])
print(response.content)
# Check trace at: https://smith.langchain.comAjout de métadonnées aux exécutions
Ajoutez des balises et des métadonnées aux traces afin de pouvoir filtrer et effectuer des recherches dans l’interface LangSmith. C’est utile pour suivre différentes versions de l’agent, des identifiants utilisateur ou des libellés d’expériences.
import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langsmith import traceable
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_API_KEY'] = 'ls__your-key'
os.environ['LANGCHAIN_PROJECT'] = 'my-agent-project'
llm = ChatOpenAI(model='gpt-4o-mini', api_key='sk-...')
@traceable(name='my-agent-run', tags=['production', 'v2'], metadata={'user_id': '42'})
def run_agent(question: str) -> str:
response = llm.invoke(
[HumanMessage(content=question)],
config={
'run_name': f'agent-{question[:20]}',
'tags': ['production'],
'metadata': {'user_id': '42', 'version': 'v2.1'}
}
)
return response.content
result = run_agent('Explain LangChain tracing')
print(result)Affichage des traces dans l’interface LangSmith
Dans le tableau de bord LangSmith, vous pouvez voir chaque exécution avec son arbre de traces complet. Chaque nœud affiche les entrées, les sorties, le nombre de jetons, la latence et les éventuelles erreurs. Vous pouvez comparer les exécutions et filtrer par balise ou par projet.
- Filtrez par statut d’erreur pour trouver les exécutions ayant échoué
- Triez par latence pour identifier les étapes lentes
- Comparez deux exécutions côte à côte pour déboguer les régressions
# Programmatically query LangSmith for run data
from langsmith import Client
client = Client(api_key='ls__your-key')
# List recent runs for a project
runs = list(client.list_runs(
project_name='my-agent-project',
execution_order=1, # Top-level runs only
error=True, # Only failed runs
limit=10
))
for run in runs:
print(f'Run: {run.name}')
print(f' Status: {run.status}')
print(f' Latency: {run.end_time - run.start_time if run.end_time else "running"}')
print(f' Error: {run.error}')
print()Langfuse pour le traçage personnalisé
Langfuse est une alternative à LangSmith à code source ouvert. Il fonctionne avec n’importe quel framework LLM ou avec du code personnalisé. Utilisez le SDK Langfuse pour créer manuellement des traces et des spans.
from langfuse import Langfuse
lf = Langfuse(
public_key='pk-lf-...',
secret_key='sk-lf-...',
host='https://cloud.langfuse.com' # Or your self-hosted URL
)
# Create a trace
trace = lf.trace(
name='email-agent-run',
user_id='user-42',
metadata={'environment': 'production'}
)
# Create a span for entity extraction
span = trace.span(
name='entity-extraction',
input={'text': 'Meeting with Alice from Google tomorrow'}
)
# Simulate work
extracted = ['Alice', 'Google']
# End the span with output
span.end(output={'entities': extracted})
print('Trace created in Langfuse')
print(f'View at: https://cloud.langfuse.com/trace/{trace.id}')Traçage des appels LLM dans Langfuse
Créez un span generation pour chaque appel LLM. Celui-ci capture le modèle utilisé, l’invite, la complétion et le nombre de jetons — les données les plus importantes pour l’analyse des coûts.
from langfuse import Langfuse
import openai
lf = Langfuse(public_key='pk-lf-...', secret_key='sk-lf-...')
client = openai.OpenAI(api_key='sk-...')
def traced_llm_call(trace, prompt: str, model: str = 'gpt-4o-mini') -> str:
generation = trace.generation(
name='llm-call',
model=model,
input=[{'role': 'user', 'content': prompt}]
)
response = client.chat.completions.create(
model=model,
messages=[{'role': 'user', 'content': prompt}]
)
content = response.choices[0].message.content
generation.end(
output=content,
usage={
'prompt_tokens': response.usage.prompt_tokens,
'completion_tokens': response.usage.completion_tokens,
'total_tokens': response.usage.total_tokens
}
)
return content
trace = lf.trace(name='test-trace')
result = traced_llm_call(trace, 'What is the capital of France?')
print('Result:', result)Filtrage des exécutions par erreur et par latence
Utilisez le client LangSmith pour rechercher par programmation les exécutions problématiques. Filtrez par statut d’erreur, seuil de latence ou balises spécifiques afin de cibler vos efforts de débogage.
from langsmith import Client
from datetime import datetime, timedelta
client = Client(api_key='ls__your-key')
def find_slow_runs(project: str, latency_threshold_ms: int = 10000):
runs = list(client.list_runs(
project_name=project,
execution_order=1,
start_time=datetime.utcnow() - timedelta(hours=24)
))
slow_runs = []
for run in runs:
if run.end_time and run.start_time:
duration_ms = (run.end_time - run.start_time).total_seconds() * 1000
if duration_ms > latency_threshold_ms:
slow_runs.append({
'id': str(run.id),
'name': run.name,
'duration_ms': round(duration_ms),
'tags': run.tags
})
slow_runs.sort(key=lambda x: x['duration_ms'], reverse=True)
return slow_runs
print('Find slow runs function defined')
print('Usage: find_slow_runs("my-agent-project", latency_threshold_ms=5000)')Comparaison des exécutions
LangSmith vous permet de comparer deux exécutions dans son interface pour voir ce qui a changé. Par programmation, vous pouvez comparer les sorties, l’utilisation de jetons et la latence des exécutions afin de détecter les régressions après des modifications du modèle ou de l’invite.
from langsmith import Client
client = Client(api_key='ls__your-key')
def compare_runs(run_id_1: str, run_id_2: str) -> dict:
run1 = client.read_run(run_id_1)
run2 = client.read_run(run_id_2)
def get_tokens(run):
if run.total_tokens:
return run.total_tokens
return 0
def get_latency_ms(run):
if run.end_time and run.start_time:
return (run.end_time - run.start_time).total_seconds() * 1000
return 0
return {
'run1': {'id': run_id_1, 'tokens': get_tokens(run1), 'latency_ms': get_latency_ms(run1), 'status': run1.status},
'run2': {'id': run_id_2, 'tokens': get_tokens(run2), 'latency_ms': get_latency_ms(run2), 'status': run2.status},
'token_delta': get_tokens(run2) - get_tokens(run1),
'latency_delta_ms': get_latency_ms(run2) - get_latency_ms(run1)
}
print('Run comparison function defined')Ajout de scores et de commentaires
Après avoir évalué une exécution de l’agent, manuellement ou automatiquement, ajoutez un score ou un commentaire à la trace. Cela crée un jeu de données pour le réglage fin ou l’évaluation des modifications apportées à l’invite.
from langsmith import Client
client = Client(api_key='ls__your-key')
def score_run(run_id: str, score: float, reasoning: str = ''):
# score: 0.0 (bad) to 1.0 (perfect)
client.create_feedback(
run_id=run_id,
key='quality',
score=score,
comment=reasoning
)
def auto_evaluate_run(run_id: str, expected_output: str, actual_output: str) -> float:
# Simple heuristic: check if key terms from expected output are present
expected_terms = set(expected_output.lower().split())
actual_terms = set(actual_output.lower().split())
overlap = len(expected_terms & actual_terms) / max(len(expected_terms), 1)
score = min(1.0, overlap * 1.5) # Normalize
score_run(run_id, score, f'Term overlap: {overlap:.2f}')
return score
print('Scoring functions defined')
print('Example: score_run("run-id-abc", 0.85, "Good answer but missing one detail")')Contexte structuré des traces
Associez un contexte pertinent aux traces : identifiant de session, identifiant utilisateur, version de l’agent et indicateurs de fonctionnalités. Vous pourrez ainsi segmenter facilement les traces et comparer les performances entre différentes configurations.
import os
from langsmith import traceable
from langchain_core.runnables import RunnableConfig
def build_trace_config(user_id: str, session_id: str, version: str) -> dict:
return {
'metadata': {
'user_id': user_id,
'session_id': session_id,
'agent_version': version,
'environment': os.environ.get('ENV', 'development')
},
'tags': [version, os.environ.get('ENV', 'development')],
'run_name': f'agent-{user_id[:8]}'
}
@traceable
def run_agent_with_context(question: str, user_id: str, session_id: str):
config = build_trace_config(user_id, session_id, 'v2.3')
# Pass config to any LangChain component
# llm.invoke([HumanMessage(content=question)], config=config)
print(f'Running agent for user {user_id}, session {session_id}')
return 'Answer here'
result = run_agent_with_context('Question', 'user-001', 'sess-xyz')
print(result)Configuration des alertes
Surveillez l’état de santé de votre agent en configurant des alertes dans LangSmith ou Langfuse. Déclenchez une alerte lorsque le taux d’erreur dépasse un seuil, lorsque la latence P99 augmente fortement ou lorsqu’une étape spécifique échoue systématiquement.
from langsmith import Client
from datetime import datetime, timedelta
client = Client(api_key='ls__your-key')
def check_error_rate(project: str, window_minutes: int = 60, threshold: float = 0.05) -> dict:
runs = list(client.list_runs(
project_name=project,
execution_order=1,
start_time=datetime.utcnow() - timedelta(minutes=window_minutes)
))
if not runs:
return {'error_rate': 0.0, 'alert': False}
error_count = sum(1 for r in runs if r.status == 'error')
error_rate = error_count / len(runs)
if error_rate > threshold:
print(f'ALERT: Error rate {error_rate:.1%} exceeds threshold {threshold:.1%}')
# Send to Slack/PagerDuty here
return {
'total_runs': len(runs),
'error_count': error_count,
'error_rate': round(error_rate, 4),
'alert': error_rate > threshold
}
print('Error rate monitor defined')Vérification des connaissances : traçage
Testez votre compréhension du traçage des agents avec LangSmith et Langfuse.
Résumé du traçage
LangSmith et Langfuse sont des outils complémentaires : LangSmith s’intègre étroitement à LangChain et nécessite une configuration minimale, tandis que Langfuse fonctionne avec n’importe quel framework et vous offre davantage de contrôle. Tous deux enregistrent les entrées, les sorties, l’utilisation de jetons, la latence et les erreurs pour chaque étape de l’agent. Utilisez le filtrage, l’attribution de scores et les alertes pour maintenir la qualité de l’agent en production.
Questions Fréquemment Posées
La leçon « Analyser les traces avec LangSmith et Langfuse » est-elle gratuite ?
Oui — le texte complet de « Analyser les traces avec LangSmith et Langfuse » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours AI Agents, passe à CoddyKit PRO. Le cours AI Agents comprend 4 leçons au total.
Qu'est-ce que j'apprendrai dans « Analyser les traces avec LangSmith et Langfuse » ?
Lire les traces : identifier les outils lents, les mauvaises décisions et les schémas d’erreur. Tu pratiques AI Agents avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.
Dois-je avoir de l'expérience pour commencer AI Agents ?
Aucune expérience préalable n'est requise. AI Agents sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 1 sur 4.
Combien de temps prend la leçon « Analyser les traces avec LangSmith et Langfuse » ?
La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.
Peux-tu écrire et exécuter du code dans cette leçon AI Agents ?
Oui. Chaque leçon AI Agents inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.
Toutes les leçons de ce cours
- Analyser les traces avec LangSmith et Langfuse
- Profilage des jetons et des coûts à chaque étape
- Identifier les étapes lentes et coûteuses
- Analyse des causes profondes des défaillances d’agents