---
title: "Agent Swarms"
description: "Deploy and manage agent swarms for parallel task execution and collaborative intelligence"
canonical: "https://docs.ainative.studio/docs/agent-framework/swarms"
last-updated: "2026-10-22T17:48:46.689Z"
---

# Agent Swarms

Source: https://docs.ainative.studio/docs/agent-framework/swarms

> Deploy and manage agent swarms for parallel task execution and collaborative intelligence

## Agent Swarms

The Agent Swarm API lets you submit work to a coordinated team of specialist agents. Tasks are queued asynchronously — submit a task and poll for results using the returned `task_id`.

**Base URL:** `https://api.ainative.studio`

**Authentication:** JWT bearer or API key. All endpoints require `Authorization: Bearer <your_api_key>`.

---

## Supported Agent Types

When submitting a task you can specify which agent roles to involve. The following types are supported:

| Type | Role |
|------|------|
| `architect` | System design and high-level planning |
| `backend` | Server-side implementation |
| `frontend` | UI and client-side implementation |
| `qa` | Testing and quality assurance |
| `devops` | Infrastructure and deployment |
| `data` | Data pipeline and analytics |
| `security` | Vulnerability and threat analysis |
| `docs` | Documentation authoring |

If `agent_types` is omitted, the swarm defaults to `["architect", "backend", "qa"]`.

---

## Task Lifecycle

```
submitted → queued → running → completed
                            ↘ failed
```

Poll `GET /api/v1/agent-swarm/tasks/{task_id}` until `status` is `completed` or `failed`. The `result` field is populated on completion.

---

## Endpoints

### Submit a Swarm Task

<span className="badge badge--post">POST</span> `/api/v1/agent-swarm/tasks`

Queue a new task for execution. Returns immediately with `status: queued` and a `task_id` to poll.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | Yes | Natural-language task description (1–4096 chars) |
| `agent_types` | string[] | No | Agent roles to involve. Defaults to `["architect", "backend", "qa"]`. Optional when `registry_agent_id` is provided. |
| `registry_agent_id` | string | No | ID of a registered agent from the agent cloud registry. When provided, agent config is loaded from the registry. |
| `config` | object | No | Arbitrary key-value config forwarded to the swarm execution context |

```bash
curl -X POST https://api.ainative.studio/api/v1/agent-swarm/tasks \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Add rate limiting middleware to all public API routes",
    "agent_types": ["architect", "backend", "qa", "devops"],
    "config": {
      "repo": "my-org/api-service",
      "branch": "main"
    }
  }'
```

```python
import httpx

resp = httpx.post(
    "https://api.ainative.studio/api/v1/agent-swarm/tasks",
    headers={"Authorization": "Bearer <your_api_key>"},
    json={
        "description": "Add rate limiting middleware to all public API routes",
        "agent_types": ["architect", "backend", "qa", "devops"],
        "config": {"repo": "my-org/api-service", "branch": "main"},
    },
)
task = resp.json()
task_id = task["task_id"]
```

**Response** `201 Created`

```json
{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "description": "Add rate limiting middleware to all public API routes",
  "agent_types": ["architect", "backend", "devops", "qa"],
  "registry_agent_id": null,
  "config": {
    "repo": "my-org/api-service",
    "branch": "main"
  },
  "result": null,
  "agents_used": [],
  "created_at": "2026-04-25T10:00:00Z",
  "updated_at": "2026-04-25T10:00:00Z",
  "owner_id": "user-uuid"
}
```

---

### Submit Using a Registry Agent

You can bind a swarm task to a registered agent from the agent cloud registry. The swarm loads capabilities and config from the registry automatically. The agent must be `ACTIVE` and either public or owned by you.

```bash
curl -X POST https://api.ainative.studio/api/v1/agent-swarm/tasks \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Run a full security audit on the payment module",
    "registry_agent_id": "550e8400-e29b-41d4-a716-446655440001"
  }'
```

When `registry_agent_id` is provided, `agent_types` becomes optional. If omitted, the type is derived from the registry agent's `agent_type` field.

---

### Get Task Status and Results

<span className="badge badge--get">GET</span> `/api/v1/agent-swarm/tasks/{task_id}`

Retrieve the current status and result for a previously submitted task. Returns `404` if the task does not exist or belongs to another user.

```bash
curl https://api.ainative.studio/api/v1/agent-swarm/tasks/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer <your_api_key>"
```

```python
import httpx, time

task_id = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
while True:
    resp = httpx.get(
        f"https://api.ainative.studio/api/v1/agent-swarm/tasks/{task_id}",
        headers={"Authorization": "Bearer <your_api_key>"},
    )
    task = resp.json()
    if task["status"] in ("completed", "failed"):
        break
    time.sleep(5)

print(task["result"])
```

**Response when completed**

```json
{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "description": "Add rate limiting middleware to all public API routes",
  "agent_types": ["architect", "backend", "devops", "qa"],
  "registry_agent_id": null,
  "config": {...},
  "result": {
    "summary": "Rate limiting middleware implemented using token bucket algorithm",
    "files_changed": ["middleware/rate_limit.py", "app/main.py"],
    "tests_added": 12,
    "coverage": "94%"
  },
  "agents_used": ["arch-agent-01", "backend-agent-03", "qa-agent-02"],
  "created_at": "2026-04-25T10:00:00Z",
  "updated_at": "2026-04-25T10:04:23Z",
  "owner_id": "user-uuid"
}
```

**Task status values**

| Status | Description |
|--------|-------------|
| `queued` | Task accepted, waiting for agent capacity |
| `running` | Agents are actively working on the task |
| `completed` | Task finished successfully. `result` is populated. |
| `failed` | Task could not be completed. Check `result` for error details. |
| `cancelled` | Task was cancelled before execution |

---

### List Swarm Tasks

<span className="badge badge--get">GET</span> `/api/v1/agent-swarm/tasks`

Paginated list of all tasks submitted by the authenticated user, ordered by `created_at` descending.

**Query parameters**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `status` | string | — | Filter by status: `queued`, `running`, `completed`, `failed`, `cancelled` |
| `limit` | integer | 20 | Max results per page (1–100) |
| `offset` | integer | 0 | Number of results to skip |

```bash
## List only completed tasks
curl "https://api.ainative.studio/api/v1/agent-swarm/tasks?status=completed&limit=10" \
  -H "Authorization: Bearer <your_api_key>"
```

**Response**

```json
{
  "tasks": [
    {
      "task_id": "f47ac10b-...",
      "status": "completed",
      "description": "Add rate limiting middleware...",
      ...
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}
```

---

## Error Responses

| Status | Cause |
|--------|-------|
| `401` | Missing or invalid authentication |
| `403` | Task belongs to another user (private registry agent) |
| `404` | Task not found |
| `422` | Unknown `agent_types` value or invalid `status` filter |
| `500` | Internal error — safe to retry |