Missions

Overview

Missions are multi-agent execution plans created when the system classifies a query as COMPLEX. Each mission contains a DAG of subtasks (agents) that execute in dependency order, with parallel execution within each layer.

See the Missions guide for a conceptual overview.

---

Data Models

Mission

Field	Type	Description
id	UUID	Unique mission identifier
workspace_id	UUID	Owner workspace
conversation_id	UUID	Originating conversation
user_id	UUID	Creator
title	string	First 500 chars of the original prompt
status	string	pending running completed failed partially_failed cancelled
dag_definition	object	Subtask DAG structure
agent_count	integer	Total number of subtasks
parallel_count	integer	Maximum agents running concurrently
original_prompt	string	Full user query
completion_summary	string|null	AI-generated synthesis of all results
overall_rqs	float|null	Aggregate quality score (0–1)
overall_credits	number	Total credits consumed across all subtasks
total_duration_ms	integer|null	Wall-clock execution time
started_at	datetime|null	When execution began
completed_at	datetime|null	When execution finished
created_at	datetime	Proposal timestamp
updated_at	datetime	Last state change
subtasks	MissionSubTask[]	Ordered list of all subtasks

MissionSubTask

Field	Type	Description
id	UUID	Subtask identifier
mission_id	UUID	Parent mission
subtask_index	integer	0-based execution order
title	string	Agent name / role
workflow_type	string	synthesis recommendation drafting chat full_pipeline
prompt	string	Current prompt (may be updated by redirect)
depends_on	integer[]	Indices of prerequisite subtasks
status	string	pending running completed failed cancelled redirected
agent_name	string|null	Human-readable agent identifier
artifact_summary	string|null	Description of outputs created
artifact_counts	object|null	{"insights": 3, "documents": 1, ...}
quality_score	float|null	Per-agent verifier score (0–1)
credits_consumed	number	Credits billed for this agent
redirect_count	integer	Number of times prompt was redirected
redirect_history	array|null	[{at, from_prompt, to_prompt}]
started_at	datetime|null	Agent start time
completed_at	datetime|null	Agent completion time

---

Endpoints

List Missions

Query Parameters:

Parameter	Type	Required	Description
workspace_id	UUID	Yes	Workspace to query
status	string	No	Filter by status (e.g. running)
limit	integer	No	Page size (default 20, max 100)
offset	integer	No	Pagination offset (default 0)

Response (200):

{
  "missions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "...",
      "conversation_id": "...",
      "title": "Analyze Q4 user interview data and build a feature prioritization PRD",
      "status": "completed",
      "agent_count": 4,
      "parallel_count": 2,
      "overall_rqs": 0.84,
      "overall_credits": 12.5,
      "total_duration_ms": 87400,
      "started_at": "2026-04-03T10:00:00Z",
      "completed_at": "2026-04-03T10:01:27Z",
      "created_at": "2026-04-03T09:59:58Z",
      "subtasks": [...]
    }
  ],
  "total": 47
}

---

Get Mission

Response (200): Full Mission object including subtasks array.

Errors:

Code	Condition
404	Mission not found or user not a workspace member

---

Redirect Subtask

Request Body:

{
  "newPrompt": "Focus specifically on enterprise pricing pain points, ignore SMB data"
}

Response (200): Updated MissionSubTask with incremented redirect_count and appended redirect_history entry.

Errors:

Code	Condition
400	Subtask is not in running status
404	Mission or subtask not found

---

Spawn Agent

Request Body:

Field	Type	Required	Description
title	string	Yes	Agent name (e.g. "Check G2 reviews")
prompt	string	Yes	What this agent should do
workflow_type	string	No	Default: "chat"
dependsOn	integer[]	No	Subtask indices that must complete first

Response (201): New MissionSubTask with status: "pending".

Errors:

Code	Condition
400	Mission is not in running or pending status

---

Cancel Subtask

Response (200): Updated MissionSubTask with status: "cancelled".

Errors:

Code	Condition
400	Subtask is already completed, failed, or cancelled
404	Mission or subtask not found

---

SSE Events

Mission progress is delivered over the chat stream (see Streaming SSE).

mission_proposed

Emitted when a complex query has been decomposed. Displayed as the Mission Proposal card.

{
  "event": "mission_proposed",
  "data": {
    "mission_id": "uuid",
    "subtasks": [
      {
        "index": 0,
        "title": "Research market trends",
        "workflow_type": "synthesis",
        "depends_on": []
      },
      {
        "index": 1,
        "title": "Generate recommendations",
        "workflow_type": "recommendation",
        "depends_on": [0]
      }
    ],
    "agent_count": 2,
    "parallel_count": 1
  }
}

agent_thread_start

Emitted when a subtask begins execution.

{
  "event": "agent_thread_start",
  "data": {
    "mission_id": "uuid",
    "subtask_index": 0,
    "agent_name": "Research market trends",
    "workflow_type": "synthesis"
  }
}

agent_thread_done

Emitted when a subtask completes.

{
  "event": "agent_thread_done",
  "data": {
    "mission_id": "uuid",
    "subtask_index": 0,
    "artifact_summary": "Created 4 insights on market positioning",
    "artifact_counts": {
      "insights": 4,
      "documents": 1
    },
    "duration_ms": 34200
  }
}

done (with mission_id)

The final done event includes the mission_id when a mission has completed:

{
  "message_id": "uuid",
  "summary": "Mission complete: 4 agents, 12 artifacts",
  "model": "claude-sonnet-4-20250514",
  "mission_id": "uuid",
  "num_turns": 16,
  "duration_ms": 87400,
  "credits": 12.5
}

---

Mission Events Log

Each state change creates an immutable MissionEvent record:

Event Type	Trigger
proposed	Mission decomposed
launched	User clicks Launch
agent_started	Subtask begins execution
agent_completed	Subtask finishes
agent_redirected	Subtask prompt updated
agent_stopped	Subtask cancelled
agent_spawned	New subtask added
mission_completed	All subtasks done
mission_failed	Execution error
mission_cancelled	User cancelled