> ## Documentation Index > Fetch the complete documentation index at: https://www.algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Compact Context > Summarize the older part of a conversation into a single user message via the caller's LLM. Everything except the trailing `keepLastMessages` messages is summarized; the summary is returned as a user-role message followed by the kept tail verbatim. Your provider runs the summary, so the provider adds the cost to your account. A conversation too large for the summarizer's context window is split into chunks that each fit, summarized concurrently, then merged in a reduce pass - so payload size alone does not fail the request. When the conversation still cannot be summarized (it needs more chunks than the server allows, or the chunk summaries will not converge), the response is a `400`, not a `500`. Two optional controls shape the output. `instructions` adds caller guidance inside the server-owned prompt frame, so it steers the summary without the model echoing the wording back. `targetTokensEstimate` sets a desired summary size, translated into word-count guidance. The `compaction` block reports what happened: `compacted` is `false` when the payload passed through untouched (nothing older than the kept tail), alongside chunk/pass counts and the summarizer's own token usage. **Required ACL:** `search` ## OpenAPI ````yaml specs/agent-studio.yml post /1/unstable/context/compact openapi: 3.1.0 info: title: Agent Studio API description: > The Agent Studio API lets you build and operate generative AI agents that use Algolia data, tools, and your chosen LLM provider. Use it to create, configure, publish, and update agents, then generate chat completions grounded in live data from your Algolia indices. You can manage LLM providers, Agent Studio tools, conversations, feedback, secret keys, user data, caching, and application settings for your AI experiences. ## Client libraries Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps. The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla). For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/libraries). ## Base URLs Base URLs for the Agent Studio API: - `https://{APPLICATION_ID}.algolia.net` - `https://{APPLICATION_ID}-dsn.algolia.net`. If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra), this ensures that requests are sent to servers closest to users. Both URLs provide high availability by distributing requests with load balancing. All Agent Studio paths are prefixed with `/agent-studio`. **All requests must use HTTPS.** ## Retry strategy To guarantee high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks: - `https://{APPLICATION_ID}-1.algolianet.com` - `https://{APPLICATION_ID}-2.algolianet.com` - `https://{APPLICATION_ID}-3.algolianet.com` These URLs use a different DNS provider than the primary URLs. Randomize this list to ensure an even load across the three servers. All Algolia API clients implement this retry strategy. ## Authentication Add these headers to authenticate requests: - `x-algolia-application-id`. Your Algolia application ID. - `x-algolia-api-key`. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). ## Rate limits The Agent Studio API rate-limits requests. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers with the current limit. When you exceed the limit, the API returns a `429` status with a `Retry-After` header. ## Request format Request bodies must be JSON objects. ## Parameters Parameters are passed as query parameters for GET and DELETE requests, and in the request body for POST and PUT requests. Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). Non-ASCII characters must be UTF-8 encoded. Plus characters (`+`) are interpreted as spaces. ## Response status and errors The Agent Studio API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses. Error responses have a `message` property with more information. ## Version The current version of the Agent Studio API is version 1, indicated by the `/1/` in each endpoint's URL. version: 1.0.0 servers: - url: https://{APPLICATION_ID}.algolia.net/agent-studio description: Agent Studio API. variables: APPLICATION_ID: default: EXAMPLE description: Your Algolia application ID. security: - appId: [] apiKey: [] tags: - name: Agents description: Manage your agents. - name: Allowed Domains description: Restrict where an agent's API key may be used. - name: Completions description: Generate completions. - name: Configurations description: Manage Agent Studio related application configurations. - name: Context description: Compact or trim conversation context before sending it to completions. - name: Conversations description: View, export, and delete conversation history. - name: Feedback description: Capture user feedback on agent responses. - name: Providers description: Manage your LLM providers. - name: Secret Keys description: Manage secret keys used to authenticate requests. - name: Tasks description: Run configured agent tasks. - name: User Data description: Manage end-user data associated with conversations. paths: /1/unstable/context/compact: post: tags: - Context summary: Compact Context description: >- Summarize the older part of a conversation into a single user message via the caller's LLM. Everything except the trailing `keepLastMessages` messages is summarized; the summary is returned as a user-role message followed by the kept tail verbatim. Your provider runs the summary, so the provider adds the cost to your account. A conversation too large for the summarizer's context window is split into chunks that each fit, summarized concurrently, then merged in a reduce pass - so payload size alone does not fail the request. When the conversation still cannot be summarized (it needs more chunks than the server allows, or the chunk summaries will not converge), the response is a `400`, not a `500`. Two optional controls shape the output. `instructions` adds caller guidance inside the server-owned prompt frame, so it steers the summary without the model echoing the wording back. `targetTokensEstimate` sets a desired summary size, translated into word-count guidance. The `compaction` block reports what happened: `compacted` is `false` when the payload passed through untouched (nothing older than the kept tail), alongside chunk/pass counts and the summarizer's own token usage. operationId: compactContext requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ContextCompactRequest' responses: '200': description: Successful Response. content: application/json: schema: $ref: '#/components/schemas/ContextResponse' '422': description: Validation Error. content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: csharp label: C# source: |- // Initialize the client var client = new AgentStudioClient( new AgentStudioConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY") ); // Call the API var response = await client.CompactContextAsync( new ContextCompactRequest { ProviderID = "c2905529-b933-4b69-87ec-75f9829d5f59", Model = "gpt-4o-mini", Messages = new MessagesUnion( new List { new MessageV4(new UserMessageV4 { Role = "user", Content = "Hello, how are you?" }), } ), } ); // print the response Console.WriteLine(response); - lang: dart label: Dart source: |- // Initialize the client final client = AgentStudioClient( appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY'); // Call the API final response = await client.compactContext( contextCompactRequest: ContextCompactRequest( providerID: "c2905529-b933-4b69-87ec-75f9829d5f59", model: "gpt-4o-mini", messages: [ UserMessageV4( role: "user", content: "Hello, how are you?", ), ], ), ); // print the response print(response); - lang: go label: Go source: >- // Initialize the client client, err := agentStudio.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY") if err != nil { // The client can fail to initialize if you pass an invalid parameter. panic(err) } // Call the API response, err := client.CompactContext(client.NewApiCompactContextRequest( agentStudio.NewEmptyContextCompactRequest(). SetProviderID("c2905529-b933-4b69-87ec-75f9829d5f59"). SetModel("gpt-4o-mini"). SetMessages(agentStudio.ArrayOfMessageV4AsMessagesUnion( []agentStudio.MessageV4{*agentStudio.UserMessageV4AsMessageV4( agentStudio.NewEmptyUserMessageV4().SetRole("user").SetContent("Hello, how are you?"))})), )) if err != nil { // handle the eventual error panic(err) } // print the response print(response) - lang: java label: Java source: >- // Initialize the client AgentStudioClient client = new AgentStudioClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY"); // Call the API ContextResponse response = client.compactContext( new ContextCompactRequest() .setProviderID("c2905529-b933-4b69-87ec-75f9829d5f59") .setModel("gpt-4o-mini") .setMessages(MessagesUnion.ofListOfMessageV4(Arrays.asList(new UserMessageV4().setRole("user").setContent("Hello, how are you?")))) ); // print the response System.out.println(response); - lang: javascript label: JavaScript source: >- // Initialize the client const client = agentStudioClient('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY'); // Call the API const response = await client.compactContext({ providerID: 'c2905529-b933-4b69-87ec-75f9829d5f59', model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello, how are you?' }], }); // print the response console.log(response); - lang: kotlin label: Kotlin source: >- // Initialize the client val client = AgentStudioClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY") // Call the API var response = client.compactContext( contextCompactRequest = ContextCompactRequest( providerID = "c2905529-b933-4b69-87ec-75f9829d5f59", model = "gpt-4o-mini", messages = MessagesUnion.ofListOfMessageV4( listOf(UserMessageV4(role = "user", content = "Hello, how are you?")) ), ) ) // print the response println(response) - lang: php label: PHP source: >- // Initialize the client $client = AgentStudioClient::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY'); // Call the API $response = $client->compactContext( ['providerID' => 'c2905529-b933-4b69-87ec-75f9829d5f59', 'model' => 'gpt-4o-mini', 'messages' => [ ['role' => 'user', 'content' => 'Hello, how are you?', ], ], ], ); // print the response var_dump($response); - lang: python label: Python source: >- # Initialize the client # In an asynchronous context, you can use AgentStudioClient instead, which exposes the exact same methods. client = AgentStudioClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY") # Call the API response = client.compact_context( context_compact_request={ "providerID": "c2905529-b933-4b69-87ec-75f9829d5f59", "model": "gpt-4o-mini", "messages": [ { "role": "user", "content": "Hello, how are you?", }, ], }, ) # print the response print(response) - lang: ruby label: Ruby source: >- # Initialize the client client = Algolia::AgentStudioClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY") # Call the API response = client.compact_context( Algolia::AgentStudio::ContextCompactRequest.new( provider_id: "c2905529-b933-4b69-87ec-75f9829d5f59", model: "gpt-4o-mini", messages: [Algolia::AgentStudio::UserMessageV4.new(role: "user", content: "Hello, how are you?")] ) ) # print the response puts(response) - lang: scala label: Scala source: >- // Initialize the client val client = AgentStudioClient(appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY") // Call the API val response = Await.result( client.compactContext( contextCompactRequest = ContextCompactRequest( providerID = "c2905529-b933-4b69-87ec-75f9829d5f59", model = "gpt-4o-mini", messages = MessagesUnion( Seq( UserMessageV4( role = "user", content = "Hello, how are you?" ) ) ) ) ), Duration(100, "sec") ) // print the response println(response) - lang: swift label: Swift source: >- // Initialize the client let client = try AgentStudioClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY") // Call the API let response = try await client.compactContext(contextCompactRequest: ContextCompactRequest( providerID: "c2905529-b933-4b69-87ec-75f9829d5f59", model: "gpt-4o-mini", messages: MessagesUnion.arrayOfMessageV4([MessageV4.userMessageV4(UserMessageV4( role: "user", content: "Hello, how are you?" ))]) )) // print the response print(response) - lang: cURL label: curl source: |- curl --request POST \ --url https://example.algolia.net/agent-studio/1/unstable/context/compact \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-algolia-api-key: ALGOLIA_API_KEY' \ --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \ --data ' { "providerID": "lorem", "model": "lorem", "messages": [ { "id": "lorem", "role": "user", "content": "lorem", "parts": [ { "type": "text", "text": "lorem" } ], "annotations": [ {} ] } ], "keepLastMessages": 4, "instructions": "lorem", "targetTokensEstimate": 64 } ' components: schemas: ContextCompactRequest: properties: messages: $ref: '#/components/schemas/MessagesUnion' model: type: string title: model description: Model name (e.g., gpt-4o-mini). providerID: type: string title: providerid description: Provider UUID for LLM credentials. instructions: type: string maxLength: 2000 title: instructions description: >- Extra guidance for the summarizer (e.g. 'keep every product reference'). Appended inside the server-owned prompt frame, so it steers the summary without the model echoing your wording back into it. keepLastMessages: type: integer minimum: 0 title: keeplastmessages description: >- Number of trailing messages kept verbatim; everything older is summarized. default: 4 targetTokensEstimate: type: integer minimum: 64 title: targettokensestimate description: >- Desired size of the final summary, in tokens. Translated into word-count guidance for the summarizer (best-effort, not a hard cap). Omit to let the summarizer default to a concise summary. type: object required: - providerID - model - messages title: contextCompactRequest description: >- LLM-summarization request. Your provider runs the summary, so the provider adds the cost to your account. ContextResponse: properties: messages: $ref: '#/components/schemas/MessagesUnion' stats: $ref: '#/components/schemas/ContextStats' compaction: oneOf: - $ref: '#/components/schemas/CompactionStats' - type: 'null' type: object required: - messages - stats title: contextResponse description: Result of a context operation, ready to feed to ``/completions``. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: detail type: object title: hTTPValidationError MessagesUnion: oneOf: - items: $ref: '#/components/schemas/MessageV4' type: array - items: $ref: '#/components/schemas/MessageV5' type: array ContextStats: properties: messagesAfter: type: integer title: messagesafter description: Message count after the operation. messagesBefore: type: integer title: messagesbefore description: Message count before the operation. messagesDropped: type: integer title: messagesdropped description: Net reduction in message count (before - after). tokensAfterEstimate: type: integer title: tokensafterestimate description: Estimated token count after the operation. tokensBeforeEstimate: type: integer title: tokensbeforeestimate description: Estimated token count before the operation. type: object required: - messagesBefore - messagesAfter - tokensBeforeEstimate - tokensAfterEstimate - messagesDropped title: contextStats description: >- Before/after accounting for a context operation. ``tokens*Estimate`` fields are heuristic, not an authoritative provider count. ``messages_dropped`` is the net reduction in message count (``messages_before - messages_after``); for compaction the summarized tail is replaced by a single summary message, so this reflects the net change rather than a raw delete count. CompactionStats: properties: compacted: type: boolean title: compacted description: >- Whether a summary was actually produced. `false` means the payload passed through untouched (nothing older than the kept tail, or no summarizable text). chunksProcessed: type: integer title: chunksprocessed description: >- Number of transcript chunks summarized in the map phase. 0 on passthrough, 1 when the transcript fit in a single summarizer call. default: 0 passes: type: integer title: passes description: >- Number of summarizer rounds. 1 for a direct summary; 2+ when chunk summaries had to be merged (map-reduce). default: 0 summarizerCompletionTokens: oneOf: - type: integer - type: 'null' title: summarizercompletiontokens description: >- Provider-reported output tokens summed across every summarizer call. Null when the provider reported no usage metadata. summarizerPromptTokens: oneOf: - type: integer - type: 'null' title: summarizerprompttokens description: >- Provider-reported input tokens summed across every summarizer call. Null when the provider reported no usage metadata. targetTokensEstimate: oneOf: - type: integer - type: 'null' title: targettokensestimate description: >- The requested output budget, echoed back when `targetTokensEstimate` was set. type: object required: - compacted title: compactionStats description: >- Compaction-specific telemetry, returned only by ``/context/compact``. ``compacted`` makes the short-conversation passthrough detectable: without it a caller cannot tell a no-op from a summary that happened to be short. ValidationError: properties: loc: items: $ref: '#/components/schemas/LocationItemUnion' type: array title: location msg: type: string title: message type: type: string title: errorType type: object required: - loc - msg - type title: validationError MessageV4: oneOf: - $ref: '#/components/schemas/UserMessageV4' - $ref: '#/components/schemas/AssistantMessageV4' discriminator: mapping: assistant: '#/components/schemas/AssistantMessageV4' user: '#/components/schemas/UserMessageV4' propertyName: role MessageV5: oneOf: - $ref: '#/components/schemas/UserMessageV5' - $ref: '#/components/schemas/AssistantMessageV5' discriminator: mapping: assistant: '#/components/schemas/AssistantMessageV5' user: '#/components/schemas/UserMessageV5' propertyName: role LocationItemUnion: oneOf: - type: string - type: integer UserMessageV4: properties: content: title: content type: string role: const: user default: user title: role type: string annotations: oneOf: - items: type: object additionalProperties: true type: array - type: 'null' default: null title: annotations id: oneOf: - type: string - type: 'null' default: null title: id parts: items: $ref: '#/components/schemas/TextPartV4' title: parts type: array required: - role - content title: userMessageV4 type: object AssistantMessageV4: properties: content: title: content type: string role: const: assistant default: assistant title: role type: string id: oneOf: - type: string - type: 'null' default: null title: id parts: items: $ref: '#/components/schemas/AssistantPartV4' title: parts type: array toolInvocations: $ref: '#/components/schemas/ToolInvocationsUnion' required: - role - content title: assistantMessageV4 type: object UserMessageV5: properties: role: const: user default: user title: role type: string id: oneOf: - type: string - type: 'null' default: null title: id metadata: oneOf: - $ref: '#/components/schemas/UserMessageMetadataV5' - type: 'null' parts: items: $ref: '#/components/schemas/TextPartV5' title: parts type: array title: userMessageV5 type: object required: - role AssistantMessageV5: properties: role: const: assistant default: assistant title: role type: string id: oneOf: - type: string - type: 'null' default: null title: id parts: items: $ref: '#/components/schemas/AssistantPartV5' title: parts type: array title: assistantMessageV5 type: object required: - role TextPartV4: properties: text: title: text type: string type: const: text default: text title: type type: string required: - text title: textPartV4 type: object AssistantPartV4: oneOf: - $ref: '#/components/schemas/StepStartPartV4' - $ref: '#/components/schemas/ReasoningPartV4' - $ref: '#/components/schemas/TextPartV4' - $ref: '#/components/schemas/ToolInvocationPartV4' ToolInvocationsUnion: oneOf: - items: $ref: '#/components/schemas/ToolInvocationV4' type: array - type: 'null' UserMessageMetadataV5: additionalProperties: true description: >- Client-supplied metadata on a v5 user message. `turn_context` is namespaced so other callers can use `metadata` for unrelated purposes without collision. Unknown keys are preserved and ignored by this pipeline. `turn_context` accepts any JSON object (arbitrarily nested values, no size caps). A value that cannot be serialized as JSON is rejected with a 422. properties: turnContext: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: turncontext title: userMessageMetadataV5 type: object TextPartV5: properties: text: title: text type: string type: const: text default: text title: type type: string required: - text title: textPartV5 type: object AssistantPartV5: oneOf: - $ref: '#/components/schemas/StepStartPartV5' - $ref: '#/components/schemas/TextPartV5' - $ref: '#/components/schemas/ReasoningPartV5' - $ref: '#/components/schemas/DataGuardrailViolationPartV5' - $ref: '#/components/schemas/DataPartV5' - $ref: '#/components/schemas/ToolPartV5' StepStartPartV4: properties: type: const: step-start default: step-start title: type type: string title: stepStartPartV4 type: object ReasoningPartV4: properties: reasoning: title: reasoning type: string type: const: reasoning default: reasoning title: type type: string required: - reasoning title: reasoningPartV4 type: object ToolInvocationPartV4: properties: toolInvocation: $ref: '#/components/schemas/ToolInvocationV4' type: const: tool-invocation default: tool-invocation title: type type: string required: - toolInvocation title: toolInvocationPartV4 type: object ToolInvocationV4: description: A tool invocation in a message. properties: toolCallId: title: toolcallid type: string toolName: title: toolname type: string args: additionalProperties: true title: args type: object argsHash: oneOf: - type: string - type: 'null' default: null title: argshash description: oneOf: - type: string - type: 'null' default: null title: description providerOptions: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: provideroptions requiresApproval: oneOf: - type: boolean - type: 'null' default: null title: requiresapproval result: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: result state: oneOf: - type: string - type: 'null' default: null title: state step: oneOf: - type: integer - type: 'null' default: null title: step required: - toolCallId - toolName title: toolInvocationV4 type: object StepStartPartV5: properties: type: const: step-start default: step-start title: type type: string title: stepStartPartV5 type: object ReasoningPartV5: properties: text: title: text type: string type: const: reasoning default: reasoning title: type type: string required: - text title: reasoningPartV5 type: object DataGuardrailViolationPartV5: description: >- A ``data-guardrail-violation`` part that an AI SDK v5 client sends back. Send this part to tell the completions endpoint that a guardrail blocked the previous turn. properties: data: $ref: '#/components/schemas/GuardrailViolationDataV5' type: const: data-guardrail-violation default: data-guardrail-violation title: type type: string required: - data title: dataGuardrailViolationPartV5 type: object DataPartV5: description: >- AI SDK v5 transient data part (``type`` prefixed with ``data-``). We emit these on the streamed assistant response (e.g. ``data-suggestions``, ``data-tool-approval``, ``data-*-usage``, etc.). The client echoes the whole assistant message back as history on the next turn, so the inbound schema must tolerate them or the entire request 422s. They carry UI payload only (not model context) and are dropped on conversion to internal messages. properties: type: title: type type: string data: type: object additionalProperties: true title: data required: - type title: dataPartV5 type: object ToolPartV5: description: A tool invocation in a message. properties: toolCallId: title: toolcallid type: string type: title: type type: string argsHash: oneOf: - type: string - type: 'null' default: null title: argshash description: oneOf: - type: string - type: 'null' default: null title: description errorText: oneOf: - type: string - type: 'null' default: null title: errortext input: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: input output: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: output outputMetadata: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: outputmetadata providerOptions: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: provideroptions rawInput: oneOf: - type: object additionalProperties: true - type: 'null' default: null title: rawinput requiresApproval: oneOf: - type: boolean - type: 'null' default: null title: requiresapproval state: $ref: '#/components/schemas/ToolState' terminal: oneOf: - type: boolean - type: 'null' default: null title: terminal required: - type - toolCallId title: toolPartV5 type: object GuardrailViolationDataV5: additionalProperties: true description: >- Payload of a persisted ``data-guardrail-violation`` part. The response stream sends the same fields: ``category``, ``guardrailType``, and ``fallbackResponse``. Unknown keys are tolerated so a newer client that carries extra violation detail still round-trips without a 422. properties: category: title: category type: string fallbackResponse: oneOf: - type: string - type: 'null' default: null title: fallbackresponse guardrailType: oneOf: - type: string - type: 'null' default: null title: guardrailtype required: - category title: guardrailViolationDataV5 type: object ToolState: type: string enum: - input-streaming - input-available - output-available - output-error securitySchemes: appId: type: apiKey in: header name: x-algolia-application-id description: Your Algolia application ID. apiKey: type: apiKey in: header name: x-algolia-api-key description: > Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference. ````