Cette page explique comment utiliser l'API et le SDK du service Feedback pour gérer les entrées et le contexte des commentaires. Vous pouvez implémenter des commandes de commentaires personnalisées (comme des boutons "J'aime" ou "Je n'aime pas") dans une interface utilisateur telle que des widgets de chat ou des applications mobiles, et utiliser le service de commentaires pour suivre les commentaires.
Avant de commencer
Assurez-vous de disposer des éléments suivants :
- Le rôle Utilisateur Agent Platform (
roles/aiplatform.user) - Configurez l'authentification en suivant les étapes de la section Authentification.
- Instance Agent Runtime déployée. Si vous n'avez pas d'instance déployée, consultez Déployer un agent ou initialisez-en une et créez-en une en suivant les étapes de la section suivante.
- Facultatif : Pour afficher les entrées de commentaires à côté des événements de trace dans la console, assurez-vous que le traçage est activé dans votre instance Agent Runtime.
Créer une instance Agent Runtime
Si vous ne disposez d'aucune instance Agent Runtime, vous pouvez initialiser le client et en créer une :
SDK Python
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)
API REST
Un nom de ressource Agent Runtime utilise le format suivant :
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : votre région. Consultez les régions disponibles pour Runtime.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Runtime.
Créer une entrée de commentaires
Avant d'envoyer des commentaires, vous devez avoir une session existante avec quelques messages échangés entre l'utilisateur et l'agent. Identifiez la réponse sur laquelle vous souhaitez envoyer des commentaires, puis obtenez son ID d'événement et son ID de session.
Pour ce faire, procédez comme suit :
Créez une session d'interaction avec un agent.
Envoyez une requête à l'agent et identifiez la réponse pour laquelle vous souhaitez envoyer des commentaires.
Récupérez l'ID de session et l'ID de l'événement de réponse (qui sert d'ID d'événement pour l'entrée de commentaires). Si vous utilisez le service de session géré avec ADK, vous pouvez obtenir l'ID d'événement à partir du champ
raw_event.idde la réponse "List events" (voir Lister les événements d'une session).
Enregistrez par programmation une entrée de commentaires directement liée à un session_id et un event_id cibles, définissant un événement de conversation de l'agent utilisateur.
SDK Python
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}")
Les valeurs acceptées pour feedback_type sont les suivantes :
"THUMBS_UP""THUMBS_DOWN""FEEDBACK_TYPE_UNSPECIFIED"
API REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
- SESSION_ID : ID de la session définissant la conversation associée au commentaire.
- EVENT_ID : ID de l'événement identifiant le message ou le nœud spécifique ciblé par le commentaire.
Méthode HTTP et URL :
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries
Corps JSON de la requête :
{
"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"
}
}
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
$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
Vous recevez une opération de longue durée indiquant l'état de la création de l'entrée de commentaires.
Récupérer une entrée de commentaires
Récupérez la charge utile structurée complète d'un enregistrement de commentaires isolé à l'aide de son adresse de ressource unique.
SDK Python
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}")
API REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
- FEEDBACK_ENTRY_ID : ID de ressource de l'entrée de commentaires.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Exécutez la commande suivante :
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
Exécutez la commande suivante :
$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
La réponse inclut les détails de l'entrée de commentaires, tels que l'ID de session, le type, les libellés et le texte.
Lister les entrées de commentaires
Lister les entrées de commentaires dans votre instance Agent Runtime Vous pouvez appliquer des filtres et des propriétés de tri.
SDK Python
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}")
API REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Exécutez la commande suivante :
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
Exécutez la commande suivante :
$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
La réponse inclut une liste des commentaires correspondant aux filtres appliqués, ainsi qu'un jeton de pagination s'il existe d'autres commentaires.
Vous pouvez utiliser le paramètre de requête filter pour interroger des attributs spécifiques. Pour trier les résultats, utilisez le paramètre de requête order_by.
Champs acceptant le filtrage :
session_id, commesession_id="SESSION_ID"user_id, commeuser_id="YOUR_USER_ID"feedback_type, commefeedback_type="THUMBS_DOWN"feedback_labels, commefeedback_labels: "inaccurate"create_timeupdate_time
Champs compatibles pour le tri :
create_timeupdate_time
Modifier une entrée de commentaires
Mettez à jour les détails d'une entrée de commentaires existante, par exemple en modifiant les libellés, les commentaires ou les métadonnées personnalisées.
SDK Python
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}")
API REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
- FEEDBACK_ENTRY_ID : ID de ressource de l'entrée de commentaires à modifier.
Méthode HTTP et 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
Corps JSON de la requête :
{
"feedbackType": "THUMBS_DOWN",
"feedbackLabels": ["inaccurate", "incomplete"],
"feedbackText": "The response was details-lacking and inaccurate."
}
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
$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
Vous recevez une opération de longue durée indiquant la progression de l'opération de mise à jour.
Supprimer une entrée de commentaires
Supprimez définitivement une entrée de commentaires de votre projet.
SDK Python
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.")
API REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
- FEEDBACK_ENTRY_ID : ID de ressource de l'entrée de commentaires à supprimer.
Méthode HTTP et URL :
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Exécutez la commande suivante :
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
Exécutez la commande suivante :
$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
Vous recevez une opération de longue durée indiquant l'état de la suppression.
Contexte des commentaires
Le contexte de commentaires (FeedbackContext) est une ressource enfant d'une entrée de commentaires (FeedbackEntry) qui est automatiquement créée et supprimée en même temps que son entrée de commentaires parente. Par défaut, le contexte de commentaires contient une liste vide d'événements.
Le contexte des commentaires stocke les transcriptions ou les états d'événement associés à l'entrée de commentaires. Cette séparation des ressources :
- Conservation de l'historique des conversations : même si la session d'origine est supprimée, les transcriptions ou les journaux stockés dans le contexte des commentaires sont conservés.
- Réduit la taille de la réponse : lorsque vous récupérez des entrées de commentaires, vous n'avez pas besoin d'extraire les détails contextuels.
La ressource FeedbackContext présente la structure suivante :
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext
Récupérer le contexte des commentaires
Obtenez les détails et les événements de conversation stockés dans le contexte des commentaires :
SDK Python
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}")
API REST
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
- FEEDBACK_ENTRY_ID : ID de ressource de l'entrée de commentaires.
Méthode HTTP et URL :
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Exécutez la commande suivante :
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
Exécutez la commande suivante :
$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
La réponse inclut des informations sur le contexte des commentaires demandés, y compris la liste des événements de conversation associés à l'entrée de commentaires parent.
Créer et mettre à jour le contexte des commentaires
SDK Python
Pour remplir ou modifier l'historique des conversations associé à une entrée de commentaires, mettez à jour le contexte des commentaires en suivant la procédure en deux étapes ci-dessous :
- Créez l'entrée de commentaires : appelez les méthodes standards pour créer l'enregistrement principal des commentaires.
- Mettez à jour le contexte des commentaires : après avoir obtenu l'ID de l'entrée de commentaires, envoyez une requête pour remplir les événements de contexte.
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.")
API REST
Pour remplir ou modifier l'historique des conversations associé à une entrée de commentaires, mettez à jour le contexte des commentaires en suivant la procédure en deux étapes ci-dessous :
- Créez l'entrée de commentaires : appelez
CreateFeedbackEntrypour créer l'enregistrement de commentaires principal. - Mettez à jour le contexte des commentaires : une fois que vous avez obtenu l'ID de l'entrée de commentaires, envoyez une requête
PATCHà la ressource enfant de contexte (UpdateFeedbackContext) pour remplircontextEvents.
Avant d'utiliser les données de requête, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : région dans laquelle se trouve votre instance Agent Engine.
- AGENT_ENGINE_ID : ID de ressource de votre instance Agent Engine.
- FEEDBACK_ENTRY_ID : ID de ressource de l'entrée de commentaires.
Méthode HTTP et URL :
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents
Corps JSON de la requête :
{
"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."
}
]
}
}
]
}
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
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
Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :
$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
Vous recevez une opération de longue durée indiquant la progression de la mise à jour du contexte des commentaires.
Pour supprimer le contexte des commentaires, envoyez une mise à jour vide (par exemple, avec context_events défini sur une liste vide).