Knowledge/AgentStudio/README.md
Agent Studio Knowledge Base
Project-scoped. This knowledge base is for Algolia Central / RC3 Phoenix. It is not generic agent guidance. It synthesizes what we learned from (a) ~34 official Algolia documentation pages, (b) 50 demo agents in Algolia's app
Q6N17K5UHW, and (c) our own 5 agents in app0EXRPAXB56.
Why this exists
We are doing three pieces of work that all need the same foundation: 1. Prompt refactoring — Maverick, Elena, Bruno prompts are bloated with persona theatre, Unicode dividers, overlapping rule sections, and XML output specs that should be tools. 2. Agent refactoring — current architecture treats Agent Studio as a text endpoint. Production pattern uses it as a tool-use platform. 3. Tool building — Elena and Bruno have 1 tool each (search). Production agents have 2-13 tools depending on archetype. We need to know which archetype applies to us before designing tools.
This knowledge base is the reference. Every decision in those three workstreams should cite a section here. If a section is wrong or out of date, fix it here first, then act.
How to use it
Skim the routing table. Read the section relevant to the task at hand. Don't load all 12 sections every time.
| If you're doing… | Read first | Then |
|---|---|---|
| Refactoring an existing agent's prompt | 03-prompt-patterns | 10-our-agents-vs-best-practice |
| Choosing tool set for a new agent | 02-tool-types | 04-agent-archetypes, 11-decision-rubrics |
| Deciding output shape (text vs tools) | 05-output-shape-decision | 04-agent-archetypes |
| Designing index strategy / multi-index routing | 06-multi-index-routing | 11-decision-rubrics |
| Picking a platform feature (memory/suggestions/etc) | 07-platform-features | 01-platform-fundamentals |
| Building or refactoring frontend integration | 12-ui-and-instantsearch | 08-frontend-integration |
| Asking "should we split this agent into multiple agents?" | 09-evolution-deprecated-patterns | 11-decision-rubrics, 06-multi-index-routing |
| Need a worked example for a specific archetype | evidence/{archetype}-pattern.md |
04-agent-archetypes |
| Cold-starting a new session on Agent Studio work | This file → 04-agent-archetypes → 10-our-agents-vs-best-practice | section relevant to specific task |
Section index
| # | Topic | One-line |
|---|---|---|
| 01 | Platform fundamentals | What Agent Studio is, the agent object model, instructions vs systemPrompt, the config object |
| 02 | Tool types | All 6 tool types, their lifecycle, when to use which, schemas |
| 03 | Prompt patterns | Section structure used by production agents, what NOT to put in prompts, anti-patterns we have today |
| 04 | Agent archetypes | The 9 distinct production archetypes, with per-archetype tool counts and prompt sizes |
| 05 | Output shape decision | Text vs structured tools — the framework for choosing, the cost of XML-in-text |
| 06 | Multi-index routing | Critical. Single-agent-many-indices vs SME-per-index — what DocSearch does, what we should do |
| 07 | Platform features | Memory, suggestions, caching, conversation IDs, secured user tokens, retention |
| 08 | Frontend integration | Chat widget, FilterSuggestions widget, addToolResult round-trip, layoutComponent |
| 09 | Evolution & deprecated patterns | Multi-agent → single-agent shift, what NOT to rebuild |
| 10 | Our agents vs best practice | Gap table: Maverick / Elena / Bruno today vs production patterns. The action page. |
| 11 | Decision rubrics | "When to add a tool", "When to split agents", "When to add an index", trees |
| 12 | UI refactoring + InstantSearch adoption | Where Algolia native libraries should replace our custom frontend code |
evidence/ |
Pattern reference cards | Per-archetype canonical schemas extracted from demo agents |
Source materials (verifiable evidence)
This knowledge base derives from sources that are checked into the repo. Every claim should cite a source by file path.
Official Algolia documentation (~34 URLs, fetched 2026-04-22 and 2026-04-24):
- docs/research/agent-studio-docs/01-core-setup.md — dashboard, quickstart, LLM providers, agent config, prompting
- docs/research/agent-studio-docs/02-tools.md — tools overview, Search tool, client-side tools, MCP tools, security
- docs/research/agent-studio-docs/03-capabilities.md — conversations, caching, overview
- docs/research/agent-studio-docs/04-frontend-widgets.md — Chat (React + JS), FilterSuggestions
- docs/research/agent-studio-docs/05-api-reference.md — REST endpoints, schemas, ACLs
- docs/research/agent-studio-docs/06-blogs-and-use-cases.md — architecture philosophy, LLM Leaderboard
- docs/research/agent-studio-docs/07-mcp-server.md — Public MCP + Productivity MCP
Demo app (Q6N17K5UHW) — 50 agent configs:
- docs/research/agent-studio-agents/*.json — every agent we analyzed
Our app (0EXRPAXB56) — 5 agent configs:
- docs/research/our-agents/elena-solutions-engineer.json
- docs/research/our-agents/bruno-solutions-architect.json
- docs/research/our-agents/sw-financial-agent.json
- docs/research/our-agents/sw-healthcare-agent.json
- docs/research/our-agents/sw-grocery-shopping-agent.json
Repo digests (predecessor of this wiki):
- docs/research/AGENT-STUDIO-LEARNINGS.md — combined notes (now superseded by this wiki for cross-session knowledge)
- docs/research/AGENT-STUDIO-FULL-INVENTORY.md — tool catalog
- docs/research/AGENT-STUDIO-REFERENCE-AGENT.md — Luxury Fashion deep dive
What this wiki is NOT
- Not a tutorial on building agents from scratch. Algolia's official docs do that. We point to them.
- Not a record of every demo agent.
evidence/50-demo-agents-summary.csvsummarizes; full configs stay in repo. - Not committed strategy decisions. Those go to
Messaging-Positioning-Pivot.mdorDecisionLog.md. This wiki is reference knowledge. - Not generic AI agent advice. Algolia Agent Studio specific, scoped to RC3 Phoenix.
Update protocol
- Add to a section when you learn something new from official docs, demo agents, or production experience.
- If a claim turns out to be wrong, correct it here BEFORE acting on the corrected understanding.
- New evidence card under
evidence/per discovered archetype or canonical pattern. - When a wiki section drives a committed decision, link to the resulting decision in
DecisionLog.md. - Cite sources by file path. "I think the platform supports X" is not acceptable; "per
02-tools.md§1.7, the platform supports X" is.
Vault routing entry
This wiki is referenced from Active-Context.md under the routing table. Any session asking "how should we [refactor a prompt | choose tools | design indices | refactor the UI]?" should land here.