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

O Agente de Ações Recomendadas na Dynamics 365 Sales destaca recomendações prioritárias para oportunidades. Fornece um pipeline de pontuação partilhado, contratos de dados e sincronização bidirecional de estados para que qualquer agente personalizado possa apresentar recomendações juntamente com agentes de primeira parte.

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

Pré-requisitos

  • Solução NextBestActionAgent implementada na organização alvo. Para mais informações, consulte Importar um agente para um ambiente alvo.

  • O vendedor tem funções de segurança Dataverse apropriadas, conforme descrito nas 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, consulte Adicionar agentes personalizados para ações recomendadas.

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

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

Arquitetura de integração

A integração do Agente de Ações Recomendadas utiliza um pipeline de processamento que recebe ações em bruto dos agentes de origem, classifica-as com recurso a um motor de pontuação UICE (Urgency, Impact, Confidence, Effort) e apresenta os resultados priorizados no carrossel do vendedor.

O pipeline de processamento funciona da seguinte forma:

  1. O agente personalizado deteta uma informação útil para ação (por exemplo, um negócio em risco, um negócio estagnado ou uma parte interessada em falta).
  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 de entidade do Dataverse.
    • Obtém dados de priorização específicos do agente do catálogo de ações.
    • Chama o LLM para pontuar a ação nas dimensões UICE (Urgência, Impacto, Confiança, Esforço).
    • Aplica os limites 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 Carrossel de Agentes de Ações Recomendadas recupera ações pontuadas e renderiza cartas.

Componentes-chave

A integração baseia-se nas seguintes tabelas e APIs do Dataverse.

Componente Location Description
Tabela de entrada msdyn_rawactioncatalogue (Dataverse) Ações brutas que os agentes personalizados promovem
Tabela de saída msdyn_prioritizedactioncatalogue (Dataverse) Ações pontuadas e classificadas para a interface
Configuração do agente msdyn_recommendedactionsourceagentconfig (Dataverse) Registo e configuração por agente
Push API msdyn_PushActionDataToRecommendedActionAgent (API personalizada) Agente → Ações recomendadas Envio da ação do agente

Registo de agentes

Registe agentes personalizados junto do Agente de Ações Recomendadas para que a plataforma reconheça e obtenha as respetivas ações. Para mais informações sobre o registo de agentes, consulte Adicionar agentes personalizados para ações recomendadas.

Quando regista um agente, é criada uma entrada em msdyn_recommendedactionsourceagentconfig. O SourceAgentId exclusivo identifica a entrada para o 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 povoar são msdyn_internalprioritizationinstruction e msdyn_syncactionexecutionstateapiconfig.

Pode aplicar a configuração atualizando manualmente o registo da tabela ou chamando a API UpsertRecommendationAgentConfigRequestpersonalizada .

Esquema de UpsertRecommendationAgentConfigRequest

O exemplo seguinte 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"
}
Campo JSON Tipo Description
nome_agente cadeia (de caracteres) Mapas para msdyn_agentname (máximo 850 personagens). Obrigatório para novos registos.
agentType cadeia (de caracteres) Categoria de agente. Use "CustomAgent" para agentes que não sejam Agentes de Oportunidades de Vendas para criar automaticamente um perfil.
isRecommendedActionAgentEnabled booleano Mapas para msdyn_isrecommendedactionagentenabled. Nulo = deixar inalterado.
salesAgentProfileId Guid? Ligações para msdyn_salesagentprofile. Usado para pesquisa de registos no upsert.
agentImpactMapping cadeia (de caracteres) Array JSON plano de nomes principais. Mapas para msdyn_agentimpactmapping.
Instrução de priorização interna cadeia (de caracteres) JSON com matriz de sinais. Mapas para msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig cadeia (de caracteres) JSON objeto {"syncactionuistatusapiname":"..."}. Mapas para msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId cadeia (de caracteres) Mapas para msdyn_sourceagentuniqueid.
description cadeia (de caracteres) Mapas para msdyn_sourcedescription (máximo 1000 caracteres).

Instrução interna de priorização

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

Campo Tipo Description
Nome cadeia (de caracteres) Identificador do sinal — utilizado como chave na secção Referência do Sinal da instrução de pontuação
tipo cadeia (de caracteres) Tipo de dados: "string", "number", "boolean"
origem cadeia (de caracteres) Rótulo descritivo para a origem do sinal. Não é usado para roteamento — fetch_info.fetch_type controla o mecanismo real de busca. Normalmente, utiliza-se "action_data" para sinais enviados pelo agente.
dimensão_influência {dimensão: força} Que dimensões da UICE este sinal afetam e com que intensidade. Chaves: "urgência", "impacto", "confiança", "esforço". Pontos fortes: "forte", "moderado", "fraco"
Interpretação cadeia (de caracteres) Descrição em linguagem natural do que o sinal significa para a pontuação — injetada no prompt do LLM
fiabilidade cadeia (de caracteres) Quão fiável é este sinal: "alto", "médio", "baixo"
required booleano Se o sinal deve estar presente para a pontuação
fetch_info objecto Controla onde e como o valor do sinal é recuperado no momento da pontuação.

Exemplos 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 para o estado de execução da ação de sincronização

A API config do estado de execução da ação de sincronização é um objeto JSON que especifica o nome personalizado da API que o Agente de Ações Recomendadas chama quando um vendedor atua num cartão (por exemplo, marca-o como completo ou irrelevante). Esta API define o estado da ação no agente personalizado de origem.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Contrato de envio de ação

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

Parâmetros de solicitação

Parâmetro Tipo Obrigatório Description
msdyn_ActionId cadeia (de caracteres) Sim Identificador único do agente para esta ação. Usado para deduplicação e sincronização de estado. Deve ser determinístico (mesma ação = mesmo ID). Formato de exemplo: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId cadeia (de caracteres) Sim Identificador do agente. Tem de corresponder à msdyn_agentname no registo de configuração do agente. Exemplo: "Agente de Fecho de Negócio"
msdyn_TargetEntityId identificador único (GUID) Sim o GUID do registo de destino (Opportunity, Lead) a que esta ação diz respeito
msdyn_TargetEntityTypeName cadeia (de caracteres) Sim Nome lógico da entidade-alvo. Exemplo: "oportunidade", "liderar"
msdyn_ActionReason cadeia (de caracteres) Sim Razão pela qual a ação foi gerada. Usado pelo motor de pontuação para o mapeamento de princípios.
msdyn_ActionUIPayload cadeia (de caracteres) No Carga útil JSON para renderização de cartões. Se for omitido, o Agente de Ações Recomendadas não pode mostrar o cartão.
msdyn_ActionPrioritizationData cadeia (de caracteres) No JSON com dados específicos do agente para pontuação
msdyn_ActionCTA cadeia (de caracteres) No Tipo de string CTA. Exemplo: "Email", "Revisão", "Chamada"
msdyn_PrioritizationPrinciples cadeia (de caracteres) No Array JSON de princípios de priorização aos quais esta ação específica está associada (pode substituir o mapeamento definido ao nível do agente)

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 de carga útil de UI de ação

O campo msdyn_ActionUIPayload contém conteúdo JSON que controla como um cartão de ação é apresentado no carrossel do Agente de Ações 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 dados de priorização

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

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

O motor de pontuação lê estes sinais juntamente com os sinais ao nível da entidade (valor do negócio, etapa, concorrentes, etc.). O msdyn_internalprioritizationinstruction na configuração do agente indica ao LLM como interpretar cada sinal, e o motor de pontuação combina todos os sinais no prompt de pontuação da UICE.

Versionamento de ações e invalidação

Quando um agente atualiza dados de uma ação previamente enviada, cria um novo registo com a mesma msdyn_ActionId ao ligar 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 a mostrar 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. Esta ação marca todos os registos msdyn_rawactioncatalogue relativos a essa ação como inativos e o cartão desaparece do carrossel.

Sincronização de estados bidirecionais

O estado da ação sincroniza-se tanto no carrossel do Agente de Ações Recomendadas como no seu agente personalizado para garantir que os vendedores vejam informação consistente, independentemente de onde atuem numa ação.
Agente de Ações Recomendadas → agente personalizado (o vendedor age no carrossel): Quando um vendedor marca uma ação como Concluída ou Ignorada 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:
Parâmetro Tipo Description
actionid GUID O identificador da ação
state cadeia (de caracteres) "Marcado como concluído" ou "Ignorado"

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

Agente personalizado → Agente de Ações Recomendadas (o vendedor atua na IU do agente): Quando um vendedor executa uma ação sobre uma ação na própria IU do agente (por exemplo, marca-a como mitigada numa página de agente personalizado), o agente sincroniza esse estado com o Agente de Ações Recomendadas ao chamar msdyn_SyncActionExecutionStateFromAgent. Esta ação atualiza o estado na tabela de saída do Agente de Ações Recomendadas, fazendo com que deixe de aparecer no carrossel.

Parâmetro Tipo Obrigatório Description
msdyn_ActionId cadeia (de caracteres) Sim O identificador da ação (o mesmo que foi enviado)
msdyn_ActionState número inteiro Sim Novo estado — valores (associados a MarkAsDone/Dismissed)
msdyn_TargetEntityId uniqueidentifier Sim GUID da entidade-alvo
NomeDoTipoDeEntidadeDeDestino cadeia (de caracteres) Sim Nome lógico da entidade-alvo
msdyn_TrackingId cadeia (de caracteres) No ID opcional de rastreio/correlação

Testes e validação

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

Verificar 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

Faça uma ação de teste ao chamar msdyn_PushActionDataToRecommendedActionAgent e verifique se msdyn_IsSuccess é verdadeira e que aparece um novo registo em msdyn_rawactioncatalogue.

Acione o cálculo da pontuação quando necessário ao chamar msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (em vez de esperar pelo temporizador de 4 horas).

Verificar resultado pontuado:

    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 é preenchida com um valor na gama 0–10.
  • msdyn_hascrossedfloor é falso (a ação está acima do chão e nota-se no carrossel).
  • msdyn_actionuistatus é 1 (Ativo).
  • msdyn_scoredetails contém a explicação gerada pelo LLM.

Verifique a exibição do carrossel abrindo um formulário de Oportunidade no Dynamics 365 Sales e verificando a secção de Ações Sugeridas. Verifique a sincronização do estado descartando uma ação no carrossel (a API de sincronização de retorno deve ser chamada com state = "Dismissed") e assinalando uma ação na interface do agente (o registo 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 no Agente de Ações Recomendadas, e a sua integração serve como implementação de referência.

Valores de configuração do agente:

Campo de Configuração Valor do Agente de Oportunidades de Venda (de OraDefaults.cs)
msdyn_agentname "AgenteDeOportunidade de Vendas"
msdyn_agentimpactmapping ["DealRisk", "Velocidade do negócio"]
msdyn_syncactionexecutionstateapiconfig {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction Veja o valor de produção do Agente de Oportunidade de Vendas

Quando a pesquisa do Agente de Oportunidades de Vendas conclui e identifica os riscos do negócio, DealRiskToNBAService encaminha cada risco como uma ação separada:

Parâmetro push Valor para Agentes de Oportunidades de Vendas
msdyn_ActionId DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId DealRiskAgent
msdyn_TargetEntityTypeName "Oportunidade"
msdyn_ActionReason Descrição do risco a partir da investigação
msdyn_ActionUIPayload Cartão com cabeçalho de risco + descrição
msdyn_ActionPrioritizationData {"riskType":"8","risk":"Missing BANT Info"} (exemplo)

Comportamento da sincronização de estado:

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