Integre agentes personalizados com o Agente de Ações Recomendadas

O Agente de Ações Recomendadas no Dynamics 365 Sales destaca recomendações priorizadas para oportunidades. Ele oferece um pipeline compartilhado de pontuação, contratos de dados e sincronização bidirecional de estados para que qualquer agente personalizado possa apresentar recomendações junto com agentes de primeira parte.

Este artigo descreve a arquitetura, componentes-chave, contratos de dados e o fluxo de integração usados quando um agente personalizado se integra com o Agente de Ações Recomendadas. Ele fornece o conhecimento fundamental necessário para implementar uma integração.

Pré-requisitos

• Solução NextBestActionAgent implantada na organização alvo. Para mais informações, veja Importar um agente para um ambiente de destino.

• O vendedor possui papéis de segurança apropriados no Dataverse , conforme descrito em Permissões necessárias para funções de segurança personalizadas.

• Uma string SourceAgentId estável e única para o agente personalizado. Para mais informações, veja Adicionar agentes personalizados para ações recomendadas.

• As seguintes permissões são necessárias para impulsionar as ações recomendadas:

  Tabela	Privilégios necessários	Scope
  msdyn_rawactioncatalogue	Ler, Escrever, Anexar e Anexar A	Global
  msdyn_prioritizedactioncatalogue	Ler, Escrever, Anexar e Anexar A	Global
  msdyn_recommendedactionsourceagentconfig	Ler	Global
  msdyn_salesagentprofile	Ler	Global

Arquitetura de integração

A integração do Agente de Ações Recomendadas usa um pipeline de processamento que ingere ações brutas dos agentes de origem, as pontua usando um mecanismo de pontuação UICE (Urgência, Impacto, Confiança, Esforço) e exibe os resultados priorizados no carrossel do vendedor.

O pipeline de processamento funciona da seguinte forma:

1. O agente alfandegário detecta um insight acionável (por exemplo, risco de negócio, negócio paralisado ou um stakeholder ausente).
2. O agente personalizado chama a msdyn_PushActionDataToRecommendedActionAgent API personalizada para empurrar a ação.
3. A ação é armazenada em msdyn_rawactioncatalogue (tabela de entrada).
4. Para cada ação, o Motor de Pontuação:
   • Obtém sinais da entidade do Dataverse.
   • Busca dados de priorização específicos do agente do catálogo de ações.
   • Chama o LLM para atribuir uma pontuação à ação nas dimensões do UICE (Urgência, Impacto, Confiança, Esforço).
   • Aplica regras de limite mínimo e máximo.
   • Calcula a pontuação final de prioridade usando GetRecommendedActionAgentResponse.
5. A ação pontuada é inserida em msdyn_prioritizedactioncatalogue (tabela de saída).
6. O Agente Carrossel de Ações Recomendadas busca ações pontuadas e renderiza cartas.

Componentes principais

A integração depende das seguintes tabelas e APIs do Dataverse.

Registro do agente

Registre agentes personalizados no Agente de Ações Recomendadas para que a plataforma reconheça e busque suas ações. Para mais informações sobre como registrar agentes, veja Adicionar agentes personalizados para ações recomendadas.

Quando você registra um agente, ele cria uma entrada em msdyn_recommendedactionsourceagentconfig. O SourceAgentId exclusivo identifica a entrada do agente personalizado.

Configuração do agente

A msdyn_recommendedactionsourceagentconfig tabela contém a configuração por agente que governa como o Agente de Ações Recomendadas interpreta as ações de um agente. Os dois campos mais importantes a serem povoados são msdyn_internalprioritizationinstruction e msdyn_syncactionexecutionstateapiconfig.

Você pode aplicar configuração atualizando manualmente o registro da tabela ou chamando a API UpsertRecommendationAgentConfigRequestpersonalizada .

Esquema do UpsertRecommendationAgentConfigRequest

O exemplo a seguir mostra os campos de configuração disponíveis no 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"
}

Instrução de priorização interna

A instrução interna de priorização contém metadados de sinal específicos do agente que informam ao mecanismo de pontuação como interpretar os campos de dados de priorização do agente. É um objeto JSON com um array de nível signals superior. Cada sinal é desserializado em AgentSignalInstructionConfig com os seguintes campos:

Exemplo de bloco de sinais:

{
  "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" }
    }
  ]
}

Configuração da API de estado de execução da ação de sincronização

A configuração da API do estado de execução da ação de sincronização é um objeto JSON que especifica o nome da API personalizada que o Agente de Ações Recomendadas chama quando um vendedor realiza uma ação em um cartão (por exemplo, marca-o como concluído ou irrelevante). Essa API define o status da ação no agente personalizado de origem.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Contrato de ação push

Agentes personalizados executam ações usando a msdyn_PushActionDataToRecommendedActionAgent API personalizada. A API é chamada toda vez que o agente gera ou atualiza uma ação para uma entidade-alvo.

Parâmetros de solicitação

Exemplo: chamada de plugin 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 do payload da interface de ação

O campo msdyn_ActionUIPayload contém um payload JSON que controla como um cartão de ação é exibido no carrossel do Recommended Actions Agent.

{
  "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 dados de priorização

O campo msdyn_prioritizationdata permite que um agente transmita sinais específicos do agente que influenciam a forma como o mecanismo de pontuação UICE prioriza uma ação.

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

O motor de pontuação lê esses sinais junto com sinais em nível de entidade (valor do negócio, estágio, concorrentes e assim por diante). O msdyn_internalprioritizationinstruction na configuração do agente informa ao LLM como interpretar cada sinal, e o mecanismo de pontuação combina todos os sinais em um prompt de pontuação do UICE.

Versionamento de ações e invalidação

Quando um agente atualiza dados de uma ação previamente enviada, ele cria um novo registro com a mesma msdyn_ActionId ao chamar msdyn_PushActionDataToRecommendedActionAgent novamente. O sistema cria uma nova linha em msdyn_rawactioncatalogue com o mesmo msdyn_actionid, mas um novo msdyn_rawactioncatalogueid. O Agente de Ações Recomendadas continua mostrando a versão antiga até processar a nova.

Para invalidar uma ação (por exemplo, quando um risco é resolvido), o agente chama a msdyn_RAAgent_RemoveActionsV2 API personalizada com o actionId. Essa ação marca todos os registros msdyn_rawactioncatalogue dessa ação como inativos, e o cartão desaparece do carrossel.

Sincronização de estados bidirecionais

O estado da ação se sincroniza tanto no carrossel do Agente de Ações Recomendadas quanto no seu agente personalizado para garantir que os vendedores vejam informações consistentes, independentemente de onde atuem em uma ação.
Agente de ações recomendadas → agente personalizado (o vendedor executa ações no carrossel): Quando um vendedor marca uma ação como Concluída ou Dispensada no carrossel:

1. O agente de ações recomendadas atualiza o msdyn_actionuistatus em msdyn_prioritizedactioncatalogue.
2. O Agente de Ações Recomendadas lê msdyn_syncactionexecutionstateapiconfig da configuração do agente.
3. O Agente de Ações Recomendadas chama a API personalizada do agente com:

O agente deve implementar uma API personalizada que aceite esses dois parâmetros e atualize o estado da ação em seu próprio armazenamento de dados.

Agente personalizado → Agente de Ações Recomendadas (o vendedor atua na interface do agente): Quando um vendedor age em uma ação na interface do próprio agente (por exemplo, marca-a como mitigada em uma página de agente personalizado), o agente sincroniza esse estado com o Agente de Ações Recomendadas chamando msdyn_SyncActionExecutionStateFromAgent. Essa ação atualiza o status na tabela de saída do Agente de Ações Recomendadas, ocultando-a do carrossel.

Teste e validação

Após a configuração e implementação, valide o fluxo de ponta a ponta realizando as seguintes verificações.

Verifique a configuração do agente:

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

Envie uma ação de teste chamando msdyn_PushActionDataToRecommendedActionAgent e verifique se msdyn_IsSuccess é verdadeira e um novo registro aparece em msdyn_rawactioncatalogue.

Inicie a pontuação sob demanda chamando msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (em vez de esperar o temporizador de 4 horas).

Verifique a pontuação:

    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 é preenchido com um valor no intervalo de 0 a 10.
• msdyn_hascrossedfloor é falso (a ação é acima do chão e aparece no carrossel).
• msdyn_actionuistatus é 1 (Ativo).
• msdyn_scoredetails contém a explicação gerada por LLM.

Verifique a exibição do carrossel abrindo um formulário de Oportunidade no Dynamics 365 Sales e conferindo a seção de Ações Sugeridas. Verifique a sincronização de estado descartando uma ação no carrossel (a API de sincronização de volta deve ser chamada com state = "Dismissed") e marcando uma ação na interface do agente (o registro da tabela de saída deve refletir o msdyn_actionuistatus atualizado).

Exemplo: Agente de Oportunidades de Vendas

O Agente de Oportunidades de Vendas é o primeiro agente integrado ao Agente de Ações Recomendadas, e sua integração serve como referência na implementação.

Valores de configuração do agente:

Quando a pesquisa do Agente de Oportunidades de Venda é concluída e identifica riscos da negociação, DealRiskToNBAService envia cada risco como uma ação separada:

Comportamento de sincronização de estado:

• Agente de Oportunidade de Vendas → Agente de Ações Recomendadas: Quando um vendedor marca um risco como concluído na página de pesquisa, o agente chama msdyn_SyncActionExecutionStateFromAgent.
• Agente de Ações Recomendadas → Agente de Oportunidade de Venda: Quando um vendedor descarta um cartão no carrossel, o Agente de Ações Recomendadas invoca ora_UpdatedActionStateFromRAAgent (conforme configurado na configuração do agente).

Informações relacionadas

• Configurar o agente de Ações Recomendadas
• Visão geral das ações recomendadas