Migrar dos aplicativos de agente para o novo ponto de extremidade de agente e a nova experiência de publicação

Este guia explica como a experiência de publicação do agente mudou no Microsoft Foundry. Ele compara o modelo herdado (que criou um recurso de aplicativo de agente separado) com o novo modelo de objeto do agente e orienta você na migração de seus agentes existentes e aplicativos publicados.

Visão geral da alteração

O novo modelo de objeto do agente integra Aplicações de Agente e Implantações de Agente no próprio objeto Agent. Anteriormente, a publicação criava um recurso de aplicativo de agente separado, com identidade, ponto de extremidade e implantação próprios. Agora, cada agente tem esses recursos desde o momento em que é criado.

Antes (modelo herdado)

1. Modelo de recurso: um agente (plano de dados), o aplicativo do agente (plano de controle) e a implantação (plano de controle) são objetos separados.
2. Propriedades do objeto agent: id (identificador exclusivo para o agente) namee versions (a versão mais recente do agente).
3. Identidade: os agentes não publicados em um projeto do Foundry compartilham uma identidade de agente do Entra e um modelo de agente do Entra. Após a publicação, um agente recebe uma identidade exclusiva e um blueprint vinculado ao recurso Aplicativo do Agente.
4. Publicação: dois gestos. Primeiro, a publicação de um agente cria um recurso de Aplicativo de Agente e uma Implantação, onde a Implantação referencia a versão do agente publicada. O aplicativo do agente expõe um endpoint estável que encaminha 100% do tráfego para essa versão. Uma implantação oferece suporte ao gerenciamento do ciclo de vida de inicialização/desligamento. O segundo gesto é que o Aplicativo do Agente pode ser publicado no Microsoft 365 e no Teams.

Após (novo modelo)

1. Modelo de recurso: somente objetos do Agente existem (plano de dados e plano de controle). Elas assumem as responsabilidades anteriormente atribuídas ao Agente de Aplicação e Implantação.
2. Propriedades do objeto agent: id, name, versions, agent_endpoint (ponto de extremidade estável), protocols, authorization_schemes, version_selector, blueprint, instance_identity, e agent_card (apresenta detalhes do agente e funcionalidades para consumidores e A2A).
3. Identidade: todos os agentes recebem, por padrão, uma Identidade de Agente do Entra e o Blueprint de Agente do Entra exclusivos. O modelo Traga seu próprio Entra Agent é compatível, mas não é a configuração padrão.
4. Publicação: dois gestos equivalentes. Primeiro, selecione uma versão do agente para expor por meio do ponto de extremidade estável. Em segundo lugar, publique o ponto de extremidade estável do agente no M365/Teams.

A mudança de chave: criar um agente é a única etapa necessária para obter um ponto de extremidade estável e uma identidade de agente exclusiva. Não há nenhuma etapa de publicação separada para o endpoint. Atualmente, a publicação refere-se especificamente à distribuição do agente através dos canais do M365 e do Teams.

Tipos de agente durante a transição

Durante o período de transição, você pode encontrar três tipos de agentes:

O agent.identity valor distingue novos agentes de agentes herdados: nulo significa herdado, não nulo significa novo.

O que continua funcionando

• Aplicativos de agente existentes continuam a processar o tráfego através de seus terminais.
• Agentes publicados no M365/Teams por meio dos Aplicativos de Agente continuam funcionando.
• O endpoint do projeto permanece disponível para compatibilidade retroativa (embora não seja mais o caminho recomendado).
• Os agentes herdados permanecem totalmente funcionais para desenvolvimento e teste no projeto Foundry.

Caminhos de migração

Caminho 1: novos agentes (nenhuma ação necessária)

Se você criar agentes após a atualização do modelo de objeto, eles obterão automaticamente o novo modelo com identidade exclusiva, ponto de extremidade estável e todos os novos recursos. Nenhuma migração é necessária.

Caminho 2: Atualizar um agente antigo

Os agentes herdados (criados antes da atualização) usam a identidade do projeto compartilhado e não podem ser publicados por meio do novo modelo. Para atualizar:

1. Verifique se o seu agente é um agente antigo:

   GET {endpoint}/agents/{agent_name}?api-version=2025-11-15-preview
   Authorization: Bearer {{token}}
   Foundry-Features: AgentEndpoints=V1Preview
   

   Se instance_identity for nulo na resposta, trata-se de um agente legado.

2. Crie um novo agente usando a mesma definição:

   Nota

   Atualmente, não há como atualizar um agente legado para uma identidade única no sistema. Para obter uma identidade exclusiva, crie um novo agente usando a mesma definição (instruções, ferramentas, configuração de modelo). O novo agente recebe automaticamente uma identidade exclusiva e um ponto de extremidade estável. Uma opção de atualização no local está planejada para uma atualização futura.

3. Depois que o novo agente é criado, ele tem uma identidade exclusiva e você pode usar todos os novos recursos, incluindo uma experiência de publicação aprimorada que usa o endpoint do agente.

Caminho 3: Migrar um aplicativo de agente existente

Se você tiver um aplicativo de agente publicado no M365/Teams e quiser migrar para o novo modelo, siga estas etapas:

1. Crie um novo agente usando a mesma definição que o agente por trás do aplicativo agent (instruções, ferramentas, configuração de modelo). O novo agente recebe automaticamente uma identidade exclusiva e um ponto de extremidade estável. Consulte o Caminho 2 para obter detalhes.

2. Publique o novo agente no Microsoft 365 e no Teams no portal do Foundry. A publicação só está disponível por meio do portal do Foundry— não há nenhuma API de publicação pública. Para obter etapas, consulte Publicar agentes no Microsoft 365 Copilot e no Microsoft Teams.

3. Verifique se o novo agente funciona no M365/Teams com o novo ponto de extremidade estável.

4. Desativar o aplicativo do agente antigo depois de confirmar que o novo agente funciona:

   • Exclua o recurso do Aplicativo de Agente do Azure. Excluir o recurso não exclui as versões do agente.
   • Para manter as integrações existentes funcionando, atualize qualquer código que faça referência à URL do ponto de extremidade de aplicativo antiga para usar a URL do ponto de extremidade estável do novo agente.

Alterações na URL do endpoint

Ao migrar, atualize qualquer código ou integrações que referenciem o formato de ponto de extremidade antigo:

Divulgação da Experiência do Usuário durante a transição

Durante a transição, você poderá ver diferentes experiências de publicação dependendo do tipo de agente:

• Novos agentes (agent.identity != nulo): você verá a nova interface de usuário de publicação com seleção de endpoints estáveis, roteamento de versões e publicação direta no M365/Teams.
• Agentes legados (agent.identity == null): Você vê a interface de usuário de publicação do aplicativo de agente legado. Um banner pode indicar que a nova experiência está disponível com um link para atualização.

Cronograma e descontinuação

Faqs

Preciso migrar imediatamente?

Não. Os aplicativos de agente existentes continuam funcionando. No entanto, novos recursos (divisão de tráfego, vários protocolos, desabilitação/habilitação, A2A) só estão disponíveis no novo modelo de agente.

Meu aplicativo de agente deixará de funcionar?

Não imediatamente. Os aplicativos de agente serão descontinuadas mediante aviso prévio e com um período de migração. Eles continuam funcionando até a data de fim do suporte.

Posso ter tanto um Aplicativo de Agente quanto um agente de novo modelo para o mesmo agente subjacente?

Durante a transição, sim. A Aplicação do Agente e o novo agente endpoint podem coexistir. No entanto, são recursos separados com identidades e pontos de extremidade separados.

O que acontece com as funções de controle de acesso baseado em função (RBAC) do Azure que atribuí aos recursos do Aplicativo de Agente?

O RBAC aplicado aos recursos do aplicativo do agente não é transferido para o objeto do agente. Você precisa atribuir funções (como Consumidor do Agente Foundry) ao recurso de agente para o novo ponto de extremidade.

Meu agente usa ferramentas que autenticam com a identidade do agente. O que muda?

Com o novo modelo, o agente tem uma identidade exclusiva da criação, portanto, não há nenhuma alteração de identidade no momento da publicação. No entanto, se você migrar de um agente herdado, o agente receberá uma nova identidade, diferente da identidade compartilhada do projeto e de qualquer identidade de aplicativo do agente. Você precisa reatribuir o RBAC aos recursos subordinados.

Conteúdo relacionado

• Aplicações de agentes no Microsoft Foundry
• Publicar agentes no Microsoft 365 Copilot and Teams
• Conceitos de identidade do agente na Foundry