Multi-Agent Architecture & Specialized Agents

Overview

The Storytell AI platform uses a multi-agent architecture where a main orchestrating agent delegates complex tasks to specialized agents. Each specialized agent has its own context window, tool access, and execution limits, allowing the system to handle sophisticated workflows that would exceed a single agent's capabilities.

Available specialized agents

The platform includes five specialized agent types, each optimized for specific use cases:

General Agent

The General agent is the default orchestrator with access to all available tools. It handles:

• Task coordination and delegation

• Multi-step workflows requiring diverse capabilities

• Situations where task requirements aren't clearly specialized

When to use: Default choice for general-purpose tasks or when task requirements span multiple specializations.

Explorer Agent

The Explorer agent specializes in web research and external information gathering. It's optimized for:

• Internet research and fact-checking

• Reading and analyzing web pages

• Synthesizing findings from multiple online sources

• Cross-referencing information across websites

Research methodology:

1. Start broad: Initial search to understand the landscape

2. Go deep: Read primary sources in full via web_page

3. Verify: Cross-reference key claims across multiple sources

4. Synthesize: Organize findings with clear source attributions

Quality standards:

• Cites every factual claim with its source URL

• Notes confidence levels (well-established vs. single-source claims)

• Identifies gaps where information is unavailable or conflicting

• Prefers recent sources for time-sensitive information

When to use: Tasks requiring external web research, current events, or information not in your knowledge base.

Librarian Agent

The Librarian agent specializes in exploring and analyzing your internal document library. It excels at:

• Searching across uploaded documents

• Extracting specific data points from spreadsheets and structured files

• Synthesizing information from multiple internal sources

• Discovering connections across documents

Search strategy:

1. Identify query topics (finance, HR, engineering, etc.)

2. Match topics to relevant assets by description

3. Use multiple focused queries rather than one broad search

4. Same assets can appear in multiple queries for different facets

5. For cross-domain questions, search broadly across relevant assets

Best practices:

• Uses natural language queries, not keyword stuffing

• Breaks complex questions into multiple targeted searches

• Only includes assets whose descriptions match the query topic

• Cites document sources clearly in responses

When to use: Tasks requiring deep exploration of your uploaded documents, internal knowledge base queries, or analysis of proprietary information.

Researcher Agent

The Researcher agent combines the capabilities of both Explorer and Librarian agents. It's designed for:

• Comprehensive research across both web and internal sources

• Cross-referencing findings between external and internal documents

• Synthesizing unified summaries from all available sources

• Clearly attributing which information came from web vs. internal documents

Research strategy:

1. Start with internal knowledge base to understand what you already have

2. Search web for external context, updates, or missing information

3. Cross-reference findings between sources

4. Synthesize into a coherent summary with clear source attribution

Quality standards:

• Cites sources clearly (web URLs and document names)

• Notes when internal docs conflict with or complement external sources

• Identifies gaps in available information

• Prefers authoritative sources (official docs, primary sources)

When to use: Tasks requiring comprehensive research that combines both your internal documents and external web sources.

Plan Agent

The Plan agent specializes in gathering context and creating structured execution plans for complex multi-step tasks. It:

• Gathers information from knowledge bases and web searches

• Creates structured execution plans

• Recommends which agent types to use for each step

• Returns concise plans that the main agent can use to orchestrate other agents

When to use: Complex multi-step tasks where you need a structured plan before execution, or when you want to break down a large task into manageable steps with agent recommendations.

How agent delegation works

Task tool mechanism

Agents delegate work to specialized agents using the task tool. This tool allows an agent to:

• Specify which specialized agent type to use

• Provide a task description

• Optionally override the model or inherit from parent

• Receive structured results back

Delegation decision process

The main agent decides to delegate when:

1. Task complexity: The task requires multiple tool calls that would consume too much of the main context window

2. Specialization needed: The task clearly benefits from a specialized agent's expertise

3. Parallelization opportunity: Multiple agents can work simultaneously on different aspects

4. Resource management: Delegating prevents hitting execution limits in the main agent

💡 Important: If you can accomplish the task with 1-3 direct tool calls, do NOT delegate to an agent. The overhead is not worth it. Delegation adds latency and resource overhead, so reserve it for genuinely complex tasks.

Good delegation use cases

✅ Research tasks requiring multiple web searches with follow-up queries
Example: "Research the latest developments in quantum computing from 2024"

✅ Deep knowledge base exploration across many documents
Example: "Find all information about our authentication system across docs"

✅ Complex analysis requiring 4+ tool invocations
Example: "Analyze competitor pricing strategies across their websites"

✅ Parallel execution opportunities
Example: Launch multiple explorer agents to research different topics simultaneously

✅ Planning complex multi-step workflows before execution

Result handling

When a specialized agent completes, it returns:

• Structured summary: Condensed findings added to the parent agent's context

• Tool UI outputs: Rich outputs for frontend rendering (charts, search results, etc.)

• Execution metadata: Tool calls made, duration, tokens consumed

• Completion status: Whether the agent finished successfully or hit limits

The parent agent receives this structured result and can:

• Incorporate findings into its response

• Make follow-up tool calls based on agent results

• Delegate additional subtasks if needed

• Synthesize multiple agent results into a unified response

Using agents in the UI

The Storytell AI platform provides an intuitive interface for enabling, disabling, and selecting specialized agents in your prompts. You can control agent availability globally or specify individual agents for specific tasks.

Enabling and disabling agents

Agents are controlled through the Tool Selector menu in the prompt bar. To access it:

1. Click the tools icon in the prompt bar

2. Find the Agents option in the tool list

3. Toggle the switch to enable or disable agents

Enabling agents:

• When enabled, the system can automatically delegate tasks to specialized agents

• Agents appear in the mention menu (when you type @) for explicit selection

• The main agent can intelligently choose which specialized agent to use

Disabling agents:

• When disabled, the system will not use specialized agents

• Agents will not appear in the mention menu

• All tasks are handled by the general agent with direct tool calls

💡 Tip: You can enable or disable all tools at once using the "All" toggle at the top of the tool selector menu. This is useful for quickly resetting your tool preferences.

Selecting specific agents in prompts

When agents are enabled, you can explicitly specify which agent to use for your task:

1. Type @ in the prompt bar to open the mention menu

2. Browse available agents: You'll see Explorer, Librarian, and Researcher listed

3. Select an agent: Click on the agent you want to use

4. Agent badge appears: The selected agent appears as a violet badge in your prompt

Available agents in the UI:

• Explorer: Web research specialist

• Librarian: Internal knowledge specialist

• Researcher: Multi-source research specialist

Example prompt with agent selection:

@Explorer Research the latest developments in quantum computing 

When you include an agent mention in your prompt, the system will prioritize using that specific agent for the task, rather than letting the main agent decide automatically.

Agent badges and visual indicators

Selected agents appear as violet badges in your prompt with:

• Robot icon: Visual indicator that this is an agent mention

• Agent name: The name of the selected agent (Explorer, Librarian, or Researcher)

• Remove option: Hover over the badge to see an X button for removing the agent selection

Removing an agent selection:

• Hover over the agent badge

• Click the X button that appears

• The agent mention is removed from your prompt

💡 Tip: You can include multiple agent mentions in a single prompt if you want to use different agents for different parts of your request. The system will intelligently route each part to the appropriate agent.

Automatic vs. explicit agent selection

The system supports two modes of agent usage:

Automatic selection (default):

• Agents are enabled but not explicitly mentioned

• The main agent analyzes your request and decides which specialized agent to use

• Works seamlessly without any additional input from you

• Best for: General tasks where you trust the system's judgment

Explicit selection:

• You mention a specific agent using @AgentName in your prompt

• The system prioritizes using that agent for your task

• Provides more control over which agent handles your request

• Best for: When you know exactly which agent specialization you need

Tool selection persistence

Your agent enable/disable preferences are automatically saved to your browser's local storage:

• Persists across sessions: Your preferences remain when you close and reopen the browser

• Syncs across tabs: Changes in one tab are reflected in other open tabs

• Per-browser basis: Preferences are stored locally, not synced across devices

To reset your tool preferences:

1. Open the tool selector menu

2. Toggle the "All" switch off and back on

3. Or manually toggle each tool to your desired state

Agent availability indicators

When agents are disabled, you'll notice:

• Agents don't appear in the @ mention menu

• The system uses direct tool calls instead of delegation

• Task complexity may be limited by the main agent's context window

When agents are enabled:

• Agents appear in the mention menu

• The system can delegate complex tasks automatically

• You can explicitly select agents for specific tasks

Agent configuration and limits

Execution limits

Tool access filtering

Each specialized agent only has access to tools relevant to its purpose:

• General: All tools (no filtering)

• Explorer: Web-focused tools (web_search, web_page)

• Librarian: Knowledge base tools (knowledge_base_search)

• Researcher: Both web and knowledge base tools

• Plan: Both web and knowledge base tools (for gathering context)

This filtering ensures agents stay focused on their specialization and don't waste context on irrelevant tools.

Tool preferences

Agents can define tool preferences that guide their usage patterns:

• Prefer when: Conditions where a tool should be preferred

• Use before: Tool execution order recommendations

• Avoid when: Conditions where a tool should be avoided

These preferences help agents make better tool selection decisions during execution.

Timeout and budget management

Each agent operates with:

• Timeout: Default 10 minutes (configurable per agent type)

• Token budget: Default 125,000 tokens (shared across all agents in a turn)

• Budget warnings: System warns when budget drops below 20% remaining

Agents track their resource consumption and can gracefully handle budget exhaustion by returning partial results.

Best practices for agent selection

Choosing the right agent

Selecting the appropriate agent type significantly impacts task success:

Use Explorer when:

• Task requires external web research

• You need current events or recent information

• Information isn't in your knowledge base

• Task involves fact-checking across multiple sources

Use Librarian when:

• Task involves your uploaded documents

• You need to extract data from internal files

• Task requires cross-referencing internal documents

• Information is proprietary or internal-only

Use Researcher when:

• Task requires both web and internal research

• You need to cross-reference external and internal sources

• Task benefits from comprehensive multi-source analysis

• You want unified synthesis from all available sources

Use Plan when:

• Task is complex and multi-step

• You need a structured execution plan before starting

• Task would benefit from breaking into smaller steps

• You want agent recommendations for each step

Use General when:

• Task requirements span multiple specializations

• Task doesn't clearly fit a specialized agent

• You need coordination across multiple tools

• Task is relatively simple (1-3 tool calls)

Delegation patterns

Common patterns for effective agent delegation:

Sequential delegation:
Main agent → Plan agent (creates plan) → Execute plan steps with appropriate agents

Parallel delegation:
Main agent → Multiple Explorer agents (research different topics simultaneously) → Synthesize results

Hierarchical delegation:
Main agent → Researcher agent → Researcher delegates to Explorer and Librarian → Results flow back up

Iterative delegation:
Main agent → Agent completes task → Main agent analyzes results → Delegates follow-up tasks if needed

FAQ