Area Configuration — Agent Areas

Creating an Area via API

// POST /api/octopus/areas
POST /api/octopus/areas
Authorization: Bearer {adminToken}
Content-Type: application/json

{
  "name":        "HR",
  "description": "Human Resources agent area — leave, policies, onboarding",
  "isActive":    true
}

// Response:
{
  "areaId":      "area_7f3a...",
  "tenantId":    "tenant_acme",
  "name":        "HR",
  "description": "Human Resources agent area...",
  "isActive":    true,
  "agentCount":  0,
  "userCount":   0,
  "createdAt":   "2025-03-01T08:00:00Z"
}

Assigning Agents to an Area

// POST /api/octopus/areas/{areaId}/agents
POST /api/octopus/areas/area_7f3a.../agents
Authorization: Bearer {adminToken}

{
  "agentIds": [
    "agent_hr_assistant",
    "agent_leave_manager",
    "agent_policy_advisor"
  ]
}

// An agent can belong to multiple areas (unusual but supported)
// An agent not in any area is only accessible via direct ID reference (no area routing)

Area-Level Defaults

Areas can define default configurations that agents inherit unless overridden at the agent level:

// PATCH /api/octopus/areas/{areaId}/defaults
{
  "defaultLLMProvider":  "Anthropic",
  "defaultModel":        "claude-sonnet-4-5",
  "defaultPruning":      "FIFO",
  "defaultSemanticTopK": 5,
  "brandingName":        "HR Assistant",
  "welcomeMessage":      "Hello! I'm your HR assistant. How can I help today?"
}

Area Configuration Properties

Property	Type	Description
`name`	string	Display name shown in the chat-app area selector
`description`	string	Internal description for admin reference
`isActive`	bool	Inactive areas are hidden from all users
`brandingName`	string	Override the area display name in the chat UI
`welcomeMessage`	string	Message shown when a user enters the area in chat
`defaultAgentId`	Guid?	Agent selected by default when the user enters the area

Area Management API

Method	Endpoint	Action
GET	/api/octopus/areas	List all areas for tenant
POST	/api/octopus/areas	Create new area
GET	/api/octopus/areas/{id}	Get area details
PATCH	/api/octopus/areas/{id}	Update area settings
DELETE	/api/octopus/areas/{id}	Deactivate area (soft delete)
POST	/api/octopus/areas/{id}/agents	Add agents to area
DELETE	/api/octopus/areas/{id}/agents/{agentId}	Remove agent from area

← What Are Agent Areas Next: Knowledge Scoping →