Investigando execuções

O melhor uso do MCP do TunnelHub hoje é investigação operacional.

Em vez de navegar manualmente pelo portal, você pode combinar ferramentas para localizar uma execução, abrir o resumo e seguir para logs ou traces.

Fluxo recomendado

O fluxo mais seguro costuma ser:

1. localizar a execução por janela de tempo;

2. capturar automationId, executionId e executionPeriod;

3. abrir o resumo da execução;

4. aprofundar em logs ou traces.

Passo 1: encontrar a execução

Use find_execution_tunnelhub quando você já tem uma janela de tempo e quer localizar uma execução específica.

Exemplo de parâmetros:

{
  "startDate": "2026-03-17 00:00:00",
  "endDate": "2026-03-17 23:59:59",
  "automationId": "<automation-id>",
  "status": "ERROR"
}

Essa etapa é importante porque as ferramentas de detalhe exigem executionPeriod no formato YYYY-MM.

Passo 2: abrir o resumo

Depois de encontrar a execução, use summarize_execution_tunnelhub ou get_execution_tunnelhub.

Exemplo conceitual:

{
  "automationId": "<automation-id>",
  "executionId": "<execution-id>",
  "executionPeriod": "2026-03"
}

O resumo é o melhor ponto de entrada para entender:

• status consolidado;

• mensagens principais;

• volume processado;

• indícios iniciais de falha.

Passo 3: abrir traces

Quando o problema parece técnico, siga para get_execution_traces_tunnelhub.

Use filtros quando quiser reduzir ruído, por exemplo:

• level;

• status;

• message;

• timestampStart e timestampEnd.

Os traces ajudam mais quando você quer reconstruir a sequência de eventos internos da execução.

Passo 4: abrir logs de processamento

Quando o problema parece ligado a registros de negócio, use get_execution_logs_tunnelhub.

Esse caminho é ideal para responder perguntas como:

• quais itens falharam;

• qual ação foi tentada;

• quais mensagens apareceram por item;

• como os metadados definidos no SDK explicam o erro.

Quando usar cada ferramenta

• find_execution_tunnelhub: localizar a execução certa.

• summarize_execution_tunnelhub: obter contexto rápido.

• get_execution_tunnelhub: abrir o detalhe estruturado.

• get_execution_traces_tunnelhub: investigar comportamento técnico.

• get_execution_logs_tunnelhub: investigar itens de negócio.

Exemplo de pergunta em linguagem natural

Você pode pedir algo como:

"Encontre execuções com erro da automação X hoje, resuma a mais recente e destaque os traces com falha."

O bom resultado depende de informar:

• período;

• automação, quando conhecida;

• status desejado;

• profundidade esperada da análise.

Cuidados práticos

• sempre informe janela de tempo explícita nas buscas;

• guarde executionPeriod, porque ele é obrigatório nas ferramentas de detalhe;

• lembre que logs e traces podem conter dados sensíveis dependendo da automação;

• sanitize qualquer saída antes de reutilizar o conteúdo em documentação pública ou tickets externos.