AG-UI Integração com o Agent Framework

Integração com .NET

A integração .NET expõe um MAF AIAgent como um endpoint HTTP AG-UI. O adaptador de hospedagem converte o fluxo de resposta do agente em eventos AG-UI; O comportamento dos agentes centrais, como a execução e aprovação da ferramenta, mantém-se parte do MAF.

Use a integração .NET para:

• Transmita texto do agente através de Server-Sent Events (SSE).
• Exponha chamadas de ferramentas backend e frontend como eventos AG-UI.
• Envie pedidos de aprovação da ferramenta MAF ao cliente e devolva a decisão.
• Troque o estado do cliente, instantâneos do estado e deltas, e propriedades encaminhadas.
• Retomar sessões hospedadas persistentes com a AG-UI threadId.
• Expor fluxos de trabalho convertidos em agentes através do mesmo endpoint.

Os clientes AG-UI decidem como apresentar eventos de texto, de ferramentas, de aprovação e de estado.

Architecture

O pacote de alojamento C# adiciona um endpoint ASP.NET Core em torno de um agente MAF comum:

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

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

Installation

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

Passos seguintes

Recursos relacionados

• Visão geral do Agent Framework
• Documentação do protocolo AG-UI
• Repositório Microsoft Agent Framework

AG-UI vs. Uso Direto do Agente

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

Visão geral da arquitetura

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

┌─────────────────┐
│  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-chave

• FastAPI Endpoint: Endpoint HTTP que gere streaming SSE, comentários configuráveis para keepalive e encaminhamento de pedidos
• AgentFrameworkAgent: wrapper leve que adapta os agentes do Agent Framework ao protocolo AG-UI
• Orquestradores: lidam com diferentes fluxos de execução (padrão, human-in-the-loop, gerenciamento de estado)
• Event Bridge: converte eventos do Agent Framework em eventos de protocolo AG-UI
• Adaptadores de mensagem: conversão bidirecional entre os formatos de mensagem AG-UI e 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 se traduz em AG-UI

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

Installation

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

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

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

Capturas de mensagens do terminal de controlo

Por defeito, AgentFrameworkAgent emite um evento terminal MESSAGES_SNAPSHOT contendo a transcrição completa. Se um HistoryProvider ou a sua aplicação já gere o estado da conversa, defina emit_messages_snapshot=False para evitar reescrever a transcrição do cliente no final de cada execução:

from agent_framework_ag_ui import AgentFrameworkAgent

wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    emit_messages_snapshot=False,
)

Esta configuração suprime apenas o snapshot da mensagem do terminal. Outros eventos transmitidos, incluindo RUN_FINISHED, mantiveram-se inalterados.

Processar citações e anotações

Conteúdo de texto com Content.annotations emite um evento de AG-UI CUSTOM ligado à mensagem chamado annotations. Este evento inclui atualizações apenas por anotação que chegam após o texto de resposta, como citações de fundamentação da API de Respostas. O evento chega antes de RUN_FINISHED e não repete a mensagem de resposta.

{
  "type": "CUSTOM",
  "name": "annotations",
  "value": {
    "messageId": "assistant-message-id",
    "annotations": [
      {
        "type": "citation",
        "title": "Document",
        "url": "https://contoso.example/document.pdf",
        "annotated_regions": [
          {
            "type": "text_span",
            "start_index": 0,
            "end_index": 6
          }
        ]
      }
    ]
  }
}

Cada evento contém anotações recém-emitidas para a mensagem identificada. Anexe-as a essa mensagem e use o título, URL ou ID do ficheiro para renderizar as origens. O evento mantém campos de anotação do framework e propriedades adicionais, mas não inclui objetos do provedor raw_representation.

AGUIChatClient restaura estes lotes de eventos como Content.annotations em atualizações em streaming e respostas agregadas. Também mantém o evento personalizado em update.additional_properties["ag_ui_custom_event"]. A renderização das citações e a persistência continuam a ser responsabilidades da aplicação porque MESSAGES_SNAPSHOT não reproduz estes eventos personalizados ao vivo.

Próximas Etapas

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

1. Introdução: crie seu primeiro servidor e cliente AG-UI
2. Renderização de ferramentas de back-end: adicione ferramentas de função aos seus agentes
3. Fluxos de trabalho: Exponha fluxos de trabalho multi-agente através de AG-UI
4. Humano no Ciclo: Implementar fluxos de trabalho de aprovação
5. Compatibilidade com Aplicações MCP: Use Aplicações MCP com o seu endpoint AG-UI
6. Gestão de Estado: Sincronizar o estado entre cliente e servidor

Recursos adicionais

• Documentação do Agent Framework
• Documentação do ProtocoloAG-UI
• AG-UI Dojo App - Exemplo de aplicação que demonstra a integração com o Agent Framework
• Integração com o CopilotKit MAF - Liga frontends do CopilotKit React aos backends AG-UI
• Repositório GitHub do Agent Framework

Go suporta a AG-UI através de provider/aguiprovider para 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)
}