Compartilhar via

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

Recursos suportados

A integração AG-UI do Agent Framework dá suporte a todos os 7 recursos de protocolo AG-UI:

  1. Chat Agentic: Chat de streaming básico com chamada automática de ferramenta
  2. Renderização de Ferramentas do Backend: ferramentas executadas no backend com resultados transmitidos para o cliente
  3. Human in the Loop: Solicitações de aprovação de função para confirmação do usuário
  4. Interface do usuário do Agentic Generative: ferramentas assíncronas para operações de execução prolongada com atualizações de progresso
  5. Interface do usuário generativa baseada em ferramentas: componentes de interface do usuário personalizados renderizados com base em chamadas de ferramenta
  6. Estado Compartilhado: sincronização de estado bidirecional entre cliente e servidor
  7. 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 de vários cenários de interface do usuário do agente, compatíveis com o CopilotKit, no aplicativo de exemplo AG-UI Dojo.

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 integração do Microsoft Agent Framework para a documentação do CopilotKit .

AG-UI vs. Uso do Agente Direto

Embora você possa executar agentes diretamente em seu aplicativo usando os métodos Run e RunStreamingAsync do Agent Framework, AG-UI fornece recursos adicionais.

Característica Uso do Agente Direto Integração AG-UI
Implantação Inserido no aplicativo Serviço remoto via HTTP
Acesso para Cliente Aplicativo único Vários clientes (Web, móvel)
Transmissão ao vivo Iteração assíncrona em processo Eventos enviados pelo servidor (SSE)
Gerenciamento de estado Gerenciado pelo aplicativo Instantâneos de estado no nível do protocolo
Contexto da sessão Gerenciado pelo aplicativo IDs de sessão gerenciadas por protocolo
Fluxos de trabalho de aprovação Implementação personalizada Padrão de middleware interno

Visão geral da arquitetura

A integração AG-UI usa ASP.NET Core e segue uma arquitetura limpa baseada em middleware:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  ASP.NET Core           │
│  MapAGUI("/", agent)    │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AIAgent                │
│  (with Middleware)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  IChatClient            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Componentes Principais

  • ASP.NET Core Endpoint: MapAGUI este método de extensão manipula solicitações HTTP e streaming de SSE
  • AIAgent: agente do Agent Framework criado a partir de IChatClient ou implementação personalizada
  • Middleware Pipeline: middleware opcional para aprovações, gerenciamento de estado e lógica personalizada
  • Adaptador de protocolo: converte entre tipos do Agent Framework e eventos de protocolo AG-UI
  • Cliente de chat: Microsoft.Extensions.AI cliente de chat (Azure OpenAI, OpenAI, Ollama etc.)

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
AIAgent Endereço do agente Cada agente se torna uma interface HTTP
agent.Run() Solicitação HTTP POST O cliente envia mensagens via HTTP
agent.RunStreamingAsync() Eventos enviados pelo servidor Respostas de streaming via SSE
AgentResponseUpdate Eventos de AG-UI Convertido em eventos de protocolo automaticamente
AIFunctionFactory.Create() Ferramentas de back-end Executado no servidor, resultados transmitidos
ApprovalRequiredAIFunction Human-in-the-Loop Middleware converte para protocolo de aprovação
AgentSession Gerenciamento da sessão ConversationId mantém o contexto
ChatResponseFormat.ForJsonSchema<T>() Instantâneos de estado A saída estruturada transforma-se em eventos de estado

Installation

A integração AG-UI está incluída no pacote de hospedagem do ASP.NET Core:

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

Esse pacote inclui todas as dependências necessárias para AG-UI integração, incluindo Microsoft.Extensions.AI.

Próximas etapas

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

  1. Introdução: criar seu primeiro AG-UI servidor e cliente
  2. Renderização de ferramenta de back-end: adicionar ferramentas de função aos seus agentes

Recursos adicionais

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
Implantação Inserido no aplicativo Serviço remoto via HTTP
Acesso para Cliente Aplicativo único Vários clientes (Web, móvel)
Transmissão ao vivo 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 manipula o streaming de SSE e o 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 Ponto de extremidade 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_STARTetc.
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 de conversas 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:

  1. Introdução: criar seu primeiro AG-UI servidor e cliente
  2. Renderização de ferramenta de back-end: adicionar ferramentas de função aos seus agentes

Recursos adicionais

  • Last updated on