Protocolo AG-UI explicado: o novo padrão para interfaces entre humanos e agentes

O AG-UI é o protocolo aberto para streaming em tempo real entre agentes de IA e interfaces de frontend. Veja como funciona o modelo de eventos, que tipos de mensagens suporta e por que isso é importante para programadores de aplicações agentivas.

by AnyCap

Diagrama de arquitetura do protocolo AG-UI — mostrando eventos em streaming bidireccional entre um frontend de UI e um agente de IA

À medida que os agentes de IA se tornam suficientemente capazes para lidar com fluxos de trabalho reais, surgiu 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 precisamente para resolver isto. Define um padrão para a forma como os agentes de IA fazem streaming de eventos, pedem entrada e expõem estado a aplicações de 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 falam 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 construía uma aplicação de agente de IA virada para humanos tinha de inventar o seu próprio protocolo de comunicação. Como diz o agente ao frontend que está a pensar? Como pede uma decisão humana? Como envia o utilizador uma correcção a meio da tarefa? Como é apresentado o progresso?

As respostas eram diferentes em cada equipa — muitas vezes ad hoc, mal documentadas e difíceis de reutilizar. Isto criou um ecossistema fragmentado em que:

  • frameworks de agentes não conseguiam partilhar componentes de frontend
  • os programadores tinham de reconstruir a infraestrutura de UI em streaming de raiz em cada projecto
  • os utilizadores tinham experiências inconsistentes entre diferentes produtos com agentes
  • depurar o comportamento do agente exigia logging personalizado em cada implementação

O AG-UI estabelece um vocabulário comum e uma estrutura de eventos partilhada para que qualquer framework de agentes 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 eventos em streaming que define o formato e a semântica das mensagens trocadas entre agentes de IA e interfaces voltadas para o utilizador.

É:

  • agnóstico quanto ao transporte: funciona sobre HTTP (Server-Sent Events), WebSockets ou qualquer transporte de streaming
  • agnóstico quanto ao framework: pode ser implementado em qualquer linguagem ou framework de agentes
  • bidireccional: os agentes enviam eventos ao frontend; os utilizadores enviam mensagens e interrupções ao agente
  • com estado: 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
  • uma biblioteca de componentes de UI, embora existam implementações de referência

AG-UI vs. MCP: perceber 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
Objectivo Comunicação agente ↔ ferramenta Comunicação agente ↔ humano/frontend
Direcção O agente chama ferramentas e recebe resultados O agente transmite eventos; o humano envia mensagens
Público Programadores de ferramentas/servidores Programadores de frontend e de frameworks de agentes
Foco Que capacidades o agente pode usar Como o agente comunica estado e progresso
Relação Trata do lado das ferramentas do agente Trata do lado da interface com o utilizador

São complementares. Um agente em produção utiliza normalmente o MCP para aceder a ferramentas, como pesquisa na web, geração de imagem e execução de código, e o AG-UI para comunicar o seu progresso e pedir entrada humana.

Conceitos centrais no AG-UI

Tipos de evento

O AG-UI define um conjunto padrão de tipos de evento emitidos pelos agentes:

Eventos de ciclo de vida:

  • RUN_STARTED / RUN_FINISHED — o agente iniciou ou concluiu a execução
  • STEP_STARTED / STEP_FINISHED — uma etapa discreta dentro do fluxo de trabalho começou ou terminou
  • RUN_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 agente
  • TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END — o agente está a chamar uma ferramenta

Eventos de estado:

  • STATE_SNAPSHOT — um snapshot completo do estado actual do agente
  • STATE_DELTA — uma actualização incremental do estado
  • MESSAGES_SNAPSHOT — o histórico completo da conversa num dado momento

Eventos personalizados:

  • CUSTOM — para eventos específicos da aplicação não cobertos pelo conjunto padrão

O turno 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, redireccionar ou fornecer informação 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 actual.

Arquitectura baseada em threads

O AG-UI organiza execuções de agentes em threads — contextos persistentes de conversa que mantêm 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 no protocolo para retomar, ramificar e reproduzir.

Como o AG-UI funciona: um fluxo típico

1. O utilizador submete uma tarefa através do frontend
2. O frontend envia um pedido InitialRun com RunAgentInput para o backend do agente
3. O agente inicia a execução e emite o evento RUN_STARTED
4. O agente emite STEP_STARTED para cada etapa 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 actualizar o estado do frontend em tempo real
8. O utilizador decide redireccionar o agente → envia AgentInput com uma correcção
9. O agente incorpora a correcção e continua
10. O agente emite RUN_FINISHED

O frontend recebe estes eventos como um stream e renderiza-os progressivamente — mostrando chamadas de ferramentas à medida que acontecem, exibindo texto em tempo real e actualizando um indicador de progresso com base nos eventos de etapa.

Implementar o AG-UI

Suporte de 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 SDK Python do AG-UI
  • Integração AG-UI com CopilotKit: o CopilotKit, um framework de frontend em React para IA, disponibiliza suporte nativo a AG-UI
  • Implementações personalizadas: a especificação do AG-UI é aberta; qualquer framework pode implementá-la com as definições dos tipos de evento

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 com AG-UI precisa de capacidades do mundo real, como pesquisa na web, geração de imagem e armazenamento de ficheiros, a AnyCap integra-se como uma camada de ferramentas por baixo da orquestração. O agente chama ferramentas da 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:

User: "Pesquisa os 5 principais frameworks de IA e cria uma imagem-resumo"

Agent emits: TOOL_CALL_START (tool: "anycap_search", args: {...})
Agent emits: TOOL_CALL_END (result: search results)
Agent emits: TOOL_CALL_START (tool: "anycap_image_generate", args: {...})
Agent emits: TOOL_CALL_END (result: image URL)
Agent emits: TEXT_MESSAGE (streaming summary with embedded image)

Esta transparência total — exposta através dos eventos do AG-UI — é o que separa uma interface humano-agente fiável de uma caixa-preta.

Porque é que o AG-UI importa para aplicações de agentes em produção

Se está a criar produtos com agentes, o AG-UI oferece:

Reutilização de componentes. Componentes de frontend criados de acordo com a especificação do AG-UI funcionam com qualquer backend compatível. Crie uma UI de chat em streaming uma vez e use-a com LangGraph, CrewAI e AutoGen sem alterações.

Experiência do utilizador consistente. Os utilizadores veem os mesmos padrões de interacção em diferentes fluxos de trabalho com agentes porque os tipos de evento 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 exactamente o que o agente viu e fez em cada etapa.

Supervisão humana. O mecanismo AgentInput para intervenção humana a meio da tarefa já faz parte do protocolo — não foi acrescentado mais tarde como remendo.

Conclusão

O AG-UI preenche uma lacuna real na stack de infraestrutura de IA agentiva. À medida que os agentes se tornam mais capazes e mais virados para o utilizador, o protocolo de como comunicam o seu estado e recebem entrada humana torna-se tão importante como as ferramentas a que conseguem aceder.

Para programadores que constroem produtos com agentes em 2026, adoptar 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 feita à medida que se torna um passivo à medida que o produto cresce.

Leituras adicionais: