Dashboard/Algolia-Central/Knowledge/AgentStudio/04-agent-archetypes.md
Algolia-Central

Knowledge/AgentStudio/04-agent-archetypes.md

04 — Agent Archetypes

Production Algolia agents fall into 9 distinct archetypes. Each has a recognizable shape — tool count, prompt size, output format, when it fits. Pick the closest archetype before designing a new agent. Don't invent shapes.

Quick comparison table

# Archetype Tools Prompt Output Indices Examples
1 Shopping Assistant 11-13 2-3K words Tool-driven UI cards 1 luxury-fashion, fashion, grocery, electronics, ecom, b2b, furnishings, demo
2 AskAI / DocSearch 1 (search) 500-700 words Markdown w/ citations 2-6 docsearch-demo, sw-financial, sw-healthcare
3 PDP Product Expert 2-3 300-500 words Plain text + suggested questions 1 pdp-fashion, pdp-ecom, pdp-electronics, pdp-grocery, pdp-b2b, pdp-furnishings, luxury-fashion-pdp
4 Category Page Pitch 1 (search) 100-150 words 5-6 sentence sales pitch 1 category-page-assistant + 5 vertical variants
5 Classifier 0 400-600 words Single enum word 0 demo-classifier, alpha-fashion-orchestrator, milo-orchestrator
6 Suggestion Generator 0 150-250 words Text list 0 nav-suggestions, pdp-suggestions, welcome-prompts
7 Filter Suggestions 0 150 words JSON array 0 filter-suggestions
8 Query Builder 0-1 200 words Algolia query JSON 0-1 grocery-enhance-query
9 Multi-Agent Worker (deprecated) 0-2 50-200 words Text or simple tool 1 alpha-fashion-fast, alpha-fashion-product-discovery, milo-product-discovery

Archetype 1: Shopping Assistant

Single agent with rich tool set for product discovery, comparison, viewing, refinement.

  • Tools (10-tool core every shopping assistant has): algolia_search_index + suggest_searches + suggest_conv_prompts + ui_refinement + view_product + compare_products + show_products + bundle_suggestion + trending_items + welcome_prompts
  • Vertical-specific additions: Fashion adds analyze_image, outfit_components, store_search, clear_search, show_multi_query_results. Grocery adds display_recipes, display_ingredients, nutrition_info. Electronics/Furnishings/Ecom add review_summary. B2B strips fashion-specific tools.
  • Prompt structure: AGENT ROLE → RESPONSE GUIDELINES → CUSTOMER INTENT RECOGNITION (numbered intents 1-N) → TOOL USAGE PRIORITIES → INTENT OVERLAP HANDLING → ACTION LIMITATIONS
  • Output: Tools render UI; conversational text is glue ("Here's what I found.")
  • Model: gpt-4.1-mini (fast, cheap)
  • Config: {} or { widgetType: "chat" } typically; memory and suggestions rarely enabled

When to use: User is browsing/buying products. Many distinct interaction modes (discovery vs refinement vs comparison vs viewing). Frontend is a chat interface alongside a product grid that the agent controls via tool calls.

When NOT to use: Knowledge Q&A (use AskAI). Single-product context (use PDP Expert).

Reference: evidence/shopping-assistant-10-tool-core.md

Archetype 2: AskAI / DocSearch

Single agent that searches multiple knowledge indices and synthesizes cited answers. This is the closest archetype to Elena, Bruno, and likely the future Maverick.

  • Tools: 1 — algolia_search_index with multiple indices (2-6 typically; 10 max). All routing happens via per-index description and prompt-level routing rules.
  • Prompt structure: AGENT IDENTITY → DATA SOURCES (index list) → RESPONSIBILITIES (numbered: understand intent, query, respond) → BEHAVIOR GUIDELINES (no hallucination, partial answer rules) → MULTI-INTENT HANDLING (which indices for which use case) → CONSTRAINTS → FALLBACK RULE
  • Often paired with systemPrompt containing: HIERARCHY OF INSTRUCTIONS + TOOL-USAGE RULES + BEHAVIORAL GUIDELINES + GENERAL CONVERSATIONAL NORMS + INFORMATION GUARD
  • Output: Markdown with inline citations as [Title](URL). Source attribution per claim. Multi-source synthesis. Length target ~250-300 characters per answer (DocSearch) or longer for complex queries.
  • Model: gpt-5.2 (SW agents) or gpt-4.1-mini (DocSearch)
  • Config: { memory: { enabled: true }, suggestions: { enabled: true }, widgetType: "chat" } for SW agents. {} for DocSearch.
  • templateType: "askai" for SW agents.

When to use: Knowledge Q&A across multiple structured knowledge sources. User wants information, not actions. Multiple content types (docs, support, blogs, forums) need to be searchable.

When NOT to use: Product browsing (Shopping Assistant). Single product detail (PDP Expert). Pure classification (Classifier).

Reference: evidence/askai-pattern.md

Archetype 3: PDP Product Expert

Single agent on a product detail page. Takes a productID, answers questions, suggests follow-ups.

  • Tools: 2-3:
  • algolia_search_index (with strict rule: filter by objectID, never search-by-objectID)
  • suggest_searches (PDP variant — array of 3 strings)
  • Optional: show_multi_query_results (Fashion) for outfit suggestions
  • Prompt structure: Agent role + 2-3 numbered responsibilities + critical instructions (objectID filter rule repeated 3 times) + few-shot examples
  • Output: Plain text answer + 3 suggested questions (separator-delimited or via tool)
  • Same prompt verbatim across 6 verticals — only the index changes.

When to use: Single-product context, user asks questions about ONE product. Product ID is known from page state.

When NOT to use: Multi-product comparison (Shopping Assistant). Generic discovery (Shopping Assistant).

Reference: evidence/pdp-pattern.md

Archetype 4: Category Page Pitch

Stateless agent that takes a categoryPageId and writes a 5-6 sentence sales pitch.

  • Tools: 1 — algolia_search_index (the agent searches its own index for grounding — to find brands/products that actually exist before name-dropping them)
  • Prompt: ~120 words. "You are a sales representative. For each category you receive, write a compelling 5-6 sentence pitch. Use search to verify brands. Hierarchical inputs: refer to subcategory only."
  • Output: Plain text, ≤200 words.
  • Same prompt verbatim across 5 verticals.

When to use: Hero text generation for category landing pages. Backend-triggered, not chat.

When NOT to use: Anything conversational.

Archetype 5: Classifier

Single-turn classifier that returns one enum label. Zero tools.

  • Tools: 0
  • Prompt: Enum list with definitions + critical instructions (injection defense + priority rules) + <examples> block with input/output/reason XML triplets
  • Output: ONE word matching an enum value. Nothing else.
  • Models: gpt-4 or gpt-4.1-mini

When to use: Safety routing, scope filtering, intent labeling. Anything where you need a deterministic single-label decision.

When NOT to use: Anything that needs to act on the classification (the classifier is a pure label producer; downstream code or another agent acts on it).

Reference: evidence/classifier-pattern.md

Note: Used to be the entry point of multi-agent shopping (the "orchestrator"). Multi-agent shopping is deprecated, but the classifier pattern itself is still valid for safety/scope routing where you genuinely need a binary or N-way deterministic decision.

Archetype 6: Suggestion Generator

Stateless prompt-driven generator producing welcome prompts, follow-up questions, navigation suggestions.

  • Tools: 0
  • Prompt: Output spec is the prompt — "Write exactly 3 groups of 3 suggestions, ≤5 words each, from user perspective."
  • Output: Text list, format-conventionally delimited (newlines, separator chars).
  • Notable: Many of these have been REPLACED in shopping assistants by welcome_prompts and suggest_conv_prompts client-side tools (which produce structured JSON instead of text). The standalone-agent versions persist for backwards compatibility or simpler integrations.

When to use: Backend-triggered text generation for static UI elements (welcome screens, nav menus).

When NOT to use: Anything inside an active chat conversation (use the tool form).

Archetype 7: Filter Suggestions

Specialized agent for the InstantSearch FilterSuggestions widget.

  • Tools: 0
  • Prompt: Output JSON array of {attribute, value, label, count}. Rules: count > 0, only facets from input, prioritize meaningful filters.
  • Config: { widgetType: "filterSuggestions" }
  • Frontend binding: <FilterSuggestions agentId={...} /> in react-instantsearch
  • Used with the "Filter suggestions" agent template.

When to use: When you have an InstantSearch-powered search interface and want AI-suggested facet filters alongside it.

When NOT to use: Anything other than filter suggestion. Doesn't generalize.

Archetype 8: Query Builder

NL-to-Algolia-query agent. Takes natural language search input, outputs structured query JSON with filters extracted.

  • Tools: 0-1 (some include algolia_search_index to actually execute the built query)
  • Prompt: Output spec + 3 inline examples showing input → JSON output
  • Output: Algolia query JSON object

When to use: Specialized backend pipeline — pre-processing search queries, normalizing user inputs, integrating with non-AS search frontends.

When NOT to use: Anything conversational; anything where the agent should also synthesize a final answer.

Archetype 9: Multi-Agent Worker (DEPRECATED)

Older pattern: small specialized agents called by an orchestrator agent.

  • Tools: 0-2
  • Prompt: 50-200 words, very narrow scope ("You are a product expert. Answer questions about the given product.")
  • Examples: alpha-fashion-fast (1-line prompt, 0 tools, just product Q&A), alpha-fashion-product-discovery (2 tools — search+displayResults).

Why deprecated: Algolia's Agent Studio team consolidated these into single-agent shopping assistants with prompt-level intent routing. Reasons: - Multi-agent routing latency (every routing decision = LLM call) - Loss of conversational context across handoffs - Harder to debug (which agent failed? where?) - More to tune (5 prompts × N verticals = sprawl)

Status: Don't build new agents in this shape. The single-agent + many-tools shape is the current standard.

Exception: Classifiers (archetype 5) are still valid — they're not "workers" in the deprecated sense; they're focused single-decision agents that complement, not replace, a main agent. Distinguish: a classifier returns a label that a router USES; a deprecated worker did actual work that's now better done by tools inside one agent.

Mapping our current agents to archetypes

Our agent Closest archetype Notes
Maverick (today) Hybrid: Discovery + AskAI + Handoff Orchestrator Currently in code, not in Agent Studio. Conceptually closest to AskAI for the "search and answer" role, with a custom 8-signal discovery overlay and persona-handoff logic.
Elena (today) AskAI with overcomplicated XML output Uses 1 tool (algolia_search_index × 2 indices). Should drop XML output and use client-side render tools — but still in the AskAI archetype, just cleaned up.
Bruno (today) AskAI with mandatory Mermaid output Same shape as Elena. Mermaid diagram becomes a render_architecture_diagram client-side tool.
Maverick (proposed) AskAI + optional safety classifier upstream Move into Agent Studio. Add information guard. Optionally precede with a CLASSIFIER for scope routing (only if discovery framing requires it).
Elena (proposed) AskAI w/ memory, suggestions, 2-4 client-side render tools Same archetype, simplified prompt, native platform features, structured output via tools.
Bruno (proposed) Same as Elena, with one extra render tool for the diagram

Key insight: All three of our agents are AskAI-pattern, not Shopping-Assistant-pattern. We don't need 13 tools. We need 2-4 client-side render tools per specialist + the search tool, plus native memory + suggestions config. Total scope of refactor is significantly smaller than building shopping-assistant-style agents from scratch.

What this section does NOT cover