API による操作

会話ターンごとに、操作が行われます。インタラクション中に、エンドユーザーがエージェントアプリに入力を送信し、エージェントアプリがレスポンスを送信します。 Vertex AI Agents API を使用すると、実行時にエージェントアプリで操作できます。

始める前に

このガイドを読む前に、次の手順を行ってください。

新しいエージェントアプリを作成するか、エージェントアプリを作成するで作成したエージェントアプリを引き続き使用します。

ID を収集する

次のサンプルでは、入力として複数の ID が必要です。プロジェクト ID、リージョン ID、アプリ ID は次の手順で確認できます。

Agent Builder コンソールに移動します。

Agent Builder コンソール
プロジェクト ID はコンソールの上部に表示されます。
[Location] 列には、リージョン ID が表示されます。
アプリを選択します。
agents/ の後のブラウザ URL パスセグメントには、エージェントアプリ ID が含まれます。

セッション ID も必要です。セッションは、エージェントアプリとエンドユーザー間の会話を表します。会話の開始時に一意のセッション ID を作成し、会話のターンごとにそれを使用します。API を試す場合、test-session-123 のように、最大 36 バイトの任意の文字列 ID を使用できます。

通話検出インテント

次のサンプルでは、Sessions.detectIntent メソッドを呼び出します。

セッションリファレンスのプロトコルとバージョンを選択:

プロトコル	V3	V3beta1
REST	セッションリソース	セッションリソース
RPC	セッションインターフェース	セッションインターフェース
C++	SessionsClient	利用できません
C#	SessionsClient	利用できません
Go	SessionsClient	利用できません
Java	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	利用不可	利用できません
Python	SessionsClient	SessionsClient
Ruby	利用不可	利用できません

REST

リクエストのデータを使用する前に、次のように置き換えます。

PROJECT_ID: 実際の Google Cloud プロジェクト ID
AGENT_ID: ハンドブックエージェント ID（Dialogflow エージェント ID に対応）
REGION_ID: リージョン ID
SUBDOMAIN_REGION: リージョン ID が us の場合、サブドメインのリージョンは usa です。それ以外の場合は、サブドメインのリージョンはリージョン ID と同じです。
SESSION_ID: セッション ID
END_USER_INPUT: エンドユーザーの入力（例: シャツを買いたいのですが）

HTTP メソッドと URL:

POST https://SUBDOMAIN_REGION-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent

リクエストの本文（JSON）:

{
  "queryInput": {
    "text": {
      "text": "END_USER_INPUT"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://SUBDOMAIN_REGION-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://SUBDOMAIN_REGION-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "responseId": "a6cd27b0-5eaa-4f93-aa6e-11faf97dbb63",
  "queryResult": {
    "text": "I want to buy a shirt",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Great! I can help you with that. We have a wide variety of shirts to choose from. What size and color would you like?"
          ]
        }
      }
    ],
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {
      "Session Id": "123",
      "Response Id": "a6cd27b0-5eaa-4f93-aa6e-11faf97dbb63"
    },
    "match": {
      "confidence": 1
    },
    "advancedSettings": {
      "loggingSettings": {}
    }
  },
  "responseType": "FINAL"
}

エージェントアプリを作成する

エージェントアプリ