À medida que os agentes de IA se tornam capazes o suficiente para 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 fim, mas ao longo de todo o processo?
O protocolo AG-UI é uma especificação aberta projetada para resolver exatamente isso. Ele define um padrão para como agentes de IA transmitem eventos, solicitam entradas e exibem 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 se comunicam com os usuários.
Este guia explica o que é o AG-UI, por que ele importa, como funciona e como começar a usá-lo em seu 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 para o 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—frequentemente improvisadas, mal documentadas e difíceis de reutilizar. Isso criou um ecossistema fragmentado onde:
- Frameworks de agentes não podiam compartilhar componentes de frontend
- Desenvolvedores tinham que reconstruir a infraestrutura de UI de streaming do zero para cada projeto
- Usuários tinham experiências inconsistentes em 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 agentes possa produzir eventos que qualquer frontend compatível com AG-UI possa renderizar—sem código de integração personalizado.
O Que É o AG-UI?
O AG-UI é um protocolo de eventos de streaming aberto que define o formato e a semântica das mensagens trocadas entre agentes de IA e interfaces voltadas para o usuário.
É:
- 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: 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 a qualquer momento
Não é:
- Um protocolo de ferramentas (esse é o trabalho do MCP)
- Um framework de agentes em si
- Uma biblioteca de componentes de UI (embora implementações de referência existam)
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 transmite eventos; humano envia mensagens |
| Público | Desenvolvedores de ferramentas/servidor | Desenvolvedores de frontend e framework de agentes |
| Foco | Quais capacidades o agente pode usar | Como o agente comunica seu estado e progresso |
| Relação | Cuida do lado "ferramenta" do agente | Cuida do lado "interface do usuário" |
São complementares. Um agente em produção tipicamente usa MCP para acessar ferramentas (pesquisa na web, geração de imagens, execução de código) e AG-UI para comunicar seu progresso e solicitar entradas humanas.
Conceitos Centrais 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 no 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 da conversa em um determinado ponto
Eventos personalizados:
CUSTOM— para eventos específicos da aplicação não cobertos pelo conjunto padrão
A Vez do Humano
O AG-UI também padroniza como os 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 as execuções do agente em threads—contextos de conversa persistentes que mantêm o estado em 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 de protocolo para retomada, ramificação e reprodução.
Como o AG-UI Funciona: Um Fluxo Típico
1. Usuário envia uma tarefa via frontend
2. Frontend envia requisição InitialRun com RunAgentInput ao backend do agente
3. Agente inicia execução e emite 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 conforme acontecem, transmitindo texto em tempo real e atualizando um indicador de progresso com base em 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 de nós de grafo usando o AG-UI Python SDK
- Integração AG-UI CopilotKit: o CopilotKit (um framework React de frontend para IA) vem com suporte nativo ao AG-UI
- Implementações personalizadas: 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 precisa de capacidades do mundo real—pesquisa 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 exiba o que está acontecendo:
Usuário: "Pesquise os 5 principais frameworks de IA e crie uma imagem de resumo"
Agente emite: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agente emite: TOOL_CALL_END (result: resultados da pesquisa)
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 por meio de eventos 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á 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. Construa uma UI de chat em streaming uma vez; use-a com LangGraph, CrewAI e AutoGen sem alterações.
Experiência de 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 durante tarefas está integrado ao protocolo—não adicionado como um recurso secundário.
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 para comunicar seu estado e receber entradas humanas torna-se tão importante quanto as ferramentas que podem acessar.
Para desenvolvedores construindo 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 passivo à medida que seu produto cresce.
Leitura complementar: