トピックとエージェントアクションの API プロジェクトを有効化

MuleSoft for Agentforce: Topic Center (Topic Center とも呼ばれる) を使用してトピックとエージェントの API 仕様を有効にし、Salesforce の API カタログに同期できるようにします。その後、エージェントビルダーで Agentforce エージェントにトピックを割り当てることで、エージェントの機能を拡張できます。

Topic Center ビジュアルエディターを使用して、次の操作を実行できます。

トピックとエージェントの API 仕様を有効にする。
ガバナンスルールを適用して、API が Salesforce でエージェントアクションとトピックを生成する準備ができていることを検証する。
メタデータを追加して、Salesforce API カタログを使用してトピックとアクション対応 API を Salesforce で利用できるようにする。

トピックは、Agentforce エージェントがタスクを完了するために使用するアクションと手順セットのバンドルです。アクションはエージェントが実行できるタスクであり、手順はエージェントがアクションの使用方法を理解するのに役立ちます。

Topic Center では、API 操作をエージェントアクションとトピックとして使用できます。エージェントは、レコードの更新、データの検索と要約、さまざまなシステムでの安全なアクションの実行など、一般的なタスクを独立して実行します。エージェントは任意のトピックセットで再利用可能で、複数のトピックを含めることができます。

始める前に

Anypoint Platform 組織と、エージェントエンタイトルメントのある信頼済み Salesforce 組織との間にテナントリレーションを確立します。
接続された Salesforce 組織に対して API カタログが有効化されていることを確認します。
必要な権限があることを確認します。
- ユーザーがアセットのダウンロードとパブリッシュをできるようにするための Anypoint Exchange 権限
  - Viewer (閲覧者)
  - Creator (作成者)
- アプリケーションのデプロイなど、CloudHub および CloudHub 2.0 に関連するサービスを有効にするための Runtime Manager 権限
  - Read applications (アプリケーションの参照)
  - Create applications (アプリケーションの作成)
  - Delete applications (アプリケーションの削除)
- ユーザーが API の作成と表示をできるようにするための「Design Center Developer (Design Center 開発者)」権限。
Anypoint Platform → API Governance で、バージョン別の API の管理にオプトインします。
Web またはデスクトップ IDE をセットアップしてアクセスします。
API 仕様の設計の基礎を理解します。

詳細は、チュートリアルを参照してください。
ビジネスグループに精通します。

エージェントアクションとトピックの API 仕様プロジェクトを作成する

IDE のアクティビティバーで、 (Anypoint Code Builder) アイコンをクリックします。
[Quick Actions (クイックアクション)] から [Design an API (API を設計)] をクリックします。
[Enable this API for Agent Topics and Actions (エージェントトピックとアクションに対してこの API を有効化)] を選択します。

[API Specification (API 仕様)] フォームに入力します。

項目名項目値

Project Name (プロジェクト名)

プロジェクトの一意の名前。

この名前は Exchange での API 仕様のタイトル、仕様ファイルの名前、プロジェクトのルートディレクトリの名前として使用されます。たとえば、プロジェクト名が「Agent Example」 (エージェントの例) の場合、仕様ファイル名は agent-example になります。

既存のプロジェクト名を再利用するには、その名前をすでに使用しているプロジェクトを最初に削除する必要があります。API 仕様とフラグメントの削除を参照してください。

Project Location (プロジェクトの場所)

ホームディレクトリまたは作成する別のディレクトリ。

ホームディレクトリへのフォルダーの追加を参照してください。

別のプロジェクトディレクトリ内にプロジェクトを作成しないでください。

API Type (API 種別)

[REST API] を選択します。

API Specification Language (API 仕様言語)

[OAS 3.0 (YAML)] または [OAS 3.0 (JSON)] を選択します。

トピックとアクションでは OAS 3.0 のみがサポートされます。

Business Group (ビジネスグループ)

API が属するビジネスグループを選択します。API Governance および中央管理ルールセットの同期にはビジネスグループが必要です。API 仕様を Anypoint Code Builder から Exchange にパブリッシュすると、IDE でビジネスグループの名前が要求されます。

[Create Project (プロジェクトを作成)] をクリックします。

確認を促されたら、フォルダー内のファイルの作成者を信頼します。

[Agent Topics (エージェントトピック)] 設定パネルが開きます。
[Agent Topics (エージェントトピック)] 設定パネルで、エージェントトピックのメタデータと手順を設定し、[Apply (適用)] をクリックします。
引き続き API 仕様を設計します。

要素を入力するときに、オートコンプリート (または Ctrl+Space) を使用すると、コンテキスト内で使用可能なオプションが表示されます。

API プロジェクトにメタデータを追加する

[Explorer] で、API 仕様を右クリックし、[Open API Project Properties (API プロジェクトプロパティを開く)] を選択します。

[API Project Properties (API プロジェクトプロパティ)] タブが開き、次の項目が自動的に入力されます。
- Asset version (アセットバージョン)
  
  API プロジェクトのアセットバージョンは、セマンティックバージョン設定モデルに従う必要があります。詳細は、「アセットバージョン」を参照してください。
- API Version (API バージョン)
  
  API のメジャーバージョン。
- Business Group (ビジネスグループ)
  
  この API が使用可能になる Anypoint Platform ビジネスグループを選択します。
- Asset ID (アセット ID)
- Asset Name (アセット名)
- Tags (タグ)
- Categories (カテゴリ)
  
  これらのプロパティは、API 仕様を Exchange にパブリッシュするときに使用されます。
  
  タグとカテゴリは、ユーザーが Anypoint Exchange を検索するときに検索結果を絞り込むのに役立ちます。
  
  エージェントアクションとトピックの API を有効にすると、sf-api-catalog タグと sf-api-topic タグが自動的に適用されます。
  
  どの項目も編集できます。
API プロジェクトプロパティに変更を加えた場合は、[Apply (適用)] をクリックします。

トピックを設定する

[Agent Topics (エージェントトピック)] 設定パネルでトピックを設定します。

[Agent Topics (エージェントトピック)] 設定パネルがまだ開いていない場合は、[#] アイコンをクリックして開きます。

トピックの次の項目を設定します。

項目名	説明	例
Topic Label (トピックの表示ラベル)	トピックの一意の名前を入力します。	営業エージェント
Classification Description (分類の説明)	1 ～ 3 個のプレーンテキスト文を入力します。エージェントはこの説明を使用して、会話でトピックをいつ使用するかを決定します。ユーザーがメッセージを入力すると、エージェントはユーザーのインテントを識別し、トピック名および分類の説明を比較して、最も一致するトピックを使用します。	分類の説明のいくつかの例を次に示します。ビジネスポリシー、手順、または商品に関する質問に答えます。ユーザーとやり取りしてコンテンツのドラフト作成や修正を行います。ユーザーの注文状況、返品状況、返品に関する質問に答えます。
Scope (スコープ)	スコープは、特定のトピックに対してエージェントができることとできないことを正確に定義します。スコープは、トピックに含める必要があるジョブやスコープの範囲外でエージェントが応答しないように制限できるため、特定のトピックに対してエージェントのジョブを詳細に定義する場合に最も効果的です。	スコープの説明のいくつかの例を次に示します。あなたの役割は、商談を成立させるための商談成立戦略の設定に関連するタスクのみを処理することです。これには、商品関連の価格設定に関する質問への回答、会話に基づく顧客のセンチメントに関するユーザーへのブリーフィング、ユーザーが商談を成立させるために役立つ商談成立プランの提案、ビデオ通話や音声通話に基づくアドバイスの提供などが含まれます。あなたの役割は、ユーザーの予約に関する質問に対して情報を提供すること、および予約確認メールを再送信して今後の予約や既存の予約の変更を処理することのみです。新規予約を行うことはできません。
Instructions (手順)	プレーンテキストの手順は、エージェントがさまざまなユースケースでトピック内のアクションをどのように使用するか決定するのに役立ちます。各手順は 1 つのトピック固有のガイドラインであり、通常は「常に…」、「決して…」、「x の場合は y…」、「最初のステップとして、…」などで表されます。手順は非確定的であるため、機密性が高いか、確定的なビジネスルールは含めないでください。	手順のいくつかの例を次に示します。 [ナレッジを使用して質問に回答] 機能を使用してトラブルシューティング情報を取得する前に、常にモバイルデバイスの種別 (iOS または Android) を明確にします。決してユーザーに ID を尋ねないでください。代わりに、レコードの名前を使用するか、レコードの名前を尋ねて、IdentifyRecordByName を使用して ID を取得し、他のアクションをコールします。ユーザーから注文の状況や注文確認について質問があった場合は、注文番号またはメールアドレスを持っているかどうかを尋ねます。ユーザーがメールアドレスまたは注文番号を持っていない場合は、エージェントにエスカレーションするかケースを作成するかを尋ねます。

項目名

説明

例

Topic Label (トピックの表示ラベル)

トピックの一意の名前を入力します。

営業エージェント

Classification Description (分類の説明)

1 ～ 3 個のプレーンテキスト文を入力します。エージェントはこの説明を使用して、会話でトピックをいつ使用するかを決定します。ユーザーがメッセージを入力すると、エージェントはユーザーのインテントを識別し、トピック名および分類の説明を比較して、最も一致するトピックを使用します。

分類の説明のいくつかの例を次に示します。

ビジネスポリシー、手順、または商品に関する質問に答えます。

ユーザーとやり取りしてコンテンツのドラフト作成や修正を行います。

ユーザーの注文状況、返品状況、返品に関する質問に答えます。

Scope (スコープ)

スコープは、特定のトピックに対してエージェントができることとできないことを正確に定義します。スコープは、トピックに含める必要があるジョブやスコープの範囲外でエージェントが応答しないように制限できるため、特定のトピックに対してエージェントのジョブを詳細に定義する場合に最も効果的です。

スコープの説明のいくつかの例を次に示します。

あなたの役割は、商談を成立させるための商談成立戦略の設定に関連するタスクのみを処理することです。これには、商品関連の価格設定に関する質問への回答、会話に基づく顧客のセンチメントに関するユーザーへのブリーフィング、ユーザーが商談を成立させるために役立つ商談成立プランの提案、ビデオ通話や音声通話に基づくアドバイスの提供などが含まれます。

あなたの役割は、ユーザーの予約に関する質問に対して情報を提供すること、および予約確認メールを再送信して今後の予約や既存の予約の変更を処理することのみです。新規予約を行うことはできません。

Instructions (手順)

プレーンテキストの手順は、エージェントがさまざまなユースケースでトピック内のアクションをどのように使用するか決定するのに役立ちます。各手順は 1 つのトピック固有のガイドラインであり、通常は「常に…」、「決して…」、「x の場合は y…」、「最初のステップとして、…」などで表されます。

手順は非確定的であるため、機密性が高いか、確定的なビジネスルールは含めないでください。

手順のいくつかの例を次に示します。

[ナレッジを使用して質問に回答] 機能を使用してトラブルシューティング情報を取得する前に、常にモバイルデバイスの種別 (iOS または Android) を明確にします。

決してユーザーに ID を尋ねないでください。代わりに、レコードの名前を使用するか、レコードの名前を尋ねて、IdentifyRecordByName を使用して ID を取得し、他のアクションをコールします。

ユーザーから注文の状況や注文確認について質問があった場合は、注文番号またはメールアドレスを持っているかどうかを尋ねます。ユーザーがメールアドレスまたは注文番号を持っていない場合は、エージェントにエスカレーションするかケースを作成するかを尋ねます。

アクションを設定する

必要なメタデータを定義するスキーマを使用して、エージェントアクションを作成します。要素を入力するときに、オートコンプリート (または Ctrl+Space) を使用すると、コンテキスト内で使用可能なオプションが表示されます。

エージェントトピックとアクションの API を有効にするには、エージェントとして使用する操作の少なくとも 1 つに x-sfdc/agent/action/publishAsAgentAction のアノテーションを追加し、値を true に設定する必要があります。

エクステンション説明デフォルト値

エクステンション	説明	デフォルト値
x-sfdc/agent/action/publishAsAgentAction	必須。操作をアクションとして有効にするには、この属性を `true` に設定します。	false
x-sfdc/privacy/isPii	省略可能。この属性を `true` に設定すると、その操作で送信されたクエリの PII サービスが有効になります。	false
x-sfdc/agent/action/isUserInput	必須。この属性を `true` に設定すると、ユーザーがさらに入力できる項目が表示されます。	false
x-sfdc/agent/action/isDisplayable	必須。項目をユーザーに表示できるようにするには、この属性を `true` に設定します。	false

x-sfdc/agent/action/publishAsAgentAction

必須。操作をアクションとして有効にするには、この属性を true に設定します。

false

x-sfdc/privacy/isPii

省略可能。この属性を true に設定すると、その操作で送信されたクエリの PII サービスが有効になります。

false

x-sfdc/agent/action/isUserInput

必須。この属性を true に設定すると、ユーザーがさらに入力できる項目が表示されます。

false

x-sfdc/agent/action/isDisplayable

必須。項目をユーザーに表示できるようにするには、この属性を true に設定します。

false

$ref を使用して定義されたスキーマでのエージェントメタデータの追加はサポートされていません。メタデータはスキーマ内で定義する必要があります。次に例を示します。

... (Inside response, request body, etc..)
schema:
  $ref: '#/components/schemas/Pet'

...

components:
  schemas:
    Pet:
      x-sfdc:
        agent:
            action:
                isDisplayable: true
      required:
        - name
        - photoUrls
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold

トピックとエージェントのガバナンスルールセット

API が Salesforce でエージェントアクションとトピックを生成する準備ができていることを確認するために、[SF API Topic and Action Enablement (SF API トピックとアクションの有効化)] 中央管理ルールセットがトピック対応 API プロジェクトに自動的に追加されます。

必要に応じて、プロジェクトに必要なその他のルールセットを追加します。
ガバナンスルールセットを検証します。

API プロジェクトから sf-api-catalog タグと sf-api-topic タグを削除すると、トピックとアクションのルールセットも自動的に削除されます。

API 仕様を Exchange にパブリッシュする

API 仕様ルールセットを検証したら、API 仕様を Exchange にパブリッシュします。

API を Exchange にパブリッシュし、API Manager でアクティブな API インスタンスを作成したら、API カタログで使用できるようになります。詳細は、「API Catalog (API カタログ)」を参照してください。

トピックの API 仕様を無効にする

[Explorer] で、API 仕様を右クリックし、[Open API Project Properties (API プロジェクトプロパティを開く)] を選択します。
[Enable this API for Agent Topic and Actions (エージェントトピックとアクションに対してこの API を有効化)] を選択解除し、[Apply (適用)] をクリックします。

sf-api-catalog タグと sf-api-topic タグおよび [SF API Topic and Action Enablement (SF API トピックとアクションの有効化)] ルールセットが API プロジェクトから削除されます。

トピックとエージェントアクションの API プロジェクトを有効化

始める前に

エージェントアクションとトピックの API 仕様プロジェクトを作成する

API プロジェクトにメタデータを追加する

トピックを設定する

アクションを設定する

トピックとエージェントのガバナンスルールセット

API 仕様を Exchange にパブリッシュする

トピックの API 仕様を無効にする

関連情報