Questa pagina descrive come utilizzare l'API e l'SDK del servizio di feedback per gestire le voci e il contesto del feedback. Puoi implementare controlli di feedback personalizzati (ad esempio pulsanti Mi piace o Non mi piace) in un'interfaccia utente come widget di chat o app mobile e utilizzare il servizio Feedback per monitorare il feedback.
Prima di iniziare
Assicurati di disporre di quanto segue:
- Il ruolo Agent Platform User (
roles/aiplatform.user). - Configura l'autenticazione seguendo i passaggi Autenticazione.
- Un'istanza di Agent Runtime di cui è stato eseguito il deployment. Se non hai un'istanza di cui è stato eseguito il deployment, consulta Eseguire il deployment di un agente o inizializzane e creane una seguendo i passaggi della sezione successiva.
- (Facoltativo) Per visualizzare le voci di feedback accanto agli eventi traccia nella console, assicurati che la tua istanza di Agent Runtime abbia tracing abilitato.
Crea un'istanza di Agent Runtime
Se non disponi di un'istanza di Agent Runtime esistente, puoi inizializzare il client e crearne una:
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
Il nome di una risorsa Agent Runtime utilizza il seguente formato:
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID
Sostituisci quanto segue:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la tua regione. Vedi le regioni supportate per Runtime.
- AGENT_ENGINE_ID: l'ID risorsa dell'istanza di Agent Runtime.
Creare una voce di feedback
Prima di inviare un feedback, devi avere una sessione esistente con pochi messaggi scambiati tra l'utente e l'agente. Identifica la risposta su cui vuoi inviare un feedback e ottieni il relativo ID evento e ID sessione.
A tal fine:
Crea una sessione di interazione con un agente.
Invia una query all'agente e identifica la risposta per cui vuoi inviare un feedback.
Prendi l'ID sessione e l'ID dell'evento di risposta (che funge da ID evento per la voce di feedback). Se utilizzi il servizio di sessione gestito con ADK, puoi ottenere l'ID evento dal campo
raw_event.iddella risposta Elenca eventi (vedi Elencare gli eventi in una sessione).
Registra in modo programmatico una voce di feedback associata direttamente a un session_id di destinazione
e a un event_id che definisce un evento di conversazione user-agent.
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}")
I valori supportati per feedback_type sono:
"THUMBS_UP""THUMBS_DOWN""FEEDBACK_TYPE_UNSPECIFIED"
API REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
- SESSION_ID: l'ID sessione che definisce la conversazione associata al feedback.
- EVENT_ID: l'ID evento che identifica il messaggio o il nodo specifico a cui si riferisce il feedback.
Metodo HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries
Corpo JSON della richiesta:
{
"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"
}
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
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
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$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
Ricevi un'operazione a lunga esecuzione che indica lo stato della creazione della voce di feedback.
Recuperare una voce di feedback
Recupera il payload completo e strutturato di un record di feedback isolato utilizzando il suo indirizzo della risorsa univoco.
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
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
- FEEDBACK_ENTRY_ID: l'ID risorsa della voce di feedback.
Metodo HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo comando:
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
Esegui questo comando:
$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 risposta include i dettagli della voce di feedback, come ID sessione, tipo, etichette e testo.
Elenco delle voci di feedback
Elenca le voci di feedback nell'istanza di Agent Runtime. Puoi applicare filtri e proprietà di ordinamento.
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
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
Metodo HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo comando:
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
Esegui questo comando:
$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 risposta include un elenco di voci di feedback corrispondenti a eventuali filtri applicati, insieme a un token di paginazione se sono presenti altre voci.
Puoi utilizzare il parametro di query filter per eseguire query in base ad attributi specifici. Per
ordinare, utilizza il parametro di query order_by.
Campi supportati per il filtro:
session_id, ad esempiosession_id="SESSION_ID"user_id, ad esempiouser_id="YOUR_USER_ID"feedback_type, ad esempiofeedback_type="THUMBS_DOWN"feedback_labels, ad esempiofeedback_labels: "inaccurate"create_timeupdate_time
Campi supportati per l'ordinamento:
create_timeupdate_time
Aggiorna una voce di feedback
Aggiorna i dettagli di una voce di feedback esistente, ad esempio modificando etichette, commenti o metadati personalizzati.
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
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
- FEEDBACK_ENTRY_ID: l'ID risorsa della voce di feedback da aggiornare.
Metodo HTTP e 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
Corpo JSON della richiesta:
{
"feedbackType": "THUMBS_DOWN",
"feedbackLabels": ["inaccurate", "incomplete"],
"feedbackText": "The response was details-lacking and inaccurate."
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
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
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$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
Ricevi un'operazione a lunga esecuzione che indica l'avanzamento dell'operazione di aggiornamento.
Eliminare una voce di feedback
Elimina definitivamente una voce di feedback dal progetto.
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
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
- FEEDBACK_ENTRY_ID: l'ID risorsa della voce di feedback da eliminare.
Metodo HTTP e URL:
DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo comando:
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
Esegui questo comando:
$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
Ricevi un'operazione a lunga esecuzione che mostra lo stato dell'eliminazione.
Contesto del feedback
Il contesto del feedback (FeedbackContext) è una risorsa secondaria di una voce di feedback (FeedbackEntry) che viene creata ed eliminata automaticamente insieme alla relativa voce di feedback principale. Per impostazione predefinita, il contesto del feedback
contiene un elenco vuoto di eventi.
Il contesto del feedback memorizza le trascrizioni o gli stati degli eventi associati alla voce di feedback. Questa separazione delle risorse:
- Conserva la cronologia delle conversazioni: anche se la sessione originale viene eliminata, le trascrizioni o i log archiviati nel contesto del feedback vengono conservati.
- Riduce le dimensioni della risposta:quando recuperi le voci di feedback, non devi recuperare i dettagli contestuali.
La risorsa FeedbackContext ha la seguente struttura:
projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext
Recuperare il contesto del feedback
Visualizza i dettagli e gli eventi di conversazione archiviati nel contesto del feedback:
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
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
- FEEDBACK_ENTRY_ID: l'ID risorsa della voce di feedback.
Metodo HTTP e URL:
GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext
Per inviare la richiesta, scegli una di queste opzioni:
curl
Esegui questo comando:
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
Esegui questo comando:
$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 risposta include i dettagli del contesto del feedback richiesto, incluso l'elenco degli eventi di conversazione associati alla voce di feedback principale.
Creare e aggiornare il contesto del feedback
SDK Python
Per compilare o modificare la cronologia delle conversazioni associata a una voce di feedback, aggiorna il contesto del feedback utilizzando il seguente flusso in due passaggi:
- Crea la voce di feedback: chiama i metodi standard per creare il record di feedback principale.
- Aggiorna il contesto del feedback: dopo aver ottenuto l'ID della voce di feedback, invia una richiesta per popolare gli eventi di contesto.
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
Per compilare o modificare la cronologia delle conversazioni associata a una voce di feedback, aggiorna il contesto del feedback utilizzando il seguente flusso in due passaggi:
- Crea la voce di feedback: chiama
CreateFeedbackEntryper creare il record di feedback principale. - Aggiorna il contesto del feedback: una volta ottenuto l'ID voce di feedback,
invia una richiesta
PATCHalla risorsa secondaria di contesto (UpdateFeedbackContext) per compilarecontextEvents.
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: il tuo ID progetto.
- LOCATION: la regione in cui si trova l'istanza Agent Engine.
- AGENT_ENGINE_ID: l'ID risorsa della tua istanza di Agent Engine.
- FEEDBACK_ENTRY_ID: l'ID risorsa della voce di feedback.
Metodo HTTP e URL:
PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/feedbackEntries/FEEDBACK_ENTRY_ID/feedbackContext?updateMask=contextEvents
Corpo JSON della richiesta:
{
"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."
}
]
}
}
]
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
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
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$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
Ricevi un'operazione a lunga esecuzione che mostra l'avanzamento dell'aggiornamento del contesto del feedback.
Per rimuovere il contesto del feedback, invia un aggiornamento vuoto (ad esempio, con
context_events impostato su un elenco vuoto).