このページでは、フィードバック サービス 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 を取得します。
操作:
エージェントとのインタラクション セッションを作成します。
エージェントにクエリを送信し、フィードバックを送信するレスポンスを特定します。
セッション 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_timeupdate_time
並べ替えに対応するフィールド:
create_timeupdate_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 ステップのフローを使用してフィードバック コンテキストを更新します。
- フィードバック エントリを作成する: 標準メソッドを呼び出して、プライマリ フィードバック レコードを作成します。
- フィードバック コンテキストを更新する: フィードバック エントリ 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 ステップのフローを使用してフィードバック コンテキストを更新します。
- フィードバック エントリを作成する:
CreateFeedbackEntryを呼び出して、プライマリ フィードバック レコードを作成します。 - フィードバック コンテキストを更新する: フィードバック エントリ 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 を空のリストに設定します)。