Migrar a Microsoft Agent 365 SDK 2.0

El SDK Microsoft Agent 365 2.0 está disponible para Python, JavaScript y .NET. Esta versión incluye cambios incompatibles, pero la mayoría afectan solo a los paquetes de observabilidad obsoletos, y cada cambio tiene una ruta de migración directa. Utiliza este artículo para encontrar los cambios que se aplican a tu agente y actualizar tu código.

Resumen de cambios importantes que generan incompatibilidades

Area Languages Cambiar Action
Notificaciones Python El AgentLifecycleEvent.USERDELETED valor cambió. Actualizar el código que compara con el valor literal de la cadena.
Extensiones de herramientas .NET authToken ya no se autentica con los servidores MCP. Proporcione UserAuthorization y authHandlerName, o establezca BEARER_TOKEN variables de entorno.
Tiempo de ejecución Python get_observability_authentication_scope() devuelve el alcance solo /.default de la app. Usa el ámbito con un resolver de token solo para la app.
Exportación de observabilidad Python, JavaScript, .NET La exportación siempre utiliza el endpoint service-to-service (S2S) y requiere un resolver de token solo para la app. Sustituye el código de token delegado por un resolver solo para la aplicación.
Telemetría de observabilidad Python, JavaScript, .NET Los atributos de los mensajes, nombres de atributos y validación de inferencia cambiaron. Actualiza código, consultas y paneles que dependan del formato anterior.

Note

Los paquetes de observabilidad están en desuso. El SDK 2.0 sigue publicándolas, pero no las uses para nuevas integraciones. En lugar de actualizar una integración de observabilidad existente al SDK 2.0, considera migrar a la Microsoft OpenTelemetry Distro.

Actualiza tus paquetes a Agent 365 SDK 2.0

Actualiza todos los paquetes del SDK Agent 365 de tu proyecto a la versión 2.0 al mismo tiempo. Para la lista completa de paquetes, véase paquetes del SDK de Agent 365.

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

Añade cualquier otro paquete de Agent 365 que use tu agente, como extensiones de herramientas, al mismo comando.

Notifications

Revisa el valor actualizado del evento del ciclo de vida y los nuevos eventos disponibles en el SDK 2.0.

Python: Se cambió el valor del evento del ciclo de vida del usuario eliminado

El valor AgentLifecycleEvent.USERDELETED ahora es agenticuserdeleted. En versiones anteriores, el valor era agenticuseridentitydeleted.

Si tu código compara el evento del ciclo de vida con una cadena literal, compara el tipo de evento en minúsculas con el valor del miembro AgentLifecycleEvent en su lugar:

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")

Nuevos eventos del ciclo de vida

El SDK 2.0 añade cinco eventos del ciclo de vida y manejadores a Python y JavaScript. El SDK .NET ya los incluye. Para la lista completa, véase Eventos del ciclo de vida del agente.

Extensiones de herramientas de desarrollo

Si usas las extensiones de herramientas .NET, actualiza cómo tu agente se autentica en los servidores MCP.

.NET: El parámetro authToken ya no autentica los servidores MCP

Este cambio se aplica a las extensiones de herramientas Kernel semántico, Agent Framework y Fundición de IA de Azure.

Cuando no suministras UserAuthorization y authHandlerName, la extensión usa solo authToken para descubrir servidores MCP a través de la pasarela de herramientas. Luego autentica cada servidor MCP solo con un token de la variable de entorno BEARER_TOKEN_<SERVERNAME> o BEARER_TOKEN. La extensión omite y registra cualquier servidor que no tenga token, así que un agente que dependía solo de authToken no puede devolver herramientas MCP sin error.

Este cambio también afecta a los siguientes métodos de Fundición de IA de Azure, que siempre utilizan esta ruta:

  • AddToolServersToAgent (sincrónico)
  • GetMcpToolDefinitionsAndResourcesAsync(agentInstanceId, authToken, turnContext)

Para migrar, utiliza una de las siguientes opciones:

  • Autenticación agéntica (recomendada): Pasa UserAuthorization y authHandlerName para que la extensión adquiera tokens a través del flujo agéntico 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);

  • Variables de entorno: Configura BEARER_TOKEN_<SERVERNAME> para cada servidor MCP, o configura BEARER_TOKEN para usar un token para todos los servidores. Esta opción es adecuada para el desarrollo y pruebas locales.

Para más información, consulta Registrar herramientas con tu orquestador.

Runtime

Si tu agente Python utiliza el paquete runtime para obtener el alcance de autenticación de observabilidad, revisa el siguiente cambio.

Python: El alcance de autenticación de observabilidad es solo para aplicaciones

get_observability_authentication_scope() ahora devuelve el ámbito de recurso /.default de observabilidad, api://9b975845-388f-4429-889e-eab1ef63949c/.default. En versiones anteriores, devolvía el alcance delegado Agent365.Observability.OtelWrite .

Utiliza este ámbito solo para adquirir un token solo de aplicación para la instancia del agente exportador. Para más detalles, Observability export uses app-only authentication.

Cambios en la observabilidad en SDK 2.0

Los siguientes cambios se aplican a los paquetes de observabilidad Agent 365 obsoletos en los tres lenguajes.

La exportación de observabilidad utiliza autenticación solo por aplicación

El SDK 2.0 elimina la autenticación delegada para la exportación de observabilidad:

  • El exportador siempre envía telemetría a la ruta S2S. Las opciones use_s2s_endpoint (Python), useS2SEndpoint (JavaScript) y UseS2SEndpoint (.NET) se ignoran, incluso cuando se configuran en false.
  • El exportador requiere un resolvedor de token que devuelva un token solo de aplicación para la instancia del agente exportador. La ruta S2S rechaza los tokens delegados.
  • La caché de tokens de alojamiento adquiere tokens de solo aplicación. Los métodos de registro delegados ya no adquieren tokens.
  • En .NET, EnvironmentUtils.GetObservabilityAuthenticationScope() devuelve el ámbito de solo aplicación /.default en lugar del ámbito delegado Agent365.Observability.OtelWrite.
Language Remove Use en su lugar
Python AgenticTokenCache.register_observability(...), que ahora es un no-op que registra un error AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver)
JavaScript RefreshObservabilityToken con un TurnContext y Authorization, y runWithExportToken para tokens de exportación RefreshObservabilityToken(agentId, tenantId, tokenResolver) con withTokenResolver(...) o exporterOptions.tokenResolver
.NET AgenticTokenCache.RegisterObservability(...) con AgenticTokenStruct, que ahora está obsoleto y causa un error en el compilador ObservabilityTokenResolver con AgenticTokenCache.RefreshObservabilityToken(...), y TokenResolver o ContextualTokenResolver en las opciones de exportador

La autenticación de carga de trabajo para servidores MCP, Microsoft Graph y flujos OBO no cambia.

Para requisitos de resolver y ejemplos de código en cada lenguaje, véase Token resolver.

Cambios en el formato de telemetría de observabilidad

Actualizar el código que genere telemetría y cualquier consulta o panel que dependa del formato del mensaje, las reglas de validación o los nombres de atributos descritos en esta sección.

Los atributos de los mensajes son arrays JSON

Los atributos gen_ai.input.messages y gen_ai.output.messages ahora siguen las convenciones semánticas de IA generativa de OpenTelemetry. Se serializan como un array JSON simple, como [{"role": ..., "parts": [...]}], en lugar del {"version": "0.1.0", "messages": [...]} envoltorio.

  • Python: La A365_MESSAGE_SCHEMA_VERSION constante y el version campo en InputMessages y OutputMessages se eliminan. OutputMessage.finish_reason se establece de forma predeterminada en "stop".
  • JavaScript: La A365_MESSAGE_SCHEMA_VERSION export y la version propiedad en InputMessages y OutputMessages se eliminan. Utilice DEFAULT_FINISH_REASON en su lugar. Los mensajes de salida que creas a partir de cadenas simples se establecen por defecto de finish_reason a "stop".
  • .NET: Se eliminan la clase MessageConstants y las propiedades InputMessages.Version y OutputMessages.Version. OutputMessage.FinishReason no admite valores nulos y por defecto es "stop".

Actualiza cualquier código, consulta o panel que analice estos atributos para que espere un array JSON.

Se validan los detalles de la inferencia

  • Python:InferenceCallDetails requiere un model o responseModel no vacío. Si ambos faltan o están en blanco, la construcción lanza ValueError.
  • JavaScript:InferenceDetails.providerName es necesario. model es opcional, pero debes aportar un model o responseModel no vacío. InferenceScope.start() lanza si faltan estos valores. También lanza si endpoint.port no es un entero de 1 a 65535.

Cambios en los nombres de atributos y operaciones

  • Python: Los nombres de operaciones de inferencia y los prefijos de nombres de span utilizan los valores canónicos de OpenTelemetry en minúsculas chat, text_completion y generate_content. Por ejemplo, Chat gpt-4 se convierte en chat gpt-4. Actualiza los filtros, paneles y alertas con distinción entre mayúsculas y minúsculas.
  • JavaScript:
    • La inferencia abarca el registro server.port cuando el puerto es 443.
    • Las extensiones de respuesta de OpenAI reportan el modelo servido en gen_ai.response.model en lugar de gen_ai.request.model.
    • La extensión LangChain ya no utiliza el modelo servido como respaldo para gen_ai.request.model. Informa del modelo servido solo en gen_ai.response.model.
  • .NET: El gen_ai.tool.arguments atributo se renombra como gen_ai.tool.call.arguments.

.NET: Cambios en la interfaz de IA365EtwLogger

La IA365EtwLogger interfaz añade un LogApplyGuardrail(...) método y un parámetro opcional Exception? error en cada método existente Log* . Si implementas IA365EtwLogger, actualiza tu implementación y recompila.

Contenido relacionado

  • Se actualizó por última vez el