Integrar agentes personalizados con el Agente de Acciones Recomendadas

El Agente de Acciones Recomendadas en Dynamics 365 Sales destaca recomendaciones prioritarias para oportunidades. Proporciona una canalización compartida de puntuación, contratos de datos y sincronización bidireccional de estados para que cualquier agente personalizado pueda mostrar recomendaciones junto con agentes de primera mano.

Este artículo describe la arquitectura, los componentes clave, los contratos de datos y el flujo de integración utilizados cuando un agente personalizado se integra con el Agente de Acciones Recomendadas. Proporciona el conocimiento básico necesario para implementar una integración.

Prerequisites

• NextBestActionAgent solución desplegada en la organización objetivo. Para más información, consulte Importar un agente a un entorno objetivo.

• El vendedor tiene los roles de seguridad adecuados en Dataverse como se describe en Permisos requeridos para roles de seguridad personalizados.

• Una cadena SourceAgentId estable y única para el agente personalizado. Para más información, consulte Añadir agentes personalizados para las acciones recomendadas.

• Se requieren los siguientes permisos para impulsar las acciones recomendadas:

  Tabla	Privilegios necesarios	Ámbito
  msdyn_rawactioncatalogue	Leer, Escribir, Añadir y Añadir a	Global
  msdyn_prioritizedactioncatalogue	Leer, Escribir, Añadir y AppendTo	Global
  msdyn_recommendedactionsourceagentconfig	Lectura	Global
  msdyn_salesagentprofile	Lectura	Global

Arquitectura de integración

La integración con el Agente de Acciones Recomendadas utiliza una cadena de procesamiento que ingiere acciones en bruto de los agentes fuente, las puntua mediante un motor de puntuación UICE (Urgencia, Impacto, Confianza, Esfuerzo) y muestra los resultados priorizados en el carrusel del vendedor.

La tubería de procesamiento funciona de la siguiente manera:

1. El agente de aduanas detecta una información accionable (por ejemplo, un riesgo de acuerdo, un acuerdo estancado o un interesado ausente).
2. El agente personalizado llama a la msdyn_PushActionDataToRecommendedActionAgent API personalizada para enviar la acción.
3. La acción se almacena en msdyn_rawactioncatalogue (tabla de entrada).
4. Para cada acción, el Motor de Puntuación:
   • Captura las señales de entidad de Dataverse.
   • Obtiene los datos de priorización específicos del agente del catálogo de acciones.
   • Invoca al LLM para evaluar la acción en las dimensiones UICE (Urgencia, Impacto, Confianza, Esfuerzo).
   • Aplica las reglas de mínimo y máximo.
   • Calcula la puntuación de prioridad final usando GetRecommendedActionAgentResponse.
5. La acción puntuada se inserta en msdyn_prioritizedactioncatalogue (tabla de salida).
6. El Carrusel de Acciones Recomendadas recoge acciones puntuadas y renderiza cartas.

Componentes clave

La integración se basa en las siguientes tablas y APIs de Dataverse.

Registro del agente

Registra agentes personalizados con el Agente de Acciones Recomendadas para que la plataforma reconozca y obtenga sus acciones. Para más información sobre cómo registrar agentes, consulte Añadir agentes personalizados para las acciones recomendadas.

Cuando registras a un agente, se crea una entrada en msdyn_recommendedactionsourceagentconfig. El SourceAgentId único identifica la entrada para el agente de aduanas.

Configuración del agente

La msdyn_recommendedactionsourceagentconfig tabla contiene la configuración por agente que regula cómo el Agente de Acciones Recomendadas interpreta las acciones de un agente. Los dos campos más importantes a poblar son msdyn_internalprioritizationinstruction y msdyn_syncactionexecutionstateapiconfig.

Puedes aplicar la configuración actualizando manualmente el registro de la tabla o llamando a la API UpsertRecommendationAgentConfigRequestpersonalizada .

Esquema de UpsertRecommendationAgentConfigRequest

El siguiente ejemplo muestra los campos de configuración disponibles en el esquema.

{
  "agentName": "YourAgentName",
  "agentType": "CustomAgent",
  "isRecommendedActionAgentEnabled": true,
  "salesAgentProfileId": "<SourceAgentId that was configured>",
  "agentImpactMapping": "[]",
  "internalPrioritizationInstruction": "{\"signals\":[...]}",
  "syncActionExecutionStateApiConfig": "{\"syncactionuistatusapiname\":\"your_SyncBackCustomApiName\"}",
  "description": "Brief description of your agent"
}

Instrucción de priorización interna

La instrucción interna de priorización contiene metadatos específicos de la señal del agente que indican al motor de puntuación cómo interpretar los campos de datos de priorización de un agente. Es un objeto JSON con un array de signals nivel superior. Cada señal se deserializa en AgentSignalInstructionConfig con los siguientes campos:

Ejemplo de bloque de señales:

{
  "signals": [
    {
      "name": "risk_type",
      "type": "string",
      "source": "action_data",
      "dimension_influence": { "urgency": "moderate", "confidence": "weak" },
      "interpretation": "Risk category code assigned by the source agent (e.g. 8 = Missing BANT Info). Used for pre-filter rule matching and prompt context.",
      "reliability": "high",
      "required": false,
      "fetch_info": { "fetch_type": "action_data", "crm_field": "riskType" }
    },
    {
      "name": "risk_label",
      "type": "string",
      "source": "action_data",
      "dimension_influence": { "urgency": "weak", "confidence": "weak" },
      "interpretation": "Human-readable risk name from the source agent (e.g. 'Missing BANT Info', 'Stalled Pipeline'). Useful for prompt context and seller explanation.",
      "reliability": "high",
      "required": false,
      "fetch_info": { "fetch_type": "action_data", "crm_field": "risk" }
    }
  ]
}

Configuración de la API de estado de ejecución de la acción de sincronización

La configuración de la API del estado de ejecución de la acción de sincronización es un objeto JSON que especifica el nombre de API personalizado al que llama el Agente de Acciones Recomendadas cuando un vendedor realiza una acción en una tarjeta (por ejemplo, la marca como completada o irrelevante). Esta API establece el estado de la acción en el agente personalizado de origen.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Contrato de acción push

Los agentes personalizados ejecutan acciones usando la msdyn_PushActionDataToRecommendedActionAgent API personalizada. La API se llama cada vez que el agente genera o actualiza una acción para una entidad objetivo.

Parámetros de solicitud

Ejemplo: llamada a un complemento de C#

var request = new OrganizationRequest("msdyn_PushActionDataToRecommendedActionAgent")
{
    ["msdyn_ActionId"] = $"DealRisk_{opportunityId}_{riskType}",
    ["msdyn_SourceAgentId"] = "DealClosingAgent",
    ["msdyn_TargetEntityId"] = opportunityId, // Guid
    ["msdyn_TargetEntityTypeName"] = "opportunity",
    ["msdyn_ActionReason"] = "Customer has not responded in 14 days, deal is at risk of stalling",

    ["msdyn_ActionUIPayload"] = JsonConvert.SerializeObject(new
    {
        version = "1.0",
        payload = new
        {
            header = "Follow up with Contoso",
            description = "No customer response in 14 days. Deal may stall without re-engagement.",
            oncardClickActionType = "Navigate",
            oncardClickActionTypeParameters =
                "{etn=\"opportunity\", id=\"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb\", pagetype=\"entityrecord\"}"
        }
    }),

    ["msdyn_ActionPrioritizationData"] = JsonConvert.SerializeObject(new
    {
        riskType = "14",
        risk = "low"
    })
};

var response = orgService.Execute(request);

bool success = (bool)response["msdyn_IsSuccess"];

Contrato de carga útil de la interfaz de acción

El msdyn_ActionUIPayload campo contiene una carga útil JSON que controla cómo aparece una carta de acción en el carrusel del Agente de Acciones Recomendadas.

{
  "version": 1.0,
  "header": "Follow up with Contoso on pricing proposal",
  "description": "Stakeholder engagement has dropped. The customer expressed interest in the enterprise tier but hasn't responded to the last proposal sent 10 days ago.",
  "oncardClickActionType": "Navigate",
  "oncardClickActionTypeParameters": "{\"etn\":\"opportunity\",\"id\":\"<guid>\",\"pagetype\":\"entityrecord\"}",
  "onctaClickActionType": "Navigate",
  "onctaClickActionTypeParameters": "{\"etn\":\"opportunity\",\"id\":\"<guid>\",\"pagetype\":\"entityrecord\"}"
}

Contrato de datos de priorización

El msdyn_prioritizationdata campo permite que un agente pase señales específicas de cada agente que influyen en cómo el motor de puntuación UICE prioriza una acción.

[
  { "signalName": "risk", "value": "low" },
  { "signalName": "riskType", "value": "4" }
]

El motor de puntuación lee estas señales junto con las señales a nivel de entidad (valor de la operación, etapa, competidores, etc.). La msdyn_internalprioritizationinstructionconfiguración del agente le indica al LLM cómo interpretar cada señal, y el motor de puntuación combina todas las señales en la instrucción de puntuación de UICE.

Versionado de acciones e invalidación

Cuando un agente actualiza los datos de una acción previamente enviada, crea un nuevo registro con la misma msdyn_ActionId llamando msdyn_PushActionDataToRecommendedActionAgent de nuevo. El sistema crea una nueva fila en msdyn_rawactioncatalogue con el mismo msdyn_actionid pero un nuevo msdyn_rawactioncatalogueid. El Agente de Acciones Recomendadas sigue mostrando la versión antigua hasta procesar la nueva.

Para invalidar una acción (por ejemplo, cuando se resuelve un riesgo), el agente llama a la API personalizada msdyn_RAAgent_RemoveActionsV2 con el actionId. Esta acción marca todos msdyn_rawactioncatalogue los registros de esa acción como inactivos, y la carta desaparece del carrusel.

Sincronización de estados bidireccional

El estado de las acciones se sincroniza tanto en el carrusel del agente de acciones recomendadas como en tu agente personalizado para garantizar que los vendedores vean información coherente independientemente de dónde realicen la acción.
Acciones recomendadas Agente → agente de aduanas (el vendedor actúa en el carrusel): Cuando un vendedor marca una acción como Realizada o Desestimada en el carrusel:

1. El Agente de acciones recomendadas actualiza el msdyn_actionuistatus en msdyn_prioritizedactioncatalogue.
2. El agente de Acciones recomendadas lee msdyn_syncactionexecutionstateapiconfig de la configuración del agente.
3. El Agente de Acciones Recomendadas llama a la API personalizada del agente con:

El agente debe implementar una API personalizada que acepte estos dos parámetros y actualice el estado de la acción en su propio almacén de datos.

Agente personalizado → Agente de Acciones Recomendadas (el vendedor actúa en la interfaz del agente): Cuando un vendedor actúa sobre una acción en la propia interfaz del agente (por ejemplo, la marca como mitigada en una página de agente personalizado), el agente sincroniza ese estado con el Agente de Acciones Recomendadas mediante una llamada a msdyn_SyncActionExecutionStateFromAgent. Esta acción actualiza el estado en la tabla de salida del agente de Acciones recomendadas, ocultándolo del carrusel.

Pruebas y validación

Tras la configuración e implementación, valida el flujo de extremo a extremo realizando las siguientes comprobaciones.

Verificar configuración del agente:

GET [org-url]/api/data/v9.2/msdyn_recommendedactionsourceagentconfigs
?$filter=msdyn_agentname eq 'YourAgentName'
&$select=msdyn_agentname,msdyn_agentimpactmapping,msdyn_internalprioritizationinstruction,msdyn_syncactionexecutionstateapiconfig

Empuja una acción de prueba llamando msdyn_PushActionDataToRecommendedActionAgent y verifica que msdyn_IsSuccess sea cierta y que aparezca un nuevo registro en msdyn_rawactioncatalogue.

Activa la puntuación a demanda llamando msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (en lugar de esperar al temporizador de 4 horas).

Verificar la salida puntuada:

    GET [org-url]/api/data/v9.2/msdyn_prioritizedactioncatalogues
    ?$filter=msdyn_actionid eq 'your-action-id'
    &$select=msdyn_actionid,msdyn_actionscore,msdyn_actionuipayload,msdyn_hascrossedceiling,msdyn_hascrossedfloor,msdyn_actionuistatus,msdyn_scoredetails

Valores esperados:

• msdyn_actionscore se rellena con un valor en el intervalo de 0 a 10.
• msdyn_hascrossedfloor es falso (la acción está por encima del suelo y se nota en el carrusel).
• msdyn_actionuistatus es 1 (Activo).
• msdyn_scoredetails contiene la explicación generada por LLM.

Verifica la visualización del carrusel abriendo un formulario de Oportunidad en Dynamics 365 Sales y marcando la sección de Acciones Sugiridas. Verifica la sincronización del estado descartando una acción en el carrusel (la API de sincronización inversa debe invocarse con state = "Dismissed") y marcando una acción en la interfaz de usuario del agente (el registro de la tabla de salida debe reflejar el valor actualizado de msdyn_actionuistatus).

Ejemplo: Agente de Oportunidades de Ventas

Sales Opportunity Agent es el primer agente incorporado al Agente de Acciones Recomendadas, y su integración sirve como referencia para la implementación.

Valores de configuración de agentes:

Cuando finaliza la investigación de Sales Opportunity Agent y se identifican los riesgos de la operación, DealRiskToNBAService genera cada riesgo como una acción independiente:

Comportamiento de sincronización de estado:

• Agente de oportunidades de venta → Agente de acciones recomendadas: Cuando un vendedor marca un riesgo como completado en la página de investigación, el agente llama a msdyn_SyncActionExecutionStateFromAgent.
• Agente de acciones recomendadas → Agente de oportunidades de ventas: Cuando un vendedor descarta una tarjeta en el carrusel, el Agente de acciones recomendadas llama a ora_UpdatedActionStateFromRAAgent (configurado en la configuración del agente).

Información relacionada

• Configurar el agente de acciones recomendadas
• Introducción a las acciones recomendadas