01 — Platform Fundamentals

What Agent Studio is

Agent Studio is Algolia's hosted agent runtime. It connects an LLM (OpenAI, Anthropic, Google Gemini, Azure OpenAI, OpenAI-compatible) to Algolia search and other tools, manages the orchestration loop, and exposes a single /completions REST endpoint.

It is NOT just a text-generation API. It is a tool-use platform. Treating it as a text endpoint (which is what we did with Elena and Bruno) leaves most of the platform's capability on the table.

Core architectural commitment (from Algolia's blogs): retrieval-first, not model-first. The LLM is the generation layer on top of structured, business-ranked search results. Improvements to search ranking, rules, merchandising, and personalization automatically improve the agent's answers. (Source: 06-blogs-and-use-cases.md §1.2.)

The agent object model

Every agent has these fields (per 05-api-reference.md §2.2):

instructions vs systemPrompt

Both are populated as the agent's prompt. The platform prepends systemPrompt before instructions (per 05-api-reference.md §2.2). In practice across the 50 demo agents:

• 48 of 50 demo agents have systemPrompt: null. Everything goes into instructions.
• The 2 exceptions are the SW Financial and SW Healthcare agents (templateType: "askai"), which use systemPrompt for a "Hierarchy of Instructions" block + Information Guard (prompt-injection defense), and instructions for the agent's behavior + tool-usage rules.
• Our Elena and Bruno populate BOTH heavily, with overlapping content — voice rules in instructions, persona identity in systemPrompt, but behavior rules split awkwardly between the two. This is an anti-pattern we will fix in 03-prompt-patterns.

Rule of thumb (from production evidence): - If you only have one of them, populate instructions and leave systemPrompt: null. - If you split, put identity + injection-defense + hierarchy-of-rules in systemPrompt; put behavior + tool-usage + intent-recognition in instructions. The SW pattern is the cleanest reference.

The config object

The config field carries feature flags. Production agents use this much more than we do. (Source: 05-api-reference.md §7 "Agent Config Object" and 03-capabilities.md §2-3.)

We currently use NONE of these on Elena/Bruno. SW agents use memory, suggestions, widgetType. See 07-platform-features.

The agent lifecycle

1. Draft — agent created via POST /1/agents. Editable via PATCH /1/agents/{id}.
2. Published — POST /1/agents/{id}/publish. Makes the agent live for /completions consumers.
3. Completion request — POST /1/agents/{id}/completions?compatibilityMode=ai-sdk-4&stream=true with messages array. Optionally id for memory, algolia.searchParameters for runtime overrides, toolApprovals for MCP approval flow.
4. Tool invocation — LLM analyzes available tools, selects, calls. Built-in tools execute server-side; client-side tools return tool-call requests to the app for execution + addToolResult.
5. Streaming response — SSE-style stream of text + tool-call events.

The completions API

POST https://{APP_ID}.algolia.net/agent-studio/1/agents/{AGENT_ID}/completions?compatibilityMode=ai-sdk-4&stream=true

Headers: - Content-Type: application/json - X-Algolia-Application-Id: {APP_ID} - X-Algolia-API-Key: {API_KEY} (Search ACL is sufficient — good for frontend) - X-Algolia-Secure-User-Token: {JWT} (optional, for authenticated user mode)

Body:

{
  "id": "alg_cnv_abc123",
  "messages": [
    { "id": "alg_msg_1", "role": "user", "content": "..." }
  ],
  "algolia": {
    "searchParameters": {
      "{indexName}": { "filters": "...", "userToken": "...", "enablePersonalization": true }
    }
  },
  "toolApprovals": { "{toolCallId}": { "approved": true, "timestamp": "..." } }
}

Source: 02-tools.md Appendix.

Rate limits and quotas

Per 05-api-reference.md §1: - 100 requests per minute per application — global Agent Studio ceiling. Apply to all completions endpoints together. - Up to 10 indices per algolia_search_index tool (parallel or sequential). - 3-5 tools per agent recommended; >10-15 discouraged. Production shopping assistants run 11-13 tools and work, but they're heavily tuned. - MCP tools: 10-second connection timeout. Max 10 headers per server. - Tool name: 3-64 chars, alphanumeric + underscores only.

ACL requirements

For frontend keys, only search is needed. This is significant — production frontends can call agents without admin ACL.

Supported LLM providers

LLM Leaderboard finding (per 06-blogs-and-use-cases.md §4): - Gemini 3.1 Flash Lite scored 92% quality at $0.002/query, ~5s latency. - GPT-5.4 scored 91% at $0.07/query (35x more expensive). - Claude Opus 4.6 scored 88% at $0.83/query (375x more expensive). - Extended thinking can HURT quality (GPT-5.4 with thinking: 89%, 48s). - 100x cost variance for similar quality.

Implication: Model choice is a major lever for both latency and cost. Our current Gemini 2.5 Flash is mid-tier. We have meaningful room to recover both axes by selecting more carefully — not by upgrading to the most expensive model, but by matching model to task.

Things easy to miss

1. Caching is first-message-only. Multi-turn conversations always call the LLM. Cache key includes messages + tool configs + agent config + date-awareness.
2. Conversation persistence is built-in. Pass id: "alg_cnv_..." and per-message id: "alg_msg_...". Title auto-generated from first user message (60 char max). Retention: 0/30/60/90 days via maxRetentionDays.
3. Memory can be disabled per-request via ?memory=false query param.
4. Cache can be bypassed per-request via ?cache=false.
5. Privacy mode (maxRetentionDays: 0) disables caching AND message-content storage; stores conversation metadata only.
6. Runtime search parameter overrides — frontend can adjust per-request via algolia.searchParameters in the completions request body. Tool config takes precedence; runtime adds.
7. Secured user tokens (JWT) provide row-level security via filters keyed on user identity. Use X-Algolia-Secure-User-Token header.
8. Beta status — Agent Studio is beta. Frontend widgets in particular ship breaking changes in minor versions.

What this section does NOT cover

• Tool types deep-dive — see 02-tool-types
• Prompt structure and patterns — see 03-prompt-patterns
• Multi-index strategy — see 06-multi-index-routing
• Platform features deep-dive — see 07-platform-features
• Frontend widgets and integration — see 08-frontend-integration, 12-ui-and-instantsearch