Dashboard/Algolia-Central/Knowledge/AgentStudio/06-multi-index-routing.md
Algolia-Central

Knowledge/AgentStudio/06-multi-index-routing.md

06 — Multi-Index Routing

This is the most consequential architectural decision in the whole RC3 Phoenix refactor. Get it wrong and we re-platform later. Get it right and the rest of the agent design follows naturally.

The question

Algolia Central will eventually contain content from many sources: Algolia documentation, Zendesk support, Academy training, marketing, customer stories, blog, changelog, API reference, possibly Discourse community. Today everything is in 2 indices (algolia-central_atlas for case studies + algolia-central_enterprise_ledger for everything else, with source-type filters).

Three architectures are on the table:

  • A. Single agent, single index. Everything in one big index, all queries against it.
  • B. Single agent, N indices. One agent with algolia_search_index tool configured with N indices (zendesk + academy + docs + marketing + ...). Agent decides which to query per turn based on per-index descriptions.
  • C. Orchestrator + SME (subject matter expert) agents. One main agent calls separate per-content-type agents as tools (via MCP or via custom client-side wrappers around /completions). Each SME owns one index.

Direct answer

Option B is the right architecture. It is what DocSearch and SW-Financial actually do. Option C is NOT what DocSearch does — it's an architecture that's possible to build with Agent Studio but not the documented production pattern. Option A is what we have today; it doesn't scale to the content-engagement vision.

The rest of this section is the evidence and the why.

What DocSearch actually does (verifiable)

docs/research/agent-studio-agents/docsearch-demo.json — the production DocSearch demo agent — has exactly this configuration:

  • 1 agent.
  • 1 tool: algolia_search_index.
  • 3 indices in that one tool:
  • demo_zendesk_articles_prod_2025 (Zendesk support content)
  • demo_algolia_documentation_2025 (official documentation)
  • demo_discourse_posts_2023 (community forum)
  • Routing happens in the prompt, not in agent topology. The instructions explicitly say:

    "Always prioritize the most recent and official information (documentation > zendesk > discourse, when in doubt)."

There is NO orchestrator agent, NO per-source SME agent, NO inter-agent calls. One agent reads the user's question, decides which of the 3 indices to query, queries them, synthesizes. Per the prompt: "Combine information from multiple sources if necessary. Reference the source ('According to Algolia Documentation...' or 'From a Zendesk article...')."

This is Option B in its simplest form.

What SW-Financial does (Algolia's customer reference)

docs/research/our-agents/sw-financial-agent.json — Algolia's published reference agent for the AskAI template:

  • 1 agent.
  • 1 tool: algolia_search_index.
  • 6 indices in that one tool:
  • SW_Financial_PROD_US_EN_Advisors
  • SW_Financial_PROD_US_EN_Pages
  • SW_Financial_PROD_US_EN_FAQ
  • SW_Financial_PROD_US_EN_Products
  • SW_Financial_PROD_US_EN_Promotions
  • SW_Financial_PROD_US_EN_Documents
  • Each index has a description that doubles as a routing instruction:
  • "Advisors → expert guidance, advisor recommendations, personalized investment support"
  • "Pages → educational content, financial literacy"
  • "FAQ → quick, direct answers"
  • "Products → financial products and services"
  • "Promotions → offers, rewards, deals"
  • "Documents → official forms, disclosures, reports"
  • The prompt has a Multi-Intent Handling section explicitly:
  • "Financial education queries → Pages + Products"
  • "Product comparison or benefits → Products + Promotions"
  • "Account or feature questions → FAQ + Products"
  • "Complex financial planning → Pages + Products + Advisors"

Six indices, one tool, prompt-level routing. Same pattern as DocSearch, scaled up.

SW-Healthcare follows the same shape with 4 indices (Products, Pages, FAQ, Doctors). Alpha-Grocery does it with 3 (Ingredients, Recipes, Products).

Multi-index inside one tool is Algolia's blessed AskAI pattern. The platform supports up to 10 indices per tool.

Why Option B works

Built-in metadata enrichment per index

Per 02-tools.md §1.3, when you configure algolia_search_index with a list of indices, Agent Studio reads each index's settings (attributesForFaceting, searchableAttributes, custom ranking) and injects them into the LLM-visible tool description as enhancedDescription. The LLM sees the available facets and valid values per index. This means per-index intelligence is automatic. Routing accuracy improves the moment you split content across well-described indices, with zero extra prompt work.

Parallel queries, single LLM call

The platform supports parallel querying inside a single algolia_search_index tool call. The LLM can query multiple indices in one round-trip, get all results, synthesize. Total LLM round-trips: 1 search + 1 synthesis = 2. Compare to Option C, where each SME = full LLM round-trip = 2N round-trips for N SMEs. With 4-6 SMEs that's 8-12 round-trips for the same workload. Latency multiplies linearly.

Each index keeps its own search tuning

Putting Zendesk content in one index means it can have Zendesk-style ranking (recency, vote_sum, support tier). Docs gets docs ranking (priority, hierarchy depth). Marketing gets marketing ranking (campaign weight, recency). Custom ranking, synonyms, rules all live at the index level. You can't get this with one big index, and you don't get it any better with SME agents — you get it via the indices themselves regardless of agent topology.

This is the key insight: the value of "per-content-type intelligence" lives in the index configuration, not in the agent topology.

Low migration risk

Today: 2 indices. To go to Option B with 6-8 indices, we (a) split the existing data, (b) add the new sources via connectors, (c) update Elena/Bruno/Maverick's algolia_search_index tool config to list the new indices with descriptions, (d) update prompt's Multi-Intent Handling section. Zero new agents, zero inter-agent communication, zero new failure modes.

Why Option C (SME-per-index agents) is wrong for us

It's not a documented Agent Studio pattern

The platform's client_side tool type is round-trip frontend execution. The mcp_tools type connects to external services. Neither is "call another Agent Studio agent." Technically you could MCP-wrap the /completions endpoint and treat each SME as an MCP tool, but Agent Studio does NOT advertise this as a pattern, and the demo apps don't show it. Building it means working against the platform's grain.

Latency multiplies with each SME

Each SME = full LLM round-trip = 2-5+ seconds (depending on model). With 4-6 SMEs queried for a complex question, that's 10-30+ seconds before the orchestrator even starts synthesizing. The same workload in Option B is one LLM call to pick indices + parallel index queries + one LLM call to synthesize.

We're already at 30+ seconds with our current text-generating Elena/Bruno. Going to SME-per-index would make this worse, not better.

Algolia's evolution went the OTHER direction

Look at the deprecated multi-agent shopping pattern in the demo app: - alpha-fashion-orchestrator (classifier agent) - alpha-fashion-fast (Q&A worker) - alpha-fashion-product-discovery (search worker) - alpha-fashion-nav-suggestions (suggestion worker) - alpha-fashion-pdp-suggestions (PDP worker) - alpha-fashion-pdp (PDP worker)

This was the original pattern. Algolia's team consolidated these into fashion-shopping-assistant — ONE agent with 13 tools and prompt-level routing. They explicitly moved AWAY from multi-agent. Reasons (inferred from agent timestamps and the 50-agent inventory): - Routing latency - Loss of conversational context across agent handoffs - Harder to debug - More to tune (5 prompts × N verticals = sprawl)

We'd be reinventing the deprecated pattern.

Rate limits cap the multi-agent approach

The platform-wide rate limit is 100 requests per minute per application (per 05-api-reference.md §1). Each user turn in Option C = 1 orchestrator call + N SME calls = N+1 requests. If a single user generates 5+ requests per turn, we hit the rate limit at 20 concurrent users. In Option B, one user turn = 1 search request + 1 LLM completion = 2 requests, supporting 50 concurrent users at the same throughput.

"Each SME has focused context" is solved by index descriptions

The argument FOR Option C is: "Each SME has a focused prompt that knows just its content type, so it produces better answers."

But this is solved without splitting agents. Each index in algolia_search_index already has its own description and enhancedDescription (full facet catalog). When the agent queries one index, the search results come back tagged with that index's structure. The LLM gets the same focus per-index that an SME agent would have, without the latency cost of separate LLM round-trips.

If a content type genuinely needs a wildly different prompt (different tone, different output structure, different synthesis rules), that's a sign the content shouldn't be in the same agent at all — split it into a separate top-level agent invoked by the user, not as a sub-agent.

Where Option C IS legitimate

There are scenarios where SME-per-index agents make sense:

Different domains with regulatory boundaries

Healthcare + Financial + Legal in one app, where each domain has separate compliance requirements (HIPAA, SOX, etc.) and the SMEs need to enforce different rules. Splitting agents lets each have its own information guard, its own retention policy, its own audit trail.

Algolia Central is not this case. All our content is "Algolia knowledge" — same domain, same compliance posture, same audience.

One content type SO large the prompt can't hold the routing

If you have 50+ indices, no single agent prompt can describe all routing rules clearly. Splitting into a few coordinator agents, each handling a subset of indices, becomes worth the latency.

Algolia Central is not this case. Estimated 6-10 indices total. Easily fits in one agent.

Truly different output formats

If one content type needs Mermaid diagrams (architecture content) and another needs code blocks (docs), and a third needs marketing prose (case studies), that's three different output shapes. You COULD split agents. But the better solution is one agent with multiple render tools — render_architecture_diagram, render_code_block, render_evidence_card — each tool's layoutComponent handles its specific format.

That's what Bruno needs (Mermaid) and Elena needs (code blocks + evidence cards). Same agent shape, different tools.

Based on the above, here's the proposed index split for Algolia Central:

Index Content Custom ranking signals
algolia-central_atlas Curated case studies, customer quotes, ROI metrics, business scenarios (already exists) priority, verification_status
algolia-central_docs Official documentation, API references, guides priority, hierarchy depth, freshness
algolia-central_zendesk Support knowledge base articles promoted, vote_sum, recency
algolia-central_academy Algolia Academy training content course completion priority, freshness
algolia-central_marketing Marketing pages, landing pages, product pages campaign weight, recency
algolia-central_blog Blog posts, articles recency, engagement
algolia-central_changelog Product changelog, release notes recency (heavily)
algolia-central_customer_stories Customer story long-form content priority, vertical match

8 indices, well within the 10-index ceiling. Each has its own custom ranking, synonyms, rules. Agent's algolia_search_index tool config lists all 8. Per-index descriptions guide the LLM.

This is a starting point — actual splits should be validated against R1-R6 research outputs (connector inventory, data normalization). But the topology — 1 agent, 1 tool, 8 indices — is the architectural commitment.

Per-index description writing

The per-index description field is how the LLM picks the right index. It is a PROMPT, not metadata. Production examples:

Good description (from SW Financial):

"Use this index when users are seeking expert financial guidance, advisor recommendations, or personalized investment support."

Better description (specific data + use cases):

"Algolia documentation: official product docs, API reference, integration guides, technical tutorials. Use this index for HOW-TO questions, API behavior, configuration syntax, and feature reference. Authoritative source — prefer over Zendesk and blog when both have coverage."

Bad description:

"Documents."

Rules of thumb: - Lead with what the data IS, not how to use it (the LLM infers usage from data shape) - Include source-of-truth ranking ("authoritative", "community-contributed", "promotional") so the LLM knows when to prefer this over other indices - Mention exclusions where overlap is likely ("docs covers feature behavior; for support resolution prefer zendesk")

Per-index searchParameters use cases

When configuring an index, searchParameters lets you bake in defaults at the tool level:

Parameter When to use
filters Hard restriction — only published docs, only active products, only English content
attributesToRetrieve Limit returned fields to keep results compact for the LLM
hitsPerPage Control how many results per query (default ~5-10 for AskAI; ~20-50 for shopping)
attributesToHighlight Useful for citation extraction (snippets become available for the LLM to quote)
facets Expose specific facets even if not in attributesForFaceting
analytics, clickAnalytics Enable for production usage tracking

Example, for the Zendesk index:

"searchParameters": {
  "filters": "is_published:true",
  "attributesToRetrieve": ["title", "url", "section.name", "plain_body", "vote_sum"],
  "attributesToHighlight": ["title", "plain_body"],
  "hitsPerPage": 5
}

Migration path from today

Current state: Elena and Bruno each have 2 indices (algolia-central_atlas + algolia-central_enterprise_ledger).

Target state: All three agents (Maverick post-migration + Elena + Bruno) have 6-8 indices configured per appropriate-to-role.

Migration steps (high level — implementation is in R1-R6 research scope): 1. Define canonical schema across content types (R7). 2. Add connectors / data ingestion for missing sources (R1, R4). 3. Split algolia-central_enterprise_ledger into source-specific indices. 4. Configure per-index custom ranking, synonyms, rules. 5. Update Elena/Bruno/Maverick algolia_search_index tool configs to list all 8 indices. 6. Update prompts' Data Sources + Multi-Intent Handling sections. 7. Test routing accuracy against held-out queries.

No agent topology change required. This is a content + index restructure, not an agent restructure.

Open questions for R-track research

  • Q-IDX-1: Should every agent (Maverick, Elena, Bruno) see all 8 indices, or should each agent's tool config list only the indices relevant to its role? (E.g., Bruno doesn't need marketing or customer_stories; Maverick needs all of them.)
  • Q-IDX-2: Per-pilot index naming — Algolia Central has algolia-central_*, but Sherwin Williams will have sherwin_*. Is the agent prompt parameterizable, or do we generate per-pilot agent variants?
  • Q-IDX-3: What's the right index granularity for blog content — one index, or split by year / topic / author?

These are not blocking the architectural decision. Option B is committed regardless. These are tuning questions for after the topology is in place.

What this section does NOT cover