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.

Quando usar agentes hospedados

Escolha agentes hospedados em vez de agentes baseados em prompts 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 cargas úteis não relacionadas ao OpenAI por meio do protocolo Invocations.
• Controlar recursos de computação – especifique a CPU e a memória para a sandbox do seu agente.
• Executar cargas de trabalho com estado – manter arquivos e estado entre turnos por meio de $HOME e do ponto de extremidade /files.

Como funciona

Empacote seu agente como uma imagem de contêiner e envie-o por push para Registro de Contêiner do Azure. Quando você implanta, o Serviço de Agente puxa a imagem, provisiona a computação, atribui um Microsoft Entra ID dedicado (identidade do agente) e expõe um ponto de extremidade dedicado. Em tempo de execução, o código do agente lida com solicitações de clientes e pode chamar modelos do Foundry, ferramentas da Caixa de Ferramentas e serviços Azure subsequentes usando sua identidade de agente. A plataforma lida com dimensionamento, persistência de estado de sessão, observabilidade e gerenciamento do ciclo de vida.

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 uma sandbox dedicada com um sistema de arquivos persistente ($HOME e /files), permitindo escalar para zero com continuidade do estado e reinícios 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 e Invocações

Contêineres de agente hospedado expõem um ou ambos os protocolos. Cada protocolo é fornecido por uma biblioteca leve que manipula o servidor HTTP, verificações de integridade e integração do OpenTelemetry.

Qual protocolo devo usar?

Comparação de protocolo

Protocolos adicionais

Os agentes hospedados também dão suporte ao protocolo Activity para integração de canais do Teams e M365 (normalmente usado junto com Responses) e ao protocolo A2A para delegação de agente para agente. Todos os quatro protocolos — Respostas, Invocações, Atividade e A2A — podem ser combinados em um único agente.

Identidade e ponto de extremidade do agente

Cada agente hospedado implantado em um projeto do Foundry obtém seu próprio ID dedicado do Microsoft Entra (identidade do agente) e endpoint dedicado — 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/v1/responses
• Invocações: {project_endpoint}/agents/{name}/endpoint/protocols/invocations

Os pontos de extremidade que estão ativos dependem dos protocolos declarados na definição de versão do agente (definido em agent.yaml ao usar o azd, ou via container_protocol_versions ao usar o SDK).

Duas identidades estão envolvidas:

Quando você implanta com o azd, a função RBAC necessária (Usuário do Azure AI no escopo da conta) é atribuída automaticamente ao Microsoft Entra ID do agente. Para recursos externos (por exemplo, seu próprio Armazenamento do Azure), você atribui manualmente o RBAC ao Microsoft Entra ID do agente.

Quando integrados por meio de canais do Microsoft 365 (por exemplo, Teams), os agentes hospedados também podem operar com a identidade do usuário em nome de (OBO). A identidade Microsoft Entra do agente pode trocar um token de usuário para chamar serviços a jusante em nome do usuário, de acordo com políticas de locatário. 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 de computação sob demanda e restaura o estado persistente nesses recursos.

• 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: as sessões persistem por até 30 dias. O tempo limite ocioso é de 15 minutos— se nenhuma solicitação chegar nessa janela, a plataforma desprovisiona a computação e persiste o estado da sessão.
• 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

Segurança e manipulação de dados

Trate um agente hospedado como o código do 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— um instantâneo da imagem de contêiner, alocação de recursos, variáveis de ambiente e configuração de protocolo. As implantações fazem referência a uma versão específica. Para atualizar seu agente, você cria uma nova versão e a plataforma a implanta. Observe que as solicitações para criar a versão do agente sem nenhuma alteração nos parâmetros de versão do agente, como imagem de contêiner, variáveis de ambiente etc. não resultarão na criação de uma nova versão. Você pode dividir o tráfego entre versões com distribuições ponderadas suportando implantações do tipo canary e blue-green.

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.

Caixa de ferramentas na Foundry

Os agentes hospedados acessam ferramentas gerenciadas pelo Foundry (Interpretador de Código, Pesquisa na Web, Pesquisa de IA do Azure , OpenAPI, conexões MCP personalizadas, A2A) por meio de um ponto de extremidade mcp Toolbox provisionado em seu projeto foundry. O código do agente se conecta a este endpoint usando bibliotecas clientes padrão do MCP — a plataforma não injeta ferramentas automaticamente. Para obter detalhes, consulte Curate uma caixa de ferramentas baseada em intenção no Foundry. Recomendamos que os clientes usem o conjunto de ferramentas na Foundry para conectar ferramentas no agente hospedado com suporte unificado de autenticação abrangendo passagem de OAuth Identity, identidade do agente, autenticação baseada em chave e muito mais.

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 a alocações de CPU e memória que variam de 0,25 vCPU/0,5 GiB a 2 vCPU/4 GiB.

Rede privada

Os agentes hospedados oferecem suporte à implantação em recursos de Foundry isolados em rede. Para obter mais informações, consulte Configurar redes virtuais. Observe que o Registro de Contêiner do Azure que mantém a imagem do agente deve permanecer acessível no momento em seu ponto de extremidade público; o ACR seguro pela rede privada não tem suporte no momento.

Limites, preços e disponibilidade (versão prévia)

Os agentes hospedados estão atualmente em versão prévia.

Limitações durante a visualização

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 dos EUA 2
• Centro-Norte dos EUA
• Suécia Central
• Canadá Central
• Sudeste Asiático
• Polônia Central
• Norte da África do Sul
• Coreia Central
• Sul da Índia
• Sul do Brasil
• Oeste dos EUA
• Oeste dos EUA 3
• Leste da Noruega
• Leste do Japão
• França Central
• Norte da Suíça
• Espanha Central
• Leste da Austrália

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
• Descobrir ferramentas nas Ferramentas da Foundry
• Documentação do Registro de Contêiner do Azure