OpenAPI ツール

エージェントは、OpenAPI スキーマを提供することで、OpenAPI ツールを使用して外部 API に接続できます。エージェントがユーザーに代わって API を呼び出します。

制限事項:

各 OpenAPI ツールには、オペレーションまたは関数を 1 つだけ指定できます。

サンプルスキーマ:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          x-ces-session-context: $context.session_id
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

セッションコンテキスト変数の挿入

セッション ID などのセッションコンテキストから、OpenAPI リクエストに変数を挿入できます。パラメータ定義内で x-ces-session-context 拡張フィールドを使用します。値は、context オブジェクト内の変数へのパスにする必要があります。

次に例を示します。

      parameters:
        - name: X-SESSION
          in: header
          description: session id
          required: true
          schema:
            type: string
          # This extension injects the session ID
          x-ces-session-context: $context.session_id

セキュリティに関する考慮事項

OpenAPI ツールを構成する際は、権限の処理方法を理解することが重要です。

ツールの実行 ID: OpenAPI ツールによって実行されるアクションは、エージェントとやり取りするエンドユーザーの直接の権限ではなく、CX Agent Studio サービスアカウントに付与された権限を使用して実行されます。
推移的アクセスリスク: CX Agent Studio サービスアカウントに Cloud Run functions を呼び出す権限がある場合、エンドユーザーが直接アクセスできない場合でも、そのサービスアカウントがアクセスできる任意の関数をツールが呼び出す可能性があります。

この動作に関連する潜在的なリスクを軽減するには:

専用プロジェクトを使用する: 他の重要なリソースや機密性の高い関数とは別に、専用のプロジェクトにエージェントアプリケーションをデプロイすることを強くおすすめします。この分離により、CX Agent Studio サービスアカウントで使用できる権限の範囲が制限されます。
VPC Service Controls を実装する: VPC Service Controls を使用して、機密性の高いサービスの周囲にサービス境界を定義します。これにより、Cloud Run functions などのサービスへのアクセスを制御し、CX Agent Studio サービスアカウントからの不要な呼び出しを防ぐことができます。
最小権限に従う: CX Agent Studio サービスアカウントに、目的の機能に必要な最小限の Identity and Access Management ロールと権限のみが付与されていることを確認します。

API の認証

外部 API を呼び出す際は、次の認証オプションがサポートされています。

サービスエージェントの ID トークン

CX Agent Studio は、Customer Engagement Suite のサービスエージェントを使用して ID トークンを生成できます。トークンは、CX Agent Studio が外部 API を呼び出すときに認可 HTTP ヘッダーに追加されます。

Cloud Run functions と Cloud Run のサービスがエージェントと同じプロジェクト内にある場合、これらを呼び出すための追加の IAM 権限は必要ありません。異なるプロジェクトにある場合は、サービスエージェントアドレスに roles/cloudfunctions.invoker ロールと roles/run.invoker ロールを付与すると、ID トークンを使用して Cloud Run functions と Cloud Run サービスにアクセスできます。

サービスアカウントの認証

サービスアカウントは、サポートされている任意の Google API へのツールリクエストを認証するために使用できます。サービスアカウントのメールアドレスを指定します。

まだ作成していない場合は、サービスアカウントを作成します。

サービスアカウントはプリンシパルであるため、他のプリンシパルと同様に、ロールを付与することでプロジェクト内のリソースにアクセスできます。サービスアカウントのメールアドレスは、アクセストークンを生成するために使用されます。このトークンは、ツールリクエストの Authorization ヘッダーで送信されます。

サービスアカウントを使用するようにツールを構成するユーザーには、次の権限が必要です。

roles/iam.serviceAccountUser

Dialogflow CX がトークンを生成するには、Customer Engagement Suite のサービスエージェントに次の権限が必要です。

roles/iam.serviceAccountTokenCreator

サービスアカウントには、ツールをホストしているサービスにアクセスする権限も必要です。

OAuth

使用しているサービスの OAuth 情報を入力します。

Google サービスに OAuth を使用している場合は、サービス用に OAuth を構成する必要があります。

API キー

API キー認証は、キー名、リクエストの場所（ヘッダーまたはクエリ文字列）、API キーを指定して、CX Agent Studio がリクエストで API キーを渡すことで構成できます。Secret Manager のシークレットバージョンを使用して API キーを指定します。

Secret Manager の認証

Secret Manager を使用して、認証情報をシークレットとして保存できます。シークレットを使用してツールを認証するために必要な手順は次のとおりです。

シークレットをまだ作成していない場合は、シークレットを作成します。
新しいシークレットに対する Customer Engagement Suite サービスエージェントに Secret Manager のシークレットアクセサー（roles/secretmanager.secretAccessor）ロールを付与します。
認証情報をクリップボードにコピーします。
シークレットに新しいシークレットバージョンを追加します。認証情報をシークレット値として貼り付けます。
- 末尾の改行文字は省略します。
追加したシークレットバージョンの名前をコピーします。名前の形式は projects/{project_id}/secrets/{secret_id}/versions/{version_id} です。このシークレットバージョンをツール構成に使用します。