AG-UI Protocol: A Peça que Faltava no Stack MCP + A2A

Se você acompanhou as novidades desta semana, já sabe que março de 2026 foi marcado por uma corrida de protocolos. O MCP consolidou seu papel como padrão aberto para ferramentas e recursos. O A2A trouxe comunicação estruturada entre agentes. Cada grande lab lançou sua versão de "agente que usa o computador".

Mas tem uma lacuna que todo esse movimento ainda não fechou completamente: como o agente se comunica com a interface do usuário em tempo real?

Não estou falando de resposta de texto no chat. Estou falando de agentes que atualizam dashboards enquanto trabalham, que pedem aprovação inline antes de uma ação irreversível, que renderizam componentes interativos dentro da conversa, que mostram o progresso de tarefas longas sem o usuário precisar perguntar "e aí, terminou?".

É exatamente isso que o AG-UI Protocol endereça.

O Triângulo do Stack Agêntico

Antes de entrar no AG-UI, o contexto ajuda a entender por que ele existe.

O MCP (Model Context Protocol) resolve a conexão entre o agente e ferramentas externas — bancos de dados, APIs, sistemas de arquivos, browsers. É o padrão de como o agente acessa recursos.

O A2A (Agent-to-Agent) resolve a comunicação entre agentes — como um orchestrator delega tarefas para subagentes, como resultados são trocados, como estado é sincronizado entre múltiplos agentes colaborando. É o padrão de como agentes se falam.

O AG-UI fecha o triângulo: é o protocolo de como o agente fala com a interface. Não é apenas streaming de texto — é um conjunto de eventos tipados, bidirecionais, que permitem ao agente e à UI se comunicarem de forma rica durante toda a execução de uma tarefa.

Por Que SSE e Streaming de Texto Não Bastam

A maioria das implementações de agentes hoje usa Server-Sent Events (SSE) ou WebSockets com streaming de texto simples. O modelo gera tokens, a UI exibe tokens. Funciona para um chatbot.

Mas quando você começa a construir sistemas agênticos reais, as limitações aparecem:

Problema 1 — Sem semântica de eventos: como a UI sabe que o agente começou a chamar uma ferramenta? Que um subagente foi invocado? Que o estado interno mudou? Com streaming de texto puro, você está adivinhando a partir do conteúdo — frágil e não escalável.

Problema 2 — Sem comunicação do usuário para o agente durante a execução: o usuário quer aprovar uma ação antes de o agente executar, ou corrigir o curso no meio de uma tarefa longa. Com SSE tradicional, a comunicação é unidirecional. Você precisa encerrar e reiniciar a sessão.

Problema 3 — Sem estado compartilhado: o agente tem um estado interno rico (variáveis, resultados parciais, plano de execução). A UI não tem visibilidade disso — não consegue renderizar uma barra de progresso real, não consegue mostrar o que o agente está "pensando".

Problema 4 — Sem suporte a Generative UI: se você quer que o agente renderize componentes personalizados na interface (um formulário de aprovação, um gráfico com os dados que acabou de calcular, um botão de ação contextual), streaming de texto não tem como fazer isso.

O AG-UI resolve todos os quatro.

Os Eventos Tipados do AG-UI

O coração do AG-UI é um conjunto de eventos bem definidos que viajam entre o agente e a interface. São eventos bidirecionais — tanto o agente quanto o usuário podem emiti-los.

Eventos do Agente → Interface

RUN_STARTED — sinaliza o início de uma execução, com metadados (ID da run, timestamp, configuração).

TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END — os eventos de streaming de texto, mas com semântica clara de início e fim, e com o messageId para a UI correlacionar chunks.

TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END — o agente sinaliza que está chamando uma ferramenta, com nome e argumentos sendo streamados. A UI pode renderizar "🔧 Executando busca no banco de dados..." em tempo real.

STATE_SNAPSHOT — o agente publica um snapshot do estado atual. A UI pode usar isso para atualizar um painel de progresso, mostrar variáveis intermediárias, ou sincronizar estado para recuperação de falhas.

STATE_DELTA — versão incremental do snapshot, usando JSON Patch (RFC 6902). Mais eficiente para atualizações frequentes — só o que mudou, não o estado inteiro.

MESSAGES_SNAPSHOT — snapshot completo do histórico de mensagens para sincronização ou recovery.

CUSTOM — evento de escape hatch: qualquer payload JSON arbitrário. Permite que frameworks estendam o protocolo para casos específicos sem quebrar compatibilidade.

RUN_FINISHED / RUN_ERROR — fim da execução, com resultado ou erro estruturado.

Eventos da Interface → Agente

USER_MESSAGE — mensagem do usuário durante a execução (não apenas no início). Isso é o que permite ao usuário "falar com o agente enquanto ele trabalha".

APPROVAL_RESPONSE — resposta a uma solicitação de aprovação. O agente pode pausar e esperar o usuário confirmar antes de executar uma ação irreversível.

CANCEL — interrompe a execução em andamento de forma graciosa.

Generative UI: O Caso de Uso Mais Poderoso

O AG-UI foi projetado com Generative UI em mente — a capacidade do agente de renderizar componentes de interface personalizados dentro da conversa.

A ideia: em vez de o agente descrever os dados em texto ("aqui estão os 5 melhores leads ordenados por score"), ele renderiza diretamente um componente de interface (uma tabela interativa com os dados, com botões de ação para cada linha).

Com o evento CUSTOM, o agente envia um payload estruturado que a UI sabe como renderizar:

// Agente emite:
{
  type: "CUSTOM",
  payload: {
    component: "LeadsTable",
    data: [
      { id: 1, name: "Acme Corp", score: 94, action: "schedule_demo" },
      { id: 2, name: "TechStart", score: 87, action: "send_proposal" }
    ]
  }
}

// UI renderiza o componente <LeadsTable /> com os dados recebidos

Isso muda fundamentalmente o que um assistente pode fazer: em vez de ser um gerador de texto, ele vira um coordenador de interface.

Implementação: Python e TypeScript

O AG-UI tem SDKs oficiais para as duas linguagens mais usadas em sistemas agênticos.

Python — FastAPI + ag-ui-python

from ag_ui.core import (
    RunAgentInput, EventType,
    RunStartedEvent, TextMessageStartEvent,
    TextMessageContentEvent, TextMessageEndEvent,
    RunFinishedEvent, ToolCallStartEvent, ToolCallEndEvent
)
from ag_ui.encoder import EventEncoder
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import uuid

app = FastAPI()
encoder = EventEncoder()

@app.post("/agent")
async def run_agent(input: RunAgentInput):
    async def event_stream():
        run_id = str(uuid.uuid4())
        msg_id = str(uuid.uuid4())

        # Sinaliza início
        yield encoder.encode(RunStartedEvent(
            type=EventType.RUN_STARTED,
            thread_id=input.thread_id,
            run_id=run_id
        ))

        # Sinaliza uso de ferramenta
        tool_call_id = str(uuid.uuid4())
        yield encoder.encode(ToolCallStartEvent(
            type=EventType.TOOL_CALL_START,
            tool_call_id=tool_call_id,
            tool_call_name="search_database",
            parent_message_id=msg_id
        ))
        # ... executa a ferramenta ...
        yield encoder.encode(ToolCallEndEvent(
            type=EventType.TOOL_CALL_END,
            tool_call_id=tool_call_id
        ))

        # Streama resposta em texto
        yield encoder.encode(TextMessageStartEvent(
            type=EventType.TEXT_MESSAGE_START,
            message_id=msg_id
        ))
        for chunk in "Encontrei 3 resultados relevantes...":
            yield encoder.encode(TextMessageContentEvent(
                type=EventType.TEXT_MESSAGE_CONTENT,
                message_id=msg_id,
                delta=chunk
            ))
        yield encoder.encode(TextMessageEndEvent(
            type=EventType.TEXT_MESSAGE_END,
            message_id=msg_id
        ))

        yield encoder.encode(RunFinishedEvent(
            type=EventType.RUN_FINISHED,
            thread_id=input.thread_id,
            run_id=run_id
        ))

    return StreamingResponse(event_stream(), media_type="text/event-stream")

TypeScript — Lado do Cliente

import { AgentClient } from "@ag-ui/client";
import { EventType } from "@ag-ui/core";

const client = new AgentClient({ url: "http://localhost:8000/agent" });

const run = client.runAgent({
  threadId: "thread-abc123",
  messages: [{ role: "user", content: "Analise os leads da semana" }],
});

run.on(EventType.TOOL_CALL_START, (event) => {
  console.log(`🔧 Usando ferramenta: ${event.toolCallName}`);
  // UI mostra indicador de tool call em andamento
});

run.on(EventType.TEXT_MESSAGE_CONTENT, (event) => {
  // Adiciona chunk ao bubble de mensagem
  appendToMessage(event.messageId, event.delta);
});

run.on(EventType.CUSTOM, (event) => {
  // Renderiza componente customizado
  if (event.payload.component === "LeadsTable") {
    renderComponent("LeadsTable", event.payload.data);
  }
});

run.on(EventType.RUN_FINISHED, () => {
  console.log("✅ Execução concluída");
});

await run.start();

Adaptadores para Frameworks Existentes

O AG-UI foi desenhado para se integrar com os frameworks de agentes que você já usa, não para substituí-los.

LangGraph: o adaptador oficial converte os eventos do grafo (node start, edge traversal, state update) em eventos AG-UI. Você adiciona um output handler ao seu grafo e o protocolo é gerado automaticamente.

from ag_ui.adapters.langgraph import LangGraphAdapter

adapter = LangGraphAdapter(graph=meu_grafo_compilado)

@app.post("/agent")
async def run_agent(input: RunAgentInput):
    return StreamingResponse(
        adapter.stream(input),
        media_type="text/event-stream"
    )

Mastra: integração nativa no framework, com suporte automático a state snapshots e tool call events a partir das definições de agente existentes.

CrewAI: adaptador de comunidade disponível que mapeia eventos de crew execution (task started, agent assigned, result returned) para o protocolo AG-UI.

LlamaIndex Workflows: adaptador que converte os Steps e Events do LlamaIndex Workflows para AG-UI events, mantendo compatibilidade total com workflows existentes.

Checkpoints e Aprovação Humana

Um dos usos mais críticos do AG-UI em sistemas de produção é o human-in-the-loop: pausar a execução do agente e aguardar aprovação antes de uma ação de alto risco.

# Agente solicita aprovação antes de deletar registros
yield encoder.encode({
    "type": "CUSTOM",
    "payload": {
        "component": "ApprovalRequest",
        "action": "delete_records",
        "description": "Deletar 847 registros duplicados da tabela orders",
        "preview": { "count": 847, "table": "orders", "ids": ["..."] },
        "requires_approval": True
    }
})

# Agente fica em await até receber USER_MESSAGE ou APPROVAL_RESPONSE
approval = await wait_for_approval(run_id)
if not approval.approved:
    return  # Cancelado pelo usuário
# Continua a execução

A interface renderiza o componente ApprovalRequest com os detalhes da ação. O usuário vê exatamente o que vai acontecer e pode aprovar ou cancelar. Sem essa capacidade, sistemas agênticos que executam ações irreversíveis são um risco operacional.

Quando Usar AG-UI (e Quando Não Usar)

Use AG-UI quando:

• Você está construindo uma interface de usuário customizada para um agente (não usando o ChatGPT ou Claude diretamente)
• Seu agente executa tarefas longas e você quer feedback de progresso em tempo real
• Você precisa de human-in-the-loop em pontos específicos da execução
• Você quer renderizar componentes customizados na interface (Generative UI)
• Você está construindo sobre LangGraph, Mastra ou outro framework que já tem adaptador

Não use AG-UI quando:

• Você está construindo um chatbot simples sem estado complexo
• Você usa diretamente a API de streaming da OpenAI/Anthropic e não tem uma UI customizada
• Seu agente executa em background sem interface de usuário (pipelines de dados, automações de CI/CD)

O AG-UI adiciona complexidade. Vale a pena quando a experiência de usuário durante a execução do agente é importante — o que é o caso para a maioria dos produtos de IA voltados para usuários finais.

O Stack Completo

Com MCP, A2A e AG-UI, o stack de um sistema agêntico moderno tem camadas claras:

┌─────────────────────────────────────────┐
│            Interface do Usuário          │
│     (React, Next.js, Flutter, etc.)      │
└──────────────── AG-UI ──────────────────┘
                    │ eventos bidirecionais
┌─────────────────────────────────────────┐
│            Orchestrator Agent            │
│     (LangGraph, Mastra, CrewAI)          │
└────────── A2A ──────────┬───────────────┘
                          │ delegação
┌─────────────────────────▼───────────────┐
│              Sub-Agents                  │
│     (especializados por domínio)         │
└──────────────── MCP ────────────────────┘
                    │ tools + resources
┌─────────────────────────────────────────┐
│      Ferramentas e Recursos Externos     │
│  (DBs, APIs, browsers, filesystems)      │
└─────────────────────────────────────────┘

Cada protocolo tem seu papel, e eles não se sobrepõem. MCP é sobre acesso a recursos. A2A é sobre colaboração entre agentes. AG-UI é sobre a experiência do usuário durante a execução.

Recursos

• AG-UI Protocol — Documentação Oficial
• SDK JavaScript/TypeScript
• Adaptadores para frameworks
• Especificação completa dos eventos
• Posts relacionados: MCP padrão aberto · A2A Protocol