Publique o seu agente como uma Aplicação de Agente

Publicar promove um agente de um ativo de desenvolvimento dentro do seu projeto Foundry para um recurso Azure gerido que consumidores externos podem aceder através de um endpoint estável. Pense nisso como o passo que faz o seu agente passar de "trabalha no meu projeto" para "pronto para outros usarem".

Este artigo mostra-lhe como publicar um agente, configurar a sua autenticação e permissões, invocar a sua Aplicação de Agente usando o protocolo Response API e atualizar a sua Aplicação de Agente à medida que lança novas versões de agentes. Após a publicação, pode invocar a sua Aplicação Agente usando o protocolo Respostas ou Atividade.

O que é a publicação?

Durante o desenvolvimento, constrói e testa o seu agente dentro de um projeto da Foundry. O projeto dá-te a ti e aos teus colegas um espaço de trabalho partilhado, mas não foi concebido para uma distribuição ampla porque todos os que têm acesso ao projeto podem interagir com todos os agentes e partilham o mesmo contexto de conversa e permissões. A publicação é o passo que move um agente para fora desse espaço de desenvolvimento partilhado e para um recurso Azure pronto para produção.

Quando publica uma versão de agente, Foundry cria um recurso Aplicação de Agente que envolve a sua versão de agente com o seu próprio URL de invocação, política de autenticação, identidade de agente Entra única e blueprint de agente Entra único. Uma Implementação também é criada como um recurso filho da aplicação, referenciando a versão específica do agente que está a ser publicada e suportando a gestão do ciclo de vida de arranque/paragem.

Porquê publicar?

A publicação dá-lhe capacidades que o desenvolvimento a nível de projeto não proporciona:

• Partilha externa — Conceda acesso a colegas ou clientes sem lhes dar acesso ao seu projeto Foundry.
• Endpoint estável — O URL da aplicação permanece o mesmo, mesmo quando são lançadas novas versões do agente.
• Identidade distinta do agente — O agente publicado recebe a sua própria identidade de agente Entra e o seu modelo de agente Entra, separados da identidade e modelo partilhados do projeto.
• RBAC independente e autorização — A Aplicação de Agente é um recurso da Azure separado com o seu próprio âmbito RBAC. Pode atribuir funções como Azure AI User diretamente no recurso Agent Application para controlar quem pode invocá-lo.
• Integração com o Azure Policy — Como um recurso do Azure Resource Manager (ARM), a aplicação pode ser governada pelo Azure Policy.
• Integração com Microsoft 365 Copilot e Teams — Distribua a tua Aplicação de Agente para canais como Microsoft 365 Copilot e Teams.

O que muda quando você publica?

A mudança mais importante é a identidade. Um agente não publicado utiliza a identidade de agente partilhada do projeto. Uma vez publicado, o agente recebe a sua própria identidade exclusiva. Qualquer ferramenta que utilize autenticação por identidade de agente irá mudar da identidade partilhada do projeto para a identidade única da aplicação agente.

O que observar

Como a identidade muda, as permissões não se transferem automaticamente. Quando publica um agente, deve reatribuir permissões RBAC à nova identidade do agente para quaisquer recursos a que o agente precise aceder. Se saltar este passo, as chamadas de ferramenta que trabalham durante o desenvolvimento falham com erros de autorização assim que o agente é publicado.

Pré-requisitos

• Um projeto Foundry com pelo menos uma versão agente criada
• Azure Gestor de Projeto de IA no âmbito dos recursos Foundry para publicação de agentes
• funcionalidade de utilizador do Azure IA no escopo da Aplicação do Agente para interagir com um agente publicado através do protocolo de API de Respostas
• Familiaridade com Azure role-based access control (RBAC) para configuração de permissões
• Familiaridade com Conceitos de Identidade de Agente em Foundry
• Instale os runtimes de linguagem necessários, ferramentas globais e extensões Visual Studio Code conforme descrito em Prepare o seu ambiente de desenvolvimento

Compreenda as Aplicações de Agentes e as respetivas implantações

Antes de publicar, é importante compreender a relação entre projetos, versões do agente, aplicações e implementações.

Um projeto Foundry é um conceito de organização de trabalho que agrupa recursos relacionados, como agentes, ficheiros e índices. Um agente representa uma unidade componível — definida pelas suas instruções, modelo e ferramentas. Uma versão do agente regista um instantâneo específico e imutável de um agente. Cada vez que faz alterações ao seu agente, como atualizar o prompt ou adicionar ferramentas, é criada uma nova versão do agente. Cada versão agente é exposta no projeto Foundry, onde os programadores com acesso ao projeto podem criar, executar e testar.

Uma Aplicação de Agente projeta um ou mais agentes como um serviço — endereçável de forma independente, governável e equipada com capacidades de ciclo de vida e gestão de conteúdos. Proporciona uma interface duradoura que estabelece autenticação, identidade e um ponto de entrada estável para os consumidores. Uma implementação é uma instância em execução de uma versão de agente dentro de uma aplicação que pode ser iniciada, parada e atualizada para referenciar novas versões de agente.

Encaminhamento e gestão de versões

Cada Aplicação Agente atua como uma tabela de encaminhamento para implementações específicas de agentes. Atualmente, uma Aplicação Agente suporta uma implementação ativa, direcionando 100% do tráfego recebido pelo endpoint da aplicação para essa implementação. Quando publica uma nova versão do agente numa aplicação existente, 100% do tráfego recebido pelo endpoint da aplicação é direcionado para a implementação que faz referência à nova versão do agente.

Protocolos

Um recurso de Aplicação Agente expõe um endpoint estável com múltiplas opções de protocolo e autenticação.

Protocolo de Respostas

Os agentes da Foundry, por defeito, expõem um protocolo compatível com OpenAI baseado em Respostas para interagir com agentes.

Para as aplicações, este endpoint está disponível em:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/openai

A API compatível com OpenAI exposta através das aplicações foi modificada para garantir que as conversas dos utilizadores permaneçam privadas. Esta restrição é temporária e será removida assim que suportarmos o isolamento do utilizador final. Como resultado, a API é mais limitada do que a API OpenAI servida pelo endpoint do projeto. Especificamente:

• Apenas a API de Respostas sem estado (POST /responses) é suportada.
• Outras APIs, incluindo /conversations, /files, /vector_stores, e /containers são inacessíveis.

Esta limitação significa que o cliente tem de armazenar o histórico para conversas com múltiplos turnos.

Protocolo de Atividade

Os agentes da fundição também podem expor o Protocolo de Atividade utilizado por Azure Bot Service.

Para aplicações, este endpoint é exposto em:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/activityprotocol

Autenticação

Pode configurar a autenticação de entrada do utilizador final na aplicação. As seguintes opções estão disponíveis:

• Default (RBAC): O chamador deve ter o papel Azure AI User (ou um papel personalizado com a permissão /applications/invoke/action) no recurso de Aplicação do Agente. Escolha esta opção se quiser invocar a sua aplicação agente usando o protocolo Responses API. Para mais informações sobre as funções RBAC da Foundry, consulte Controlo de acesso baseado em funções para Microsoft Foundry.
• Channels (Azure Bot Service): Quando publica no M365/Teams ou no A365 como trabalhador digital, channels é a autenticação utilizada. Isto é selecionado automaticamente na interface através do fluxo de publicação do M365/Teams.

A autenticação por chave API não é suportada para invocar Aplicações Agente. Use o Microsoft Entra ID (Azure RBAC) para autorizar os chamadores.

Publique um agente

Portal da fundição

Esta secção mostra-lhe como publicar um agente usando a interface do portal Foundry.

1. No Construtor de Agentes, crie ou selecione uma versão de agente que queira publicar.

2. Selecione Publicar Agente para criar uma Aplicação de Agente e a implementação.

Resultado esperado: A publicação termina e a versão do agente mostra um estado de publicação.

3. Configure a autenticação para a sua Aplicação de Agente:

   • Por defeito, o tipo de autenticação está definido para RBAC (Role-Based Controlo de Acesso).
   • Os utilizadores que chamam a aplicação de agente usando o protocolo Respostas devem receber o papel incorporado Azure AI User do Azure RBAC (ou um papel personalizado equivalente) no recurso da aplicação de agente.

4. Atribuir permissões para autenticação de ferramentas:

   • Se o seu agente incluir ferramentas que usam identidade de agente para autenticação, a identidade de agente recém-criada deve ter permissões apropriadas
   • Navegue até cada recurso Azure a que o seu agente acede e atribua o papel RBAC necessário à nova identidade do agente

5. Após a publicação, pode:

   • Partilhe o endpoint publicado com consumidores externos ou integre-o na sua aplicação existente.
   • Partilhe e converse com a sua aplicação em canais como o Teams/M365 Copilot.

API REST

Para publicar uma versão do agente, deve criar uma aplicação e uma implementação que faça referência à sua versão do agente.

Antes de começares

1. Inicie sessão e adquira um token de acesso do Azure Resource Manager:

az login
az account get-access-token --resource https://management.azure.com

Utilize o valor accessToken como cabeçalho Authorization: Bearer <token> nas solicitações seguintes.

Se quiser capturar apenas o valor do token (por exemplo, para uso num script), use:

az account get-access-token --resource https://management.azure.com --query accessToken -o tsv

2. Recolhe os valores necessários para o URL do pedido.

   • subscription_id: Use a subscrição que contém o seu recurso Foundry. Pode encontrá-lo no portal Azure (Subscrições) ou executando az account show --query id -o tsv.
   • resource_group: O grupo de recursos que contém o teu recurso da Foundry. Pode encontrá-lo na página de recursos da Foundry Overview no portal Azure.
   • account_name: O nome do seu recurso Foundry (nome do recurso Azure).
   • project_name: O nome do projeto Foundry.
   • application_name e deployment_name: Escolha os nomes da Aplicação Agente e da implementação que pretende criar.

3. Escolha um api-version.

Criar aplicação de agente.

Para uma referência completa de propriedades e um exemplo de infrastructure-as-code (Bicep) para Aplicações de Agentes, consulte a referência do modelo Azure Resource Manager para Microsoft.CognitiveServices/contas/projetos/aplicações.

Campo obrigatório: Defina o agentName campo para o nome do agente que pretende publicar.

O exemplo seguinte mostra apenas os campos mínimos obrigatórios. Por defeito, authorizationPolicy está definido para Default (Azure RBAC) e trafficRoutingPolicy encaminha todo o tráfego para a primeira implementação.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "agents": [{"agentName": "Publishing Agent"}]
  }
}

2. Criar uma implementação de agente.

Para uma referência completa das propriedades e um exemplo de infraestrutura-como-código (Bicep) para implementações de agentes, consulte a referência do modelo Azure Resource Manager para Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments.

Campos obrigatórios:

• deploymentType: O modo de implantação. Use Managed para prompts e agentes de fluxo de trabalho. Use Hosted para agentes alojados.
• agents: O nome e a versão do agente a implementar.
• protocols: O protocolo que a implantação expõe. Para respostas, defina protocol como Responses e version como 1.0.

Mais campos obrigatórios apenas para hospedagem:

• minReplicas: Define o número mínimo de réplicas
• maxReplicas: Define o número máximo de réplicas

Agentes de comando e fluxo de trabalho

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "1"
        }
    ]
  }
}    

Agentes alojados

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json
{
  "properties": {
    "displayName": "Test Hosted Deployment",
    "deploymentType": "Hosted",
    "minReplicas": 1,
    "maxReplicas": 1,
    "protocols": [
        {
            "protocol": "Responses",
            "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "ContainerAgent",
            "agentVersion": "1"
        }
    ]
  }
}

3. Verificar se a implementação está a correr

As implementações de prompts e agentes de workflow normalmente começam a correr automaticamente. As implementações de agentes hospedados herdam o estado da versão publicada do agente — se a versão for interrompida, a implementação também é interrompida.

Para verificar o estado atual, obtenha o recurso de implementação e inspecione a propriedade state.

GET https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}

Use a seguinte chamada para iniciar uma implementação interrompida:

POST https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}/start?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

Verifique se a publicação foi bem-sucedida

Confirme que o seu agente publicou com sucesso antes de partilhar o endpoint com os consumidores. Depois de publicar, verifique que:

• O recurso Agent Application existe.
• A implementação está a decorrer.
• Podes invocar o endpoint da aplicação.

Verificação rápida ao ligar para o endpoint

Para executar os seguintes comandos, precisas do CLI do Azure.

1. Obtenha um token de acesso para o utilizador que chama.

az account get-access-token --resource https://ai.azure.com

2. Chame o endpoint da Aplicação Agente (protocolo de Respostas).

curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

Se receber 403 Forbidden, confirme que o chamador tem o papel de Utilizador de IA Azure no recurso de Aplicação Agente.

Atualizar uma Candidatura de Agente publicada

Quando precisares de lançar uma nova versão do teu agente, atualiza a aplicação existente e a implementação para referenciar a nova versão do agente.

Portal da fundição

1. No Construtor de Agentes, navega até à versão específica do agente que queres publicar.

2. Selecione Publicar Atualizações.

3. Confirma a atualização. A Aplicação do Agente direciona automaticamente 100% de tráfego para a nova versão do agente.

O URL estável do ponto final mantém-se inalterado, garantindo que os consumidores finais não sejam perturbados pela atualização.

API REST

Se o nome do seu agente se mantiver igual e só quiser implementar uma nova versão do agente, atualize a implementação para referenciar uma nova versão do agente.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "description": "This is a managed deployment",
     "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "<updated-agent-version>"
        }
    ]
  }
}

Para lançar um agente com um nome diferente, deve:

1. Atualize a Aplicação do Agente para permitir o novo nome do agente.
2. Crie ou atualize uma implementação para referenciar a nova versão do agente.
3. Se criaste uma nova implementação, atualiza a política de encaminhamento de tráfego da Aplicação Agente para que 100% de tráfego sejam direcionados para a nova implementação.

Conceder aos utilizadores acesso para invocar um agente publicado

Depois de publicar um agente, os chamadores precisam da função Azure AI User (ou uma função personalizada que inclua a permissão Microsoft.CognitiveServices/accounts/projects/applications/invoke/action) no recurso da Agent Application. Esta atribuição de função está relacionada com a Aplicação de Agente individual, pelo que pode conceder acesso a um único agente publicado sem dar aos utilizadores acesso a todo o seu projeto Foundry ou a outros agentes.

Para mais informações sobre Azure RBAC, consulte Controlo de acesso baseado em papéis para Microsoft Foundry

Invocar a sua Aplicação de Agente

Após a publicação, invoca o seu agente através do seu endpoint usando o protocolo Responses API ou o protocolo de atividade. O protocolo de atividade é usado quando o seu agente é publicado no Microsoft 365 e no Teams.

Para usar a sua Aplicação de Agente no Microsoft 365 Copilot e no Teams, veja Publicar agentes para Microsoft 365 Copilot e Microsoft Teams.

Para publicar o seu agente como trabalhador digital, veja Publicar um agente como trabalhador digital no Agente 365

Invocar usando o protocolo Responses API

Para invocar a sua Aplicação Agente usando o protocolo Responses API, precisa de:

• função de utilizador do Azure AI no âmbito da Aplicação de Agente
• Os pacotes openai e azure-identity instalados e autenticados conforme descrito em Prepare o seu ambiente de desenvolvimento

Utilize o cliente OpenAI com o ponto final Aplicações do Agente

from openai import OpenAI 
from azure.identity import DefaultAzureCredential, get_bearer_token_provider 

# Replace placeholders with your resource, project, and app names
BASE_URL = "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai"

# Create OpenAI client authenticated with Azure credentials
openai = OpenAI(
    api_key=get_bearer_token_provider(DefaultAzureCredential(), "https://ai.azure.com/.default"),
    base_url=BASE_URL,
    default_query={"api-version": "2025-11-15-preview"}
)

# Send a request to the published agent
response = openai.responses.create( 
  input="Write a haiku", 
) 
print(f"Response output: {response.output_text}")

Esta abordagem autentica usando credenciais do Azure e exige que o chamador tenha o papel de Utilizador IA Azure no recurso de Aplicação Agente.

Considerações de segurança e privacidade

• Use o privilégio mínimo. Conceder aos utilizadores o papel mínimo necessário (por exemplo, separar permissões de publicação das permissões de invocação).
• Evite partilhar o acesso ao projeto quando só precisa de partilhar um agente. Utilize o endpoint da Aplicação de Agente e o RBAC no recurso da aplicação.
• Não incorpores tokens de acesso no código-fonte, scripts ou aplicações clientes. Use fluxos de autenticação Microsoft Entra adequados à sua aplicação.
• Planeie as mudanças de identidade antes de publicar. Chamadas de ferramenta autenticadas pela identidade do agente utilizam a identidade da aplicação após a publicação, não a identidade do projeto.
• Guarde o histórico de conversas no seu cliente se precisar de experiências com múltiplos turnos. As Aplicações Agente atualmente restringem APIs e não armazenam respostas.

Limitações

Os agentes publicados como Aplicações de Agente apresentam as seguintes limitações:

Resolução de problemas

Liberar recursos

Se já não precisar de um endpoint publicado, elimine o recurso Agent Application Azure (e as suas implementações). Apagar a aplicação não elimina as versões dos teus agentes no projeto Foundry.

Referência: Aplicação do Agente e propriedades de implementação

Use as tabelas seguintes quando construir pedidos de API REST ou quando precisar de compreender os campos devolvidos nas respostas.

Perguntas Frequentes

Porque é que as conversas não são mantidas para agentes publicados (ou seja, porque é que só são suportadas respostas sem estado)?

Hoje existe uma limitação temporária em que os agentes publicados apenas suportam interações sem estado da API de Respostas (ou seja, sem conversas persistentes). O trabalho para resolver isto já está em andamento.

A razão para esta limitação é que, embora o Foundry Agent Service suporte o histórico de conversas geridas, ainda não impõe o isolamento do utilizador final entre conversas dentro do mesmo projeto. Ou seja, se alguém souber o ID de conversa de outro utilizador, pode aceder a esse histórico de conversas mesmo que não seja dele. Isto é aceitável num contexto de desenvolvimento dentro de um único projeto, mas não é aceitável para produção, onde os clientes precisam de isolamento rigoroso de conversa por utilizador.

As Aplicações Agente destinam-se a expor funcionalidades a um público diferente (por exemplo, outros na sua organização ou clientes), separados dos programadores de projetos, com versões estáveis, configuração e acesso controlado. Dado esse objetivo, os utilizadores de aplicações agente esperam naturalmente que as suas interações com a aplicação sejam privadas e não visíveis para os outros. Isto não é atualmente possível porque as APIs OpenAI de utilizador único sobre as quais construímos não fornecem isolamento nativo de dados, e precisamos de construir essa camada de isolamento nós próprios. Até que suportemos o isolamento total de dados do utilizador final para aplicações, apenas respostas sem estado estão disponíveis. Esta limitação é temporária.

Qual é o modelo de preços para um agente publicado? O custo baseia-se num modelo de consumo, ou o cliente incorre em encargos simplesmente porque o recurso da aplicação (endpoint) tem a infraestrutura subjacente implementada assim que o agente é publicado?

Os agentes publicados utilizam um modelo de pagamento pelo editor: o editor (o proprietário do projeto Foundry) incorre em custos com base na infraestrutura subjacente que é implementada quando o agente é publicado como aplicação, e não com base no consumo por chamada. Os utilizadores finais da aplicação publicada não têm custos por padrão, embora os clientes possam escolher colocar a sua própria camada de medição ou faturação sobre a aplicação se quiserem implementar um modelo com base no consumo para a sua organização ou utilizadores externos.

Conteúdo relacionado

• Aprenda sobre conceitos de identidade de agente na Foundry
• Saiba mais sobre agentes alojados
• Aprenda a publicar agentes para Microsoft 365 Copilot e Microsoft Teams
• Migrar das Aplicações de Agente para o novo modelo de agente

Próximos passos