Mergulho Profundo no MCP, Parte 10: Quando o Agente Está Off — Depuração e Observabilidade para MCP em Produção

Uma API web falha de forma barulhenta: um 500, um rastreamento de pilha, um alerta. Um agente falha silenciosamente. Ele não trava — ele silenciosamente leva seis turnos em vez de dois, chama a ferramenta errada, gasta o triplo dos tokens e retorna uma resposta que está sutilmente errada. Nada disso lança uma exceção, e nada disso aparece nos logs de qualquer solicitação única.

Esta é a Parte 10 de uma série de 15 partes sobre o Protocolo de Contexto de Modelo (MCP). A Parte 3 deu a cada chamada de ferramenta um intervalo no servidor; esta parte junta tudo isso na imagem completa — uma execução de agente através do host, do modelo e de todos os três servidores, correlacionados para que, quando algo parecer errado, você tenha uma resposta em vez de um encolher de ombros.

Uma execução de agente, como um rastreamento

agent.run  (tenant, goal)                                       [==================] 1.8s
|
+- agent.turn 0                                                 [======]
|    +- agent.model_call  (plan)                                [===]
|    +- tool.get_campaign_kpis  -> mattrx-analytics             [==]   120ms
|    +- tool.query_events       -> mattrx-analytics             [===]  180ms
|
+- agent.turn 1                                                 [=====]
|    +- agent.model_call  (synthesize)                          [====]
|    +- tool.create_report      -> mattrx-reports (enqueue)     [=]    90ms
|
+- eval gate 0.93 (pass) -> resposta final

1. Correlacione toda a execução com um id de rastreamento

Inicie um intervalo raiz por execução de agente e propague seu contexto através do transporte MCP, para que os intervalos de cada servidor estejam aninhados sob ele.

public async Task<AgentAnswer> RunAsync(AiPrincipal p, string goal, CancellationToken ct)
{
    using var run = ActivitySource.StartActivity("agent.run");   // o intervalo raiz para toda a execução
    run?.SetTag("mattrx.tenant", p.TenantId);
    run?.SetTag("agent.goal", Redact(goal));

    // OTel context se propaga pelo transporte MCP (traceparent) -> cada intervalo de servidor se aninha aqui.
    return await LoopAsync(p, goal, ct);
}

A unidade de observabilidade para um agente é a execução, não a solicitação. Um id de rastreamento, e toda a execução entre servidores está diante de você — é por isso que a triagem de incidentes caiu de horas para minutos.

2. Rastreie o loop, não apenas a ferramenta

Um intervalo por turno, por chamada de modelo e por chamada de ferramenta, aninhados sob a execução.

for (var turn = 0; turn < MaxTurns; turn++)
{
    using var turnSpan = ActivitySource.StartActivity("agent.turn");
    turnSpan?.SetTag("agent.turn", turn);

    using (ActivitySource.StartActivity("agent.model_call"))
        reply = await model.ChatAsync(messages, tools, ct);           // um intervalo por chamada de modelo

    foreach (var call in reply.ToolCalls)
        using (var t = ActivitySource.StartActivity($"tool.{call.Name}"))
        {
            t?.SetTag("mcp.server", Route(call.Name));
            results.Add(await manager.InvokeAsync(call, ct));
        }
}

O intervalo da ferramenta responde "a ferramenta estava lenta?"; a árvore execução->turno->chamada responde "por que o agente levou seis turnos?".

3. Registro de protocolo estruturado e redigido

Logs estruturados da interação MCP — método, ferramenta, servidor, inquilino, latência, resultado — correlacionados pelo id de rastreamento e redigidos.