Por que observabilidade de agente virou prioridade
Olha só: subir um agente de IA sem observabilidade é tipo rodar um microsserviço sem log. Você vê a resposta final, mas não faz ideia de por que o modelo chamou aquela tool, por que queimou 40k tokens em um único turno, ou onde o handoff para o subagente deu ruim.
O novo recurso Agent Runs da Vercel resolve exatamente isso para agentes baseados no eve. Quando você faz deploy de um agente eve na Vercel, os traces são ingeridos automaticamente — sem SDK pra configurar, sem coletor OpenTelemetry pra subir. Cada sessão vira um Agent Run consultável, com reasoning, tool calls e uso de tokens anexados.
Segundo o changelog oficial, isso agora aparece por dois caminhos: o Vercel MCP, para agentes de código, e a Vercel CLI, para humanos (e agentes headless sem acesso a MCP).
As 4 ferramentas MCP que você realmente vai usar
A superfície MCP é pequena de propósito — quatro ferramentas que mapeiam direto para um fluxo de debug:
| Ferramenta | Para que serve |
|---|---|
list_agent_run_projects | Encontra projetos de um time com atividade de Agent Runs |
list_agent_runs | Lista execuções recentes de um projeto |
get_agent_run | Inspeciona metadados, eventos de ciclo de vida, uso e dados de subagente |
get_agent_run_trace | Puxa o trace completo: turnos, mensagens, reasoning, tool calls, tokens e I/O das tools |
Instala o servidor MCP numa linha:
# Registra o servidor MCP da Vercel no seu agente de código
npx add-mcp https://mcp.vercel.com
Depois de registrar, dá pra perguntar pro seu agente em linguagem natural:
> Mostra os últimos Agent Runs de produção do meu projeto
> Atualiza as skills com base nas execuções recentes
O segundo prompt é o mais interessante. Como get_agent_run_trace devolve reasoning estruturado e I/O das tools, um agente consegue ler as próprias falhas e propor mudanças em prompts ou schemas de tool. É o loop de feedback que a maioria dos times ainda monta na mão com harness de eval caseiro.
CLI: os mesmos dados, sem precisar de MCP
Nem todo ambiente fala MCP — runners de CI, cron jobs ou um bash pelado. A Vercel CLI espelha as ferramentas MCP quase 1:1:
# Atualiza pra CLI mais recente
npm i -g vercel@latest
# Descobre projetos com atividade de Agent Runs
vercel agent-runs projects
# Lista execuções recentes
vercel agent-runs list
# Inspeciona metadados e ciclo de vida de uma run
vercel agent-runs inspect <run-id>
# Puxa o trace completo
vercel agent-runs trace <run-id>
Dois detalhes de design que valem destaque:
- Todo subcomando aceita
--json— saída legível por máquina pra scripts e agentes sem MCP. - Traces viram markdown quando passados por pipe — então
vercel agent-runs trace <id> | lesste dá um transcript legível em vez de JSON cru.
Esse último é silenciosamente importante. Significa que um agente rodando num container sem cliente MCP pode simplesmente chamar a CLI, ler o próprio trace e se autocorrigir.
Limites e cuidados
- Só eve (por enquanto). Os traces são auto-ingeridos pra agentes eve na Vercel. Se você roda LangGraph, CrewAI ou um loop caseiro, vai precisar emitir spans compatíveis por conta própria — a doc não promete um caminho genérico de ingestão.
- Superfície de lock-in. Os Agent Runs vivem no dashboard e no MCP da Vercel. Exportar traces crus pro seu stack de observabilidade (Datadog, Honeycomb) não é o fluxo principal aqui.
- Ver custo ≠ controlar custo. Você enxerga o uso por run, mas não há enforcement de budget embutido nesta release.
- Reasoning depende do modelo. Se o modelo não emite tokens de reasoning, o
get_agent_run_tracemostra turnos e tool calls, mas a seção de reasoning vem magra.
Se você já está pensando em fronteiras de autorização para APIs acionadas por agente, vale combinar com os padrões do nosso deep dive em autorização de API fine-grained.
Próximos passos
- Começa por um template. A Vercel tem starters de eve — escolhe um, faz deploy, e os Agent Runs já começam a aparecer minutos depois da primeira sessão.
- Pluga o MCP no seu agente de código. O one-liner
npx add-mcpé o caminho mais rápido. Pede pra ele resumir as últimas 10 runs com falha e agrupar por tool call. - Monta um loop de auto-melhoria. Faz o agente ler o
get_agent_run_tracedas próprias falhas recentes e propor diffs em prompts ou schemas. Revisa, faz merge, redeploya. - Fica de olho na portabilidade. Se multi-cloud ou observabilidade self-hosted importa pra você, trata os Agent Runs como uma camada de conveniência em cima do seu backend de tracing principal, não como substituto.
Pra times que já usam execução sandboxed pra código de agente, isso encaixa bem ao lado do GA do Cloudflare Sandboxes — um te dá o runtime, o outro te dá o recibo.
Leitura complementar: o changelog oficial de Agent Runs da Vercel e a doc do framework eve no GitHub são os dois links pra salvar antes de subir seu próximo agente.