Migrar das aplicações do agente para o novo endpoint do agente e para a experiência de publicação

Este guia explica como a experiência de publicação por agentes mudou no Microsoft Foundry. Compara o modelo legado (que criou um recurso separado de Aplicação de Agente) com o novo modelo de objetos de agente, e guia-o na migração dos seus agentes existentes e aplicações publicadas.

Visão geral da mudança

O novo modelo de objeto agente colapsa as Aplicações e Implementações de Agentes no próprio objeto Agente. Anteriormente, a publicação criava um recurso de Aplicação Agente separado com a sua própria identidade, endpoint e implementação. Agora, todos os agentes têm estas capacidades desde o momento em que são criados.

Antes (modelo legado)

1. Modelo de recursos: Um Agente (plano de dados), Aplicação do Agente (plano de controlo) e Deployment (plano de controlo) são objetos separados.
2. Propriedades do objeto do agente: id (identificador único do agente), name, e versions (a versão mais recente do agente).
3. Identidade: Agentes não publicados num projeto Foundry partilham a identidade de um agente Entra e um plano de agente Entra. Após a publicação, um agente recebe uma identidade única e um blueprint atribuídos ao recurso de Aplicação do Agente.
4. Publicação: Dois gestos. Primeiro, publicar um agente cria um recurso de Aplicação Agente e uma Implementação, onde a Implementação faz referência à versão publicada do agente. A Aplicação Agente expõe um endpoint estável que encaminha 100% de tráfego para essa versão. Uma Implementação suporta a gestão do ciclo de vida inicial/paragem. O segundo gesto é que a Aplicação Agente pode então ser publicada para Microsoft 365 e Teams.

Depois (novo modelo)

1. Modelo de recursos: Existem apenas objetos Agente (plano de dados e plano de controlo). Eles absorvem as responsabilidades anteriormente associadas à Aplicação e Implementação de Agentes.
2. Propriedades do objeto agente: id, name, versions, agent_endpoint (endpoint estável), protocols, authorization_schemes, version_selector, blueprint, instance_identity, e agent_card (expõe detalhes e capacidades do agente aos consumidores e ao A2A).
3. Identidade: Todos os agentes recebem automaticamente uma Identidade de Agente Entra única e um Esquema de Agente Entra. O Blueprint Bring-your-own Entra Agent é suportado, mas não é o padrão.
4. Publicação: Dois gestos equivalentes. Primeiro, selecione uma versão do agente para expor através do endpoint estável. Em segundo lugar, publique o endpoint estável do agente no Microsoft 365/Teams.

A mudança chave: criar um agente é o único passo necessário para obter um endpoint estável e uma identidade única de agente. Não existe uma etapa de publicação separada para o endpoint. Publicação refere-se agora especificamente à distribuição do agente através dos canais M365 e Teams.

Tipos de agentes durante a transição

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

O agent.identity valor distingue agentes novos de agentes legados: nulo significa legado, não-nulo significa novo.

O que continua a funcionar

• As Aplicações de Agente existentes continuam a servir o tráfego através dos seus endpoints.
• Os agentes publicados no M365/Teams através das Aplicações de Agentes continuam a funcionar.
• O endpoint do projeto continua disponível para compatibilidade retroativa (embora já não seja o caminho recomendado).
• Os agentes legados mantêm-se totalmente funcionais para desenvolvimento e testes no projeto Foundry.

Rotas migratórias

Caminho 1: Novos agentes (sem necessidade de ação)

Se criares agentes após a atualização do modelo de objetos, eles recebem automaticamente o novo modelo com identidade única, endpoint estável e todas as novas funcionalidades. Não é necessária migração.

Caminho 2: Atualizar um agente legado

Agentes legados (criados antes da atualização) usam a identidade partilhada do projeto e não podem ser publicados através 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, isso significa que é um agente legado.

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

   Nota

   Atualmente, não há forma de atualizar um agente legado para uma identidade única. Para obter uma identidade única, cria um novo agente usando a mesma definição (instruções, ferramentas, configuração do modelo). O novo agente recebe automaticamente uma identidade única e um endpoint estável. Está planeado um caminho de atualização no local para uma atualização futura.

3. Uma vez criado o novo agente, ele tem uma identidade única e pode usar todas as novas funcionalidades, incluindo a nova experiência de publicação que utiliza o endpoint do agente.

Caminho 3: Migrar uma Aplicação de Agente existente

Se tiver uma Aplicação de Agente publicada no M365/Teams e quiser migrar para o novo modelo, siga estes passos:

1. Crie um novo agente usando a mesma definição do agente por trás da sua Aplicação de Agente (instruções, ferramentas, configuração do modelo). O novo agente recebe automaticamente uma identidade única e um endpoint estável. Consulte o Caminho 2 para mais detalhes.

2. Publique o novo agente para Microsoft 365 e Teams a partir do portal Foundry. A publicação só está disponível através do portal Foundry — não existe uma API pública de publicação. Para os passos, veja Publicar agentes para Microsoft 365 Copilot e Microsoft Teams.

3. Certifica-te de que o novo agente está a funcionar no M365/Teams com o novo endpoint estável.

4. Descomissionar a antiga Aplicação de Agente depois de confirmar que o novo agente funciona:

   • Eliminar o recurso Agent Application Azure. Eliminar o recurso não apaga as versões do teu agente.
   • Para manter as integrações existentes a funcionar, atualize qualquer código que faça referência à antiga URL do endpoint da Aplicação para usar a nova URL do endpoint estável do agente.

Alterações ao URL do endpoint

Ao migrar, atualize qualquer código ou integrações que refiram ao formato antigo do endpoint:

Publicação de UX durante o processo de transição

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

• Novos agentes (agent.identity != nulo): Vê a nova experiência de utilizador de publicação com seleção estável de endpoint, roteamento de versões e publicação direta para M365/Teams.
• Agentes legados (agent.identity == null): Vê a aplicação de agente legada a publicar a experiência de utilizador. Um banner pode indicar que a nova experiência está disponível com um link para atualizar.

Cronologia e descontinuação

Perguntas Frequentes

Preciso de migrar imediatamente?

Não. As Aplicações de Agente existentes continuam a funcionar. No entanto, novas funcionalidades (divisão de tráfego, múltiplos protocolos, desativação/ativação, A2A) só estão disponíveis no novo modelo de agente.

A minha Aplicação de Agente vai deixar de funcionar?

Não imediatamente. As aplicações de agente são descontinuadas com aviso prévio e período de migração. Continuam a funcionar até ao fim do suporte.

Posso ter tanto uma Aplicação de Agente como um agente de novo modelo para o mesmo agente subjacente?

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

O que acontece às funções de controlo de acesso baseado em funções (RBAC) do Azure que atribuí aos recursos de Aplicações de Agente?

O RBAC nos recursos da Aplicação do Agente não é transferido para o objeto do agente. Tens de atribuir funções (como Foundry Agent Consumer) ao recurso agente para o novo endpoint.

O meu agente utiliza ferramentas que se autenticam com a identidade do agente. O que muda?

Com o novo modelo, o agente tem uma identidade única desde a criação — por isso não há alteração de identidade no momento da publicação. No entanto, se migrar de um agente legado, o agente recebe uma nova identidade que difere tanto da identidade partilhada do projeto como de qualquer identidade de Aplicação do Agente. Você precisa reatribuir o RBAC para os recursos downstream.

Conteúdo relacionado

• Aplicações de agentes na Microsoft Foundry
• Publicar agentes para Microsoft 365 Copilot e Teams
• Conceitos de identidade de agentes na Foundry