À medida que os agentes de IA se tornam suficientemente capazes para lidar com fluxos de trabalho reais, surge um novo desafio de infraestrutura: como comunicam humanos e agentes 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 criada para resolver exatamente isto. Define um padrão para a forma como os agentes de IA transmitem eventos em fluxo contínuo, solicitam entradas e apresentam estado a aplicações frontend e operadores humanos em tempo real. Se o MCP (Model Context Protocol) normalizou a forma como os agentes acedem a ferramentas, o AG-UI normaliza a forma como os agentes comunicam com os utilizadores.
Este guia explica o que é o AG-UI, por que razão é importante, como funciona e como começar a utilizá-lo no seu stack de agentes.
O Problema que o AG-UI Resolve
Antes do AG-UI, cada equipa que construía uma aplicação de agente de IA voltada para o utilizador tinha de inventar o seu próprio protocolo de comunicação. Como é que o agente informa o frontend de que está a pensar? Como solicita uma decisão humana? Como é que o utilizador envia uma correção a meio de uma tarefa? Como é apresentado o progresso?
As respostas eram diferentes para cada equipa — muitas vezes improvisadas, mal documentadas e difíceis de reutilizar. Isto criou um ecossistema fragmentado onde:
- Os frameworks de agentes não podiam partilhar componentes de frontend
- Os programadores tinham de reconstruir a infraestrutura de UI de streaming do zero para cada projeto
- Os utilizadores tinham experiências inconsistentes em produtos baseados em agentes
- A depuração do comportamento do agente exigia logging personalizado em cada implementação
O AG-UI estabelece um vocabulário partilhado 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 utilizador.
É:
- 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 utilizadores 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 em qualquer momento
Não é:
- Um protocolo de ferramentas (esse é o papel do MCP)
- Um framework de agentes em si mesmo
- Uma biblioteca de componentes de UI (embora existam implementações de referência)
AG-UI vs. MCP: Compreender a Distinção
Uma fonte comum de confusão é a forma 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 | O agente chama ferramentas, recebe resultados | O agente transmite eventos; o humano envia mensagens |
| Público | Programadores de ferramentas/servidor | Programadores de frontend e de framework de agentes |
| Foco | Que capacidades o agente pode usar | Como o agente comunica o seu estado e progresso |
| Relação | Trata do lado "ferramenta" do agente | Trata do lado "interface do utilizador" |
São complementares. Um agente em produção usa tipicamente o MCP para aceder a ferramentas (pesquisa na web, geração de imagens, execução de código) e o AG-UI para comunicar o 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— um passo discreto 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á a invocar 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 num determinado momento
Eventos personalizados:
CUSTOM— para eventos específicos da aplicação não abrangidos pelo conjunto padrão
A Vez do Humano
O AG-UI também normaliza a forma como os humanos interagem com agentes em execução. O frontend envia um AgentInput para interromper, redirecionar ou fornecer informações ao agente a meio da execução. Isto é diferente de um novo turno de conversa — o agente está em execução e o humano está a influenciar a 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. Uma thread no AG-UI é aproximadamente equivalente a uma sessão ou conversa noutros 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. O utilizador envia uma tarefa através do frontend
2. O frontend envia um pedido InitialRun com RunAgentInput ao backend do agente
3. O agente inicia a execução e emite o evento RUN_STARTED
4. O agente emite STEP_STARTED para cada passo de planeamento
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 utilizador decide redirecionar o agente → envia AgentInput com correção
9. O agente incorpora a correção e continua
10. O agente emite RUN_FINISHED
O frontend recebe estes eventos como um stream e renderiza-os progressivamente — exibindo chamadas de ferramentas à medida que acontecem, transmitindo texto em tempo real e atualizando um indicador de progresso com base em eventos de passo.
Implementar o AG-UI
Suporte a Frameworks
O AG-UI está a ganhar suporte nos principais frameworks de agentes:
- LangGraph: os eventos AG-UI podem ser emitidos a partir 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) inclui 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)
Ligar ao AnyCap
Quando o seu agente baseado em AG-UI precisa de capacidades do mundo real — pesquisa na web, geração de imagens, armazenamento de ficheiros — o AnyCap integra-se como uma camada de ferramentas abaixo da orquestração. O agente chama as ferramentas do AnyCap durante o seu ciclo de execução e emite os eventos TOOL_CALL_* correspondentes para que o frontend mostre o que está a acontecer:
Utilizador: "Pesquisa os 5 principais frameworks de IA e cria 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)
Esta transparência total — exposta através de eventos AG-UI — é o que distingue uma interface humano-agente de confiança de uma caixa negra.
Por Que o AG-UI Importa para Aplicações de Agentes em Produção
Se está a construir produtos baseados em agentes, o AG-UI oferece:
Reutilização de componentes. Os 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; utilize-a com LangGraph, CrewAI e AutoGen sem alterações.
Experiência de utilizador consistente. Os utilizadores veem os mesmos padrões de interação em diferentes fluxos de trabalho de agentes porque os tipos de eventos são normalizados.
Depuração. Os snapshots de estado e o stream de eventos do AG-UI fornecem um registo completo da execução do agente. Reproduzir um stream de eventos mostra exatamente o que o agente viu e fez em cada passo.
Supervisão humana. O mecanismo AgentInput para intervenção humana durante tarefas está integrado no 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 para o utilizador, o protocolo para comunicar o seu estado e receber entradas humanas torna-se tão importante quanto as ferramentas a que podem aceder.
Para os programadores que constroem produtos baseados em agentes em 2026, adotar o AG-UI cedo significa construir sobre uma base para a qual o ecossistema está a convergir — em vez de manter uma camada de comunicação à medida que se torna um passivo à medida que o produto cresce.
Leitura adicional: