Integruj niestandardowych agentów z Agentem Zalecanych Działań

Agent Zalecanych Działań w Dynamics 365 Sales prezentuje priorytetowe rekomendacje dotyczące możliwości, leadów, kont i kontaktów. Zapewnia wspólny mechanizm oceniania, kontrakty danych oraz dwukierunkową synchronizację stanu, dzięki czemu każdy niestandardowy agent może prezentować rekomendacje obok agentów natywnych.

Ten artykuł opisuje architekturę, kluczowe komponenty, kontrakty danych oraz przepływ integracji używany podczas integracji niestandardowego agenta z agentem Zalecanych Działań. Zapewnia podstawową wiedzę niezbędną do wdrożenia integracji.

Wymagania wstępne

  • Rozwiązanie NextBestActionAgent wdrożone w organizacji docelowej. Więcej informacji można znaleźć w artykule Import agenta do środowiska docelowego.

  • Stabilny, unikalny ciąg SourceAgentId dla niestandardowego agenta. Aby uzyskać więcej informacji, zobacz Dodawanie niestandardowych agentów dla zalecanych akcji.

  • Do wykonywania zalecanych działań wymagane są następujące uprawnienia:

    Tabela Wymagane uprawnienia Scope
    msdyn_rawactioncatalogue Odczyt, zapis, dołączanie i dołączanie do Global
    msdyn_prioritizedactioncatalogue Odczyt, zapis, dołączanie i dołączanie do Global
    msdyn_recommendedactionsourceagentconfig Read Global
    msdyn_salesagentprofile Read Global

Architektura integracji

Integracja z Agentem Zalecanych Działań wykorzystuje pipeline przetwarzający, który pobiera surowe działania od agentów źródłowych, ocenia je za pomocą silnika punktacji UICE (Urgency, Impact, Confidence, Effort) oraz wyświetla priorytetowe wyniki w karuzeli sprzedawcy.

Potok przetwarzania działa następująco:

  1. Agent niestandardowy wykrywa praktyczne szczegółowe informacje (na przykład ryzyko dotyczące transakcji, zablokowaną transakcję lub brak interesariusza).
  2. Niestandardowy agent wywołuje niestandardowe msdyn_PushActionDataToRecommendedActionAgent API, aby przesłać akcję.
  3. Akcja jest przechowywana w msdyn_rawactioncatalogue (tabeli wejściowej).
  4. Dla każdej akcji Silnik Punktacji:
    • Pobiera sygnały encji z platformy Dataverse.
    • Pobiera dane priorytetyzacji specyficzne dla agenta z katalogu akcji.
    • Wzywa LLM, aby ocenić działania na podstawie wymiarów UICE (Pilność, Wpływ, Pewność, Wysiłek).
    • Stosuje zasady podłogi i sufitu.
    • Oblicza ostateczny wynik priorytetu, używając GetRecommendedActionAgentResponse.
  5. Oceniona akcja jest wstawiana do msdyn_prioritizedactioncatalogue (tabeli wyjściowej).
  6. Karuzela Zalecanych Akcji pobiera punktowane akcje i renderuje karty w widoku listy podmiotu, pod warunkiem, że karuzela jest aktywowana dla tej jednostki.

Najważniejsze składniki

Integracja opiera się na następujących tabelach i API Dataverse.

Składnik Lokalizacja Description
Tabela wejściowa msdyn_rawactioncatalogue (Dataverse) Pierwotne akcje, które wypychają agenty niestandardowe
Tabela danych wyjściowych msdyn_prioritizedactioncatalogue (Dataverse) Oceniane i sklasyfikowane akcje dla interfejsu użytkownika
Konfiguracja agenta msdyn_recommendedactionsourceagentconfig (Dataverse) Rejestracja i konfiguracja poszczególnych agentów
Push API msdyn_PushActionDataToRecommendedActionAgent (niestandardowy interfejs API) Agent → Zalecane działania — wypychanie akcji agenta

Rejestracja agenta

Zarejestruj niestandardowych agentów w Agencie Zalecanych Akcji, aby platforma rozpoznawała i pobierała ich działania. Więcej informacji o rejestrowaniu agentów można znaleźć w artykule Dodawanie agentów niestandardowych dla zalecanych akcji.

Gdy rejestrujesz agenta, tworzy on wpis w msdyn_recommendedactionsourceagentconfig. Unikalny SourceAgentId identyfikuje wpis dla niestandardowego agenta.

Konfiguracja agenta

Tabela msdyn_recommendedactionsourceagentconfig zawiera konfigurację dla agenta, która reguluje, jak Agent Zalecanych Działań interpretuje działania agenta. Dwa najważniejsze pola do wypełnienia to msdyn_internalprioritizationinstruction i msdyn_syncactionexecutionstateapiconfig.

Możesz zastosować konfigurację, ręcznie aktualizując rekord tabeli lub wywołując niestandardowe API UpsertRecommendationAgentConfigRequest.

UpsertRecommendationAgentConfigRequest schema

Poniższy przykład pokazuje dostępne pola konfiguracyjne w schemacie.

{
  "agentName": "YourAgentName",
  "agentType": "CustomAgent",
  "isRecommendedActionAgentEnabled": true,
  "salesAgentProfileId": "<SourceAgentId that was configured>",
  "agentImpactMapping": "[]",
  "internalPrioritizationInstruction": "{\"signals\":[...]}",
  "syncActionExecutionStateApiConfig": "{\"syncactionuistatusapiname\":\"your_SyncBackCustomApiName\"}",
  "description": "Brief description of your agent"
}
Pole JSON Typ Description
nazwa_agenta ciąg Mapy na msdyn_agentname (maksymalnie 850 postaci). Wymagane dla nowych rekordów.
typ agenta ciąg Kategoria agenta. Użyj "CustomAgent", aby automatycznie utworzyć profil.
czyAgentZalecanychAkcjiJestWłączony wartość logiczna Mapuje do msdyn_isrecommendedactionagentenabled. null = pozostaw bez zmian.
salesAgentProfileId Identyfikator GUID? Łącza do msdyn_salesagentprofile. Służy do wyszukiwania rekordów w operacji upsert.
agentImpactMapping ciąg Tablica płaska JSON z nazwami zasad. Mapuje do msdyn_agentimpactmapping.
internalPrioritizationInstruction ciąg JSON z układem sygnałów. Mapuje do msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig ciąg Obiekt JSON {"syncactionuistatusapiname":"..."}. Mapuje do msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId ciąg Mapuje do msdyn_sourceagentuniqueid.
description ciąg Mapy do msdyn_sourcedescription (maksymalnie 1000 postaci).

Instrukcja priorytetyzacji wewnętrznej

Wewnętrzna instrukcja priorytetyzacji zawiera metadane sygnału specyficzne dla agenta, które informują silnik punktacji, jak interpretować pola danych priorytetyzacyjnych agenta. To obiekt JSON z tablicą najwyższego poziomu signals . Każdy sygnał jest deserializowany do AgentSignalInstructionConfig z następującymi polami:

Pole Typ Description
nazwa ciąg Identyfikator sygnału — używany jako klucz w sekcji Sygnał Referencyjny w promptie punktacji
typ ciąg Typ danych: "string", "number", "boolean"
przesłać źródło ciąg Etykieta opisowa miejsca, z którego pochodzi sygnał. Nie używany do routingu — fetch_info.fetch_type kontroluje faktyczny mechanizm pobierania. Zazwyczaj „action_data” dla sygnałów przesyłanych przez agentów.
wpływ_wymiaru {wymiar: wytrzymałość} Na które wymiary UICE wpływa ten sygnał i w jakim stopniu. Klucze: "pilność", "wpływ", "pewność", "wysiłek". Mocne strony: "silny", "umiarkowany", "słaby"
interpretacja ciąg Opis w języku naturalnym opisujący, co sygnał oznacza dla oceny — wstawiany do promptu LLM
niezawodność ciąg Jak wiarygodny jest ten sygnał: "wysoki", "średni", "niski"
required wartość logiczna Czy sygnał musi być obecny do oceniania
fetch_info obiekt Określa, gdzie i jak jest pobierana wartość sygnału w czasie oceniania.

Przykładowy blok sygnałów:

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

Konfiguracja interfejsu API stanu wykonywania akcji synchronizacji

Konfiguracja interfejsu API stanu wykonania akcji synchronizacji to obiekt JSON, który określa nazwę niestandardowego interfejsu API wywoływanego przez agenta zalecanych działań, gdy sprzedawca podejmuje działanie dotyczące karty (na przykład oznacza ją jako ukończoną lub nieistotną). Ten interfejs API ustawia stan akcji w źródłowym agencie niestandardowym.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Kontrakt dotyczący wypychania akcji

Agenty niestandardowe wypychają akcje, korzystając z niestandardowego interfejsu API msdyn_PushActionDataToRecommendedActionAgent. API jest wywoływane za każdym razem, gdy agent generuje lub aktualizuje akcję dla jednostki docelowej.

Parametry żądania

Parametr Typ Wymagane Description
msdyn_ActionId ciąg Yes Unikalny identyfikator agenta przypisany do tej akcji. Służy do deduplikacji i synchronizacji stanu. Musi być deterministyczny (ta sama akcja = ten sam identyfikator). Przykładowy format: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId ciąg Yes Identyfikator agenta. Musi odpowiadać wartości msdyn_agentname w rekordzie konfiguracji agenta. Przykład: "DealClosingAgent"
msdyn_TargetEntityId uniqueidentifier (GUID) Yes GUID rekordu docelowego (Opportunity, Lead), którego dotyczy ta akcja
msdyn_TargetEntityTypeName ciąg Yes Nazwa logiczna jednostki docelowej. Przykład: „okazja”, „potencjalny klient”
msdyn_ActionReason ciąg Yes Przyczyna wygenerowania akcji. Używany przez silnik oceniania do mapowania zasad.
msdyn_ActionUIPayload ciąg No Ładunek danych JSON służący do renderowania kart. Jeśli zostanie pominięta, Agent Zalecanych Działań nie może wyświetlić karty.
msdyn_ActionPrioritizationData ciąg No JSON z danymi przypisanymi do agenta na potrzeby oceny
msdyn_ActionCTA ciąg No Ciąg typu CTA. Przykład: "Email", "Review", "Call"
msdyn_PrioritizationPrinciples ciąg No Tablica JSON zasad priorytetyzacji, którym przypisano to konkretne działanie (może zastąpić mapowanie na poziomie agenta)

Przykład: wywołanie wtyczki C#

Poniższy przykład polega na tworzeniu i wykonywaniu żądania wypychania akcji dotyczącej ryzyka transakcji do agenta zalecanych działań. Żądanie identyfikuje agenta źródłowego i docelową szansę sprzedaży, podaje powód oraz dane interfejsu użytkownika karty, zawiera sygnały ryzyka na potrzeby ustalania priorytetów i sprawdza, czy operacja zakończyła się powodzeniem.

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"];

Kontrakt dotyczący ładunku interfejsu użytkownika akcji

Pole msdyn_ActionUIPayload zawiera obiekt JSON, który określa, w jaki sposób karta akcji jest wyświetlana w karuzeli agenta Recommended Actions.

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

Kontrakt danych priorytetyzacyjnych

Pole msdyn_prioritizationdata umożliwia agentowi przekazywanie sygnałów specyficznych dla danego agenta, które wpływają na sposób, w jaki silnik punktacji UICE nadaje priorytet działaniu.

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

Silnik punktacji odczytuje te sygnały równolegle z sygnałami na poziomie podmiotów (wartość transakcji, etap, konkurenci itd.). Element msdyn_internalprioritizationinstruction w konfiguracji agenta informuje model LLM, jak interpretować każdy sygnał, a silnik oceniania łączy wszystkie sygnały w poleceniu oceniania UICE.

Aktywuj karuzelę Zalecanych Akcji, aby pojawiła się w widoku listy podmiotów. Encja aiinsightcard kontroluje stan aktywacji karuzeli dla każdej encji. Upewnij się, że odpowiadający aiinsightcard rekord dla podmiotu jest ustawiony na aktywny.

Poniższa tabela pokazuje wartości do ustawienia aktywacji lub dezaktywacji karuzeli dla danej jednostki:

Stan karty statecode statuscode
Aktywni 0 1
Nieaktywny 1 2

Wersjonowanie akcji i unieważnienie akcji

Gdy agent aktualizuje dane dla wcześniej wypchniętej akcji, tworzy nowy rekord z tym samym identyfikatorem msdyn_ActionId, wywołując ponownie element msdyn_PushActionDataToRecommendedActionAgent. System tworzy nowy wiersz w tabeli msdyn_rawactioncatalogue z tym samym identyfikatorem msdyn_actionid, ale z nowym identyfikatorem msdyn_rawactioncatalogueid. Agent Zalecanych Akcji pokazuje starą wersję, dopóki nie przetworzy nowej.

Aby unieważnić akcję (na przykład gdy ryzyko zostanie rozwiązane), agent wywołuje niestandardowy interfejs API msdyn_RAAgent_RemoveActionsV2 za pomocą actionId. Ta akcja oznacza wszystkie msdyn_rawactioncatalogue zapisy tej akcji jako nieaktywne, a karta znika z karuzeli.

Dwukierunkowa synchronizacja stanów

Stan działania jest synchronizowany zarówno w karuzeli Agenta rekomendowanych działań, jak i w twoim agencie niestandardowym, aby zapewnić sprzedawcom spójne informacje niezależnie od miejsca, w którym podejmują dane działanie.
Zalecane działania Agent → agent niestandardowy (sprzedający działa w karuzeli): Gdy sprzedawca oznacza czynność jako Wykonaną lub Oddaloną w karuzeli:

  1. Agent zalecanych akcji aktualizuje element msdyn_actionuistatus w pliku msdyn_prioritizedactioncatalogue.
  2. Agent zalecanych działań odczytuje element msdyn_syncactionexecutionstateapiconfig z konfiguracji agenta.
  3. Agent zalecanych działań wywołuje niestandardowy interfejs API agenta z:
Parametr Typ Description
actionid GUID Identyfikator akcji
stan ciąg „Oznaczono jako ukończone” lub „Odrzucono”

Agent musi zaimplementować niestandardowe API, które akceptuje te dwa parametry i aktualizuje stan akcji w swoim własnym magazynie danych.

Agent niestandardowy → Agent zalecanych działań (sprzedawca działa w interfejsie użytkownika agenta): gdy sprzedawca podejmuje działania dotyczące akcji w interfejsie własnego agenta (na przykład oznacza je jako złagodzone na stronie agenta niestandardowego), agent synchronizuje ten stan z agentem zalecanych działań, wywołując element msdyn_SyncActionExecutionStateFromAgent. Ta akcja aktualizuje stan w tabeli wyjściowej agenta zalecanych działań, przez co nie jest on wyświetlany w karuzeli.

Parametr Typ Wymagane Description
msdyn_ActionId ciąg Yes Identyfikator akcji (taki sam jak wypchnięty)
msdyn_ActionState liczba całkowita Yes Nowy stan — wartości (przypisane do MarkAsDone/Dismissed)
msdyn_TargetEntityId uniqueidentifier Yes Identyfikator GUID encji docelowej
TargetEntityTypeName ciąg Yes Nazwa logiczna jednostki docelowej
msdyn_TrackingId ciąg No Opcjonalne śledzenie/identyfikator korelacji

Testowanie i walidacja

Po konfiguracji i wdrożeniu zweryfikowaj przepływ end-to-end, wykonując następujące kontrole.

Weryfikacja konfiguracji agenta:

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

Uruchom akcję testową, wywołując msdyn_PushActionDataToRecommendedActionAgent, i sprawdź, czy msdyn_IsSuccess ma wartość true oraz czy w msdyn_rawactioncatalogue pojawia się nowy rekord.

Uruchom ocenianie na żądanie, wywołując msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (zamiast czekać na upływ 4-godzinnego licznika czasu).

Zweryfikuj ocenione wyniki:

    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

Oczekiwane wartości:

  • msdyn_actionscore parametr jest wypełniany wartością w zakresie od 0 do 10.
  • msdyn_hascrossedfloor jest fałszywy (akcja jest powyżej podłogi i widoczna jest na karuzeli).
  • msdyn_actionuistatus jest 1 (aktywny).
  • msdyn_scoredetails zawiera wyjaśnienie wygenerowane przez moduł LLM.

Zweryfikowaj wyświetlanie karuzeli, otwierając formularz Opportunity w Dynamics 365 Sales i sprawdzając sekcję Sugerowanych Akcji. Zweryfikuj synchronizację stanu, odrzucając akcję w karuzeli (interfejs API synchronizacji zwrotnej powinien zostać wywołany z state = "Dismissed") oraz oznaczając akcję w interfejsie agenta (rekord w tabeli wyjściowej powinien odzwierciedlać zaktualizowaną msdyn_actionuistatus).

Przykład: Agent ds. Szans Sprzedaży

Agent Szans Sprzedaży jest pierwszym agentem dołączonym do Agenta Zalecanych Akcji, a jego integracja stanowi implementację referencyjną.

Wartości konfiguracji agenta:

Pole konfiguracji Wartość agenta szansy sprzedaży (z OraDefaults.cs)
msdyn_agentname SalesOpportunityAgent
msdyn_agentimpactmapping ["DealRisk", "Tempo transakcji"]
msdyn_syncactionexecutionstateapiconfig {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction Zobacz wartość produkcyjną agenta szans sprzedaży

Gdy analiza przeprowadzana przez agenta szans sprzedaży zostanie zakończona i zidentyfikuje zagrożenia transakcji, usługa DealRiskToNBAService przekaże każde ryzyko jako oddzielną akcję:

Parametr push Wartość agenta szansy sprzedaży
msdyn_ActionId DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId DealRiskAgent
msdyn_TargetEntityTypeName Szansa
msdyn_ActionReason Opis ryzyka z badań
msdyn_ActionUIPayload Karta z nagłówkiem ryzyka i opisem
msdyn_ActionPrioritizationData {"riskType":"8","risk":"Missing BANT Info"} (przykład)

Działanie synchronizacji stanu:

  • Agent szans sprzedaży → Agent zalecanych działań: gdy sprzedający oznacza ryzyko zgodnie ze stroną badań, agent wywołuje element msdyn_SyncActionExecutionStateFromAgent.
  • Agent zalecanych działań → Agent szans sprzedaży: Gdy sprzedawca odrzuca kartę w karuzeli, agent zalecanych działań wywołuje ora_UpdatedActionStateFromRAAgent (zgodnie z konfiguracją agenta).
  • Ostatnia aktualizacja o