Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar feedback usando o SDK do Python ou a API REST

Nesta página, descrevemos como usar a API e o SDK do serviço de feedback para gerenciar entradas e contexto de feedback. Você pode implementar controles de feedback personalizados (como botões "Gostei" ou "Não gostei") em uma interface do usuário, como widgets de chat ou apps para dispositivos móveis, e usar o serviço Feedback para rastrear o feedback.

Antes de começar

Verifique se você tem o seguinte:

A função de usuário da Agent Platform (roles/aiplatform.user).
Siga as etapas de Autenticação para configurar a autenticação.
Uma instância implantada do Agent Runtime. Se você não tiver uma instância implantada, consulte Implantar um agente ou inicialize e crie uma seguindo as etapas na próxima seção.
Opcional: para ver as entradas de feedback ao lado dos eventos de rastreamento no console, verifique se a instância do ambiente de execução do agente tem o rastreamento ativado.

Criar uma instância do Agent Runtime

Se você não tiver uma instância do Agent Runtime, inicialize o cliente e crie uma:

SDK do 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

Um nome de recurso do Agent Runtime usa o seguinte formato: projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Consulte as regiões compatíveis para o Runtime.
AGENT_ENGINE_ID: o ID do recurso da instância do Agent Runtime.

Criar uma entrada de feedback

Antes de enviar feedback, você precisa ter uma sessão com poucas mensagens trocadas entre o usuário e o agente. Identifique a resposta sobre a qual você quer enviar feedback e obtenha o ID do evento e da sessão.

Para fazer isso:

Crie uma sessão de interação com um agente.
Envie uma consulta ao agente e identifique a resposta que você quer avaliar.
Pegue o ID da sessão e o ID do evento de resposta (que funciona como o ID do evento para a entrada de feedback). Se você estiver usando o serviço de sessão gerenciado com o ADK, poderá extrair o ID do evento do campo raw_event.id da resposta list events (consulte Listar eventos em uma sessão).

Registre de forma programática uma entrada de feedback vinculada diretamente a um destino session_id e event_id definindo um evento de conversa do user agent.

SDK do 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}")

Os valores aceitos para feedback_type são:

"THUMBS_UP"
"THUMBS_DOWN"
"FEEDBACK_TYPE_UNSPECIFIED"

API REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.
SESSION_ID: o ID da sessão que define a conversa associada ao feedback.
EVENT_ID: o ID do evento que identifica a mensagem ou o nó específico a que o feedback se refere.

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "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"
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

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

Observação: o comando a seguir pressupõe que você fez login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

Você vai receber uma operação de longa duração indicando o status da criação da entrada de feedback.

Recuperar uma entrada de feedback

Extrai o payload completo e estruturado de um registro de feedback isolado usando o endereço exclusivo do recurso.

SDK do 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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.
FEEDBACK_ENTRY_ID: o ID do recurso da entrada de feedback.

Método HTTP e URL:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte 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

Execute o seguinte 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

A resposta inclui os detalhes da entrada de feedback, como ID da sessão, tipo, rótulos e texto.

Listar entradas de feedback

Liste as entradas de feedback na sua instância do Agent Runtime. É possível aplicar filtros e propriedades de ordenação.

SDK do 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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.

Método HTTP e URL:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte 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

Execute o seguinte 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

A resposta inclui uma lista de entradas de feedback que correspondem a filtros aplicados, além de um token de paginação se houver outras entradas.

Use o parâmetro de consulta filter para consultar por atributos específicos. Para ordenar, use o parâmetro de consulta order_by.

Campos compatíveis com a filtragem:

session_id, como session_id="SESSION_ID"
user_id, como user_id="YOUR_USER_ID"
feedback_type, como feedback_type="THUMBS_DOWN"
feedback_labels, como feedback_labels: "inaccurate"
create_time
update_time

Campos compatíveis com a classificação:

create_time
update_time

Atualizar uma entrada de feedback

Atualize os detalhes de uma entrada de feedback, como modificar rótulos, comentários ou metadados personalizados.

SDK do 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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.
FEEDBACK_ENTRY_ID: o ID do recurso da entrada de feedback a ser atualizada.

Método 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 da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

Você recebe uma operação de longa duração indicando o progresso da operação de atualização.

Excluir uma entrada de feedback

Exclui permanentemente uma entrada de feedback do seu projeto.

SDK do 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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.
FEEDBACK_ENTRY_ID: o ID do recurso da entrada de feedback a ser excluída.

Método HTTP e URL:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte 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

Execute o seguinte 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

Você vai receber uma operação de longa duração mostrando o status da exclusão.

Contexto do feedback

O contexto de feedback (FeedbackContext) é um recurso filho de uma entrada de feedback (FeedbackEntry) que é criada e excluída automaticamente junto com a entrada de feedback principal. Por padrão, o contexto de feedback contém uma lista vazia de eventos.

O contexto de feedback armazena transcrições ou estados de eventos associados à entrada de feedback. Essa separação de recursos:

Preserva o histórico de conversas:mesmo que a sessão original seja excluída, as transcrições ou os registros armazenados no contexto de feedback são mantidos.
Reduz o tamanho da resposta:ao recuperar entradas de feedback, não é necessário buscar os detalhes contextuais.

O recurso FeedbackContext tem a seguinte estrutura:

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

Recuperar contexto de feedback

Confira os detalhes e eventos de conversa armazenados no contexto de feedback:

SDK do 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

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.
FEEDBACK_ENTRY_ID: o ID do recurso da entrada de feedback.

Método HTTP e URL:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte 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

Execute o seguinte 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

A resposta inclui detalhes sobre o contexto de feedback solicitado, incluindo a lista de eventos de conversa associados à entrada de feedback principal.

Criar e atualizar o contexto de feedback

SDK do Python

Para preencher ou modificar o histórico de conversas associado a uma entrada de feedback, atualize o contexto de feedback usando o seguinte fluxo de duas etapas:

Criar a entrada de feedback: chame métodos padrão para criar o registro de feedback principal.
Atualize o contexto do feedback: depois de receber o ID da entrada de feedback, envie uma solicitação para preencher os eventos de contexto.

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

Para preencher ou modificar o histórico de conversas associado a uma entrada de feedback, atualize o contexto de feedback usando o seguinte fluxo de duas etapas:

Crie a entrada de feedback: chame CreateFeedbackEntry para criar o registro de feedback principal.
Atualize o contexto do feedback: depois de receber o ID da entrada de feedback, envie uma solicitação PATCH ao recurso filho de contexto (UpdateFeedbackContext) para preencher contextEvents.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto.
LOCATION: a região em que a instância do Agent Engine está localizada.
AGENT_ENGINE_ID: o ID do recurso da sua instância do Agent Engine.
FEEDBACK_ENTRY_ID: o ID do recurso da entrada de feedback.

Método 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 da solicitação:

{
  "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."
          }
        ]
      }
    }
  ]
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

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

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

Você recebe uma operação de longa duração mostrando o progresso da atualização do contexto de feedback.

Para remover o contexto de feedback, envie uma atualização vazia (por exemplo, com context_events definido como uma lista vazia).