Multi-Agent System
Octopus supports multi-agent architectures where a coordinating orchestrator agent routes user requests to specialized domain agents, enabling complex tasks that require multiple areas of expertise to be handled seamlessly.
Why Multi-Agent?
A single general-purpose agent struggles with depth across many domains. Multi-agent systems solve this by giving each agent a focused purpose — a smaller, better-tuned system prompt, a tighter tool set, and domain-specific knowledge. The orchestrator acts as the "front desk" — routing to the right specialist without the user needing to know which agent handles their request.
Orchestrator Agent
Receives all user messages first. Classifies intent and routes to the appropriate specialist. May aggregate results from multiple specialists into a single response.
Specialist Agents
Domain-focused agents: HR, Finance, IT Support, Legal, etc. Each has a tight system prompt, targeted tool set, and domain-specific knowledge base.
Agent Teams
A named group of agents with a shared routing policy. Teams are configured in the agents-app and define which orchestrator routes to which specialists.
Routing Strategies
| Strategy | How It Works | Best For |
|---|---|---|
| Keyword Routing | Fast string matching on user message against agent keyword lists | Simple, predictable routing with known intent phrases |
| Embedding Routing | Embed user message, cosine similarity against per-agent intent examples | Nuanced routing where keywords are insufficient |
| LLM Routing | Orchestrator LLM decides which agent to call via tool call | Complex, ambiguous requests needing reasoning |
| Explicit Routing | User selects agent directly; orchestrator honors selection | Power users who know which agent they need |
Multi-Agent Reasoning Loop
User Message Arrives
The orchestrator agent receives the user's message. It has access to agent routing tools via its MCP tool registry.
Intent Classification
AgentRouter classifies the intent using the configured routing strategy. Returns a ranked list of candidate agents.
Handoff Initiated
The orchestrator calls HandoffService.TransferAsync() with conversation context and the target agent ID.
Specialist Agent Responds
The specialist agent receives the handoff context, retrieves its own memory, and generates a response.
Response Returned to User
The specialist's response is streamed back. The orchestrator may post-process or simply relay the response.
Key Interfaces
public interface IAgentOrchestrator
{
Task<AgentRoutingResult> RouteAsync(
string userMessage,
ConversationComposite conversation,
CancellationToken ct = default);
}
public interface IAgentHandoffService
{
Task<HandoffResult> TransferAsync(
Guid conversationId,
Guid targetAgentId,
HandoffContext context,
CancellationToken ct = default);
}Read Guide1: Octopus Framework before this guide. Understanding AgentComposite and ConversationComposite is essential for the handoff mechanics described here.