AG-UI: como agentes e interfaces comunicam

Publicado a 12 de Outubro de 2026

Um agente não produz apenas uma resposta final. Pode enviar texto aos poucos, chamar ferramentas, atualizar dados ou pedir aprovação. Como pode a interface acompanhar esse trabalho sem depender de uma integração diferente para cada agente? O AG-UI define um formato comum de comunicação. Neste artigo explico como funciona, como ligar um agente e o que aprendemos ao construir um laboratório para o explorar.

O problema que o AG-UI resolve

Uma aplicação tradicional pede dados ao servidor e recebe uma resposta. Um agente pode trabalhar durante mais tempo e produzir vários resultados pelo caminho: começa uma tarefa, envia texto, chama uma ferramenta, altera o estado da aplicação ou espera por uma decisão humana. Se a interface só receber a resposta final, não consegue mostrar esse trabalho à medida que acontece.

Cada framework de agentes pode representar estes passos de maneira diferente. Sem um formato comum, a interface precisa de conhecer cada framework e a respetiva forma de transmitir atualizações. Mudar de agente pode obrigar a mudar também a integração da interface.

O AG-UI resolve essa parte: define um contrato comum para a comunicação entre um agente e a aplicação que o apresenta ao utilizador. Não cria o agente nem define o aspeto da interface. Define o que as duas partes enviam e recebem.

Como funciona

A aplicação envia um pedido ao endpoint AG-UI. O pedido, chamado RunAgentInput, pode incluir a conversa, o estado, o contexto e as ferramentas que a aplicação disponibiliza ao agente. O endpoint executa o agente e devolve um stream ordenado de eventos. A aplicação recebe os eventos e decide como os apresentar.

O stream começa com RUN_STARTED e termina com RUN_FINISHED ou RUN_ERROR. Para a maioria das integrações, o transporte é HTTP com SSE, uma forma de enviar eventos progressivamente. A especificação também define um transporte binário baseado em Protobuf.

O endpoint pode ser implementado de raiz ou fornecido por um adaptador para o framework do agente. Em ambos os casos, a interface recebe o mesmo formato de eventos. É essa separação que permite trocar o agente sem reescrever a interface, desde que o novo agente também esteja exposto através de AG-UI.

Que eventos são transmitidos

Os eventos descrevem o que acontece durante uma execução. Os identificadores permitem associar cada fragmento de texto, chamada de ferramenta ou atualização ao respetivo objeto. O cliente usa essa informação para reconstruir mensagens e estado.

Há dois pormenores importantes. Primeiro, as ferramentas podem pertencer ao agente ou ser disponibilizadas pela aplicação. As ferramentas da aplicação são descritas no pedido; cabe à aplicação controlar o que disponibiliza e como executa essas ações. Segundo, uma execução pode parar para pedir intervenção humana. Nesse caso, o agente assinala uma interrupção e a aplicação envia a resposta num pedido posterior para retomar o trabalho.

No SDK TypeScript há dois tipos com nomes parecidos. BaseEvent permite campos adicionais; Event representa a união dos eventos definidos pelo protocolo. Essa diferença é útil ao escrever código que distingue os eventos pelo campo type.

Como ligar um agente

Se o framework já tiver uma integração AG-UI, normalmente não é preciso escrever a tradução dos eventos. Instala-se o adaptador, liga-se o agente existente e expõe-se o endpoint. A configuração concreta varia por framework.

Um adaptador reduz o trabalho de tradução, mas não configura tudo por ti. Continuas a definir o agente, as credenciais, as sessões e a forma de o disponibilizar na tua aplicação.

Sem adaptador, o servidor próprio tem quatro responsabilidades: receber o pedido, iniciar o agente, converter os passos do agente em eventos AG-UI e transmiti-los pela ligação HTTP. Em SSE, cada evento é enviado num frame com o respetivo JSON. O servidor começa com RUN_STARTED e termina com RUN_FINISHED ou RUN_ERROR.

Ao implementar, valida tanto a estrutura de cada evento como a ordem em que é enviado. Não envies conteúdo de uma mensagem antes do respetivo evento de início, nem eventos depois do terminador da execução. Declara a versão do protocolo em RUN_STARTED.protocolVersion. Para ações com efeitos reais, valida os argumentos e exige a aprovação apropriada.

Explorar o protocolo no laboratório

Construí o AG-UI Wire Lab para observar o protocolo em funcionamento. Tem um agente sintético, um cliente, um inspetor do stream e um validador baseado no schema oficial e em regras de ordenação.

O laboratório embutido neste artigo reproduz execuções gravadas, evento a evento, mantendo os intervalos entre eventos. No cenário tool-call, observa como os argumentos chegam em fragmentos. No cenário state-sync, acompanha um snapshot e as alterações seguintes. Os separadores permitem comparar a conversa, os eventos, o conteúdo transmitido e o resultado da validação.

O laboratório de desenvolvimento inclui dez cenários e um validador próprio. Sete cenários passam sem avisos. Dois passam com um aviso esperado: um termina com um passo ainda aberto por causa de um erro, e outro inclui um tipo de evento desconhecido. Um cenário inválido de propósito é rejeitado com três erros de ordenação. Isto testa as regras implementadas no validador; não constitui uma certificação completa de conformidade com todas as regras da especificação.

O observador do laboratório também pode ligar-se a outros endpoints AG-UI. Assim, é possível testar um adaptador ou servidor diferente sem alterar o código do cliente.

Como o agente pode influenciar a interface

O AG-UI transmite eventos e dados, mas não escolhe os componentes visuais. A aplicação decide como apresentar cada resultado. Há várias formas de o fazer, com diferentes níveis de flexibilidade:

• Componentes definidos pela aplicação: a aplicação reconhece uma chamada ou um resultado e apresenta um componente que já conhece. No cenário tool-call, por exemplo, pode mostrar o resultado do tempo num cartão.
• Descrição declarativa com A2UI: o agente envia uma descrição estruturada da interface. A aplicação converte-a em componentes permitidos que controla.
• Interface fornecida por uma ferramenta com MCP Apps: uma ferramenta MCP pode disponibilizar uma interface própria, apresentada pelo cliente num ambiente isolado.

Estas opções não são níveis do próprio AG-UI. A2UI e MCP Apps tratam da apresentação da interface; AG-UI pode transportar eventos e dados entre o agente e a aplicação.

Como lidar com versões diferentes

Um cliente e um agente podem implementar versões diferentes do protocolo. O cliente declara a sua versão em RunAgentInput.protocolVersion. O agente declara a versão que usa no run em RUN_STARTED.protocolVersion; não deve simplesmente copiar o valor enviado pelo cliente.

A especificação distingue material desconhecido de dados malformados. Um consumidor não deve abortar uma execução só por encontrar um evento ou campo que não reconhece. Já um valor inválido num campo conhecido é um erro. Esta regra permite que versões compatíveis evoluam sem exigir que todos os clientes e agentes sejam atualizados ao mesmo tempo.

O schema oficial descreve a estrutura, mas não consegue representar sozinho todas estas regras de compatibilidade. Por isso, o validador do laboratório combina o schema com verificações comportamentais. O cenário versioning demonstra um evento desconhecido que não interrompe o stream. Não testa toda a negociação de versões nem a conversão de um stream para uma versão anterior.

Protocolos relacionados e CopilotKit

O AG-UI é uma opção para a comunicação entre agentes e aplicações. Outros protocolos tratam de ligações diferentes:

Preciso do CopilotKit?

Não. AG-UI é uma especificação aberta, não um produto que forneça sozinho um agente, um servidor ou uma interface pronta. Os SDKs @ag-ui/* ajudam a implementar o protocolo. O CopilotKit é um produto que usa AG-UI e acrescenta peças prontas, incluindo um runtime servidor e componentes React.

Em qualquer arquitetura, há três papéis: a interface, o endpoint que fala AG-UI e o agente. O endpoint pode adaptar um framework existente ou encaminhar pedidos para outro serviço. A tabela compara duas formas de montar essas peças:

Em diagramas, as três opções ficam assim:

No nosso caso, escolhemos implementar o cliente e o servidor diretamente. Isso exigiu mais trabalho, mas permitiu estudar cada parte do protocolo sem depender dos componentes do CopilotKit. O laboratório é a demonstração dessa escolha, não uma recomendação para todas as equipas.

O protocolo e os adaptadores continuam a evoluir. Antes de adotar um pacote, verifica se é mantido pelo projeto oficial, que versões do framework suporta e que partes do protocolo implementa. Para uma aplicação exclusivamente TypeScript/Next.js com requisitos simples, o Vercel AI SDK também pode ser uma solução mais direta.

Caso especial: OutSystems 11

O contrato AG-UI pode ser usado por qualquer aplicação capaz de enviar um pedido HTTP e ler um stream. Em OutSystems 11, o desafio é obter os eventos progressivamente. O consumidor REST padrão não disponibiliza os fragmentos SSE à interface à medida que chegam.

Há ainda uma diferença entre SSE e AG-UI: a API nativa EventSource do browser só faz pedidos GET, enquanto o transporte HTTP habitual do AG-UI envia um pedido POST com RunAgentInput. Por isso, o componente SSE do Forge não serve diretamente para este pedido. No browser, uma opção é usar fetch com ReadableStream num Web Block e interpretar os frames. Outra é colocar um proxy entre OutSystems e o endpoint AG-UI.

Para uma prova de conceito, começa com um Web Block e um endpoint de teste. Para produção, avalia um proxy se houver credenciais sensíveis, vários utilizadores ou requisitos de escalabilidade. Confirma as capacidades da versão concreta do componente Forge antes de escolher essa via.

Conclusões

O trabalho deixou seis distinções que evitam as confusões mais comuns:

1. AG-UI não é CopilotKit. O primeiro é o contrato, aberto e gratuito. O segundo é um produto que fala esse contrato e acrescenta servidor pronto, componentes React e serviços pagos. Usar um não exige o outro.
2. CopilotKit compensa pela velocidade, pesa pela dependência. Ganhas chat completo depressa, integrações e um runtime com auth, threads e routing. Perdes independência: há serviços pagos, o frontend é React, e sem Runtime és tu que distribuis essas responsabilidades.
3. AG-UI não é A2UI. O AG-UI transporta factos sobre a execução em eventos. O A2UI descreve interfaces em JSON declarativo. Um vive por baixo do outro: mensagens A2UI podem viajar dentro de eventos AG-UI, e a aplicação decide sempre o que renderiza.
4. Frameworks de agentes não são o CopilotKit. LangGraph, CrewAI, Mastra ou ADK constroem e correm agentes. O CopilotKit apresenta agentes em interfaces. O protocolo é a fronteira entre os dois mundos: o framework expõe o endpoint, qualquer cliente compatível consome.
5. O Google ADK liga-se com ou sem CopilotKit. Nos dois casos, o agente ADK é servido pelo middleware ag_ui_adk: com CopilotKit, o frontend aponta para esse endpoint; sem CopilotKit, qualquer cliente AG-UI serve. Em produção com gestão própria, confirma o licenciamento. Nota: o SSE nativo do Agent Engine não é AG-UI direto, precisa da tradução do middleware.
6. OutSystems faz-se com ponte. A plataforma não lê streams incrementais nem faz POST com SSE nativo. Para prova de conceito, um Web Block com fetch e leitura incremental. Para produção com credenciais e escala, um proxy entre OutSystems e o endpoint.

Fontes

• Documentação do AG-UI e especificação 1.0
• Repositório oficial do AG-UI e lista de integrações
• Dojo e guia de depuração
• A2UI
• MCP Apps
• CopilotKit