Blazor AI components: guia de componentes agentic

O ecossistema .NET por trás dos componentes

Os componentes se integram ao ecossistema .NET existente. O Microsoft.Extensions.AI fornece as abstrações de IA, enquanto o Microsoft Agent Framework constrói agentes sobre essas abstrações.

Em seguida, o AG-UI .NET SDK conecta os agentes a aplicações voltadas para o usuário. Por sua vez, o ASP.NET Core com Aspire hospeda e orquestra todo o sistema.

Com isso, o ecossistema oferece uma experiência de ponta a ponta para aplicações agentic. Você não precisa integrar ferramentas de fornecedores diferentes, porque todas as peças funcionam juntas no .NET.

Se você ainda não conhece o framework de agentes da Microsoft, vale ler nossa visão geral do Microsoft Agent Framework antes de seguir.

ChatPage para experiências rápidas

O componente ChatPage oferece uma experiência de conversa completa e pronta para usar. Ele fornece lista de mensagens, entrada de texto, status de streaming e comportamento de nova tentativa.

Além disso, ele gerencia o carregamento e o estado da interação. Use o ChatPage quando precisar de uma interface conversacional sem customizações complexas:

<ChatPage Agent="_agent" Placeholder="Ask me anything…" />

Nos Blazor AI components, o ChatPage recebe um UIAgent, que gerencia o estado de interação que os componentes renderizam. Assim, as mensagens chegam em stream, ficam agrupadas e aparecem de forma incremental, sem código extra.

Quando você precisar de mais controle, o pacote também expõe peças menores. Entre elas estão AgentBoundary, que cria o contexto da interação, MessageList, que renderiza os turnos da conversa, e MessageInput, que recebe o texto do usuário.

UIAgent e o gerenciamento de estado

O UIAgent envolve qualquer IChatClient do Microsoft.Extensions.AI. Em seguida, ele converte os valores de ChatResponseUpdate em instâncias observáveis de ContentBlock.

Para criar um UIAgent, passe um IChatClient obtido de um provedor de modelo:

IChatClient chatClient = GetChatClient();
_agent = new UIAgent(chatClient);

O UIAgent também adiciona estado de aplicação fortemente tipado, na forma de UIAgent<TState>. Isso permite que componentes Razor observem e editem dados que tanto o usuário quanto o agente podem modificar.

Um state mapper aplica o estado que chega do agente. Dessa maneira, usuário, agente e componentes comuns colaboram sobre dados que pertencem à aplicação.

ContentBlock e BlockRenderer

O ContentBlock representa, do ponto de vista da UI, uma parte da interação. Ele tem identidade, estado de ciclo de vida e notificações de mudança que permitem rerenderizar componentes enquanto os dados chegam.

O pacote inclui blocos para conteúdo conversacional, chamadas de ferramentas, aprovações e ações de frontend. Por exemplo, existem RichContentBlock, FunctionInvocationContentBlock, FunctionApprovalBlock e UIActionBlock.

Já o BlockRenderer escolhe o conteúdo Razor de acordo com o tipo do bloco. Portanto, cada tipo de interação pode ganhar uma representação visual própria.

Renderizar saída estruturada do agente

Os Blazor AI components conseguem processar o conteúdo em stream do agente e estruturá-lo. Para isso, use um DelegatingChatClient que envolve seu IChatClient e acumula o Markdown transmitido.

O FormattedChatClient do exemplo oficial acumula texto por ID de mensagem e insere um snapshot estruturado a cada atualização:

_chatClient = new FormattedChatClient(
    Agents.CreateChatClient("/agentic_chat"));
_agent = new UIAgent(_chatClient);

Assim, conforme os dados chegam, você sempre tem um snapshot completo pronto para renderizar. O RichTextContent guarda esse snapshot como nós de parágrafos, ênfase, código inline, listas, tabelas e imagens.

Você pode construir a árvore diretamente ou usar um middleware de IChatClient para converter outros formatos. De propósito, o pacote não escolhe um parser de Markdown específico, então essa decisão continua com você.

Chamadas de ferramentas do servidor como UI

Quando o agente chama uma ferramenta, os Blazor AI components permitem renderizar uma interface customizada para ela. Nesse caso, as chamadas aparecem como instâncias fortemente tipadas de FunctionInvocationContentBlock, geradas por um source generator.

Use o atributo ToolBlock para criar o mapeamento tipado. Em seguida, o gerador cria o código que projeta os argumentos e o resultado da função no bloco:

[ToolBlock("get_weather")]
public partial class WeatherToolBlock : FunctionInvocationContentBlock
{
    [ToolParameter(Name = "location")]
    public string? Location { get; set; }

    [ToolResult]
    public WeatherInfo? Weather { get; set; }
}

A página registra o handler gerado quando cria o agente. Depois disso, o BlockRenderer mostra o estado pendente enquanto a ferramenta roda no servidor e renderiza de novo quando o resultado chega:

<BlockRenderer TBlock="WeatherToolBlock">
    @{ var weather = context.Weather ?? new WeatherInfo(); }
    <div class="weather-card">
        <div>@context.Location</div>
        <div>@weather.Temperature°C</div>
    </div>
</BlockRenderer>

A ferramenta executa inteiramente no pipeline do servidor. O card, por outro lado, é a representação que a aplicação Blazor escolheu, então ele pode usar injeção de dependência, componentes filhos, CSS e localização.

Ferramentas frontend no Blazor

Nos Blazor AI components, ferramentas de frontend executam código dentro do aplicativo Blazor, como navegação, abertura de diálogo ou atualização da UI local. Elas usam o mesmo modelo de ferramentas do Microsoft.Extensions.AI, mas rodam pelo pipeline do lado do cliente no AGUIChatClient.

Com o AIFunctionFactory, você cria ferramentas executáveis que o agente remoto pode solicitar:

var setAccentColor = AIFunctionFactory.Create(
    async (string color) =>
    {
        await InvokeAsync(() => _accent = color);
        return $"Accent color set to {color}.";
    },
    name: "set_accent_color",
    description: "Set the accent color of the page.");

Em seguida, registre a ferramenta ao criar o UIAgent. Como a chamada e o resultado são conteúdo de ferramenta comum, a aplicação reaproveita o mesmo padrão de bloco gerado das ferramentas de backend:

_agent = new UIAgent(_chatClient, options =>
{
    options.ChatOptions = new ChatOptions
    {
        Tools = [setAccentColor],
    };
    options.AddGeneratedToolBlocks();
});

Ferramentas que precisam de interface ou de entrada do usuário seguem outro caminho. Nesse caso, registrar a função com RegisterUIAction produz um UIActionBlock, que pausa a interação até a UI chamar InvokeAsync().

A documentação do Agent Framework faz um alerta importante sobre esse cenário. Declarações e resultados de ferramentas vindos de um cliente não confiável também são entrada não confiável, por isso o servidor precisa validá-los antes de qualquer operação privilegiada.

Aprovações para manter o usuário no controle

O ApprovalRequiredAIFunction envolve ferramentas com consequências e cria um FunctionApprovalBlock que pausa o agente. Assim, o usuário precisa aprovar ou rejeitar a ação antes de o fluxo continuar.

Nos Blazor AI components, esse recurso é essencial para qualquer operação que modifique dados importantes. Você renderiza os botões de aprovação com o próprio BlockRenderer:

<BlockRenderer TBlock="FunctionApprovalBlock" Context="block">
    @if (block.Status == ApprovalStatus.Pending)
    {
        <button @onclick="block.Approve">Approve</button>
        <button @onclick="() => block.Reject()">Reject</button>
    }
</BlockRenderer>

Aprovar retoma o agente e permite que a ferramenta execute. Rejeitar, por outro lado, devolve a decisão ao agente sem executar nada.

Aplicações podem usar a mesma abordagem para coletar escolhas, edições ou campos ausentes. Em outras palavras, o agente solicita uma ação, enquanto o aplicativo decide como o usuário a vê e quando ela pode prosseguir.

Estado compartilhado entre usuário e agente

Nos Blazor AI components, o UIAgent expõe estado tipado que pode alimentar qualquer parte da interface. Além disso, esse estado pode ficar sincronizado com o agente por meio de eventos AG-UI, de modo que os dois editem o mesmo artefato.

Para enviar o estado inicial ao agente, use o RawRepresentationFactory:

options.ChatOptions = new ChatOptions
{
    RawRepresentationFactory = _ => new RunAgentInput
    {
        ThreadId = threadId,
        State = JsonSerializer.SerializeToElement(
            _agent.State.Value,
            s_jsonOptions),
    },
};

O RunAgentInput é o payload da requisição inicial do AG-UI. No servidor, o agente do exemplo lê esse payload e insere a receita atual logo antes da última mensagem do usuário, para que o modelo a trate como contexto.

Depois, configure um state mapper para desserializar os snapshots de estado:

options.StateMapper = context =>
{
    if (context.Update.RawRepresentation is StateSnapshotEvent snapshot &&
        snapshot.Snapshot.Deserialize<RecipeState>(s_jsonOptions) is { } state)
    {
        context.SetState(state);
    }
};

O editor de receita renderiza _agent.State.Value.Recipe como Razor comum e assina as mudanças de estado. Então, cada atualização do agente agenda uma nova renderização, e cada edição direta substitui State.Value para a próxima requisição.

Com isso, surge um espaço de trabalho compartilhado no qual o usuário faz alterações precisas e o agente constrói sobre elas. Você não precisa escrever nenhuma sincronização complicada.

Estado preditivo para propostas seguras

Nos Blazor AI components, o estado preditivo atende aos casos em que o agente quer propor uma mudança sem substituir de imediato o estado já confirmado. Dessa forma, o usuário revisa a proposta antes de aceitá-la.

Use SetPredictiveState para sugerir mudanças sem aplicá-las:

context.SetPredictiveState(new DocumentState
{
    Document = document.GetString()!,
});

O editor mostra a proposta como um diff e mantém o documento anterior como baseline. Enquanto isso, um UIActionBlock pausa a interação até o usuário aceitar ou rejeitar a mudança:

if (accepted)
{
    _agent.State.AcceptPredictiveState();
}
else
{
    _agent.State.RejectPredictiveState();
}

Aceitar confirma o documento proposto, enquanto rejeitar restaura o baseline. Além disso, o componente descarta o estado preditivo pendente quando a execução falha, é cancelada ou termina sem decisão.

UI generativa a partir do estado do agente

UI generativa significa que o agente gera, total ou parcialmente, a experiência de interface. O AG-UI transporta os eventos de interação, e o aplicativo decide como renderizá-los.

O card de clima mostrado antes ilustra a UI generativa baseada em ferramentas. Já um plano ao vivo ilustra a UI generativa agentic, em que o agente atualiza o estado e a aplicação renderiza cada mudança.

No servidor, você mapeia resultados de ferramentas como snapshots completos ou como deltas de estado:

app.MapAGUIServer(
        "/agentic_generative_ui",
        agents.CreateAgenticGenerativeUI())
    .WithMetadata(new AGUIStreamOptions()
        .MapResultAsStateSnapshot("create_plan")
        .MapResultAsStateDelta("update_plan_step"));

Os deltas seguem o formato JSON Patch da RFC 6902. Em seguida, o StateMapper aplica snapshots e deltas ao estado tipado, e o Razor renderiza um checklist a partir de _agent.State.Value.Steps.

Na prática, você sempre sabe o que o agente está fazendo. As atualizações chegam em tempo real e a interface reflete cada passo imediatamente.