À medida que os agentes de IA se tornam capazes o suficiente para lidar com fluxos de trabalho reais, surgiu um novo desafio de infraestrutura: como humanos e agentes se comunicam durante a execução — não apenas no começo e no fim, mas ao longo de todo o processo?
O protocolo AG-UI é uma especificação aberta criada exatamente para resolver isso. Ele define um padrão de como agentes de IA fazem streaming de eventos, solicitam entrada e expõem estado para aplicações de 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 é AG-UI, por que ele importa, 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, toda equipe que construía uma aplicação de agente de IA voltada para pessoas precisava inventar seu próprio protocolo de comunicação. Como o agente avisa ao frontend que está pensando? Como solicita uma decisão humana? Como o usuário envia uma correção no meio da tarefa? Como o progresso é exibido?
As respostas eram diferentes em cada equipe — muitas vezes ad hoc, mal documentadas e difíceis de reutilizar. Isso criou um ecossistema fragmentado em que:
- frameworks de agentes não conseguiam compartilhar componentes de frontend
- desenvolvedores precisavam reconstruir a infraestrutura de UI em streaming do zero em cada projeto
- usuários tinham experiências inconsistentes entre diferentes produtos com agentes
- depurar o comportamento do agente exigia logging personalizado em cada implementação
O AG-UI estabelece um vocabulário comum e uma estrutura de eventos compartilhada para que qualquer framework de agentes possa produzir eventos que qualquer frontend compatível com AG-UI consiga renderizar — sem código de integração customizado.
O que é AG-UI?
AG-UI é um protocolo aberto de eventos em streaming 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 sobre 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: agentes enviam eventos ao frontend; usuários enviam mensagens e interrupções ao agente
- stateful: o protocolo inclui snapshots de estado para que frontends possam reconstruir o contexto completo do agente em qualquer momento
Ele não é:
- um protocolo de ferramentas, esse é o papel 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 |
|---|---|---|
| Objetivo | Comunicação agente ↔ ferramenta | Comunicação agente ↔ humano/frontend |
| Direção | O agente chama ferramentas e recebe resultados | O agente transmite eventos; o humano envia mensagens |
| Público | Desenvolvedores de ferramentas/servidores | Desenvolvedores de frontend e de frameworks de agentes |
| Foco | Quais capacidades o agente pode usar | Como o agente comunica estado e progresso |
| Relação | Cuida do lado de ferramentas do agente | Cuida do lado de interface com o usuário |
Eles são complementares. Um agente em produção normalmente usa MCP para acessar ferramentas, como busca na web, geração de imagem e execução de código, e AG-UI para comunicar seu progresso e solicitar entrada humana.
Conceitos centrais do AG-UI
Tipos de evento
O AG-UI define um conjunto padrão de tipos de evento emitidos pelos agentes:
Eventos de ciclo de vida:
RUN_STARTED/RUN_FINISHED— o agente começou ou concluiu a execuçãoSTEP_STARTED/STEP_FINISHED— uma etapa discreta dentro 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á chamando 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 da conversa em um dado momento
Eventos customizados:
CUSTOM— para eventos específicos da aplicação que não sã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 no meio da 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 execuções de agentes em threads — contextos persistentes de conversa que mantêm estado ao longo de múltiplas execuções. Uma thread no AG-UI é aproximadamente equivalente a uma sessão ou conversa em outros frameworks, mas com suporte explícito no protocolo para retomar, ramificar e reproduzir.
Como o AG-UI funciona: um fluxo típico
1. O usuário envia uma tarefa pelo frontend
2. O frontend envia uma solicitação InitialRun com RunAgentInput para o backend do agente
3. O agente inicia a execução e emite o evento RUN_STARTED
4. O agente emite STEP_STARTED para cada etapa de planejamento
5. O agente chama uma ferramenta → emite TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END
6. O agente gera texto → emite TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT (streaming), TEXT_MESSAGE_END
7. O agente emite STATE_DELTA para atualizar o estado do frontend em tempo real
8. O usuário decide redirecionar o agente → envia AgentInput com uma correção
9. O agente incorpora a correção e continua
10. O agente emite RUN_FINISHED
O frontend recebe esses eventos como um stream e os renderiza progressivamente — mostrando chamadas de ferramenta conforme acontecem, exibindo texto em tempo real e atualizando um indicador de progresso com base nos eventos de etapa.
Implementando o AG-UI
Suporte de 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 SDK Python do AG-UI
- Integração AG-UI com CopilotKit: o CopilotKit, um framework de frontend em React para IA, oferece suporte nativo a AG-UI
- Implementações personalizadas: a especificação do AG-UI é aberta; qualquer framework pode implementá-la com as definições de tipos de evento
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 com AG-UI precisa de capacidades do mundo real, como busca na web, geração de imagem e armazenamento de arquivos, o AnyCap entra como uma camada de ferramentas abaixo da orquestração. O agente chama 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:
User: "Pesquise os 5 principais frameworks de IA e crie uma imagem-resumo"
Agent emits: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agent emits: TOOL_CALL_END (result: search results)
Agent emits: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
Agent emits: TOOL_CALL_END (result: image URL)
Agent emits: TEXT_MESSAGE (streaming summary with embedded image)
Essa transparência total — exposta por meio dos eventos do AG-UI — é o que separa uma interface humano-agente confiável de uma caixa-preta.
Por que o AG-UI importa para aplicações de agentes em produção
Se você está criando produtos com agentes, o AG-UI oferece:
Reutilização de componentes. Componentes de frontend criados de acordo com a especificação do AG-UI funcionam com qualquer backend compatível. Crie uma UI de chat em streaming uma vez e use com LangGraph, CrewAI e AutoGen sem mudanças.
Experiência do usuário consistente. Os usuários veem os mesmos padrões de interação em diferentes fluxos de trabalho com agentes porque os tipos de evento 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 da tarefa já faz parte do protocolo — não foi acoplado depois como remendo.
Conclusão
O AG-UI preenche uma lacuna real na stack de infraestrutura de IA agentiva. À 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 conseguem acessar.
Para desenvolvedores que constroem produtos com agentes em 2026, adotar AG-UI cedo significa construir sobre uma base para a qual o ecossistema está convergindo — em vez de manter uma camada de comunicação sob medida que se torna um passivo à medida que o produto cresce.
Leituras adicionais:
- Comparativo de frameworks de orquestração de IA
- MCP vs. Skills: qual você deve usar?
- Capacidades do AnyCap
- Repositório do AG-UI no GitHub
- Guia de ferramentas de orquestração de automação 2026 — Zapier vs n8n vs Temporal vs LangGraph: como escolher
- Ferramentas de orquestração de dados 2026 — De Airflow à orquestração nativa de IA no seu pipeline de agentes