Collect feedback on agent messages

Submit thumbs up or thumbs down feedback on Agent Studio chat messages with the feedback endpoint.

The Agent Studio feedback endpoint lets you collect binary (thumbs up or thumbs down) feedback on agent messages. Use this to measure response quality, identify problem areas, and improve your agent over time.

Before you begin

• You need an Algolia application with the Agent Studio feature enabled.
• You need an API key with the search ACL.
• You need the messageId (prefixed alg_msg_) from a prior chat response. For more information about message IDs, see Conversations.

Submit feedback

1. Send a chat message and extract the message ID

   Send a completion request to your agent. The response contains a message ID (prefixed alg_msg_) that identifies the assistant’s reply. Store this ID so you can attach feedback to it later.

   Command line

   curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions?stream=false&compatibilityMode=ai-sdk-5" \
     -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
     -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "alg_cnv_abc123",
       "messages": [
         {
           "id": "alg_msg_001",
           "role": "user",
           "content": "How do I reset my password?"
         }
       ]
     }'
   
2. Submit feedback on the message

   Send a POST request to the feedback endpoint with the messageId, agentId, and a vote value. Use 1 for thumbs up or 0 for thumbs down.

   Command line

   curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/feedback" \
     -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
     -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "messageId": "alg_msg_xyz789",
       "agentId": "$AGENT_ID",
       "vote": 1
     }'
   

   import requests
   
   app_id = "ALGOLIA_APPLICATION_ID"
   api_key = "ALGOLIA_SEARCH_API_KEY"
   agent_id = "AGENT_ID"
   
   response = requests.post(
       f"https://{app_id}.algolia.net/agent-studio/1/feedback",
       headers={
           "X-Algolia-Application-Id": app_id,
           "X-Algolia-API-Key": api_key,
           "Content-Type": "application/json",
       },
       json={
           "messageId": "alg_msg_xyz789",
           "agentId": agent_id,
           "vote": 1,
       },
   )
   print(response.status_code, response.json())
   

   const appID = "ALGOLIA_APPLICATION_ID";
   const apiKey = "ALGOLIA_SEARCH_API_KEY";
   const agentId = "AGENT_ID";
   
   const response = await fetch(
     `https://${appID}.algolia.net/agent-studio/1/feedback`,
     {
       method: "POST",
       headers: {
         "X-Algolia-Application-Id": appID,
         "X-Algolia-API-Key": apiKey,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         messageId: "alg_msg_xyz789",
         agentId,
         vote: 1,
       }),
     }
   );
   const data = await response.json();
   console.log(data);
   

Add optional tags and notes

You can include tags and notes to capture more context about why a user gave positive or negative feedback.

Command line

curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/feedback" \
  -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
  -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "alg_msg_xyz789",
    "agentId": "$AGENT_ID",
    "vote": 0,
    "tags": ["inaccurate", "incomplete"],
    "notes": "The response did not include the return policy link."
  }'

const appID = "ALGOLIA_APPLICATION_ID";
const apiKey = "ALGOLIA_SEARCH_API_KEY";
const agentId = "AGENT_ID";

const response = await fetch(
  `https://${appID}.algolia.net/agent-studio/1/feedback`,
  {
    method: "POST",
    headers: {
      "X-Algolia-Application-Id": appID,
      "X-Algolia-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messageId: "alg_msg_xyz789",
      agentId,
      vote: 0,
      tags: ["inaccurate", "incomplete"],
      notes: "The response did not include the return policy link.",
    }),
  }
);
const data = await response.json();
console.log(data);

Endpoint reference

For full details on the POST /agent-studio/1/feedback endpoint, see the Agent Studio API reference.

Constraints and error handling

• One feedback per message: each application can submit one vote per message. If you send a second feedback request for the same message, the endpoint returns a 400 error.
• Message scope: the messageId must belong to a conversation under the authenticated app. You can’t submit feedback for messages from other applications.
• Authentication: your API key must have the search ACL, and your application must have the Agent Studio feature enabled. If either is missing, the endpoint returns a 403 error.

Design your UI to disable the feedback button after a user votes, preventing duplicate submission attempts.

See also

• Agent Studio API overview
• Conversations
• Analytics