Octopus
Area Routing
When a user sends a message, Octopus must determine which agent within an area handles it. Area routing covers how users select an area, how the default agent is determined, and how the multi-agent AgentRouter operates within an area to select the most appropriate specialist.
Routing Levels
Routing happens at two levels:
- Area selection: Which area does this user's request go to? (User-driven or URL-based)
- Agent selection within area: Which agent within the area handles this message? (Intent-driven via AgentRouter)
Area Selection Methods
| Method | How It Works | Best For |
|---|---|---|
| User chooses area in chat-app | Area selector dropdown in chat-app UI; user explicitly picks HR/Finance/IT | Power users with multi-area access |
| Default area per user group | User's primary group maps to a default area; first area shown on login | Most employees who only need one area |
| URL-based area | Embedded chat-app URL includes areaId: /chat?areaId=area_hr | Embedded chatbots in specific pages (HR portal, Finance portal) |
| Single-area deployment | Only one area configured; no selection needed | Simple deployments |
Agent Selection Within Area
When an area has multiple agents, the AgentRouter selects which agent handles each message based on configured routing strategy:
// Area-level routing configuration
{
"areaId": "area_hr",
"routingStrategy": "Embedding", // Embedding | LLM | Default | RoundRobin
"defaultAgentId": "agent_hr_general",
"agents": [
{
"agentId": "agent_hr_general",
"description": "General HR questions, policies, and information"
},
{
"agentId": "agent_leave_manager",
"description": "Leave requests, leave balance, leave approval and cancellation"
},
{
"agentId": "agent_onboarding",
"description": "New employee onboarding, document collection, system access setup"
}
]
}
// AgentRouter embeds user message and compares cosine similarity
// to each agent's description embedding → picks highest similarity agentHandoff Within an Area
// When an agent determines another area agent is more appropriate:
// (e.g. HR General assistant receives a leave request)
Handler for "handoff_to_agent":
{
"targetAgentId": "agent_leave_manager",
"reason": "User requested leave — routing to Leave Manager",
"contextSummary": "User Mary K (EMP-1042) wants to take 5 days in June 2025."
}
// The session switches to the leave_manager agent
// The context summary is injected into the new agent's working memory
// User sees a seamless handoff notification in the chat-app