Skip to content
Ishvana Ishvana Docs

Create Swarm

POST
/api/agents/swarm/create

Create a new swarm for task execution

Creates a multi-agent swarm optimized for the specified task type. The swarm will be assembled with agents specialized for the task type and will execute the task with the specified priority and agent constraints. Supports various swarm types including code analysis, testing, performance optimization, creative content generation, and more.

@param request: Swarm creation parameters including type, description, priority, max_agents, and timeout @param swarm_engine: Injected swarm execution engine @returns SwarmResponse with swarm_id, status, type, creation time, task description, agent count, and progress @raises HTTPException: If swarm creation fails or swarm engine unavailable

Example Request:

{
    "swarm_type": "code_analysis",
    "task_description": "Analyze codebase for performance issues",
    "priority": "high",
    "max_agents": 5,
    "timeout_minutes": 30
}

Request Body required

Section titled “Request Body required ”
SwarmCreationRequest

Request model for creating a new multi-agent swarm.

Represents a request to create a specialized multi-agent swarm for executing complex tasks requiring coordination between multiple AI agents. Swarms can be configured for different task types with customizable resource allocation and execution parameters.

Fields:

  • swarm_type: Type of swarm to create (code_analysis, testing, performance, recovery, etc.)
  • task_description: Description of the task to execute
  • priority: Task priority level (low, normal, high)
  • max_agents: Maximum number of agents in the swarm
  • timeout_minutes: Swarm execution timeout in minutes

Swarm Types:

  • code_analysis: Multi-agent code review and analysis swarm
  • testing: Comprehensive testing swarm with multiple test strategies
  • performance: Performance optimization and benchmarking swarm
  • recovery: System recovery and healing swarm
  • creative: Creative content generation swarm
  • conflict: Conflict resolution and decision-making swarm
  • risk: Risk assessment and mitigation swarm
  • code_generation: Multi-agent code generation swarm
  • cleanup: Codebase cleanup and refactoring swarm
  • data: Data processing and analysis swarm

Priority Levels:

  • low: Background execution, lowest resource priority
  • normal: Standard execution, balanced resource allocation
  • high: Expedited execution, prioritized resource access

Usage: POST /api/swarm/create with this model to initiate a new swarm execution.

JSON Example:

{
  "swarmType": "code_analysis",
  "taskDescription": "Analyze Python codebase for type safety issues",
  "priority": "normal",
  "maxAgents": 5,
  "timeoutMinutes": 30
}

Integration:

  • SwarmExecutionEngine: Creates and coordinates the swarm
  • Agent Registry: Selects appropriate agents for swarm membership
  • Resource Manager: Allocates resources based on priority and max_agents
  • Task Queue: Schedules swarm execution based on priority
object
swarmType
required
Swarmtype

Type of swarm to create

string
taskDescription
required
Taskdescription

Description of the task

string
priority
Priority

Task priority (low, normal, high)

string
default: normal
maxAgents
Any of:
integer
timeoutMinutes
Any of:
integer

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

SwarmResponse

Response model for swarm operations.

Represents the current state and metadata of a multi-agent swarm, including execution status, progress tracking, and swarm composition details. Used for swarm creation responses, status queries, and monitoring updates.

Fields:

  • swarm_id: Unique swarm identifier
  • status: Current swarm status (pending, active, completed, failed, cancelled)
  • swarm_type: Type of swarm
  • created_at: Creation timestamp
  • task_description: Task description
  • agent_count: Number of agents in swarm
  • progress: Task completion progress (0.0-1.0)

Status Values:

  • pending: Swarm created but not yet started
  • active: Swarm currently executing
  • completed: Swarm finished successfully
  • failed: Swarm failed with error
  • cancelled: Swarm cancelled by user or system

Progress Range: 0.0 (0%) to 1.0 (100%), calculated based on completed sub-tasks

Usage: Returned from swarm creation, status queries, and list operations.

JSON Example:

{
  "swarmId": "swarm_abc123",
  "status": "active",
  "swarmType": "code_analysis",
  "createdAt": "2024-12-20T10:30:00Z",
  "taskDescription": "Analyze Python codebase for type safety issues",
  "agentCount": 5,
  "progress": 0.65
}

Integration:

  • SwarmExecutionEngine: Updates status and progress during execution
  • Monitoring Dashboard: Displays swarm state in real-time
  • Analytics System: Tracks swarm performance and completion rates
object
swarmId
required
Swarmid

Unique swarm identifier

string
status
required
Status

Current swarm status

string
swarmType
required
Swarmtype

Type of swarm

string
createdAt
required
Createdat

Creation timestamp

string
taskDescription
required
Taskdescription

Task description

string
agentCount
required
Agentcount

Number of agents in swarm

integer
progress
required
Progress

Task completion progress (0.0-1.0)

number

422

Section titled “422 ”

Validation Error

HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object