エージェントは、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 のサービス エージェント(形式: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com)を使用して 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}です。このシークレット バージョンをツールの構成に使用します。
署名なしトークン
署名なしトークン認証を構成して、セッション コンテキスト変数に保存されている署名なしトークンを OpenAPI ツール リクエストの Authorization ヘッダーで渡すことができます。このオプションは、エージェントがエンドユーザーから収集したトークンを別の API に渡す必要がある場合に便利です。
セッション コンテキスト変数を $context.variables.VARIABLE_NAME の形式で指定します。ここで、VARIABLE_NAME は署名なしトークンを格納する変数の名前です。