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.

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

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:

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

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

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:

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:

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.

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:

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ę:

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).

Informacje pokrewne

• Konfiguruj agenta Zalecanych Akcji
• Omówienie zalecanych akcji