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 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.
• Controlar recursos de computação – especifique a CPU e a memória para a sandbox do seu agente.
• Execute workloads com estado — persista 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. Ao realizar a implantação, o Serviço do Agente efetua pull da imagem, provisiona a computação, designa 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 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 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. Ambos os protocolos estão disponíveis em regiões que dão suporte a agentes hospedados.

Qual protocolo devo usar?

Comparação de protocolo

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. Todos os quatro protocolos — Respostas, Invocações, Atividade e A2A — 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/v1/responses
• Invocações: {{project_endpoint}}/agents/{{name}}/endpoint/protocols/invocations
• A2A (versão prévia): {project_endpoint}/agents/{name}/endpoint/protocols/a2a

Quais pontos de extremidade estão ativos depende dos protocolos declarados na definição da versão do agente (definida no arquivo agent.yaml ao usar o azd, ou por meio de container_protocol_versions ao usar o SDK).

Duas identidades estão envolvidas:

Ao implantar com o azd, a função RBAC necessária (Usuário de IA do Azure 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 de usuário em nome de (OBO). O Microsoft Entra ID do agente pode trocar um token de usuário para chamar serviços downstream como o usuário, sujeito às políticas do 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 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: 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

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— 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 implantações ponderadas para oferecer suporte a implantações canary e azul-verde.

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 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 Coletar um conjunto de ferramentas baseado em intenção no Foundry. Recomendamos que os clientes usem a caixa de ferramentas no Foundry, com o fim de conectar ferramentas no agente hospedado com suporte de autenticação consolidada por meio de passagem de identidade OAuth, identidade do agente, com base 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 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 (versão prévia)

Os agentes hospedados estão atualmente em fase de pré-visualização.

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