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:

• Abring seu próprio código - use qualquer estrutura (Estrutura do Agente, LangGraph, Kernel semântico ou código personalizado) em vez de definições somente prompt.
• Use protocolos personalizados – aceite webhooks ou conteúdos não OpenAI por meio do protocolo Invocações.
• Controlar recursos de computação – especifique a CPU e a memória para a área restrita do 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. No runtime, 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 de Azure downstream 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 agente em contêineres executados no Serviço do Agente. 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 áreas restritas isoladas por VM por sessão. Cada sessão obtém uma área restrita dedicada com um sistema de arquivos persistente ($HOME e /files), habilitando a escala para zero com currículo com estado e inícios frios 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 de atividade para integração de canais do Teams e M365 (normalmente usado junto com respostas) e o 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 < Microsoft Entra ID c0> dedicado (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 ponto de extremidade está disponível imediatamente após a implantação– a publicação não é necessária para acesso programático:

• Respostas: {project_endpoint}/agents/{name}/endpoint/protocols/openai/v1/responses
• Invocações: {project_endpoint}/agents/{name}/endpoint/protocols/invocações

Quais pontos de extremidade estão ativos depende 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 (Azure usuário de IA no escopo da conta) é atribuída automaticamente ao Microsoft Entra ID do agente. Para recursos externos (por exemplo, seus próprios Armazenamento do Azure), você atribui o RBAC manualmente ao Microsoft Entra ID do agente.

Quando integrados por meio de canais de Microsoft 365 (por exemplo, Teams), os agentes hospedados também podem operar com a identidade de usuário OBO (em nome de). O Microsoft Entra ID do agente pode trocar um token de usuário para chamar serviços downstream como o usuário, sujeito a 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

Uma ID de sessão identifica uma sessão lógica com estado persistente, incluindo $HOME e arquivos carregados por meio do ponto de extremidade /files. A plataforma provisiona a computação sob demanda e restaura o estado persistente nela.

• 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 a computação 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 a ID da sessão para o cliente, que pode usá-la para carregar arquivos por meio do ponto de extremidade /files, disponibilizando esses arquivos para a computação da conversa.

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

Ciclo de vida da computação 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 agente chamar ferramentas apoiadas por não serviços Microsoft, 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

Versão

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 para dar suporte a implantações canário 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.

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 esse ponto de extremidade usando bibliotecas de cliente MCP padrão. A plataforma não injeta ferramentas automaticamente. Para obter detalhes, consulte Curate intent-based toolbox in Foundry. Recomendamos que os clientes usem a caixa de ferramentas na Foundry para conectar ferramentas no agente hospedado com suporte de autenticação consolidada em passagem do OAuth Identity, 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 área restrita

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 de Fundimento isolados pela 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 Agent no Microsoft Foundry
• Descobrir ferramentas nas Ferramentas de Pesquisa
• Registro de Contêiner do Azure documentação