integração do AG-UI com o Agent Framework

O AG-UI é um protocolo que permite criar aplicativos de agente de IA baseados na Web com recursos avançados, como streaming em tempo real, gerenciamento de estado e componentes interativos da interface do usuário. A integração AG-UI do Agent Framework fornece conectividade perfeita entre seus agentes e clientes Web.

O que é AG-UI?

AG-UI é um protocolo padronizado para a criação de interfaces de agente de IA que fornece:

Hospedagem de agente remoto: implantar agentes de IA como serviços Web acessíveis por vários clientes
Streaming em tempo real: transmitir respostas do agente usando Server-Sent Events (SSE) para feedback imediato
Comunicação Padronizada: formato de mensagem consistente para interações de agente confiável
Gerenciamento de Sessão: manter o contexto de conversa em várias solicitações
Recursos Avançados: aprovações com intervenção humana, sincronização de estado e renderização de UI personalizada

Quando usar AG-UI

Considere usar AG-UI quando precisar:

Criar aplicativos Web ou móveis que interagem com agentes de IA
Implantar agentes como serviços acessíveis por vários usuários simultâneos
Transmitir respostas do agente em tempo real para fornecer comentários imediatos do usuário
Implementar fluxos de trabalho de aprovação em que os usuários confirmam ações antes da execução
Sincronizar o estado entre o cliente e o servidor para experiências interativas
Renderizar componentes de interface do usuário personalizados com base em chamadas de ferramenta de agente

cenários de AG-UI

AG-UI define sete cenários de demonstração. O suporte ao MAF varia de acordo com o SDK; use a seção específica do idioma nesta página para o nível de suporte atual e as diretrizes de implementação.

Chat Agentic: Chat de streaming básico com chamada automática de ferramenta
Renderização de Ferramentas do Backend: ferramentas executadas no backend com resultados transmitidos para o cliente
Human in the Loop: Solicitações de aprovação de função para confirmação do usuário
Interface do usuário do Agentic Generative: ferramentas assíncronas para operações de execução prolongada com atualizações de progresso
Interface do usuário generativa baseada em ferramentas: componentes de interface do usuário personalizados renderizados com base em chamadas de ferramenta
Estado Compartilhado: sincronização de estado bidirecional entre cliente e servidor
Atualizações de Estado Preditivo: Transmitir argumentos da ferramenta como atualizações de estado otimistas

Construir interfaces de usuário do agente com CopilotKit

O CopilotKit fornece componentes ricos de interface de usuário para criar interfaces de usuário de agentes com base no protocolo padrão AG-UI. O CopilotKit dá suporte a interfaces de chat de streaming, chamada de ferramenta de front-end &back-end, interações humanas no loop, interface do usuário generativa, estado compartilhado e muito mais. Você pode ver exemplos dos vários cenários de interface do usuário do agente compatíveis com o CopilotKit no aplicativo de exemplo AG-UI Dojo.

Para conectar um front-end do CopilotKit React a um back-end do Agent Framework AG-UI, registre seu endpoint como um HttpAgent no runtime do CopilotKit. Isso permite que as ferramentas de front-end do CopilotKit fluam como ferramentas de cliente AG-UI e todos os recursos de AG-UI (streaming, aprovações, sincronização de estado) funcionam automaticamente.

O CopilotKit ajuda você a se concentrar nas funcionalidades do agente ao mesmo tempo em que oferece uma experiência de usuário polida sem reinventar a roda. Para saber mais sobre como começar a usar o Microsoft Agent Framework e o CopilotKit, consulte a documentação sobre a integração do Microsoft Agent Framework com o CopilotKit.

Integração do .NET

A integração .NET expõe um MAF AIAgent como um ponto de extremidade HTTP AG-UI. O adaptador de hospedagem converte o fluxo de resposta do agente em eventos AG-UI; O comportamento do agente principal, como a execução e a aprovação da ferramenta, continua sendo parte do MAF.

Use a integração .NET para:

Transmitir texto do agente por Server-Sent Eventos (SSE).
Surface chamadas de ferramenta de back-end e front-end como eventos de AG-UI.
Envie solicitações de aprovação da ferramenta MAF para o cliente e retorne a decisão.
Exchange estado do cliente, instantâneos de estado e deltas e propriedades encaminhadas.
Retomar sessões hospedadas persistentes usando o AG-UI threadId.
Exponha fluxos de trabalho convertidos em agentes por meio do mesmo ponto de extremidade.

AG-UI clientes decidem como renderizar texto, ferramenta, aprovação e eventos de estado.

Architecture

O pacote de hospedagem do C# adiciona um ponto de extremidade ASP.NET Core em torno de um agente MAF comum:

AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent

MapAGUIServer adapta a solicitação AG-UI para mensagens MAF e opções de execução. Em seguida, converte a resposta de streaming do agente em eventos de AG-UI usando o SDK do AG-UI .NET.

Installation

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease

Próximas Etapas

Introdução ao AG-UI

AG-UI vs. Uso do Agente Direto

Embora você possa executar agentes diretamente em seu aplicativo usando os métodos run e run(..., stream=True) do Agent Framework, AG-UI fornece recursos adicionais.

Característica	Uso do Agente Direto	Integração AG-UI
Deployment	Inserido no aplicativo	Serviço remoto via HTTP
Acesso para Cliente	Aplicativo único	Vários clientes (Web, móvel)
Streaming	Iteração assíncrona em processo	Eventos enviados pelo servidor (SSE)
Gerenciamento de estado	Gerenciado pelo aplicativo	Sincronização de nível de protocolo bidirecional
Contexto do thread	Gerenciado pelo aplicativo	IDs de threads gerenciadas por protocolo
Fluxos de trabalho de aprovação	Implementação personalizada	Suporte a protocolo interno

Visão geral da arquitetura

A integração AG-UI usa uma arquitetura modular e limpa:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Componentes Principais

Endpoint FastAPI: endpoint HTTP que gerencia streaming SSE, comentários de keepalive configuráveis e roteamento de requisições
AgentFrameworkAgent: wrapper leve que adapta agentes do Agent Framework ao protocolo AG-UI
Orquestradores: Gerenciar diferentes fluxos de execução (padrão, intervenção humana, gerenciamento de estado)
Ponte de Eventos: converte eventos do Agent Framework em eventos de protocolo AG-UI
Adaptadores de Mensagem: conversão bidirecional entre formatos de mensagem do AG-UI e do Agent Framework
Estratégias de confirmação: estratégias extensíveis para mensagens de confirmação específicas do domínio

Como o Agent Framework é convertido em AG-UI

Entender como os conceitos do Agent Framework são mapeados para AG-UI ajuda você a criar integrações eficazes:

Conceito da Estrutura do Agente	AG-UI Equivalente	Description
`Agent`	Endereço do agente	Cada agente se torna uma interface HTTP
`agent.run()`	Solicitação HTTP POST	O cliente envia mensagens via HTTP
`agent.run(..., stream=True)`	Eventos enviados pelo servidor	Respostas de streaming via SSE
Atualizações de resposta do agente	Eventos de AG-UI	`TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`etc.
Ferramentas de função (`@tool`)	Ferramentas de back-end	Executados no servidor, resultados transmitidos para o cliente
Modo de aprovação da ferramenta	Human-in-the-Loop	Solicitações/respostas de aprovação por meio do protocolo
Histórico da conversa	Gerenciamento de threads	`threadId` mantém o contexto entre solicitações

Installation

Instale o pacote de integração AG-UI:

pip install agent-framework-ag-ui --pre

Isso instala a estrutura do agente principal e os componentes de integração AG-UI.

Próximas etapas

Para começar a AG-UI integração:

Introdução: criar seu primeiro AG-UI servidor e cliente
Renderização de ferramenta de back-end: adicionar ferramentas de função aos seus agentes
Fluxos de trabalho: expor fluxos de trabalho de vários agentes por meio de AG-UI
Human-in-the-Loop: Implementar fluxos de trabalho de aprovação
Compatibilidade de aplicativos MCP: usar aplicativos MCP com seu ponto de extremidade AG-UI
Gerenciamento de Estado: sincronizar o estado entre o cliente e o servidor

Recursos adicionais

Documentação do Agent Framework
Documentação do protocoloAG-UI
aplicativoAG-UI Dojo – aplicativo de exemplo que demonstra a integração do Agent Framework
Integração do CopilotKit MAF – Conectando interfaces front-end do CopilotKit React a sistemas back-end AG-UI
Repositório do Agent Framework no GitHub

Go oferece suporte à AG-UI por meio de provider/aguiprovider para ambos os servidores e clientes.

import "github.com/microsoft/agent-framework-go/provider/aguiprovider"

mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))

if err := http.ListenAndServe(":8888", mux); err != nil {
    log.Fatal(err)
}

Dica

Consulte os exemplos deAG-UI Go para obter exemplos completos de servidor e cliente.

Comentários

Esta página foi útil?

Last updated on 2026-08-14

integração do AG-UI com o Agent Framework

O que é AG-UI?

Quando usar AG-UI

cenários de AG-UI

Construir interfaces de usuário do agente com CopilotKit

Integração do .NET

Architecture

Installation

Próximas Etapas

Recursos relacionados

AG-UI vs. Uso do Agente Direto

Visão geral da arquitetura

Componentes Principais

Como o Agent Framework é convertido em AG-UI

Installation

Próximas etapas

Recursos adicionais

Comentários

Recursos adicionais