AG-UI Protocol Explicado: O Novo Padrão para Interfaces Humano-Agente
À medida que os agentes de IA se tornam capazes de lidar com fluxos de trabalho reais, um novo desafio de infraestrutura surge: como humanos e agentes se comunicam durante a execução — não apenas no início e no final, mas ao longo de todo o processo?
O protocolo AG-UI é uma especificação aberta projetada exatamente para resolver isso. Ele define um padrão de como os agentes de IA fazem streaming de eventos, solicitam entradas e expõem seu estado para aplicações frontend e operadores humanos em tempo real. Se o MCP (Model Context Protocol) padronizou como os agentes acessam ferramentas, o AG-UI padroniza como os agentes conversam com os usuários.
Este guia explica o que é o AG-UI, por que ele é importante, como funciona e como começar a usá-lo na sua stack de agentes.
O Problema que o AG-UI Resolve
Antes do AG-UI, cada equipe que construía uma aplicação de agente de IA voltada ao usuário tinha que inventar seu próprio protocolo de comunicação. Como o agente informa ao frontend que está "pensando"? Como ele solicita uma decisão humana? Como o usuário envia uma correção no meio de uma tarefa? Como o progresso é exibido?
As respostas eram diferentes para cada equipe — geralmente improvisadas, mal documentadas e difíceis de reutilizar. Isso criou um ecossistema fragmentado onde:
- Frameworks de agentes não conseguiam compartilhar componentes de frontend
- Desenvolvedores tinham que reconstruir a infraestrutura de streaming de UI do zero para cada projeto
- Usuários tinham experiências inconsistentes em diferentes produtos baseados em agentes
- Depurar o comportamento do agente exigia logging personalizado em cada implementação
O AG-UI estabelece um vocabulário compartilhado e uma estrutura de eventos para que qualquer framework de agente possa produzir eventos que qualquer frontend compatível com AG-UI consiga renderizar — sem código de integração customizado.
O que é o AG-UI?
AG-UI é um protocolo aberto de streaming de eventos que define o formato e a semântica das mensagens trocadas entre agentes de IA e interfaces voltadas ao usuário.
Ele é:
- Agnóstico de transporte: funciona via HTTP (Server-Sent Events), WebSockets ou qualquer transporte de streaming
- Agnóstico de framework: pode ser implementado em qualquer linguagem ou framework de agentes
- Bidirecional: os agentes enviam eventos ao frontend; os usuários enviam mensagens e interrupções ao agente
- Stateful: o protocolo inclui snapshots de estado para que os frontends possam reconstruir o contexto completo do agente a qualquer momento
Ele não é:
- Um protocolo de ferramentas (essa é a função do MCP)
- Um framework de agentes em si
- Uma biblioteca de componentes de UI (embora existam implementações de referência)
AG-UI vs. MCP: Entendendo a Diferença
Uma fonte comum de confusão é como o AG-UI se relaciona com o Model Context Protocol (MCP) da Anthropic.
| Dimensão | MCP | AG-UI |
|---|---|---|
| Propósito | Comunicação Agente ↔ Ferramenta | Comunicação Agente ↔ Humano/Frontend |
| Direção | Agente chama ferramentas, recebe resultados | Agente faz streaming de eventos; humano envia mensagens |
| Público | Desenvolvedores de ferramentas/servidores | Desenvolvedores de frontend e frameworks de agentes |
| Foco | Quais capacidades o agente pode usar | Como o agente comunica seu estado e progresso |
| Relação | Cuida do lado "ferramentas" do agente | Cuida do lado "interface do usuário" |
Eles são complementares. Um agente em produção tipicamente usa MCP para acessar ferramentas (busca na web, geração de imagens, execução de código) e AG-UI para comunicar seu progresso e solicitar entrada humana.
Conceitos Fundamentais do AG-UI
Tipos de Eventos
O AG-UI define um conjunto padrão de tipos de eventos que os agentes emitem:
Eventos de ciclo de vida:
RUN_STARTED/RUN_FINISHED— o agente iniciou ou concluiu a execuçãoSTEP_STARTED/STEP_FINISHED— uma etapa discreta do fluxo de trabalho começou ou terminouRUN_ERROR— o agente encontrou um erro irrecuperável
Eventos de mensagem:
TEXT_MESSAGE_START/TEXT_MESSAGE_CONTENT/TEXT_MESSAGE_END— saída de texto em streaming do agenteTOOL_CALL_START/TOOL_CALL_ARGS/TOOL_CALL_END— o agente está invocando uma ferramenta
Eventos de estado:
STATE_SNAPSHOT— um snapshot completo do estado atual do agenteSTATE_DELTA— uma atualização incremental do estadoMESSAGES_SNAPSHOT— o histórico completo de conversa em um determinado ponto
Eventos customizados:
CUSTOM— para eventos específicos da aplicação não cobertos pelo conjunto padrão
O Turno Humano
O AG-UI também padroniza como humanos interagem com agentes em execução. O frontend envia um AgentInput para interromper, redirecionar ou fornecer informações ao agente durante a execução. Isso é diferente de um novo turno de conversa — o agente está em execução, e o humano está influenciando sua tarefa atual.
Arquitetura Baseada em Threads
O AG-UI organiza as execuções de agentes em threads — contextos de conversa persistentes que mantêm estado ao longo de múltiplas execuções. Um thread no AG-UI é aproximadamente equivalente a uma sessão ou conversa em outros frameworks, mas com suporte explícito do protocolo para retomar, ramificar e reproduzir.
Como o AG-UI Funciona: Um Fluxo Típico
1. Usuário envia uma tarefa pelo frontend
2. Frontend envia requisição InitialRun com RunAgentInput ao backend do agente
3. Agente inicia a execução e emite o evento RUN_STARTED
4. Agente emite STEP_STARTED para cada etapa de planejamento
5. Agente chama uma ferramenta → emite TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END
6. Agente gera texto → emite TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT (streaming), TEXT_MESSAGE_END
7. Agente emite STATE_DELTA para atualizar o estado do frontend em tempo real
8. Usuário decide redirecionar o agente → envia AgentInput com correção
9. Agente incorpora a correção e continua
10. Agente emite RUN_FINISHED
O frontend recebe esses eventos como um stream e os renderiza progressivamente — exibindo chamadas de ferramentas à medida que acontecem, transmitindo texto em tempo real e atualizando um indicador de progresso com base nos eventos de etapa.
Implementando o AG-UI
Suporte a Frameworks
O AG-UI está ganhando suporte nos principais frameworks de agentes:
- LangGraph: eventos AG-UI podem ser emitidos a partir de nós do grafo usando o AG-UI Python SDK
- Integração AG-UI CopilotKit: o CopilotKit (um framework React de frontend para IA) inclui suporte nativo ao AG-UI
- Implementações customizadas: a especificação AG-UI é aberta; qualquer framework pode implementá-la com as definições de tipos de eventos
Início Rápido (Python)
from ag_ui.core import (
RunAgentInput, EventType,
RunStartedEvent, TextMessageStartEvent,
TextMessageContentEvent, TextMessageEndEvent,
RunFinishedEvent,
)
import uuid
async def run_agent(input: RunAgentInput):
run_id = str(uuid.uuid4())
yield RunStartedEvent(
type=EventType.RUN_STARTED,
thread_id=input.thread_id,
run_id=run_id,
)
msg_id = str(uuid.uuid4())
yield TextMessageStartEvent(type=EventType.TEXT_MESSAGE_START, message_id=msg_id, role="assistant")
for chunk in agent.stream(input.messages):
yield TextMessageContentEvent(
type=EventType.TEXT_MESSAGE_CONTENT,
message_id=msg_id,
delta=chunk
)
yield TextMessageEndEvent(type=EventType.TEXT_MESSAGE_END, message_id=msg_id)
yield RunFinishedEvent(type=EventType.RUN_FINISHED, thread_id=input.thread_id, run_id=run_id)
Conectando ao AnyCap
Quando seu agente baseado em AG-UI precisar de capacidades do mundo real — busca na web, geração de imagens, armazenamento de arquivos — o AnyCap se integra como uma camada de ferramentas abaixo da orquestração. O agente chama as ferramentas do AnyCap durante seu loop de execução e emite os eventos TOOL_CALL_* correspondentes para que o frontend mostre o que está acontecendo:
Usuário: "Pesquise os 5 principais frameworks de IA e crie uma imagem resumida"
Agente emite: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agente emite: TOOL_CALL_END (result: resultados da busca)
Agente emite: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
Agente emite: TOOL_CALL_END (result: URL da imagem)
Agente emite: TEXT_MESSAGE (resumo em streaming com imagem incorporada)
Essa transparência total — exposta através dos eventos AG-UI — é o que separa uma interface humano-agente confiável de uma caixa-preta.
Por que o AG-UI é Importante para Aplicações de Agentes em Produção
Se você está construindo produtos baseados em agentes, o AG-UI oferece:
Reutilização de componentes. Componentes de frontend construídos conforme a especificação AG-UI funcionam com qualquer backend compatível. Crie uma UI de chat em streaming uma vez; use com LangGraph, CrewAI e AutoGen sem alterações.
Experiência do usuário consistente. Os usuários veem os mesmos padrões de interação em diferentes fluxos de trabalho de agentes porque os tipos de eventos são padronizados.
Depuração. Os snapshots de estado e o stream de eventos do AG-UI fornecem um registro completo da execução do agente. Reproduzir um stream de eventos mostra exatamente o que o agente viu e fez em cada etapa.
Supervisão humana. O mecanismo AgentInput para intervenção humana no meio de uma tarefa está incorporado ao protocolo — não é um recurso adicionado depois.
Conclusão
O AG-UI preenche uma lacuna real na pilha de infraestrutura de IA agêntica. À medida que os agentes se tornam mais capazes e mais voltados ao usuário, o protocolo de como eles comunicam seu estado e recebem entrada humana se torna tão importante quanto as ferramentas que podem acessar.
Para desenvolvedores que constroem produtos baseados em agentes em 2026, adotar o AG-UI cedo significa construir sobre uma base para a qual o ecossistema está convergindo — em vez de manter uma camada de comunicação personalizada que se torna um problema à medida que seu produto cresce.
Leitura adicional: