Protocolo AG-UI Explicado: O Novo Padrão para Interfaces Humano-Agente
À medida que os agentes de IA se tornam capazes de gerir 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 concebida precisamente para resolver isto. Define um padrão para a forma como os agentes de IA transmitem eventos em streaming, solicitam dados e expõem o seu estado a aplicações frontend e operadores humanos em tempo real. Se o MCP (Model Context Protocol) padronizou o acesso dos agentes a ferramentas, o AG-UI padroniza a forma como os agentes comunicam com os utilizadores.
Este guia explica o que é o AG-UI, porque é importante, como funciona e como começar a utilizá-lo na sua stack de agentes.
O Problema que o AG-UI Resolve
Antes do AG-UI, cada equipa que desenvolvia uma aplicação de agente de IA voltada para o utilizador tinha de inventar o seu próprio protocolo de comunicação. Como informa o agente o frontend de que está a "pensar"? Como solicita uma decisão humana? Como envia o utilizador uma correção a meio de uma tarefa? Como é apresentado o progresso?
As respostas variavam de equipa para equipa — frequentemente improvisadas, mal documentadas e difíceis de reutilizar. Isto criou um ecossistema fragmentado onde:
- Os frameworks de agentes não conseguiam partilhar componentes frontend
- Os programadores tinham de reconstruir a infraestrutura de streaming de UI do zero em cada projeto
- Os utilizadores tinham experiências inconsistentes nos vários produtos baseados em agentes
- A depuração do comportamento do agente exigia registos personalizados em cada implementação
O AG-UI estabelece um vocabulário partilhado 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 personalizado.
O que é o AG-UI?
O 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 para o utilizador.
Características:
- Agnóstico ao transporte: funciona via HTTP (Server-Sent Events), WebSockets ou qualquer transporte de streaming
- Agnóstico ao 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
O que 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: Compreender a Distinção
Uma fonte comum de confusão é a relação entre o AG-UI e 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 invoca ferramentas, recebe resultados | Agente faz streaming de eventos; humano envia mensagens |
| Público | Programadores de ferramentas/servidores | Programadores de frontend e frameworks de agentes |
| Foco | Que capacidades o agente pode utilizar | Como o agente comunica o seu estado e progresso |
| Relação | Gere o lado das "ferramentas" do agente | Gere o lado da "interface do utilizador" |
São complementares. Um agente em produção utiliza 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 dados humanos.
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— 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 de aplicação não abrangidos pelo conjunto padrão
A Vez do Humano (Human Turn)
O AG-UI também padroniza 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 durante a execução. Isto é distinto de uma nova vez na 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 de agentes em threads — contextos de conversa persistentes que mantêm o estado ao longo de múltiplas execuções. Uma thread no AG-UI é aproximadamente equivalente a uma sessão ou conversa noutros frameworks, mas com suporte explícito do protocolo para retomar, ramificar e reproduzir.
Como Funciona o AG-UI: Um Fluxo Típico
1. O utilizador submete 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 invoca 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 prossegue
10. O agente emite RUN_FINISHED
O frontend recebe estes eventos como um stream e renderiza-os progressivamente — mostrando as invocações de ferramentas à medida que acontecem, transmitindo texto em tempo real e atualizando um indicador de progresso com base nos 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 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 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 necessitar 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 invoca as ferramentas 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: "Investiga os 5 principais frameworks de IA e cria uma imagem 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 dos eventos AG-UI — é o que distingue uma interface humano-agente de confiança de uma caixa negra.
Por que o AG-UI é Importante para Aplicações de Agentes em Produção
Se está a desenvolver produtos baseados em agentes, o AG-UI oferece:
Reutilização de componentes. Os componentes frontend construídos de acordo com a especificação AG-UI funcionam com qualquer backend compatível. Crie uma UI de chat em streaming uma vez; utilize-a com LangGraph, CrewAI e AutoGen sem alterações.
Experiência do 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 padronizados.
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 a meio de uma tarefa está incorporado no protocolo — não foi adicionado como uma funcionalidade secundária.
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 orientados para o utilizador, o protocolo para comunicar o seu estado e receber dados humanos torna-se tão importante como as ferramentas a que podem aceder.
Para 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 personalizada que se torna um encargo à medida que o produto cresce.
Leitura adicional: