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.
  • 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.

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.

Importante

Ao usar Agentes Hospedados com outros produtos e serviços Microsoft, você deve ler toda a documentação relevante para esses produtos e serviços e entender os riscos relacionados e considerações de conformidade.

Se você usar o Hosted Agent com servidores, agentes, códigos ou modelos diretos não Azure ("Sistemas de Terceiros"), você o fará por sua conta e risco. Sistemas de terceiros são produtos não Microsoft sob os Termos do Produto Microsoft e são regidos por seus próprios termos de licença de terceiros. Você é responsável por qualquer uso e custos associados.

Recomendamos revisar todos os dados compartilhados e recebidos de sistemas de terceiros e estar ciente das práticas de terceiros para manipulação, compartilhamento, retenção e localização de dados. Da mesma forma, se você se conectar a ou integrar-se a serviços e recursos da Microsoft que não sejam do Foundry, é importante analisar suas práticas de tratamento de dados. É sua responsabilidade gerenciar se seus dados fluirão fora dos limites geográficos e de conformidade da sua organização e quaisquer implicações relacionadas, e que as permissões, os limites e as aprovações apropriados sejam provisionados.

Você é responsável por examinar e testar cuidadosamente os aplicativos que cria no contexto de seus casos de uso específicos e tomar todas as decisões e personalizações apropriadas. Isso inclui implementar suas próprias mitigações de IA responsáveis, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e garantir que seus aplicativos atendam aos padrões adequados de qualidade, confiabilidade, segurança e confiabilidade. Consulte a nota de transparência do Foundry Agent Service.

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?

Cenário Protocolo Porque
Chatbot ou assistente de conversação Respostas A plataforma gerencia o histórico de conversas, os eventos de streaming e o ciclo de vida da sessão, usando qualquer SDK compatível com OpenAI como o cliente.
Perguntas&Respostas com múltiplos turnos usando RAG ou ferramentas Respostas Tratamento integrado de IDs de conversação e resultados de ferramentas.
Processamento em segundo plano/assíncrono Respostas background: true com polling e cancelamento gerenciados pela plataforma — nenhum código personalizado necessário.
Agente publicado no Teams ou no Microsoft 365 Respostas + Atividade O protocolo Responses alimenta a lógica do agente; a plataforma conecta automaticamente o Responses ao protocolo Activity para a entrega nos canais.
Receptor de webhook (GitHub, Stripe, Jira etc.) Invocações O sistema externo envia seu próprio formato de carga – você não pode alterá-lo para corresponder a /responses.
Processamento não conversacional (classificação, extração, lote) Invocações A entrada são dados estruturados, não uma mensagem de chat. JSON arbitrário dentro, JSON arbitrário fora.
Protocolo de streaming personalizado (AG-UI etc.) Invocações AG-UI e outros protocolos de interface do usuário do agente não são compatíveis com OpenAI. Você precisa de controle SSE bruto.
Ponte de protocolo (GitHub Copilot, sistemas proprietários) Invocações O chamador possui seu próprio protocolo que não corresponde a /responses.
Agente de voz em tempo real (entrada por microfone, saída em voz) Invocações (WebSocket) Streaming bidirecional em uma única conexão persistente. Emparelhe com Pipecat, LiveKit ou Voice Live em seu contêiner. Consulte Criar um agente de voz.

Dica

Não tem certeza? Comece com respostas. Você sempre pode adicionar um endpoint de Invocations mais tarde — um agente hospedado pode suportar ambos os protocolos simultaneamente.

Comparação de protocolo

Respostas Invocações
Mais adequado para A maioria dos agentes — a plataforma gerencia o histórico de conversas, o ciclo de vida do streaming e a execução em segundo plano. Agentes que precisam de controle HTTP completo, cargas personalizadas ou fluxos de trabalho assíncronos de execução prolongada
Payload Contrato /responses compatível com OpenAI JSON arbitrário por meio de /invocações – você define o esquema
SDK do cliente Qualquer SDK compatível com OpenAI (Python, JS, C#) funciona fora da caixa Cliente personalizado – você define o contrato
Histórico de sessão Gerenciado pela plataforma utilizando o identificador da conversa Você gerencia sessões (na memória, Cosmos DB etc.)
Streaming ResponseEventStream gerenciado pela plataforma com eventos de ciclo de vida SSE bruta – você formata e grava eventos diretamente
Em segundo plano/de longa duração Integrado (background: true + sondagem gerenciada pela plataforma) Acompanhamento manual de tarefas e endpoints de sondagem personalizados

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:

Identidade Scope Propósito
Microsoft Entra ID (identidade do agente, por agente) Criado automaticamente no momento da implantação A identidade com a qual o contêiner do agente se autentica em tempo de execução. Usado para invocação de modelo, acesso à ferramenta e serviços de Azure downstream.
Identidade gerenciada do projeto (abrangência do projeto) Atribuído pelo sistema no projeto Foundry Usado pela plataforma para operações de infraestrutura (por exemplo, Leitor do Repositório do Registro de Contêineres no registro de contêineres). Não é a identidade de tempo de execução do agente.

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). Nesse caso, o agente pode invocar serviços downstream em nome do usuário usando as permissões delegadas desse usuário, sujeito às 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: 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. Uma sessão é excluída permanentemente 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

Estado O que acontece
Ativo A computação está em execução. As solicitações são roteadas para ela. O conteúdo de $HOME e /files está disponível.
Ocioso Nenhuma solicitação por 15 minutos. O recurso de computação é desprovisionado. O estado da sessão ($HOME, /files) é persistente.
Retomada A mesma ID de sessão é referenciada novamente. A plataforma provisiona novos recursos de computação e restaura o estado previamente persistido.

Segurança e manipulação de dados

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

Importante

Use sistemas de terceiros por sua conta e risco e sempre implemente mitigações de IA responsáveis apropriadas. Você é responsável por gerenciar todos os dados que podem fluir fora dos limites geográficos e de conformidade da sua organização. Saiba mais.

  • 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

Importante

Não há suporte para adicionar ferramentas diretamente à definição do agente hospedado. É recomendável usar caixas 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 endpoint por meio de bibliotecas padrão de cliente MCP. A plataforma não injeta ferramentas automaticamente. Para obter detalhes, consulte Coletar um conjunto de ferramentas baseado em intenção no Foundry. Para conectar ferramentas em um agente hospedado com suporte consolidado de autenticação em OAuth Identity passthrough, identidade do agente, autenticação baseada em chave e muito mais, use a caixa de ferramentas 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:

CPU Memória
0,5 vCPU 1 GiB
1 vCPUs 2 GiB
2 vCPUs 4 GiB

Armazenamento de sessões

Cada sessão tem um $HOME persistente. Seu conteúdo é preservado quando os recursos de computação são desprovisionados após 15 minutos de inatividade e é restaurado quando a sessão é retomada, para que os arquivos gravados em $HOME sobrevivam aos períodos de inatividade. Os arquivos carregados por meio do endpoint /files são gravados em $HOME e compartilham o mesmo armazenamento. Cada sessão recebe um orçamento total de disco de até 20 GiB com 1 vCPU ou mais, reduzido proporcionalmente para níveis menores de CPU. Cerca de 20% desse orçamento são reservados para uso do sistema e não estão visíveis ou disponíveis 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, mantém esse sandbox em execução durante toda a sessão (tempo limite de inatividade de 15 minutos e vida útil máxima de 30 dias) e o encerra quando a sessão termina. 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.

Nota

Os projetos do Foundry criados após 25 de junho de 2026 oferecem suporte a um Registro de Contêiner do Azure privado (protegido por rede) para a imagem do seu agente. Os projetos criados antes dessa data exigem que o registro permaneça acessível por meio de seu endpoint público. Os projetos existentes não são afetados. Para obter mais informações, consulte Limitações.

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 dos EUA 2
  • Centro-Norte dos EUA
  • Suécia Central
  • Canadá Central
  • Leste do Canadá
  • 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
  • Centro-oeste da Alemanha
  • Norte da Suíça
  • Espanha Central
  • Leste da Austrália

Nota

Essa lista será atualizada à medida que regiões adicionais estiverem disponíveis.

Próximas etapas

Tarefa Link
Compilar e implantar seu primeiro agente hospedado Início Rápido: Implantar seu primeiro agente hospedado
Implantar usando o SDK do Foundry Implantar um agente hospedado usando o SDK do Foundry
Atualizar, excluir, invocar ou transmitir logs Gerenciar agentes hospedados
Configurar o rastreamento e o monitoramento Habilitar o rastreamento em seu projeto
Otimizar instruções do agente automaticamente Visão geral do otimizador de agentes
Avaliar o desempenho do agente Avaliadores de agentes
Publicar no Teams, Microsoft 365 ou aplicativos personalizados Aplicativos de agente
Procurar exemplos de código exemplos de Python e exemplos de C#

Conteúdo relacionado

  • Last updated on