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.

Se estiver a explorar agentes alojados com um agente de codificação de IA, a Microsoft Foundry Skill pode ajudar a ligar estes conceitos a tarefas de implementação, implementação e operações.

Quando usar agentes hospedados

Escolha agentes alojados em vez de agentes baseados em instruções quando precisar de:

• Use o seu próprio código - utilize qualquer framework (Agent Framework, LangGraph, Kernel Semântico ou código personalizado) em vez de apenas definições baseadas em prompts.
• Use protocolos personalizados - aceite webhooks ou cargas úteis não-OpenAI através do protocolo Invocations.
• Controla recursos de computação – especifica CPU e memória para o sandbox do teu agente.
• Executa cargas de trabalho com estado – persiste ficheiros e mantém o estado durante as operações via $HOME e endpoint /files.
• Execute tarefas de longa duração de forma resiliente - preserve o trabalho em curso dos agentes durante interrupções do processo e retransmita os resultados em fluxo aos clientes que se voltam a ligar.

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, atribui um Microsoft Entra ID dedicado (identidade de agente) e expõe um endpoint dedicado para o agente.

Em tempo de execução, o Serviço de Agente disponibiliza recursos de computação para a sessão e encaminha os pedidos para o seu contentor. O código do seu agente processa essas solicitações e pode invocar modelos Foundry, ferramentas Toolbox e serviços subsequentes do Azure com a identidade do agente. A plataforma gere escalabilidade, persistência do estado da sessão, observabilidade e gestão do ciclo de vida.

O diagrama seguinte mostra como a responsabilidade é dividida. Tu és dono do código que corre dentro do sandbox. A plataforma gere o endpoint, a identidade, a escalabilidade e o estado da sessão associados ao mesmo.

Conceitos-chave

Agentes alojados

Os agentes hospedados são aplicações de IA baseadas em agentes, devidamente containerizadas, que funcionam no Agent Service. Ao contrário dos agentes baseados em prompts — que são definidos inteiramente por meio de prompts e da configuração de ferramentas no portal Foundry — os Agentes alojados são o seu próprio código, empacotado numa imagem de contentor. 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 até zero com retoma com 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, Invocações e Invocações (WebSocket)

Os contentores de agentes alojados podem expor um ou mais protocolos. Cada protocolo é fornecido por uma biblioteca leve que gere o servidor HTTP ou WebSocket, verificações de saúde e integração com OpenTelemetry. Os protocolos Responses, Invocations e Invocations (WebSocket) estão disponíveis em todas as regiões que suportam agentes hospedados.

Que protocolo devo usar?

O protocolo que escolher determina a carga útil que o seu contentor recebe e quanto do ciclo de vida da sessão, streaming e segundo plano a plataforma gere por si. Um único agente pode suportar mais do que um protocolo, por isso esta escolha não é permanente. Use a seguinte árvore de decisão para escolher um ponto de partida.

Comparação de protocolos

O modo em segundo plano e a execução resiliente resolvem diferentes problemas. O modo em segundo plano permite que o trabalho continue após o retorno do pedido inicial. A execução resistente a falhas preserva o trabalho realizado depois de o processo anfitrião parar. Para o modelo de recuperação e as responsabilidades da aplicação, veja Resiliência para agentes alojados de longa duração.

Protocolos adicionais

Os agentes alojados também suportam o protocolo Activity para Teams e integração com o canal do Microsoft 365. Quando utiliza o protocolo Responses para lógica de agente e publica em canais Microsoft 365, como o Teams, a plataforma faz automaticamente a ligação entre o protocolo Responses e o protocolo Activity para entrega nos canais — não é necessária uma ligação separada. O protocolo A2A suporta a delegação de agente para agente. Os protocolos suportados podem ser combinados num único agente.

Identidade do agente e ponto final

Cada agente alojado implementado num projeto Foundry recebe o seu próprio dedicado Microsoft Entra ID (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/responses
• Invocações: {project_endpoint}/agents/{name}/endpoint/protocolos/invocações
• Invocations (WebSocket): wss://{account}.services.ai.azure.com/api/projects/{project}/agents/{name}/endpoint/protocols/invocations_ws?api-version=v1
• A2A (pré-visualização): {project_endpoint}/agents/{name}/endpoint/protocols/a2a

Os endpoints ativos dependem dos protocolos declarados na definição da versão do agente. Defina esta configuração no serviço azure.ai.agent em azure.yaml ao utilizar azd, ou através de protocol_versions ao utilizar o SDK.

Duas identidades estão envolvidas:

Por defeito, a identidade do agente pode aceder à inferência de modelos através do ponto final do projeto e ao armazenamento de sessão. Para recursos externos (por exemplo, o seu próprio Armazenamento do Azure), atribua manualmente funções RBAC ao Microsoft Entra ID do agente. Para mais informações, consulte Acesso ao Agente para além dos predefinidos.

Quando integrados através de canais Microsoft 365 (por exemplo, Teams), os agentes alojados podem operar em dois modos de identidade, dependendo de como são invocados:

• Cenários invocados pelo utilizador (interativos): Se houver um token de utilizador presente, a plataforma suporta fluxos OAuth 2.0 On-Behalf-Of (OBO). Neste caso, o agente pode invocar serviços a jusante em nome do utilizador, utilizando as permissões delegadas do utilizador, em conformidade com as políticas do inquilino do Microsoft Entra ID.

• Cenários autónomos ou em segundo plano: Se não houver token de utilizador disponível, o agente autentica-se usando o seu próprio Microsoft Entra ID (identidade do agente), normalmente via identidade gerida, para aceder aos serviços posteriores.

Em ambos os casos, o agente mantém o seu Microsoft Entra ID dedicado para autenticação, autorização e auditabilidade. 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. A plataforma provisiona recursos computacionais sob demanda e restaura o estado persistente neles.

• 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: Pode configurar o timeout de inatividade por versão do agente de 5 a 60 minutos, com um padrão 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. A plataforma apaga permanentemente uma sessão após 30 dias de inatividade.
• 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 da 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

A capacidade de computação acompanha a sessão, não a solicitação individual. A plataforma disponibiliza um sandbox quando uma sessão inicia e liberta-o quando o timeout de inatividade configurado termina após o pedido mais recente. Quando a sessão recomeça, a plataforma restaura $HOME e /files, por isso o seu código encontra os ficheiros que escreveu anteriormente. O diagrama seguinte mostra como um pedido passa por estes estados.

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 agente imutável. A versão é um instantâneo da imagem do contentor, alocação de recursos, variáveis de ambiente e configuração do protocolo. Para atualizar o seu agente, crie e implemente uma nova versão.

Um endpoint agente serve uma versão de cada vez e encaminha 100% do seu tráfego para essa versão. A divisão de tráfego entre versões não é suportada.

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.

Observabilidade

Os agentes alojados fornecem uma capacidade de observação incorporada. A plataforma injeta automaticamente uma cadeia de conexão do Application Insights para o seu contentor de agente através de variáveis de ambiente. Os agentes que utilizam as bibliotecas de protocolos emitem rastreios OpenTelemetry por padrão, que aparecem no recurso ligado ao Application Insights em Investigar>Pesquisa de Transações ou Desempenho.

Para orientações sobre configuração e análise, consulte Ativar o rastreamento no seu projeto.

Caixa de Ferramentas na Fundição

Os agentes alojados têm acesso total a ferramentas geridas pela Foundry, incluindo Code Interpreter, Web Search (com Grounding com Bing Custom Search), Pesquisa de IA do Azure, OpenAPI, MCP, A2A, Skills, entre outras. Liga estas ferramentas através de um endpoint Toolbox MCP provisionado no seu projeto Foundry, em vez de as adicionar diretamente à definição do agente. A caixa de ferramentas dá-lhe autenticação consolidada através do passthrough de identidade OAuth, identidade de agente, autenticação baseada em chaves e muito mais. Se utilizar o Microsoft Agent Framework, estabeleça ligação através de FoundryToolbox em Python ou de AddFoundryToolboxes em .NET, em vez de um cliente MCP genérico. Outros ambientes de execução ligam-se através de bibliotecas de cliente MCP padrão. 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 das áreas de teste

Os sandboxes de agentes hospedados suportam as seguintes combinações de CPU e memória:

Armazenamento de sessão

Cada sessão tem um identificador persistente $HOME. A plataforma preserva os seus conteúdos quando desprovisiona os recursos de computação após o tempo limite de inatividade configurado. A plataforma restaura os conteúdos quando a sessão é retomada, pelo que os ficheiros escritos em $HOME mantêm-se durante os períodos de inatividade. A plataforma grava ficheiros carregados através do /files endpoint em $HOME, onde partilham o mesmo armazenamento. Cada sessão tem um orçamento total de disco de até 20 GiB com 1 vCPU ou mais, que diminui proporcionalmente para escalões de CPU inferiores. A plataforma reserva cerca de 20% desse orçamento para uso no sistema, e não está visível nem disponível para o seu agente. O restante é partilhado entre a imagem do seu contentor, $HOME, e quaisquer outras localizações com permissão de escrita no seu contentor.

Escalabilidade e dimensionamento adequado

Os agentes alojados escalam por sessão, não por réplica. A plataforma cria, quando necessário, uma nova sandbox isolada por VM para cada sessão e mantém os recursos de computação ativos enquanto continuarem a chegar pedidos. Cada pedido reinicia o temporizador inativo. Quando decorre o tempo limite de inatividade configurado após o pedido mais recente, a plataforma desaprovisiona os recursos de computação da sandbox e guarda o estado da sessão.

O tempo limite de inatividade pode variar entre 5 e 60 minutos e o valor predefinido é 15 minutos. A plataforma apaga permanentemente uma sessão após 30 dias de inatividade. Não há número de réplicas para configurar nem warm pool para dimensionar.

Como cada sessão corre no seu próprio sandbox, os valores de CPU e memória que defines numa versão do agente descrevem uma única sessão, não a pegada agregada do agente. A faturação baseia-se na CPU e na memória consumidas em todas as sessões ativas, pelo que o dimensionamento excessivo multiplica o custo pelo nível de simultaneidade.

Para ajustar o tamanho correto, execute uma carga de trabalho representativa e inspecione o uso de recursos no recurso vinculado Application Insights:

1. Abra o recurso App Insights no portal Azure e selecione Investigate>Performance.
2. Revise a CPU, memória disponível, taxa de pedidos e duração média dos pedidos durante o intervalo de tempo que testou.

Compare os picos observados com o CPU e a memória que alocou. Se os picos sustentados excederem aproximadamente 70% da alocação, aumente a alocação da próxima versão do agente; se os picos se mantiverem bem abaixo desse valor, reduza a alocação para reduzir os custos. Reteste sempre após uma alteração, porque cada nova versão é imutável.

Redes privadas

Os agentes alojados suportam a implementação dentro de recursos Foundry isolados na rede e podem usar uma Rede Virtual do Azure fornecida pelo cliente para tráfego de saída. Isto permite que agentes em implementações Foundry isoladas em rede acedam a recursos privados como bases de dados ou APIs internas. Para mais informações, consulte Configurar redes virtuais.

Limites, preços e disponibilidade

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:

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

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
• O que é a Toolbox na Foundry?
• Documentação do Azure Container Registry