AG-UI: Um protocolo leve para interação entre agente e usuário

Por que os aplicativos agenticos precisam da AG-UI

Antes de vermos o código, deixa eu explicar por que precisávamos de um novo protocolo. Tudo se resume à diferença fundamental entre uma função e um agente.

A limitação da solicitação/resposta

No desenvolvimento web tradicional, as interações são transacionais. Você pede um perfil de usuário e o servidor manda pra você. É uma troca única.

Os agentes, no entanto, são imprevisíveis e demoram. Quando você pede a um agente para “depurar por que seu pipeline de CI de repente começou a falhar depois que um colega de equipe fez uma fusão”, ele não retorna um objeto JSON imediatamente. Em vez disso, pode:

1. Pega os últimos 50 registros de commit do GitHub (Ação).
2. Percebeu que uma nova dependência foi adicionada sem atualizar o arquivo de bloqueio (Observação).
3. Compare a versão do pacote com CVEs conhecidos (Raciocínio).
4. Pergunte se você quer reverter a fusão ou corrigi-la (Human-in-the-loop).

Vou explicar isso mais tarde na seção “Tipos de eventos”, mas, por enquanto, basta saber que uma solicitação HTTP padrão expiraria enquanto aguardava que tudo isso acontecesse. Você precisa de uma maneira de transmitir essas atualizações parciais para que o usuário não fique olhando para uma tela congelada.

As necessidades específicas dos agentes

Os agentes precisam de um fluxo de informações que vai além do texto. Eles precisam sincronizar o Estado.

Imagina um agente te ajudando a escrever um relatório. Não é só bater papo; é editar um documento. Você e o agente podem estar digitando ao mesmo tempo. O AG-UI resolve isso tratando o “documento” como um estado compartilhado, usando atualizações eficientes para manter sua tela e a memória do agente sincronizadas, sem sobrescrever o trabalho um do outro.

Como os agentes e as interfaces do usuário se comunicam

A AG-UI substitui o antigo modelo de Chamada de Procedimento Remoto (RPC) por um modelo de Event-Sourcing. Em vez de ficar esperando por uma resposta final, o agente manda um monte de eventos que mostram o que ele está fazendo.

A transmissão do evento

Pense no fluxo AG-UI como um ticker de notícias para o cérebro do seu agente. O aplicativo cliente (seu front-end) assina esse ticker e atualiza a interface do usuário com base no que vê. Essa abordagem separa a lógica: seu front-end React não precisa saber como o agente está pensando, só precisa saber o que mostrar.

O AG-UI evita a espera. Imagem do autor.

Tipos de eventos principais

O protocolo define tipos de eventos padrão que cobrem quase todos os cenários de interação. Aqui estão os principais que você vai ver:

1. TEXT_MESSAGE_*: Eventos que transmitem texto gerado peça por peça. Isso normalmente envolve eventos _START, _CONTENT (o fluxo de tokens) e _END, que juntos criam o efeito familiar de “digitação”.

2. TOOL_CALL: Sinais de que o agente quer fazer algo, tipo ver o tempo ou consultar um banco de dados. O mais importante é que o AG-UI consegue transmitir osargumentos da chamada da ferramenta, permitindo que sua interface do usuário preencha formulários antes mesmo que o agente termine de “falar”.

3.  STATE_DELTA: Esse é o grande responsável pela colaboração. Em vez de reenviar o documento inteiro toda vez que uma letra muda, o agente manda um pequeno “diff” (tipo “adicionar 'olá' no índice 5”).

4. INTERRUPT: A válvula de segurança. Se um agente executar uma ação sensível (como “Excluir banco de dados”), ele emitirá um evento de interrupção. O fluxo fica parado até o usuário mandar de volta um evento de aprovação.

Multimodalidade e etapas de raciocínio

O protocolo não se limita ao texto. Ele lida com multimodalidade, ou seja, streaming de imagens, áudio e anexos de arquivos junto com a conversa. Ele também padroniza as etapas de raciocínio, separando os pensamentos internos do agente (traços de raciocínio) da resposta pública final. Você pode ter notado um padrão parecido ao usar ferramentas como o chatGPT, onde os indicadores de progresso ou etapas intermediárias aparecem separadamente da resposta final. Isso permite que você decida se quer mostrar aos usuários o andamento da execução ou só o resultado final.

Blocos de construção AG-UI

Agora que você já entendeu o fluxo, vamos ver os recursos específicos que tornam a AG-UI tão útil para os desenvolvedores.

Interface do usuário generativa

O texto é ótimo, mas às vezes um gráfico é melhor. A interface do usuário generativa permite que um agente decida, durante a execução, que deve mostrar um componente da interface do usuário em vez de texto.

AG-UI transmite eventos; A2UI define componentes. Imagem do autor.

Tem uma diferença aqui que muitas vezes confunde as pessoas (vou falar sobre isso de novo na seção sobre estrutura): AG-UI é o mecanismo de entrega (camada de transporte), e A2UI (Interface Agente-para-Usuário) é a definição da interface do usuário (carga útil). Um agente pode usar um evento AG-UI TOOL_CALL para transportar uma carga útil A2UI, uma árvore JSON declarativa que descreve um componente da interface do usuário (como um “Cartão de Preço de Ações”). O seu frontend recebe isso e gera o gráfico de verdade.

Estado compartilhado com JSON Patch

Lidar com o estado compartilhado é complicado. Se o agente enviar um objeto de contexto enorme de 5 MB a cada segundo, seu aplicativo ficará lento.

O AG-UI resolveisso com o JSON Patch (RFC 6902). Como eufalei antes sobre sincronização de estado, quando o agente muda um valor na sua memória, ele calcula a diferença e manda um eventoSTATE_DELTA.

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]

O cliente recebe essa instrução leve e aplica-a ao seu estado local. Essa eficiência é o que torna possível a colaboração em tempo real com os agentes.

AG-UI no panorama dos protocolos

Você já deve ter ouvido falar de outros protocolos, como o MCP (Protocolo de Contexto de Modelo). É importante saber onde o AG-UI se encaixa na pilha para não usar a ferramenta errada para o trabalho.

A pilha de agentes

Gosto de pensar nisso como um triângulo de comunicação:

1. MCP (Agente ↔ Ferramentas): Isso conecta o agente ao mundo backend: bancos de dados, repositórios GitHub e APIs internas. É sobre conseguir informações.
2. A2A (Agente ↔ Agente): Isso permite que os agentes conversem entre si, delegando tarefas a subagentes.
3. AG-UI (Agente ↔ Usuário): Essa é a “Última Milha”. Ele conecta a inteligência do agente ao usuário humano.

O Protocolo Trinity conectando agentes. Imagem do autor.

O AG-UI não liga pra como o agente conseguiu os dados (isso é tarefa do MCP, como eu falei antes); ele só se preocupa em como mostrar esses dados pra você.

Implementando a AG-UI

Vamos ver como isso funciona na prática. Os desenvolvedores geralmente interagem com a AG-UI de uma das três maneiras: criando 1) aplicativos de agente (conectando um front-end a um agente), criando 2) integrações (tornando uma estrutura compatível) ou criando 3) clientes (criando novos front-ends). A maioria de vocês vai estar na primeira categoria.

Vou explicar o código daqui a pouco, mas primeiro entenda que normalmente você não vai escrever os manipuladores de protocolo brutos sozinho. As bibliotecas cuidam da embalagem. Mas é preciso entender o fluxo para fazer a depuração.

Criando o canal de eventos

A maioria das implementações usa Server-Sent Events (SSE) porque são simples, compatíveis com firewalls e perfeitos para streaming unidirecional do servidor para o cliente. Eu já tinha dado uma dica disso antes, mas o SSE é o segredo que deixa esse protocolo tão leve em comparação com os WebSockets.

Em uma configuração típica (como com o Microsoft Agent Framework ou CopilotKit), seu servidor expõe um endpoint que atualiza a conexão para um fluxo.

Assinatura simples de eventos

Aqui está um exemplo conceitual de como um cliente front-end escuta o fluxo. Observe como lidamos com diferentes tipos de eventos para atualizar a interface do usuário.

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};

Esse padrão esconde a complexidade da lógica interna do agente. Seu front-end é só um “reprodutor” dos eventos que o agente manda.

Integrações e suporte ao ecossistema

Você não precisa criar tudo isso do zero. O ecossistema está amadurecendo rapidamente, com as principais plataformas e estruturas convergindo para padrões de interação semelhantes, orientados por eventos.

O “Triângulo de Ouro” das ferramentas

A Microsoft fala de um “Triângulo de Ouro” para o desenvolvimento de agentes:

1. DevUI: Para visualizar o processo de pensamento do agente (depuração).
2. OpenTelemetry: Para medir o desempenho e o custo.
3. AG-UI: Para se conectar ao usuário.

Estruturas compatíveis

O ecossistema está crescendo rapidinho. Além dos principais participantes, o apoio está crescendo em todos os setores:

1. Estrutura do Microsoft Agent: Tem middleware nativo para ASP.NET Core (Microsoft.Agents.AI.Hosting.AGUI).

2. CopilotKit: Funciona como o “navegador” para AG-UI, oferecendo um front-end React completo que sabe como renderizar esses eventos prontos para uso.

3. Ecossistema Python: Frameworks como LangGraph, CrewAI, Mastra, Pydantic AI, Agno e LlamaIndex podem ser expostos como pontos finais AG-UI.

4. SDKs: Embora o, o TypeScript e o Python sejam os mais usados, os SDKs estão ativos ou em desenvolvimento para Kotlin, Go, Dart, Java eRust.

Confiabilidade, depuração e segurança

Abrir uma linha direta de comunicação entre uma IA e um navegador traz alguns riscos. Veja como manter seu aplicativo seguro.

O servidor front-end confiável

Nunca deixe um cliente se conectar diretamente ao seu agente em tempo real. Como eu falei na seção “Por que os aplicativos agenticos precisam de AG-UI”, sempre use um servidor front-end confiável (padrão BFF). Esse servidor funciona como um guardião. Ele adiciona autenticação, limitação de taxa e validação de entrada antes de passar a mensagem do usuário para o agente.

Considerações de segurança

Injeção imediata

Usuários mal-intencionados podem tentar ignorar as instruções do seu agentepor meio de ataques de injeção de prompt. Como eu faleiantes, seu middleware deve limpar as entradas.

Chamadas de ferramentas não autorizadas

Só porque um agente pode excluir um arquivo, não significa que o usuário atual deva ter permissão para fazê-lo. Seu servidor de confiança precisa filtrar as ferramentas disponíveis para o agente com base nas permissões do usuário.

Segurança do Estado

Como o estado é compartilhado por meio de patches JSON, tome cuidado com a poluição de protótipos. Certifique-se de que sua biblioteca de patches não permite modificações em propriedades protegidas, como __proto__.

Depurando com o Dojo

Se o seu agente estiver agindo de forma estranha, useo AG-UI Dojo. É um site de testeque permite visualizar o fluxo bruto de eventos. Isso ajuda você a detectar problemas como patches JSON malformados ou chamadas de ferramentas que estão sendo disparadas, mas não retornando resultados.

Conclusão

A gente falou sobre a arquitetura, os tipos de eventos e os padrões de implementação do AG-UI.

Agora, eu entendo que o desenvolvedor solo comum ou alguém em uma empresa pequena não vai, na real, “adotar AG-UI” e de repente “desacoplar seu front-end do back-end”. Tudo isso exigiria decisões arquitetônicas importantes, apoio de várias equipes e recursos que a maioria das pessoas não tem.

Mas entender a AG-UI é importante, mesmo que você não esteja implementando ela. Quando você está avaliando estruturas de agentes ou decidindo se deve criar internamente ou usar uma plataforma, saber como é uma “boa” comunicação entre o agente e a interface do usuário ajuda a tomar uma decisão melhor. Você vai perceber quando uma ferramenta estiver te forçando a seguir padrões rígidos.

Se você quiser se aprofundar na criação desses sistemas, confira nossos cursos Introdução aos agentes de IA e Criação de sistemas agenticos escaláveis para levar suas habilidades para o próximo nível.