Create Completion

Create a completion for the specified agent.

This endpoint handles two types of requests:

1. Normal completion request: User message -> Agent response
2. Tool approval response: User approval -> Execute tool -> Agent response

Tool Approval Flow (for MCP tools with requiresApproval: true):

• Request 1: User sends message -> Agent requests tool call -> Return approval request
• Request 2: User approves -> Execute tool -> Agent continues with result

POST /1/agents/{agent_id}/completions

Create Completion

cURL

curl --request POST \
  --url https://{APPLICATION_ID}.algolia.net/agent-studio/1/agents/{agent_id}/completions \
  --header 'Content-Type: application/json' \
  --header 'X-Algolia-API-Key: <x-algolia-api-key>' \
  --header 'X-Algolia-Application-Id: <x-algolia-application-id>' \
  --data '
{
  "configuration": {
    "instructions": "<string>",
    "config": {},
    "tools": [
      {
        "name": "<string>",
        "description": "<string>",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": [
            "<string>"
          ]
        },
        "type": "client_side"
      }
    ],
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "providerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model": "<string>",
    "systemPrompt": "<string>"
  },
  "messages": [
    {
      "content": "<string>",
      "id": "<string>",
      "role": "user",
      "parts": [
        {
          "text": "<string>",
          "type": "text"
        }
      ]
    }
  ],
  "id": "<string>",
  "algolia": {
    "mcpServers": {},
    "searchParameters": {
      "products": {
        "attributesToRetrieve": [
          "title",
          "price"
        ],
        "distinct": false,
        "enablePersonalization": true,
        "filters": "category:electronics",
        "personalizationImpact": 100,
        "userToken": "user-123"
      }
    }
  },
  "toolApprovals": {}
}
'

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Required ACL: search

Headers

X-Algolia-API-Key · string · required

X-Algolia-Application-Id · string · required

X-Algolia-Secure-User-Token · string | null

Path Parameters

agent_id · string<uuid> string · required

Query Parameters

compatibilityMode · enum<string> · required

Compatibility mode for the completion API

Available options: ai-sdk-4, ai-sdk-5

stream · boolean · default: true

Whether to stream the response or not

cache · boolean · default: true

Use cached responses if available

memory · boolean | null

Set to false to disable memory (enabled by default)

Body

application/json

Request model for creating a completion for an assistant.

configuration · AgentTestConfiguration · object

Dynamic configuration for testing agents.

Show child attributes

messages · (UserMessageV4 · object | AssistantMessageV4 · object)[] (UserMessageV5 · object | AssistantMessageV5 · object)[]

UserMessageV4

AssistantMessageV4

Show child attributes

id · string | null

algolia · AgentCompletionAlgoliaParams · object

Show child attributes

toolApprovals · Toolapprovals · object

Show child attributes

Response

200

application/json

Successful Response