# Missions - User Guide

Schedule AI agents to run tasks automatically — daily reports, weekly audits, continuous monitoring, and one-time jobs.

# Missions

Missions are scheduled AI tasks. Set up a mission, assign it to an agent, and it runs automatically on your schedule.

Use missions for recurring work: daily reports, weekly SEO audits, content publishing, data monitoring, and more. Missions appear in the org sidebar and are global — not tied to a specific space.

---

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Mission** | A scheduled task with a goal, schedule, and assigned agent |
| **Goal** | What the agent should accomplish (plain text instructions) |
| **Schedule** | When to run: once, cron, continuous, or manual |
| **Agent** | Optional — runs the mission with this agent's system prompt, model, and capabilities. The `characterId` field in the API refers to the agent ID |
| **Space** | Optional — gives the mission access to files, MCPs, and secrets |
| **maxTurns** | Limits how many turns the agent can take per run (default: 100) |
| **team** | Controls subagent delegation: `auto`, `on`, or `off` |
| **resumeSession** | Enables session continuity across multiple runs |

---

## Schedule Types

| Type | Description | Example |
|------|-------------|---------|
| `none` | Manual trigger only | Run on-demand |
| `once` | Run once immediately | One-time setup task |
| `cron` | Recurring schedule | `0 9 * * MON` (Mondays at 9am) |
| `continuous` | Run continuously | Always-on monitoring |

### Cron Examples

| Cron Expression | Description |
|----------------|-------------|
| `0 9 * * *` | Every day at 9:00 AM |
| `0 9 * * MON` | Every Monday at 9:00 AM |
| `0 9 * * 1-5` | Weekdays at 9:00 AM |
| `0 */6 * * *` | Every 6 hours |
| `0 9 1 * *` | First of every month at 9:00 AM |

---

## Execution Model

Missions run via a **job queue** powered by BullMQ with Redis:

- **3 concurrent workers** process missions in parallel
- **Automatic retry**: 2 attempts with exponential backoff on failure
- **Stalled job detection**: jobs that stop responding are recovered automatically
- **Status flow**: `pending` -> `running` -> `completed` / `failed`

Mission results create chat entries visible in the space (if a space is assigned).

---

## Create a Mission

### Via Web App

1. Navigate to the **Missions** section in the sidebar
2. Click **+ New Mission**
3. Configure:
   - **Title**: "Weekly SEO Report"
   - **Goal**: "Analyze this week's search performance. Compare to last week. Send the summary."
   - **Schedule**: Cron — `0 9 * * MON`
   - **Agent**: Select "Sarah" (optional)
   - **Space**: Select your SEO workspace (optional)
   - **Max Turns**: 100 (optional)
   - **Team**: auto (optional — controls subagent delegation)
4. Save

### Via CLI

```bash
teamday missions create \
  --title "Weekly SEO Report" \
  --goal "Analyze this week's search performance, compare to last week, and summarize the findings." \
  --schedule cron --cron "0 9 * * MON" \
  --agent <agent-id> \
  --space <space-id>
```

### Via API

```bash
curl -X POST "https://cc.teamday.ai/api/v1/missions" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly SEO Report",
    "goal": "Analyze this week search performance, compare to last week, and summarize the findings.",
    "spaceId": "space-abc123",
    "characterId": "agent-sarah-id",
    "schedule": {
      "type": "cron",
      "value": "0 9 * * MON"
    },
    "maxTurns": 100,
    "team": "auto"
  }'
```

Note: The `characterId` field is the agent's ID. This field name is preserved for API compatibility.

**Response:**

```json
{
  "success": true,
  "id": "mission-xyz789",
  "title": "Weekly SEO Report",
  "status": "pending",
  "schedule": {
    "type": "cron",
    "value": "0 9 * * MON",
    "nextRun": "2026-02-24T09:00:00.000Z",
    "runCount": 0
  }
}
```

---

## Mission Examples

### Daily Data Summary

```json
{
  "title": "Daily Analytics Summary",
  "goal": "Pull yesterday's Google Analytics data. Report: total visitors, top 5 pages, bounce rate change. Save to reports/daily/.",
  "schedule": { "type": "cron", "value": "0 8 * * *" },
  "maxTurns": 50
}
```

### Weekly Content Audit

```json
{
  "title": "Weekly Content Audit",
  "goal": "Check all blog posts published this week for SEO compliance. Verify: meta descriptions, image alt text, internal links. Report any issues.",
  "schedule": { "type": "cron", "value": "0 17 * * FRI" },
  "team": "on"
}
```

### Continuous Monitoring

```json
{
  "title": "Error Monitor",
  "goal": "Monitor the application for critical errors. If error rate exceeds 5%, send an alert notification.",
  "schedule": { "type": "continuous" }
}
```

### One-Time Setup

```json
{
  "title": "Initial SEO Baseline",
  "goal": "Run a comprehensive SEO audit of example.com. Document current rankings, backlinks, and technical issues. Save the baseline report to reports/.",
  "schedule": { "type": "once" }
}
```

---

## Managing Missions

### Update a Mission

Pause, change the schedule, or update the goal:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/missions/mission-xyz789" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "schedule": { "type": "cron", "value": "0 9 * * 1-5" }
  }'
```

### Mission Statuses

| Status | Description |
|--------|-------------|
| `pending` | Created, waiting for first scheduled run |
| `running` | Currently executing |
| `completed` | Finished successfully (one-time missions) |
| `failed` | Execution failed (will retry if attempts remain) |
| `paused` | Temporarily stopped by user |

### Session Continuity

Missions support session continuity via the `resumeSession` flag. When enabled, each run resumes from the previous session's context using the stored `lastSessionId`, maintaining conversation history across runs.

This is useful for missions that build on previous results — like weekly reports that compare to last week, or monitoring tasks that track changes over time.

---

## Agents and Missions

Binding an agent to a mission means:
- The mission runs with the agent's **system prompt** (`systemPrompt`)
- It uses the agent's **model** preference
- It has access to the agent's **skills and MCP references**

If no agent is bound, the mission runs with default settings.

### Best Practice

Create dedicated agents for mission types:

```bash
teamday agents create \
  --name "Report Bot" \
  --role "Automated Reporting" \
  --category data \
  --system-prompt "You generate daily and weekly reports. Be concise. Use tables. Save reports to the reports/ directory with dated filenames."
```

Then bind it to multiple missions:

```json
{"title": "Daily Sales Report", "characterId": "report-bot-id", "schedule": {"type": "cron", "value": "0 8 * * *"}}
{"title": "Weekly Performance Review", "characterId": "report-bot-id", "schedule": {"type": "cron", "value": "0 9 * * MON"}}
```

Note: `characterId` in the API refers to the agent's ID.

---

## Writing Good Mission Goals

The `goal` field is the instruction the agent receives. Write it like you'd brief a human colleague:

**Vague (bad):**
```
Check the website.
```

**Specific (good):**
```
Check example.com for broken links, missing meta descriptions, and pages with no H1 tag.
Save the results to reports/site-audit-{date}.md.
If critical issues are found, create a summary at the top.
```

**Key tips:**
- State the objective clearly
- Specify output format and location
- Include thresholds or criteria when relevant
- Mention what to do with the results

---

## Next Steps

- [Missions API Guide](https://docs.teamday.ai/guides/missions-api-guide) — Full API reference for mission management
- [Spaces & Workspaces](https://docs.teamday.ai/guides/spaces) — Set up the workspace for mission execution
- [MCP Plugins](https://docs.teamday.ai/guides/mcp-plugins) — Connect external tools for mission use