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 guarda AgentSession instâncias por um ID de continuação fornecido por aplicação ou 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.

Persiste sessões hospedadas

A persistência da sessão é opt-in. Sem um , configurado AgentSessionStore, as integrações do protocolo podem criar uma nova sessão para cada pedido, mas não conseguem recuperar o estado da sessão pertencente ao servidor a partir de um pedido anterior.

Para desenvolvimento ou uma aplicação de processo único, configure a memória de armazenamento incorporada:

builder.AddAIAgent("weather-agent", (_, _) => agent)
    .WithInMemorySessionStore(withIsolation: false);

Definir withIsolation para false é apropriado apenas quando um utilizador ou processo de confiança detém o namespace 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.

Para alojamento durável ou distribuído, implemente-o AgentSessionStore e regista-o com WithSessionStore. Uma loja implementa operações assíncronas de guardar, obter e eliminar. Recebe o proprietário AIAgent e um ID de armazenamento de sessão opaco, e deve devolver uma instância independente AgentSession de cada operação de get.

AgentSessionStore e os fornecedores de história servem propósitos diferentes. Um armazenamento de sessão mantém o AgentSession selecionado por um pedido alojado. Um fornecedor de histórico controla onde as mensagens de conversa são armazenadas. Quando a história é realizada em estado de session, persistir a sessão também persiste essa história; um fornecedor externo de histórico armazena as mensagens separadamente.

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 nomeadas AIAgent a partir da injeção de dependências e adicionam mapeamentos de rotas ASP.NET Core.

A sua aplicação continua responsável pelo pipeline de middleware, autenticação, autorização, validação de pedidos, opções de modelo permitidas e armazenamento duradouro. 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:

Cada protocolo define o seu próprio identificador de continuação e comportamento do endpoint. Mantenha a autenticação, autorização, propriedade da sessão e armazenamento duradouro numa infraestrutura de aplicação partilhada, em vez de os reimplementar para cada endpoint.

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. As sessões persistidas de âmbito por um utilizador autenticado, inquilino ou outro limite de autorização antes de aceitarem IDs fornecidos pelo cliente.

Para aplicações ASP.NET Core que utilizam autenticação baseada em reivindicações, instale o pacote de pré-lançamentoMicrosoft.Agents.AI.Hosting.AspNetCore, registe-se o fornecedor de isolamento baseado em reivindicações e mantenha o isolamento ativado na loja de sessões:

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

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

Por defeito, UseClaimsBasedAgentIsolation usa a reivindicação 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; configurar a autenticação e 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 host não HTTP ou outro modelo de tenance, regista um modelo personalizado AgentIsolationKeyProviderde . O default WithInMemorySessionStore() e WithSessionStore(...) overloads envolve a memória configurada em IsolationKeyScopedAgentSessionStore.

Passos seguintes

Vai mais fundo:

• Agentes anfitriões com A2A
• Construa aplicações de agentes web com AG-UI
• Agentes Alojados 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 Alojados da Foundry