Python SDK または REST API を使用してフィードバックを管理する

このページでは、フィードバック サービス API と SDK を使用してフィードバック エントリとコンテキストを管理する方法について説明します。チャット ウィジェットやモバイルアプリなどのユーザー インターフェースにカスタム フィードバック コントロール(高評価ボタンや低評価ボタンなど)を実装し、フィードバック サービスを使用してフィードバックを追跡できます。

始める前に

以下のものが揃っていることを確認してください。

  • Agent Platform ユーザー(roles/aiplatform.user)ロール。
  • 認証の手順に沿って認証を設定します。
  • デプロイされた Agent Runtime インスタンス。デプロイされたインスタンスがない場合は、エージェントをデプロイするをご覧ください。または、次のセクションの手順に沿ってインスタンスを初期化して作成します。
  • 省略可: コンソールでトレースイベントの横にフィードバック エントリを表示するには、Agent Runtime インスタンスでトレースが有効になっていることを確認します。

Agent Runtime インスタンスを作成する

既存の Agent Runtime インスタンスがない場合は、クライアントを初期化して作成できます。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
agent_engine = client.runtimes.create()

# Optionally, print out the Agent Runtime resource name. You will need the
# resource name to interact with the Feedback service later on.
print(agent_engine.api_resource.name)

REST API

Agent Runtime リソース名には次の形式を使用します。 projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

次のように置き換えます。

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: リージョン。Runtime のサポートされているリージョンをご覧ください。
  • AGENT_ENGINE_ID: Agent Runtime インスタンスのリソース ID。

フィードバック エントリを作成する

フィードバックを送信する前に、ユーザーとエージェントの間でメッセージが数回やり取りされている既存のセッションが必要です。フィードバックを送信するレスポンスを特定し、そのイベント ID とセッション ID を取得します。

操作:

  1. エージェントとのインタラクション セッションを作成します。

  2. エージェントにクエリを送信し、フィードバックを送信するレスポンスを特定します。

  3. セッション ID とレスポンス イベントの ID(フィードバック エントリのイベント ID として機能)を取得します。ADK でマネージド セッション サービスを使用している場合は、リスト イベント レスポンスの raw_event.id フィールドからイベント ID を取得できます(セッション内のイベントを一覧表示するをご覧ください)。

ユーザー エージェントの会話イベントを定義するターゲット session_id と event_id に直接バインドされたフィードバック エントリをプログラムでロギングします。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

operation = client.feedback_entries.create(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID",
    session_id="SESSION_ID",
    event_id="EVENT_ID",
    feedback_type="THUMBS_UP",
    config={
        "feedback_text": "The response was helpful and accurate.",
        "feedback_labels": ["accurate"],
        "user_id": "user-123",
        "source": "Chat UI",
        "custom_metadata": {"model_temperature": "0.7"},
    }
)

# Retrieve the created feedback entry details
feedback_entry = operation.response
print(f"Created feedback entry: {feedback_entry.name}")

feedback_type でサポートされている値は次のとおりです。

  • "THUMBS_UP"
  • "THUMBS_DOWN"
  • "FEEDBACK_TYPE_UNSPECIFIED"

REST API

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • SESSION_ID: フィードバックに関連付けられている会話を定義するセッション ID。
  • EVENT_ID: フィードバックの対象となる特定のメッセージまたはノードを識別するイベント ID。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries

リクエストの本文(JSON):

{
  "sessionId": "SESSION_ID",
  "eventId": "EVENT_ID",
  "feedbackType": "THUMBS_DOWN",
  "feedbackLabels": ["inaccurate"],
  "feedbackText": "The answer was incorrect.",
  "userId": "user-123",
  "source": "Chat UI",
  "customMetadata": {
    "temperature": "0.7"
  }
}

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

curl

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

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries"

PowerShell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries" | Select-Object -Expand Content

フィードバック エントリの作成ステータスを示す長時間実行オペレーションが返されます。

フィードバック エントリを取得する

一意のリソース アドレスを使用して、分離されたフィードバック レコードの完全な構造化ペイロードを取得します。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

feedback_entry = client.feedback_entries.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"
)

print(f"Feedback Type: {feedback_entry.feedback_type}")
print(f"Feedback Text: {feedback_entry.feedback_text}")

REST API

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • FEEDBACK_ENTRY_ID: フィードバック エントリのリソース ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID

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

curl

次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"

PowerShell

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID" | Select-Object -Expand Content

レスポンスには、セッション ID、タイプ、ラベル、テキストなどのフィードバック エントリの詳細が含まれます。

フィードバック エントリを一覧表示する

Agent Runtime インスタンスのフィードバック エントリを一覧表示します。フィルタと並べ替えのプロパティを適用できます。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

response = client.feedback_entries.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID",
    config={
        "filter": 'session_id="SESSION_ID"',
        "order_by": "create_time desc"
    }
)

for entry in response:
    print(f"Entry name: {entry.name}, Type: {entry.feedback_type}")

REST API

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries

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

curl

次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries"

PowerShell

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries" | Select-Object -Expand Content

レスポンスには、適用されたフィルタに一致するフィードバック エントリのリストと、追加のエントリがある場合はページネーション トークンが含まれます。

filter クエリ パラメータを使用すると、特定の属性でクエリできます。並べ替えを行うには、order_by クエリ パラメータを使用します。

フィルタリングに対応するフィールド:

  • session_id(session_id="SESSION_ID" など)
  • user_id(user_id="YOUR_USER_ID" など)
  • feedback_type(feedback_type="THUMBS_DOWN" など)
  • feedback_labels(feedback_labels: "inaccurate" など)
  • create_time
  • update_time

並べ替えに対応するフィールド:

  • create_time
  • update_time

フィードバック エントリを更新する

ラベル、コメント、カスタム メタデータの変更など、既存のフィードバック エントリの詳細を更新します。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

operation = client.feedback_entries.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID",
    feedback_type="THUMBS_DOWN",
    config={
        "feedback_text": "Actually, this response was not accurate.",
        "feedback_labels": ["inaccurate"],
    }
)

updated_entry = operation.response
print(f"Updated entry: {updated_entry.name}")

REST API

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • FEEDBACK_ENTRY_ID: 更新するフィードバック エントリのリソース ID。

HTTP メソッドと URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID?updateMask=feedbackType,feedbackLabels,feedbackText

リクエストの本文(JSON):

{
  "feedbackType": "THUMBS_DOWN",
  "feedbackLabels": ["inaccurate", "incomplete"],
  "feedbackText": "The response was details-lacking and inaccurate."
}

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

curl

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

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID?updateMask=feedbackType,feedbackLabels,feedbackText"

PowerShell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID?updateMask=feedbackType,feedbackLabels,feedbackText" | Select-Object -Expand Content

更新オペレーションの進行状況を示す長時間実行オペレーションが返されます。

フィードバック エントリを削除する

プロジェクトからフィードバック エントリを完全に削除します。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

client.feedback_entries.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"
)

print("Feedback entry deleted.")

REST API

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • FEEDBACK_ENTRY_ID: 削除するフィードバック エントリのリソース ID。

HTTP メソッドと URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID

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

curl

次のコマンドを実行します。

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID"

PowerShell

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method DELETE `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID" | Select-Object -Expand Content

削除ステータスを示す長時間実行オペレーションが返されます。

フィードバックのコンテキスト

フィードバック コンテキスト(FeedbackContext)は、フィードバック エントリ(FeedbackEntry)の子リソースです。これは、親フィードバック エントリとともに自動的に作成および削除されます。デフォルトでは、フィードバック コンテキストには空のイベント リストが含まれています。

フィードバック コンテキストには、フィードバック エントリに関連付けられた文字起こしやイベントの状態が保存されます。このリソースの分離は次のようになります。

  • 会話履歴を保持する: 元のセッションが削除されても、フィードバック コンテキストに保存された文字起こしやログは保持されます。
  • レスポンス サイズの削減: フィードバック エントリを取得する際に、詳細なコンテキストの詳細を取得する必要がなくなります。

FeedbackContext リソースの構造は次のとおりです。

projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext

フィードバックのコンテキストを取得する

フィードバック コンテキストに保存されている詳細と会話イベントを取得します。

Python SDK

import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

feedback_context = client.feedback_entries.feedback_contexts.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext"
)

# Point to event list
for event in feedback_context.context_events:
    print(f"Author: {event.author}")
    if event.content and event.content.parts:
        print(f"Content: {event.content.parts[0].text}")

REST API

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • FEEDBACK_ENTRY_ID: フィードバック エントリのリソース ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext

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

curl

次のコマンドを実行します。

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext"

PowerShell

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext" | Select-Object -Expand Content

レスポンスには、リクエストされたフィードバック コンテキストの詳細が含まれます。これには、親フィードバック エントリに関連付けられた会話イベントのリストが含まれます。

フィードバック コンテキストを作成して更新する

Python SDK

フィードバック エントリに関連付けられた会話履歴を入力または変更するには、次の 2 ステップのフローを使用してフィードバック コンテキストを更新します。

  1. フィードバック エントリを作成する: 標準メソッドを呼び出して、プライマリ フィードバック レコードを作成します。
  2. フィードバック コンテキストを更新する: フィードバック エントリ ID を取得したら、コンテキスト イベントを入力するリクエストを送信します。
import os
import agentplatform

# Set this environment variable to enable the Enterprise features.
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION"
)

# Construct conversation events
session_event = {
    "author": "user",
    "content": {
        "role": "user",
        "parts": [{"text": "Hello Agent"}]
    }
}

operation = client.feedback_entries.feedback_contexts.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID",
    context_events=[session_event]
)

updated_context = operation.response
print("Feedback context updated successfully.")

REST API

フィードバック エントリに関連付けられた会話履歴を入力または変更するには、次の 2 ステップのフローを使用してフィードバック コンテキストを更新します。

  1. フィードバック エントリを作成する: CreateFeedbackEntry を呼び出して、プライマリ フィードバック レコードを作成します。
  2. フィードバック コンテキストを更新する: フィードバック エントリ ID を取得したら、コンテキスト子リソース(UpdateFeedbackContext)に PATCH リクエストを送信して contextEvents を入力します。

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスが配置されているリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • FEEDBACK_ENTRY_ID: フィードバック エントリのリソース ID。

HTTP メソッドと URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents

リクエストの本文(JSON):

{
  "contextEvents": [
    {
      "author": "user",
      "content": {
        "role": "user",
        "parts": [
          {
            "text": "What is the capital of France?"
          }
        ]
      }
    },
    {
      "author": "agent",
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Paris is the capital of France."
          }
        ]
      }
    }
  ]
}

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

curl

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

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents"

PowerShell

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents" | Select-Object -Expand Content

フィードバック コンテキストの更新の進行状況を示す長時間実行オペレーションを受け取ります。

フィードバック コンテキストを削除するには、空の更新を送信します(たとえば、context_events を空のリストに設定します)。