Aplicações do Framework de Agentes de Auto-Hospedador

A auto-hospedagem permite-lhe executar um agente ou fluxo de trabalho do Agent Framework na sua própria aplicação, contentor, serviço ou runtime ASP.NET Core. A sua aplicação controla o encaminhamento, identidade, autorização, política de pedidos, armazenamento, implementação e escalabilidade. Adiciona integrações de protocolo ao host com base nos clientes que precisas de suportar.

Use esta opção quando precisar de integrar um endpoint de agente com a sua infraestrutura de aplicação existente. Se quiser que a Microsoft Foundry execute o agente por si, veja Foundry Hosted Agents. Se precisar de triggers do Funções do Azure ou execução durável, veja Extensão Durável.

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

O que os assistentes de alojamento oferecem

O Microsoft.Agents.AI.Hosting pacote integra agentes e fluxos de trabalho com o host genérico .NET:

• AddAIAgent regista um nomeado AIAgent com injeção de dependência.
• AddWorkflow regista um fluxo de trabalho nomeado. Chain AddAsAIAgent para tornar o fluxo de trabalho disponível para integrações de protocolos através da interface padrão do agente.
• IHostedAgentBuilder Configura os serviços de alojamento associados a esse agente.
• AgentSessionStore opcionalmente carrega e armazena instâncias de AgentSession através de um ID de continuação fornecido pela aplicação ou pelo protocolo.

O pacote de alojamento não é um servidor HTTP nem um registo de protocolo. A sua aplicação seleciona os agentes alojados e fluxos de trabalho, configura os seus serviços e adiciona os endpoints de protocolo necessários.

Integrar com o ASP.NET Core

O pacote de alojamento partilhado utiliza o host genérico .NET e a injeção de dependências. Para um servidor HTTP, cria uma aplicação ASP.NET Core e adiciona os pacotes específicos do protocolo para os endpoints que queres expor. Esses pacotes resolvem instâncias com nome AIAgent através da injeção de dependências e adicionam mapeamentos de rotas do ASP.NET Core.

Por exemplo, o pacote de alojamento OpenAI pode expor um agente configurado através de um endpoint Responses:

dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

Consulte endpoints compatíveis com OpenAI para a configuração completa.

A sua aplicação continua a ser responsável pelo pipeline do middleware, autenticação, autorização, validação dos pedidos, opções de modelo permitidas e armazenamento persistente. Um host não HTTP pode usar os serviços partilhados sem adicionar terminais do protocolo ASP.NET Core.

Adicione protocolos ao seu servidor

Escolha as integrações de protocolo de que a sua aplicação necessita:

Manter sessões alojadas

AgentSessionStore a persistência é opcional para integrações de alojamento que a utilizam. Sem um armazenamento configurado, essas integrações podem criar uma nova sessão para cada pedido, mas não conseguem recuperar o estado da sessão do servidor a partir de um pedido anterior.

Registe a tua implementação durável com injeção de dependência e passa-a para o agente alojado. Pode utilizar o armazenamento em memória condicionalmente durante o desenvolvimento:

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

Neste exemplo, MyAgentSessionStore é a implementação persistente fornecida pela sua aplicação. O ramo de desenvolvimento assume um ambiente local com um utilizador de confiança e é o único caminho que desativa o isolamento. O ramo de produção mantém o comportamento de isolamento padrão; configurar um fornecedor de chave de isolamento conforme descrito em Continuação segura da sessão.

InMemoryAgentSessionStore Perde todas as sessões quando o processo sai e não partilha o estado entre as instâncias da aplicação. Implemente o seu próprio AgentSessionStore com armazenamento persistente para manter as sessões.

Um AgentSessionStore implementa operações assíncronas de gravação, obtenção e eliminação. Recebe o AIAgent proprietário e um ID de continuação opaco selecionado por uma integração de alojamento ou por uma rota pertencente à aplicação, e deve devolver uma instância AgentSession independente em cada operação get. Trate o ID de continuação como uma chave opaca em armazenamentos personalizados; a interpretação do ID depende do protocolo.

Uma implementação duradoura tem a seguinte estrutura. Substitua cada stub por operações para o sistema de armazenamento escolhido:

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

Recordes importantes de ambos agent.Id e do opaco sessionStoreId. GetSessionAsync deve devolver uma instância de sessão independente em cada chamada; usar as APIs de serialização de sessão do agente proprietário ao armazenar o estado serializado. As sessões persistentes podem conter dados sensíveis, por isso proteja-as com controlos de acesso e encriptação adequados.

AgentSessionStore armazena o AgentSession completo selecionado por um pedido alojado, não apenas as mensagens da conversa. Dependendo da pilha de agentes, uma sessão pode conter um ID de conversa gerido pelo serviço, o histórico da conversa gerido pela framework, o estado da memória ou do fornecedor de contexto, mensagens em fila, aprovações pendentes e outro estado que tem de persistir entre execuções.

Os fornecedores de histórico controlam onde as mensagens de conversa são armazenadas. Quando o histórico é mantido no estado da sessão, a persistência da sessão também preserva esse histórico. Um fornecedor externo de histórico armazena as mensagens separadamente; A sessão pode manter uma referência ou estado de fornecedor relacionado.

Continuação segura da sessão

Um ID de continuação identifica uma sessão a retomar; Isso não prova que o interlocutor seja dono dessa sessão. Restrinja as sessões persistentes a um utilizador autenticado, tenant ou outro limite de autorização antes de aceitar IDs fornecidos pelo cliente. O IsolationKeyScopedAgentSessionStore obtém uma chave de isolamento de AgentIsolationKeyProvider, combina-a com o ID de continuação do protocolo e passa o ID delimitado resultante para o armazenamento subjacente. Como resultado, o mesmo ID de continuação sob duas chaves de isolamento diferentes corresponde a duas sessões armazenadas distintas, e o autor da chamada só pode recuperar as sessões guardadas com a respetiva chave de isolamento.

Para aplicações ASP.NET Core que utilizam autenticação baseada em declarações, instale o pacote de pré-lançamento Microsoft.Agents.AI.Hosting.AspNetCore, registe o fornecedor de isolamento baseado em declarações e mantenha o isolamento ativado no armazenamento de sessões:

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

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

Por predefinição, UseClaimsBasedAgentIsolation usa a claim ClaimTypes.NameIdentifier. Configure outra reclamação apenas quando esta for estável e única em todos os chamadores servidos pela loja. O fornecedor de isolamento não autentica pedidos; configure a autenticação e a autorização do ASP.NET Core separadamente. Com o comportamento de isolamento estrito por defeito, o acesso à sessão falha quando o principal atual não fornece a reivindicação configurada.

Para um anfitrião não HTTP ou outro modelo de tenancy, registe um AgentIsolationKeyProvider personalizado. As sobrecargas predefinidas de WithInMemorySessionStore() e WithSessionStore(...) encapsulam o armazenamento configurado em IsolationKeyScopedAgentSessionStore.

Passos seguintes

Vai mais fundo:

• Alojar agentes com A2A
• Construa aplicações de agentes web com AG-UI
• Agentes Hospedados da Foundry

A auto-hospedagem permite-lhe executar um agente ou fluxo de trabalho Agent Framework na sua própria aplicação web, contentor, serviço ou runtime. A sua aplicação controla o encaminhamento, identidade, autorização, política de pedidos, armazenamento, implementação e escalabilidade. Adiciona uma ou mais integrações de protocolo a esse servidor com base nos clientes que precisas de suportar.

Use esta opção quando precisar de integrar um endpoint de agente com a sua infraestrutura de aplicação existente. Se quiser que a Microsoft Foundry execute o agente por si, veja Foundry Hosted Agents. Se precisar de triggers do Funções do Azure ou execução durável, veja Extensão Durável.

O design destes pacotes é tal que permite máxima flexibilidade ao programador. Isto significa que, se quiser construir um host que exponha um agente com a API Responses, e abusar dos parâmetros para outros fins (por exemplo, mapear temperature para top_p), pode fazê-lo. Se não quiseres armazenar sessões, podes fazer isso, se quiseres permitir que o chamador controle toda a execução do agente, também podes fazê-lo. Não vamos interferir, disponibilizamos auxiliares para os casos mais comuns e deixamos o resto à sua responsabilidade, para que possa criar exatamente o host de que precisa.

pip install --pre agent-framework-hosting

O que os assistentes de alojamento oferecem

O pacote genérico de alojamento fornece estado de execução partilhado para um servidor propriedade da aplicação:

• AgentState Emparelha um alvo de agente com um SessionStore e cria sessões quando a aplicação seleciona uma nova chave.
• SessionStore armazena, recupera e elimina sessões por um ID selecionado pela aplicação. O seu armazenamento predefinido é local ao processo e não tem política de expulsão.
• WorkflowState resolve um alvo de fluxo de trabalho. A tua aplicação é responsável pelo armazenamento dos pontos de verificação e por qualquer mapeamento de um identificador de continuação do cliente para um ponto de verificação.

AgentState não é um servidor nem um registo de protocolo. A sua aplicação seleciona uma chave de sessão autorizada, resolve o destino e guarda o estado pós-execução. Pode usar a mesma infraestrutura de destino e de aplicação partilhada para um ou vários endpoints de protocolo.

Personalizar o armazenamento da sessão

SessionStore é uma pequena classe de armazenamento assíncrona com get, set, e delete métodos. A implementação padrão mantém as sessões na memória do processo. Crie uma subclasse e sobreponha esses métodos para armazenar objetos AgentSession no Redis, numa base de dados, em armazenamento de blobs ou noutro armazenamento pertencente à aplicação e, em seguida, passe a instância a AgentState(session_store=...).

SessionStore e os fornecedores de histórico guardam partes separadas de uma conversa de um agente. Um armazenamento de sessão guarda um objeto de sessão por ID de sessão, incluindo metadados de sessão e estado do fornecedor. Um dedicado HistoryProvider armazena a conversa separadamente, normalmente como um registo por mensagem. Esta separação é recomendada para hosts duráveis porque adicionar mensagens individuais é geralmente mais eficiente do que reescrever um objeto de sessão crescente após cada turno. Um fornecedor de histórico é definido por agente, passando a classe de fornecedor de histórico desejada para o context_providers parâmetro.

Traga o seu próprio framework ou biblioteca de clientes

Os pacotes de alojamento não estão ligados a um framework web ou biblioteca cliente. Os exemplos usam o FastAPI e aiogram porque fornecem exemplos concisos e executáveis, e não porque os auxiliares os exijam.

• Para pontos de extremidade HTTP, utilize as APIs de encaminhamento e de pedido/resposta do framework da sua aplicação, como o FastAPI, Starlette, Django, Flask, Funções do Azure ou qualquer outro framework.
• Para clientes de protocolo como o Telegram, utilize qualquer biblioteca cliente que possa fornecer uma atualização de protocolo e executar as operações produzidas pelo assistente.

A aplicação seleciona o seu framework e biblioteca cliente; os pacotes Agent Framework apenas convertem dados do protocolo e gerem o estado de execução opcional. Não registam rotas, não autenticam os autores das chamadas, não autorizam o acesso ao estado, não escolhem opções de modelo autorizadas nem fornecem armazenamento duradouro.

Adicione protocolos ao seu servidor

Escolha uma ou mais integrações de protocolo:

Cada página de protocolo descreve a sua configuração. No entanto, são concebidos para permitir construir um único host com um ou mais protocolos ativados e um alvo chamável; Ou um agente ou um fluxo de trabalho. Como não o limitamos a um único framework web, pode escolher o que quiser e configurar o host com esses protocolos com facilidade.

Continuação segura da sessão

Trate cada identificador fornecido pelo protocolo como entrada não confiável. Antes de usar um ID para carregar uma sessão, ponto de controlo, tarefa ou outro estado:

1. Autentica quem chama.
2. Autorize o chamador a aceder ao estado referenciado.
3. Particione o estado durável por tenant, utilizador ou espaço de trabalho autenticado.
4. Guarde o estado da sessão e do ponto de controlo apenas depois de a execução ou a transmissão ter terminado.

Este padrão de auto-hospedagem permite que a sua aplicação implemente apenas os endpoints do protocolo e as políticas de que necessita; não tenta implementar a superfície completa da API de todos os protocolos suportados.

Passos seguintes

Vai mais fundo:

• Telegrama
• A2A
• MCP
• Agentes Hospedados da Foundry