Migrar para o Microsoft Agent 365 SDK 2.0

O Microsoft Agent 365 SDK 2.0 está disponível para Python, JavaScript e .NET. Esta versão inclui alterações incompatíveis, mas a maioria delas afeta apenas os pacotes de observabilidade obsoletos, e cada alteração tem um caminho direto de migração. Use este artigo para encontrar as mudanças que se aplicam ao seu agente e atualize seu código.

Resumo das alterações incompatíveis

Area Languages Alterar Action
Notificações Python O AgentLifecycleEvent.USERDELETED valor mudou. Atualize o código que compara com o valor bruto da string.
Extensões de ferramentas .NET authToken não autentica mais servidores MCP. Forneça UserAuthorization e authHandlerName, ou defina BEARER_TOKEN variáveis de ambiente.
Runtime Python get_observability_authentication_scope() retorna o escopo apenas /.default do app. Use o escopo com um resolvedor de token somente para aplicativo.
Exportação de observabilidade Python, JavaScript, .NET A exportação sempre usa o endpoint service-to-service (S2S) e requer um resolvedor de token somente de aplicativo. Substitua o código de token delegado por um resolvedor exclusivo para aplicativos.
Telemetria de observabilidade Python, JavaScript, .NET Atributos de mensagens, nomes de atributos e validação de inferência foram alterados. Atualize código, consultas e dashboards que dependam do formato anterior.

Note

Os pacotes de observabilidade estão obsoletos. O SDK 2.0 ainda os publica, mas não os use para novas integrações. Em vez de atualizar uma integração de observabilidade existente para o SDK 2.0, considere migrar para a distro OpenTelemetry da Microsoft.

Atualize seus pacotes para o Agent 365 SDK 2.0

Atualize todos os pacotes do SDK do Agent 365 do seu projeto para a versão 2.0 ao mesmo tempo. Para a lista completa de pacotes, veja pacotes do SDK Agent 365.

pip install --upgrade microsoft-agents-a365-notifications microsoft-agents-a365-tooling microsoft-agents-a365-runtime

Adicione quaisquer outros pacotes do Agent 365 que seu agente utilize, como extensões de ferramentas, ao mesmo comando.

Notifications

Revise o valor atualizado do evento do ciclo de vida e os novos eventos disponíveis no SDK 2.0.

Python: Valor do evento do ciclo de vida de usuário excluído alterado

O valor AgentLifecycleEvent.USERDELETED agora é agenticuserdeleted. Em versões anteriores, o valor era agenticuseridentitydeleted.

Se seu código comparar o evento do ciclo de vida com uma string bruta, compare o tipo de evento em minúsculas com o valor do membro AgentLifecycleEvent:

from microsoft_agents_a365.notifications import AgentLifecycleEvent, AgentNotification

agent_notification = AgentNotification(app)

@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
    event_type = (notification.activity.value_type or "").lower()
    if event_type == AgentLifecycleEvent.USERDELETED.value:
        await context.send_activity("User identity deleted")

Novos eventos do ciclo de vida

O SDK 2.0 adiciona cinco eventos do ciclo de vida e manipuladores do ciclo de vida ao Python e JavaScript. O SDK .NET já os inclui. Para a lista completa, veja Eventos do ciclo de vida do Agente.

Extensões de ferramentas de desenvolvimento

Se você usar as extensões de ferramentas .NET, atualize como seu agente autentica servidores MCP.

.NET: O parâmetro authToken não autentica mais os servidores MCP

Essa mudança se aplica às extensões de ferramentas Kernel semântico, Agent Framework e Fábrica de IA do Azure.

Quando você não fornece UserAuthorization e authHandlerName, a extensão usa authToken apenas para descobrir servidores MCP através do gateway de ferramentas. Em seguida, autentica cada servidor MCP apenas com um token da variável de ambiente BEARER_TOKEN_<SERVERNAME> ou BEARER_TOKEN. A extensão pula e registra em log qualquer servidor que não tenha um token, então um agente que dependia apenas de authToken pode não retornar ferramentas MCP sem erro.

Essa mudança também afeta os seguintes métodos do Fábrica de IA do Azure, que sempre utilizam esse caminho:

  • AddToolServersToAgent (síncrono)
  • GetMcpToolDefinitionsAndResourcesAsync(agentInstanceId, authToken, turnContext)

Para migrar, use uma das seguintes opções:

  • Autenticação agentic (recomendada): Passe UserAuthorization e authHandlerName para que a extensão adquira tokens por meio do fluxo agentic on-behalf-of (OBO).

    // Semantic Kernel
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);

// Azure AI Foundry: use the async method instead of AddToolServersToAgent
await toolService.AddToolServersToAgentAsync(agentClient, userAuthorization, authHandlerName, turnContext);

  • Variáveis de ambiente: Defina BEARER_TOKEN_<SERVERNAME> para cada servidor MCP, ou defina BEARER_TOKEN para usar um token para todos os servidores. Essa opção é adequada para desenvolvimento e testes locais.

Para mais informações, veja Registrar ferramentas com seu orquestrador.

Runtime

Se seu agente Python usa o pacote de runtime para obter o escopo de autenticação de observabilidade, revise a seguinte alteração.

Python: O escopo de autenticação de observabilidade é somente de aplicativo

get_observability_authentication_scope() agora retorna o escopo do recurso de observabilidade /.default, api://9b975845-388f-4429-889e-eab1ef63949c/.default. Em versões anteriores, retornava o escopo delegado Agent365.Observability.OtelWrite .

Use este escopo apenas para adquirir um token exclusivo de aplicativo para a instância do agente exportador. Para detalhes, veja Exportação de observabilidade usando autenticação apenas por aplicativo.

Mudanças de observabilidade no SDK 2.0

As seguintes mudanças se aplicam aos pacotes de observabilidade obsoletos do Agent 365 em todas as três linguagens.

A exportação de observabilidade usa autenticação somente de aplicativo

SDK 2.0 remove autenticação delegada para exportação de observabilidade:

  • O exportador sempre envia telemetria para a rota S2S. As use_s2s_endpoint opções (Python), useS2SEndpoint (JavaScript) e UseS2SEndpoint (.NET) são ignoradas, mesmo quando definidas como false.
  • O exportador requer um resolver de token que retorne um token exclusivo do aplicativo para a instância do agente exportador. A rota S2S rejeita tokens delegados.
  • O cache de token de hospedagem adquire tokens somente de aplicativo. Os métodos de registro delegado não adquirem mais tokens.
  • No .NET, EnvironmentUtils.GetObservabilityAuthenticationScope() retorna o escopo somente de aplicativo /.default em vez do escopo delegado Agent365.Observability.OtelWrite.
Linguagem Remover Em vez disso, use
Python AgenticTokenCache.register_observability(...), que agora é um no-op que registra o erro AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver)
JavaScript RefreshObservabilityToken com um TurnContext e Authorization, e runWithExportToken para tokens do exportador RefreshObservabilityToken(agentId, tenantId, tokenResolver) com withTokenResolver(...) ou exporterOptions.tokenResolver
.NET AgenticTokenCache.RegisterObservability(...) com AgenticTokenStruct, que agora está obsoleto e causa um erro no compilador ObservabilityTokenResolver com AgenticTokenCache.RefreshObservabilityToken(...), e TokenResolver ou ContextualTokenResolver nas opções de exportador

A autenticação da carga de trabalho para servidores MCP, Microsoft Graph e fluxos OBO não muda.

Para requisitos de resolver e exemplos de código em cada linguagem, veja Resolver de Tokens.

Mudanças no formato da telemetria de observabilidade

Atualize o código que cria telemetria e quaisquer consultas ou dashboards que dependam do formato da mensagem, regras de validação ou nomes de atributos descritos nesta seção.

Atributos de mensagem são arrays JSON

Os atributos gen_ai.input.messages e gen_ai.output.messages agora seguem as convenções semânticas de IA generativa da OpenTelemetry. Eles serializam como um array JSON simples, como [{"role": ..., "parts": [...]}], em vez do {"version": "0.1.0", "messages": [...]} wrapper.

  • Python: A constante A365_MESSAGE_SCHEMA_VERSION e o campo version em InputMessages e OutputMessages são removidos. OutputMessage.finish_reason usa como padrão "stop".
  • JavaScript: O A365_MESSAGE_SCHEMA_VERSION export e a version propriedade de InputMessages e OutputMessages são removidos. Use DEFAULT_FINISH_REASON em seu lugar. As mensagens de saída que você cria a partir de strings simples têm por padrão de finish_reason a "stop".
  • .NET: A classe MessageConstants e as propriedades InputMessages.Version e OutputMessages.Version foram removidas. OutputMessage.FinishReason não é nulo e tem como padrão "stop".

Atualize qualquer código, consultas ou dashboards que analisem esses atributos para que esperem um array JSON.

Os detalhes da inferência são validados

  • Python:InferenceCallDetails requer um model ou responseModel não vazio. Se ambos estiverem ausentes ou em branco, a construção gera ValueError.
  • JavaScript:InferenceDetails.providerName é necessário. model é opcional, mas você deve fornecer um model não vazio ou responseModel. InferenceScope.start() gera uma exceção se esses valores estiverem ausentes. Também lança se endpoint.port não for um inteiro de 1 a 65535.

Alterações no nome do atributo e da operação

  • Python: Nomes de operações de inferência e prefixos de nomes de span usam os valores canônicos em minúsculas do OpenTelemetry chat, text_completion e generate_content. Por exemplo, Chat gpt-4 se tornará chat gpt-4. Atualize filtros sensíveis a maiúsculas e minúsculas, dashboards e alertas.
  • JavaScript:
    • Os intervalos de inferência registram server.port quando a porta é 443.
    • As extensões de resposta do OpenAI reportam o modelo servido em gen_ai.response.model em vez de gen_ai.request.model.
    • A extensão LangChain não usa mais o modelo servido como um plano B para gen_ai.request.model. Ele informa o modelo fornecido apenas em gen_ai.response.model.
  • .NET: O gen_ai.tool.arguments atributo é renomeado para gen_ai.tool.call.arguments.

.NET: Mudanças na interface IA365EtwLogger

A interface IA365EtwLogger adiciona o método LogApplyGuardrail(...) e um parâmetro opcional Exception? error em cada método existente Log*. Se você implementar IA365EtwLogger, atualize sua implementação e recompile.

Conteúdo relacionado

  • Última atualização em