跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
AI 与知识库

agent-observability

Instrumentation technique d'un agent IA — tracing distribué des appels LLM et outils, spans, métriques custom, corrélation de logs et dashboards de supervision. Pour les alertes et garde-fous de production, voir agent-monitoring-setup. Se déclenche avec "observabilité agent", "tracing agent", "LangSmith", "Langfuse", "OpenTelemetry agent", "spans LLM", "corréler les logs agent". Also triggers on "trace my agent", "LLM tracing", "agent spans".

khalilbenaz · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add khalilbenaz/claude-skills-collection --skill agent-observability

技能说明


name: agent-observability description: Instrumentation technique d'un agent IA — tracing distribué des appels LLM et outils, spans, métriques custom, corrélation de logs et dashboards de supervision. Pour les alertes et garde-fous de production, voir agent-monitoring-setup. Se déclenche avec "observabilité agent", "tracing agent", "LangSmith", "Langfuse", "OpenTelemetry agent", "spans LLM", "corréler les logs agent". Also triggers on "trace my agent", "LLM tracing", "agent spans".

Agent Observability

Workflow

1. Choisir la stratégie d'instrumentation

Identifie les trois piliers à couvrir selon le type d'agent :

Type d'agentTracesMétriques prioritairesLogs
Agent autonome (ReAct)Chaque itération reason→acttokens/iter, nb iterationsprompt + tool calls
Orchestrateur multi-agentsSpans parent→enfant par sous-agentlatence inter-agents, taux délégationhandoff payloads
Agent RAGRetrieval + LLM call séparésrecall@k, rerank score, latence retrievalquery + docs retenus
Pipeline séquentielUn span par étape du pipelinethroughput, erreurs par étapeinputs/outputs chaque step

Critère de décision : si tu as plus de 2 agents en chaîne → distributed tracing obligatoire. Agent isolé → métriques + logs structurés suffisent pour commencer.


2. Instrumenter avec OpenTelemetry

Installer le SDK Python ou TypeScript selon le runtime :

# Python
pip install opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-httpx

# TypeScript / Node
npm install @opentelemetry/sdk-node @opentelemetry/exporter-otlp-http @opentelemetry/instrumentation-http

Initialiser le tracer en entrée de l'agent (une seule fois) :

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider(resource=Resource({"service.name": "my-agent", "agent.version": "1.0"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-collector:4318")))
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)

Wrapper minimal autour des appels LLM :

def call_llm(prompt: str, model: str = "claude-sonnet-4-6") -> str:
    with tracer.start_as_current_span("llm.call") as span:
        span.set_attributes({
            "llm.model": model,
            "llm.prompt_tokens": count_tokens(prompt),
            "llm.prompt_hash": sha256(prompt)[:8],  # pas le texte en clair
        })
        response = client.messages.create(model=model, messages=[{"role": "user", "content": prompt}])
        span.set_attributes({
            "llm.completion_tokens": response.usage.output_tokens,
            "llm.cost_usd": estimate_cost(response.usage),
        })
        return response.content[0].text

Propager le context entre agents (HTTP) :

from opentelemetry.propagate import inject, extract

# Agent émetteur — injecter dans les headers
headers = {}
inject(headers)
requests.post("http://sub-agent/run", json=payload, headers=headers)

# Agent récepteur — extraire le context
ctx = extract(request.headers)
with tracer.start_as_current_span("sub_agent.run", context=ctx):
    ...

3. Définir les métriques custom agents IA

from opentelemetry import metrics

meter = metrics.get_meter("agent-metrics")

# Compteurs et histogrammes à créer
llm_tokens = meter.create_counter("agent.llm.tokens_total", unit="tokens")
llm_latency = meter.create_histogram("agent.llm.latency_ms", unit="ms")
tool_calls = meter.create_counter("agent.tool.calls_total")
tool_errors = meter.create_counter("agent.tool.errors_total")
task_iterations = meter.create_histogram("agent.task.iterations")
agent_cost = meter.create_counter("agent.cost_usd_total", unit="USD")

# Usage dans le code
llm_tokens.add(tokens, {"model": model, "agent_id": agent_id})
llm_latency.record(elapsed_ms, {"model": model})

Métriques critiques à ne pas oublier :

  • agent.task.success_rate — taux de tâches réussies (objectif vs résultat)
  • agent.loop.detected — compteur de boucles infinies détectées
  • agent.handoff.count — délégations entre agents (multi-agent)
  • agent.context_window.utilization — % de fenêtre contexte utilisé

4. Structurer les logs avec corrélation trace

import logging, json
from opentelemetry import trace

class AgentLogger:
    def __init__(self, name: str):
        self.logger = logging.getLogger(name)

    def _base(self, extra: dict) -> dict:
        span = trace.get_current_span()
        ctx = span.get_span_context()
        return {
            "trace_id": format(ctx.trace_id, "032x") if ctx.is_valid else None,
            "span_id": format(ctx.span_id, "016x") if ctx.is_valid else None,
            **extra,
        }

    def tool_call(self, tool: str, params: dict, result_summary: str):
        self.logger.info(json.dumps(self._base({
            "event": "tool.call",
            "tool": tool,
            "params_keys": list(params.keys()),  # pas les valeurs sensibles
            "result_summary": result_summary[:200],
        })))

    def decision(self, reason: str, action: str):
        self.logger.info(json.dumps(self._base({
            "event": "agent.decision",
            "reason": reason[:500],
            "action": action,
        })))

Règle de masquage PII : ne logguer que les clés des paramètres (pas les valeurs), tronquer les textes libres à 200-500 chars, ne jamais logguer tokens API, mots de passe, données personnelles.


5. Dashboards — panels essentiels

Grafana / Datadog — structure recommandée :

Panel 1 — Overview (last 1h)
  - Agents actifs (gauge)
  - Requêtes/min (time series)
  - Taux d'erreur % (stat + threshold rouge >5%)
  - Coût total estimé (stat)

Panel 2 — LLM Performance
  - Latence
阅读完整来源 ↗