O que são agentes hospedados?

Quando constrói aplicações agentes utilizando frameworks open-source, normalmente gere-se muitas questões transversais: contentorização, configuração de servidores web, segurança, persistência de memória, escalabilidade, instrumentação e rollbacks de versões. Estas tarefas tornam-se ainda mais desafiantes em ambientes de cloud heterogéneos.

Agentes alojados no Foundry Agent Service resolvem estes desafios para os utilizadores da Microsoft Foundry. Os agentes alojados chamam modelos do catálogo de modelos Foundry para realizar raciocínios enquanto o teu código personalizado trata da orquestração. Ao utilizar esta plataforma gerida, pode implementar e operar agentes de IA de forma segura e em escala. Pode usar o seu código de agente personalizado ou um framework de agentes preferido com implementação e gestão simplificadas.

Quando usar agentes hospedados

Escolha agentes alojados em vez de agentes baseados em prompts quando precisar:

• Traga o seu próprio código - utilize qualquer framework (Agent Framework, LangGraph, Kernel Semântico ou código personalizado) em vez de depender apenas de definições por prompts.
• Use protocolos personalizados - aceite webhooks ou payloads não-OpenAI através do protocolo Invocations.
• Controla recursos de computação – especifica CPU e memória para o sandbox do teu agente.
• Executar cargas de trabalho com estado – perpetuar ficheiros e estado entre turnos via $HOME e o endpoint /files.

Como funciona

Empacota o seu agente como uma imagem de contentor e envia-o para o Azure Container Registry. Quando implementas, o Agent Service extrai a imagem, faz o cálculo provisional, atribui um Microsoft Entra ID dedicado (identidade do agente) e expõe um endpoint dedicado. Em tempo de execução, o código do seu agente gere pedidos dos clientes e pode chamar modelos Foundry, ferramentas Foundry Toolbox e serviços Azure posteriormente, usando a identidade do seu agente. A plataforma gere escalabilidade, persistência do estado da sessão, observabilidade e gestão do ciclo de vida.

Conceitos-chave

Agentes alojados

Os agentes hospedados são aplicações de IA agencial containerizadas que executam no Agent Service. Ao contrário dos agentes baseados em prompts — definidos inteiramente através de prompts e configuração de ferramentas no portal Foundry — os agentes hospedados são o próprio código do utilizador embalado como uma imagem de contêiner. Escolhe a framework, controla o comportamento em tempo de execução e implementa a imagem na infraestrutura gerida pela Microsoft.

A plataforma gere automaticamente o ciclo de vida do contentor com base na atividade, provisionando recursos quando cria uma versão e desprovisionando quando o timeout de inatividade é atingido.

Modelo de isolamento

Agentes alojados correm em sandboxes isolados por VM por sessão. Cada sessão recebe um sandbox dedicado com um sistema de ficheiros persistente ($HOME e /files), permitindo escalar para zero com retoma com persistência de estado e arranques a frio previsíveis. As sessões são isoladas umas das outras e o estado é automaticamente restaurado quando uma sessão retoma após ficar inativa.

Protocolos: Respostas e Invocações

Os contentores de agente hospedados expõem um ou ambos os dois protocolos. Cada protocolo é fornecido por uma biblioteca leve que gere o servidor HTTP, verificações de saúde e integração com o OpenTelemetry.

Que protocolo devo usar?

Comparação de protocolos

Protocolos adicionais

Os agentes alojados também suportam o protocolo Activity para Teams e a integração do canal M365 (normalmente usado juntamente com Respostas) e o protocolo A2A para delegação agente-a-agente. Todos os quatro protocolos — Respostas, Invocações, Atividade e A2A — podem ser combinados num único agente.

Identidade do agente e ponto final

Cada agente hospedado implementado num projeto Foundry recebe o seu próprio Microsoft Entra ID dedicado (identidade do agente) e endpoint dedicado — ambos criados automaticamente no momento da implementação. Não precisas de configurar manualmente identidades geridas ou roteamento.

O endpoint está disponível imediatamente após a implementação—a publicação não é obrigatória para acesso programático:

• Respostas: {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses
• Chamadas: {project_endpoint}/agents/{name}/endpoint/protocolos/chamadas

Os endpoints que estão ativos dependem dos protocolos definidos na versão do agente (declarados no agent.yaml ao usar azd ou através de container_protocol_versions ao usar o SDK).

Duas identidades estão envolvidas:

Quando implementa com azd, o papel RBAC necessário (Azure AI User no âmbito da conta) é atribuído automaticamente ao Microsoft Entra ID do agente. Para recursos externos (por exemplo, o seu próprio Armazenamento do Azure), é necessário atribuir manualmente o RBAC ao ID do Microsoft Entra do agente.

Quando integrados através dos canais Microsoft 365 (por exemplo, Teams), os agentes alojados também podem operar com a identidade de utilizador em nome de (OBO). O Microsoft Entra ID do agente pode trocar um token de utilizador para aceder a serviços subsequentes como utilizador, sujeito às políticas de alojamento. Para mais informações, consulte Aplicações de Agente e Conceitos de identidade de Agente.

Sessões e conversas

Os agentes alojados usam sessões e conversas para gerir o estado. Como funcionam depende do protocolo.

Sessões

Um ID de sessão identifica uma sessão lógica com estado persistente, incluindo $HOME e ficheiros carregados através do endpoint /files. As provisões da plataforma computam a pedido e restauram o estado persistente nela.

• Persistência de estado: o conteúdo de $HOME e /files é mantido ao longo dos turnos e dos períodos de inatividade. Quando o cálculo fica inativo e é recuperado (em infraestrutura nova ou existente), o estado da sessão é automaticamente restaurado.
• Isolamento: Cada sessão está isolada das outras.
• Ciclo de vida automático: As sessões são criadas à primeira utilização. As provisões e desprovisões da plataforma são calculadas automaticamente.
• Duração da sessão: As sessões duram até 30 dias. O timeout de inatividade é de 15 minutos — se não chegar nenhum pedido dentro dessa janela, a plataforma desprovisiona o cálculo e mantém o estado da sessão.
• APIs de gestão de sessões: Listar sessões, terminar sessões e carregar ou descarregar ficheiros por sessão.

Conversas

Um ID de conversa é um registo duradouro do histórico de conversas (mensagens, chamadas de ferramentas e respostas) armazenado no Foundry.

• Persistência: O histórico de conversas é armazenado no Foundry e persiste independentemente do estado de computação.
• Acesso multicanal: Os utilizadores podem aceder à mesma conversa a partir do playground, API, Teams ou outros canais publicados.

Como as sessões e conversas funcionam com cada protocolo

Protocolo de respostas: o ID de conversa é o conceito principal. A plataforma gere automaticamente o histórico das conversas e associa um ID de sessão a cada conversa. A plataforma devolve o ID da sessão ao cliente, que pode usá-lo para carregar ficheiros através do endpoint /files, tornando esses ficheiros disponíveis para o cálculo da conversa.

Protocolo de invocações: o ID da sessão é o conceito principal. O cliente gere diretamente o ID de sessão para manter o estado entre interações. O cliente pode carregar conteúdo através do endpoint /files usando o ID da sessão para o tornar disponível para a sessão. Não existe histórico de conversas gerido pela plataforma — tu geres o estado no teu próprio código.

Ciclo de vida da computação da sessão

Segurança e tratamento de dados

Trata um agente alojado como código de aplicação de produção.

• Não coloque segredos em imagens de contentores ou variáveis de ambiente. Use identidades e ligações geridas, e armazene segredos numa loja secreta gerida. Para orientação, veja Configurar uma ligação Key Vault.
• Tem cuidado com ferramentas e servidores não Microsoft. Se o seu agente chamar ferramentas apoiadas por serviços que não sejam da serviços Microsoft, alguns dados podem fluir para esses serviços. Revise as políticas de partilha, retenção e localização de dados para qualquer serviço que não seja da Microsoft a que se ligue.

Detalhes da plataforma

Versionamento

Cada chamada para criar uma versão produz uma versão de agente imutável — um instantâneo da imagem do contentor, alocação de recursos, variáveis de ambiente e configuração do protocolo. As implementações referem-se a uma versão específica. Para atualizar o seu agente, cria uma nova versão e a plataforma implementa-a. Note que os pedidos para criar uma versão do agente sem alterações nos parâmetros da versão do agente, como imagem do contentor, variáveis de ambiente, etc., não resultarão na criação de uma nova versão. Pode dividir o tráfego entre versões com lançamentos ponderados para suportar implementações do tipo canário e blue-green.

As variáveis de ambiente são o principal mecanismo para passar a configuração para o seu contentor em tempo de execução (por exemplo, o endpoint do projeto, nome de implementação do modelo e definições personalizadas). São definidas por versão e são imutáveis assim que a versão é criada.

Caixa de Ferramentas da Fundição

Os agentes alojados acedem às ferramentas geridas pela Foundry (Code Interpreter, Web Search, Pesquisa de IA do Azure, OpenAPI, ligações MCP personalizadas, A2A) através de um endpoint MCP Toolbox provisionado no seu projeto Foundry. O código do seu agente liga-se a este endpoint usando bibliotecas padrão de clientes MCP — a plataforma não injeta ferramentas automaticamente. Para mais detalhes, consulte a caixa de ferramentas baseada em intenções Curate no Foundry.

Suporte linguístico

Os agentes hospedados suportam Python e C#. Pode usar qualquer framework de agentes—as bibliotecas de protocolos são independentes do framework. Para exemplos que utilizam Microsoft Agent Framework, LangGraph e código personalizado, consulte o repositório foundry-samples.

Tamanhos de Sandbox

As sandboxes de agentes hospedados suportam alocações de CPU e memória que variam desde 0,25 vCPU / 0,5 GiB até 2 vCPU / 4 GiB.

Redes privadas

Agentes alojados suportam a implementação dentro de recursos Foundry isolados em rede. Para mais informações, consulte Configurar redes virtuais. Note que o Azure Container Registry que detém a sua imagem de agente deve atualmente permanecer acessível através do seu endpoint público; o ACR protegido por rede privada não é atualmente suportado.

Limites, preços e disponibilidade (pré-visualização)

Os agentes alojados estão atualmente em pré-visualização.

Limitações durante a pré-visualização

Preços

A faturação gerida em tempo de execução de hospedagem baseia-se no consumo de recursos de CPU e memória durante sessões ativas. Para as tarifas atuais, consulte a página de preços da Foundry.

Disponibilidade regional

Os agentes alojados estão atualmente disponíveis nas seguintes regiões:

• E.U.A. Leste 2
• E.U.A. Centro-Norte
• Suécia Central
• Canadá Central
• Sudeste Asiático
• Polónia Central
• Norte da África do Sul
• Coreia Central
• Sul da Índia
• Sul do Brasil
• E.U.A. Oeste
• E.U.A. Oeste 3
• Leste da Noruega
• Leste do Japão
• Centro de França
• Norte da Suíça
• Espanha Central
• Leste da Austrália

Próximos passos

Conteúdo relacionado

• Componentes de execução do agente
• Ciclo de vida do desenvolvimento do agente
• Conceitos de identidade de agente na Microsoft Foundry
• Descubra ferramentas na Foundry Tools
• Documentação do Azure Container Registry