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 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 os 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