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.

Componente Ubicación Description
Input table (Tabla de entrada) msdyn_rawactioncatalogue (Dataverse) Acciones sin procesar que envían los agentes personalizados
Tabla de salida msdyn_prioritizedactioncatalogue (Dataverse) Acciones puntuadas y clasificadas para la interfaz de usuario
Configuración del agente msdyn_recommendedactionsourceagentconfig (Dataverse) Registro y configuración por agente
Push API msdyn_PushActionDataToRecommendedActionAgent (API personalizada) Agente → Agente de acciones recomendadas Envío de acciones del agente

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"
}
Campo JSON Tipo Description
agentName string Mapea a msdyn_agentname (máximo 850 personajes). Obligatorio para registros nuevos.
tipoDeAgente string Categoría del agente. Utiliza "CustomAgent" para agentes que no sean Agentes de Oportunidad de Ventas para crear automáticamente un perfil.
isRecommendedActionAgentEnabled booleano Mapas a msdyn_isrecommendedactionagentenabled. Null = dejar sin cambios.
salesAgentProfileId guid? Enlaces a msdyn_salesagentprofile. Se usa para la búsqueda de registros en upsert.
agentImpactMapping string Matriz JSON plana de nombres principales. Mapas a msdyn_agentimpactmapping.
Instrucción de priorización interna string JSON con matriz de señales. Mapas a msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig string objeto JSON {"syncactionuistatusapiname":"..."}. Mapas a msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId string Mapas a msdyn_sourceagentuniqueid.
description string Mapas a msdyn_sourcedescription (máximo 1000 personajes).

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:

Campo Tipo Description
nombre string Identificador de señal — utilizado como clave en la sección de Referencia de señales del prompt de puntuación
type string Tipo de datos: "cadena", "número", "booleano"
source string Etiqueta descriptiva de donde procede la señal. No se usa para el enrutamiento — fetch_info.fetch_type controla el mecanismo real de obtención. Normalmente se usa "action_data" para señales enviadas por agentes.
dimension_influencia {dimensión: fuerza} ¿A qué dimensiones de UICE afecta esta señal y con qué intensidad? Claves: "urgencia", "impacto", "confianza", "esfuerzo". Fortalezas: "fuerte", "moderado", "débil"
interpretación string Descripción en lenguaje natural de lo que significa la señal para la puntuación — inyectada en el prompt del LLM
confiabilidad string ¿Qué tan fiable es esta señal: "alta", "media", "baja"
required booleano Si la señal debe estar presente para la puntuación
fetch_info object Controla dónde y cómo se recupera el valor de señal en el momento de la puntuación.

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

Parámetro Tipo Obligatorio Description
msdyn_ActionId string Sí Identificador único del agente para esta acción. Se usa para la desduplicación y la sincronización de estado. Debe ser determinista (misma acción = mismo identificador). Formato de ejemplo: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId string Sí Identificador del agente. Debe coincidir con msdyn_agentname en el registro de configuración del agente. Ejemplo: "DealClosingAgent"
msdyn_TargetEntityId identificador único (GUID) Sí GUID del registro de destino (Oportunidad, cliente potencial) con el que se relaciona esta acción
msdyn_TargetEntityTypeName string Sí Nombre lógico de la entidad de destino. Ejemplo: "oportunidad", "liderar"
msdyn_ActionReason string Sí Motivo por el que se generó la acción. Utilizado por el motor de evaluación para el mapeo de principios.
msdyn_ActionUIPayload string No Contenido JSON para el renderizado de tarjetas. Si se omite, el Agente de Acciones Recomendadas no puede mostrar la carta.
msdyn_ActionPrioritizationData string No JSON con datos específicos de cada agente para la puntuación
msdyn_ActionCTA string No Tipo de CTA: cadena. Ejemplo: "Correo electrónico", "Revisión", "Llamada"
msdyn_PrioritizationPrinciples string No Matriz JSON de principios de priorización a los que se asigna esta acción específica (puede invalidar la asignación de nivel de agente)

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:
Parámetro Tipo Description
actionid GUID Identificador de acción
state string "MarkedDone" o "Descartado"

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.

Parámetro Tipo Obligatorio Description
msdyn_ActionId string Sí El identificador de acción (el mismo que se empujó)
msdyn_ActionState integer Sí Nuevo estado — valores (asociados a MarkAsDone/Dismissed)
msdyn_TargetEntityId uniqueidentifier Sí GUID de la entidad de destino
NombreTipoEntidadDestino string Sí Nombre lógico de la entidad de destino
msdyn_TrackingId string No Identificador opcional de seguimiento o correlación

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:

Campo de configuración Valor para Agente de Oportunidades de Ventas (de OraDefaults.cs)
msdyn_agentname AgenteDeOportunidadesDeVentas
msdyn_agentimpactmapping ["DealRisk", "Velocidad de las operaciones"]
msdyn_syncactionexecutionstateapiconfig {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction Consulta el valor de producción del Agente de Oportunidades de Ventas

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:

Parámetro de empuje Valor del agente de oportunidades de venta
msdyn_ActionId DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId DealRiskAgent
msdyn_TargetEntityTypeName "Oportunidad"
msdyn_ActionReason Descripción del riesgo de la investigación
msdyn_ActionUIPayload Tarjeta con encabezado de riesgo + descripción
msdyn_ActionPrioritizationData {"riskType":"8","risk":"Missing BANT Info"} (ejemplo)

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).
  • Last updated on