Aplicativos do Agent Framework auto-hospedados

A auto-hospedagem permite executar um agente ou fluxo de trabalho do Agent Framework em seu próprio aplicativo ASP.NET Core, contêiner, serviço ou runtime. Seu aplicativo controla roteamento, identidade, autorização, política de solicitação, armazenamento, implantação e dimensionamento. Adicione integrações de protocolo ao host com base nos clientes necessários para dar suporte.

Use esta opção quando precisar integrar um endpoint de agente à infraestrutura existente da sua aplicação. Se você quiser que Microsoft Foundry execute o agente para você, consulte Foundry Hosted Agents. Se você precisar de gatilhos do Azure Functions ou execução durável, consulte Extensão Durável.

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

O que os auxiliares de hospedagem fornecem

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

• AddAIAgent registra um nome AIAgent com injeção de dependência.
• AddWorkflow registra um fluxo de trabalho nomeado. Encadear AddAsAIAgent para disponibilizar o fluxo de trabalho para integrações de protocolo por meio da interface do agente padrão.
• IHostedAgentBuilder configura os serviços de hospedagem associados a esse agente.
• AgentSessionStore opcionalmente, carrega e salva instâncias AgentSession por uma ID de continuação fornecida pelo aplicativo ou pelo protocolo.

O pacote de hospedagem não é um servidor HTTP ou um registro de protocolo. Seu aplicativo seleciona os agentes e fluxos de trabalho hospedados, configura seus serviços e adiciona os pontos de extremidade de protocolo necessários.

Persistir sessões hospedadas

A persistência da sessão é aceita. Sem uma configuração AgentSessionStore, as integrações de protocolo podem criar uma nova sessão para cada solicitação, mas não podem recuperar o estado de sessão de propriedade do servidor de uma solicitação anterior.

Para desenvolvimento ou um aplicativo de processo único, configure o repositório interno na memória:

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

A false configuração withIsolation é apropriada somente quando um usuário ou processo confiável possui o namespace da sessão. InMemoryAgentSessionStore perde todas as sessões quando o processo é encerrado e não compartilha o estado entre instâncias do aplicativo.

Para hospedagem durável ou distribuída, implemente-a AgentSessionStore e registre-a com WithSessionStore. Um repositório implementa operações de salvamento, obtenção e exclusão assíncronas. Ele recebe a propriedade AIAgent e uma ID opaca do repositório de sessão e deve retornar uma instância independente AgentSession de cada operação get.

AgentSessionStore e provedores de histórico atendem a diferentes finalidades. Um repositório de sessão persiste o AgentSession selecionado por uma solicitação hospedada. Um provedor de histórico controla 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 persiste esse histórico; um provedor de histórico externo armazena mensagens separadamente.

Integrar com ASP.NET Core

O pacote de hospedagem compartilhada usa o .NET host genérico e a injeção de dependência. Para um servidor HTTP, crie um aplicativo ASP.NET Core e adicione os pacotes específicos do protocolo para os pontos de extremidade que você deseja expor. Esses pacotes resolvem instâncias nomeadas AIAgent da injeção de dependência e adicionam ASP.NET Core mapeamentos de rota.

Seu aplicativo permanece responsável por seu pipeline de middleware, autenticação, autorização, validação de solicitação, opções de modelo permitidas e armazenamento durável. Um host não HTTP pode usar os serviços de hospedagem compartilhada sem adicionar pontos de extremidade de protocolo ASP.NET Core.

Adicionar protocolos ao servidor

Escolha as integrações de protocolo que seu aplicativo precisa:

Cada protocolo define seu próprio identificador de continuação e comportamento de ponto de extremidade. Mantenha a autenticação, a autorização, a propriedade da sessão e o armazenamento durável na infraestrutura de aplicativos compartilhados, em vez de reimplementá-los para cada ponto de extremidade.

Continuação de sessão segura

Uma ID de continuação identifica uma sessão a ser retomada; não prova que o chamador possui essa sessão. Escopo de sessões persistentes por um usuário autenticado, locatário ou outro limite de autorização antes de aceitar IDs fornecidas pelo cliente.

Para ASP.NET Core aplicativos que usam autenticação baseada em declarações, instale o pacote de pré-lançamento, registre Microsoft.Agents.AI.Hosting.AspNetCore o provedor de isolamento baseado em declarações e mantenha o isolamento habilitado no repositório de sessão:

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

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

Por padrão, UseClaimsBasedAgentIsolation usa a declaração ClaimTypes.NameIdentifier . Configure outra declaração somente quando ela for estável e exclusiva em todos os chamadores atendidos pelo repositório. O provedor de isolamento não autentica solicitações; configure ASP.NET Core autenticação e autorização separadamente. Com o comportamento de isolamento estrito padrão, o acesso à sessão falha quando a entidade de segurança atual não fornece a declaração configurada.

Para um host não HTTP ou outro modelo de locação, registre um personalizado AgentIsolationKeyProvider. O padrão WithInMemorySessionStore() e WithSessionStore(...) as sobrecargas encapsulam o repositório configurado em IsolationKeyScopedAgentSessionStore.

Próximas Etapas 

Vá mais fundo:

• Agentes de host com A2A
• Criar aplicativos de agente Web com AG-UI
• Agentes Hospedados do Foundry

A auto-hospedagem permite executar um agente ou fluxo de trabalho do Agent Framework em seu próprio aplicativo Web, contêiner, serviço ou runtime. Seu aplicativo controla roteamento, identidade, autorização, política de solicitação, armazenamento, implantação e dimensionamento. Adicione uma ou mais integrações de protocolo a esse servidor com base nos clientes que você precisa dar suporte.

Use esta opção quando precisar integrar um endpoint de agente à infraestrutura existente da sua aplicação. Se você quiser que Microsoft Foundry execute o agente para você, consulte Foundry Hosted Agents. Se você precisar de gatilhos do Azure Functions ou execução durável, consulte Extensão Durável.

O design desses pacotes é tal que permite a máxima flexibilidade para o desenvolvedor. Isso significa que, se você quiser criar um host que exponha um agente com a API de Respostas e abuse dos parâmetros para outras finalidades (ou seja, mapear temperature para top_p), você pode fazer isso. Se você não quiser armazenar sessões, poderá fazer isso, se quiser permitir que o chamador controle a execução completa do agente, você também pode fazer isso. Não entraremos no caminho, fornecemos auxiliares para os casos comuns e o tornaremos responsável pelo resto, para permitir que você crie o host exato de que precisa.

pip install --pre agent-framework-hosting

O que os auxiliares de hospedagem fornecem

O pacote de hospedagem genérico fornece o estado de execução compartilhada para um servidor de propriedade do aplicativo:

• AgentState emparelha um destino de agente com um SessionStore e cria sessões quando o aplicativo seleciona uma nova chave.
• SessionStore armazena, recupera e exclui sessões por uma ID selecionada pelo aplicativo. Seu repositório padrão é local de processo e não tem nenhuma política de remoção.
• WorkflowState determina um alvo de fluxo de trabalho. Seu aplicativo é responsável pelo armazenamento dos pontos de verificação e por qualquer mapeamento entre um identificador de continuação do cliente e um ponto de verificação.

AgentState não é um registro de servidor ou protocolo. Seu aplicativo seleciona uma chave de sessão autorizada, resolve o destino e salva o estado após a execução. Ele pode usar a mesma infraestrutura de destino e de aplicação compartilhada para um ou mais endpoints de protocolo.

Personalizar o armazenamento de sessão

SessionStore é uma classe de armazenamento assíncrona pequena com get, sete delete métodos. A implementação padrão mantém as sessões na memória do processo. Crie uma subclasse e sobrescreva esses métodos para armazenar objetos AgentSession no Redis, em um banco de dados, no armazenamento de blobs ou em outro repositório pertencente ao aplicativo e então passe a instância para AgentState(session_store=...).

SessionStore e provedores de histórico persistem partes separadas de uma conversa de um agente. Um repositório de sessão salva um objeto de sessão por ID de sessão, incluindo metadados de sessão e estado do provedor. Um dedicado HistoryProvider armazena a conversa separadamente, normalmente como um registro por mensagem. Essa separação é recomendada para hosts duráveis porque acrescentar mensagens individuais geralmente é mais eficiente do que reescrever um objeto de sessão em crescimento após cada turno. Um provedor de histórico é definido por agente, passando a classe de provedor de histórico desejada para o context_providers parâmetro.

Traga sua própria estrutura ou biblioteca de clientes

Os pacotes de hospedagem não estão vinculados a uma estrutura da Web ou biblioteca de clientes. As amostras usam FastAPI e aiogram porque permitem exemplos executáveis concisos, não porque as funções auxiliares exigem isso.

• Para pontos de extremidade HTTP, use as APIs de roteamento e solicitação/resposta da estrutura do aplicativo, como FastAPI, Starlette, Django, Flask, Azure Functions ou outra estrutura.
• Para clientes de protocolo como o Telegram, use qualquer biblioteca de cliente que possa fornecer uma atualização de protocolo e executar as operações produzidas pelo auxiliar.

O aplicativo seleciona sua estrutura e biblioteca de clientes; os pacotes do Agent Framework convertem apenas dados de protocolo e gerenciam o estado de execução opcional. Eles não registram rotas, autenticam chamadores, autorizam o acesso ao estado, escolhem opções de modelo permitidas ou fornecem armazenamento durável.

Adicionar protocolos ao servidor

Escolha uma ou mais integrações de protocolo:

Cada página de protocolo descreve sua configuração. No entanto, eles são projetados para permitir que você crie um único host com um ou mais protocolos habilitados e um destino que pode ser chamado; um agente ou um fluxo de trabalho. Como não limitamos você a uma estrutura da Web, você pode escolher a que deseja e configurar o host com esses protocolos com facilidade.

Continuação de sessão segura

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

1. Autenticar o chamador.
2. Autorize o chamador a acessar o estado referenciado.
3. Particione o estado durável por locatário, usuário ou espaço de trabalho autenticado.
4. Persista o estado da sessão e do ponto de verificação somente após a conclusão da execução ou do fluxo.

Esse padrão de auto-hospedagem permite que seu aplicativo implemente apenas os pontos de extremidade de protocolo e as políticas necessárias; ele não tenta implementar a superfície de API completa de todos os protocolos com suporte.

Próximas Etapas 

Vá mais fundo:

• Telegrama
• A2A
• PCM
• Agentes Hospedados do Foundry