O que são agentes hospedados?

Ao criar aplicativos agente usando estruturas de software livre, você normalmente gerencia muitas preocupações de corte cruzado: contêinerização, configuração do servidor Web, segurança, persistência de memória, dimensionamento, instrumentação e reversões de versão. Essas tarefas se tornam ainda mais desafiadoras em ambientes de nuvem heterogêneos.

Os agentes hospedados no Serviço do Foundry Agent resolvem esses desafios para usuários do Microsoft Foundry. Os agentes hospedados chamam modelos do catálogo de modelos do Foundry para executar o raciocínio enquanto seu código personalizado manipula a orquestração. Usando essa plataforma gerenciada, você pode implantar e operar agentes de IA com segurança e em escala. Você pode usar o código do agente personalizado ou uma estrutura de agente preferencial com implantação e gerenciamento simplificados.

Se você estiver explorando agentes hospedados com um agente de codificação de IA, o Microsoft Foundry Skill poderá ajudar a conectar esses conceitos às tarefas de implementação, implantação e operações.

Quando usar agentes hospedados

Escolha agentes hospedados em vez de agentes baseados em prompt quando precisar:

• Traga seu próprio código — use qualquer framework (Agent Framework, LangGraph, Kernel semântico ou código personalizado) em vez de definições apenas de prompt.
• Use protocolos personalizados — aceite webhooks ou payloads que não sejam da OpenAI por meio do protocolo Invocations.
• Controle os recursos de computação - especifique CPU e memória para a sandbox do agente.
• Execute workloads com estado — persista arquivos e estado entre turnos por meio de $HOME e do ponto de extremidade /files.
• Execute tarefas de longa duração com resiliência - preserve o trabalho do agente em andamento durante interrupções de processo e reproduza os resultados transmitidos em fluxo para clientes que se reconectam.

Como funciona

Empacote seu agente como uma imagem de contêiner e envie-o por push para Registro de Contêiner do Azure. Ao realizar a implantação, o Serviço de Agente extrai a imagem, atribui um Microsoft Entra ID exclusivo (identidade do agente) e disponibiliza um ponto de extremidade dedicado para o agente.

Em tempo de execução, o Agent Service provisiona recursos computacionais para a sessão e encaminha solicitações ao seu contêiner. O código do agente processa essas solicitações e pode chamar modelos do Foundry, ferramentas do Toolbox e serviços downstream do Azure usando a identidade do agente. A plataforma lida com dimensionamento, persistência de estado de sessão, observabilidade e gerenciamento do ciclo de vida.

O diagrama a seguir mostra como a responsabilidade é dividida. Você possui o código que é executado dentro do sandbox. A plataforma gerencia o ponto de extremidade, a identidade, o escalonamento e o estado da sessão.

Principais conceitos

Agentes hospedados

Os agentes hospedados são aplicativos de IA com função de agente containerizados que rodam no Agent Service. Ao contrário dos agentes baseados em prompts, que são definidos inteiramente por meio de prompts e configuração de ferramentas no portal do Foundry, os agentes hospedados são seu próprio código empacotado como uma imagem de contêiner. Você escolhe a estrutura, controla o comportamento do runtime e implanta a imagem na infraestrutura gerenciada por Microsoft.

A plataforma gerencia automaticamente o ciclo de vida do contêiner com base na atividade, provisionando recursos quando você cria uma versão e desprovisiona quando o tempo limite ocioso é atingido.

Modelo de isolamento

Os agentes hospedados são executados em sandboxes de VM isoladas por sessão. Cada sessão recebe um ambiente de teste dedicado com um sistema de arquivos persistente ($HOME e /files), permitindo a redução a zero com retomada com estado e inicializações a frio previsíveis. As sessões são isoladas umas das outras e o estado é restaurado automaticamente quando uma sessão é retomada após ficar ociosa.

Protocolos: respostas, invocações e invocações (WebSocket)

Contêineres de agente hospedado podem expor um ou mais protocolos. Cada protocolo é fornecido por uma biblioteca leve que manipula o servidor HTTP ou WebSocket, verificações de integridade e integração do OpenTelemetry. Os protocolos Responses, Invocations e Invocations (WebSocket) estão disponíveis em todas as regiões que oferecem suporte a Agentes hospedados.

Qual protocolo devo usar?

O protocolo selecionado define o payload recebido pelo contêiner e determina quanto do ciclo de vida da sessão, do streaming e das tarefas em segundo plano será gerenciado pela plataforma. Um único agente pode dar suporte a mais de um protocolo, portanto, essa opção não é permanente. Use a árvore de decisão a seguir para escolher um ponto de partida.

Comparação de protocolo

O modo em segundo plano e a execução resiliente resolvem problemas diferentes. O modo em segundo plano permite que o trabalho continue após o retorno da solicitação de iniciação. A execução resiliente preserva o trabalho depois que o processo de hospedagem é interrompido. Para o modelo de recuperação e as responsabilidades do aplicativo, consulte Resiliência de agentes hospedados de execução prolongada.

Protocolos adicionais

Os agentes hospedados também dão suporte ao protocolo Activity para a integração de canais do Teams e Microsoft 365. Quando você usa o protocolo Responses para a lógica do agente e publica em canais do Microsoft 365, como o Teams, a plataforma conecta automaticamente o Responses ao protocolo Activity para entrega de canal. Não é necessária nenhuma configuração adicional. O protocolo A2A dá suporte à delegação de agente para agente. Os protocolos com suporte podem ser combinados em um único agente.

Identidade do agente e ponto de extremidade

Cada agente hospedado implantado em um projeto do Foundry obtém seu próprio dedicated Microsoft Entra ID (identidade do agente) e dedicated endpoint — ambos criados automaticamente no momento da implantação. Você não precisa configurar identidades gerenciadas ou roteamento manualmente.

O endpoint está disponível imediatamente após a implantação — a publicação não é necessária para acesso por programação:

• Respostas: {project_endpoint}/agents/{name}/endpoint/protocols/openai/responses
• Invocações: {{project_endpoint}}/agents/{{name}}/endpoint/protocols/invocations
• Invocações (WebSocket): wss://{account}.services.ai.azure.com/api/projects/{project}/agents/{name}/endpoint/protocols/invocations_ws?api-version=v1
• A2A (versão prévia): {project_endpoint}/agents/{name}/endpoint/protocols/a2a

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

Duas identidades estão envolvidas:

A identidade do agente pode acessar a inferência de modelos por meio do endpoint do projeto e do armazenamento de sessão, por padrão. Para recursos externos (por exemplo, seu próprio Armazenamento do Azure), atribua funções RBAC manualmente à Microsoft Entra ID do agente. Para obter mais informações, consulte o acesso do Agente além dos padrões.

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

• Cenários invocados pelo usuário (interativo): se um token de usuário estiver presente, a plataforma oferecerá suporte a fluxos OAuth 2.0 On-Behalf-Of (OBO). Neste caso, o agente pode chamar serviços downstream em nome do usuário com as permissões delegadas do usuário, sujeito a políticas de locatário do Microsoft Entra ID.

• Cenários autônomos ou em segundo plano: Se nenhum token de usuário estiver disponível, o agente se autentica usando seu próprio Microsoft Entra ID (identidade do agente), normalmente por meio de identidade gerenciada, para acessar serviços downstream.

Em ambos os casos, o agente mantém sua ID dedicada do Microsoft Entra para autenticação, autorização e auditabilidade. Para obter mais informações, consulte os aplicativos do Agente e os conceitos de identidade do Agente.

Sessões e conversas

Os agentes hospedados usam sessões e conversas para gerenciar o estado. Como eles funcionam depende do protocolo.

Sessões

ID de sessão identifica uma sessão lógica com estado persistente, incluindo $HOME e arquivos carregados via o endpoint /files. A plataforma provisiona recursos sob demanda e restaura o estado persistido neles.

• Persistência de estado: o conteúdo de $HOME e /files é mantido entre turnos e entre períodos ociosos. Quando a computação fica ociosa e é trazida de volta (na infraestrutura nova ou existente), o estado da sessão é restaurado automaticamente.
• Isolamento: cada sessão é isolada de outras sessões.
• Ciclo de vida automático: as sessões são criadas no primeiro uso. A plataforma provisiona e desprovisiona recursos computacionais automaticamente.
• Tempo de vida da sessão: você pode configurar o tempo limite ocioso por versão do agente de 5 a 60 minutos, com um padrão de 15 minutos. Se nenhuma solicitação chegar nessa janela, a plataforma desprovisiona a computação e persiste o estado da sessão. A plataforma exclui permanentemente uma sessão após 30 dias de inatividade.
• APIs de gerenciamento de sessão: listar sessões, encerrar sessões e carregar ou baixar arquivos por sessão.

Conversas

Uma ID de conversa é um registro durável do histórico de conversas (mensagens, chamadas de ferramentas e respostas) armazenado no Foundry.

• Persistência: o histórico de conversas é armazenado na Foundry e persiste independentemente do estado de computação.
• Acesso entre canais: os usuários podem acessar a mesma conversa no playground, na API, no Teams ou em outros canais publicados.

Como as sessões e conversas funcionam com cada protocolo

Protocolo de respostas: a ID da conversa é o conceito principal. A plataforma gerencia o histórico de conversas automaticamente e associa uma ID de sessão a cada conversa. A plataforma retorna o ID de sessão para o cliente, que pode usá-lo para carregar arquivos via o endpoint /files, tornando esses arquivos disponíveis para o processamento da conversa.

Protocolo de invocações: o ID de sessão é o conceito principal. O cliente gerencia a ID da sessão diretamente para manter o estado entre interações. O cliente pode fazer upload de conteúdo via o endpoint /files, utilizando o ID da sessão para disponibilizá-lo. Não há histórico de conversas gerenciadas pela plataforma— você gerencia o estado em seu próprio código.

Ciclo de vida do processamento de sessão

A computação segue a sessão, não a solicitação individual. A plataforma provisiona um ambiente isolado quando uma sessão é iniciada e o libera quando o tempo limite de inatividade configurado expira após a solicitação mais recente. Quando a sessão é retomada, a plataforma restaura $HOME e /files, portanto, o código localiza os arquivos que ele escreveu anteriormente. O diagrama a seguir mostra como uma solicitação se move por esses estados.

Segurança e manipulação de dados

Tratar um agente hospedado como código de aplicativo de produção.

• Não coloque segredos em imagens de contêiner ou variáveis de ambiente. Use identidades e conexões gerenciadas e armazene segredos em um repositório de segredos gerenciado. Para obter diretrizes, consulte Set up a Key Vault connection.
• Tenha cuidado com ferramentas e servidores não Microsoft. Se o seu agente chamar ferramentas apoiadas por serviços de terceiros, alguns dados poderão fluir para esses serviços. Examine as políticas de compartilhamento, retenção e localização de dados para qualquer serviço não Microsoft que você conectar.

Detalhes da plataforma

Versionamento

Cada chamada para criar uma versão produz uma versão do agente imutável. A versão é um instantâneo da imagem do contêiner, da alocação de recursos, das variáveis de ambiente e da configuração do protocolo. Para atualizar seu agente, crie e implante uma nova versão.

Um endpoint de agente usa uma versão por vez e direciona 100% do tráfego para essa versão. Não há suporte para a divisão de tráfego entre versões.

As variáveis de ambiente são o mecanismo principal para passar a configuração para o contêiner em runtime (por exemplo, o ponto de extremidade do projeto, o nome da implantação do modelo e as configurações personalizadas). Eles são definidos por versão e são imutáveis depois que a versão é criada.

Observabilidade

Os agentes hospedados fornecem observabilidade integrada. A plataforma injeta automaticamente uma cadeia de conexão do Application Insights no contêiner do agente por meio de variáveis de ambiente. Os agentes que usam as bibliotecas de protocolo emitem rastreamentos OpenTelemetry por padrão, que aparecem no recurso Application Insights vinculado em Investigar>Pesquisa de transações ou Desempenho.

Para obter diretrizes de configuração e análise, consulte Habilitar rastreamento em seu projeto.

Caixa de ferramentas na Foundry

Os agentes hospedados têm acesso total às ferramentas gerenciadas pelo Foundry, incluindo Interpretador de Código, Pesquisa na Web (com aterramento com pesquisa personalizada do Bing), Pesquisa de IA do Azure , OpenAPI, MCP, A2A, Skills e muito mais. Você conecta essas ferramentas por meio de um Toolbox MCP endpoint provisionado em seu projeto Foundry, em vez de adicioná-las diretamente à definição do agente. O kit de ferramentas oferece autenticação consolidada por meio de delegação de identidade via OAuth, identidade do agente, autenticação por chave e muito mais. Se você usar Microsoft Agent Framework, conecte-se por meio FoundryToolbox de Python ou AddFoundryToolboxes em .NET em vez de um cliente MCP genérico. Outros runtimes se conectam usando bibliotecas de cliente MCP padrão. Para obter detalhes, consulte Coletar um conjunto de ferramentas baseado em intenção no Foundry.

Suporte ao idioma

Os agentes hospedados dão suporte a Python e C#. Você pode usar qualquer estrutura de agente, as bibliotecas de protocolo são independentes da estrutura. Para obter exemplos usando Microsoft Agent Framework, LangGraph e código personalizado, consulte o repositório foundry-samples.

Tamanhos de sandbox

As áreas restritas do agente hospedado dão suporte às seguintes combinações de CPU e memória:

Armazenamento de sessões

Cada sessão tem um $HOME persistente. A plataforma preserva seu conteúdo quando desprovisiona a computação após o tempo limite ocioso configurado. A plataforma restaura o conteúdo quando a sessão é retomada, de modo que os arquivos gravados em $HOME sejam preservados durante períodos ociosos. A plataforma grava arquivos carregados por meio do endpoint /files em $HOME, onde eles compartilham o mesmo armazenamento. Cada sessão tem um orçamento total de disco de até 20 GiB em 1 vCPU ou maior, o que reduz proporcionalmente para camadas de CPU menores. A plataforma reserva cerca de 20% desse orçamento para uso do sistema e não está visível ou disponível para seu agente. O restante é compartilhado entre a imagem do seu contêiner, $HOME, e quaisquer outros locais com permissão de gravação no seu contêiner.

Escalonamento e dimensionamento adequado

Os agentes hospedados escalam por sessão, não por réplica. A plataforma cria, sob demanda, um novo sandbox isolado por VM para cada sessão e mantém seus recursos computacionais ativos enquanto houver solicitações em andamento. Cada solicitação reinicia o temporizador de inatividade. Quando o tempo limite de inatividade configurado expira após a requisição mais recente, a plataforma desprovisiona os recursos computacionais do sandbox e salva o estado da sessão.

O tempo limite ocioso pode ser de 5 a 60 minutos e é padrão de 15 minutos. A plataforma exclui permanentemente uma sessão após 30 dias de inatividade. Não há número de réplicas para configurar nem pool warm para dimensionar.

Como cada sessão é executada em sua própria área restrita, os valores de cpu e memória definidos em uma versão do agente descrevem uma única sessão, não o volume agregado do agente. A cobrança é baseada na CPU + memória consumidas em todas as sessões ativas, então o superdimensionamento multiplica o custo pela sua simultaneidade.

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

1. Abra o recurso do App Insights no portal do Azure e selecione Investigar>Desempenho.
2. Examine a CPU, a memória disponível, a taxa de solicitação e a duração média da solicitação ao longo do intervalo de tempo testado.

Compare os picos observados com a CPU e a memória alocadas. Se os picos sustentados excederem cerca de 70% da alocação, aumente a alocação da próxima versão do agente; se os picos permanecerem bem abaixo disso, reduza-a para reduzir os custos. Sempre teste novamente após uma alteração, pois cada nova versão é imutável.

Rede privada

Os agentes hospedados dão suporte à implantação em recursos do Foundry isolados pela rede e podem usar uma Rede Virtual do Azure fornecida pelo cliente para tráfego de saída. Isso permite que agentes em implantações do Foundry isoladas de rede alcancem recursos privados, como bancos de dados ou APIs internas. Para obter mais informações, consulte Configurar redes virtuais.

Limites, preços e disponibilidade

Preços

A cobrança de runtime de hospedagem gerenciada baseia-se no consumo de recursos de CPU e memória durante as sessões ativas. Para obter as taxas atuais, consulte a página de preços do Foundry.

Disponibilidade da região

Atualmente, os agentes hospedados estão disponíveis nas seguintes regiões:

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

Próximas etapas

Conteúdo relacionado

• Componentes de runtime do agente
• Ciclo de vida de desenvolvimento do agente
• Conceitos de identidade do Agent no Microsoft Foundry
• O que é a Caixa de Ferramentas na Foundry?
• Documentação do Registro de Contêiner do Azure