> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devctrl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> Tasks define what an agent is trying to do. They carry context, scope permissions, and expire automatically.

A task represents a specific job an agent performs — like "resolve a support ticket" or "process a refund." Tasks carry context (the ticket ID, the customer) and can restrict which tools the agent uses during that job.

## Task definitions

A task definition is a template you create in the console. It describes the type of work an agent can do.

| Field              | Purpose                                                                                |
| ------------------ | -------------------------------------------------------------------------------------- |
| **Name**           | A descriptive name (e.g., `resolve-ticket`, `generate-report`)                         |
| **Labels**         | Key-value metadata used in policies (e.g., `category: support`)                        |
| **Context schema** | A JSON Schema that defines what context the agent must provide when starting this task |
| **Allowed tools**  | Optional list of tools this task can use (overrides identity-level restrictions)       |

## Context schema

The context schema is a JSON Schema that validates the data an agent passes when starting a task session. This context becomes available in policy evaluation as `task.context`.

```json theme={null}
{
  "type": "object",
  "properties": {
    "ticket_id": { "type": "string" },
    "customer_id": { "type": "string" },
    "priority": { "type": "string", "enum": ["low", "medium", "high"] }
  },
  "required": ["ticket_id", "customer_id"]
}
```

When the agent creates a task session, it provides context that matches this schema:

```json theme={null}
{
  "ticket_id": "TICKET-123",
  "customer_id": "cust_456",
  "priority": "high"
}
```

<Note>
  Context validation happens at task session creation time. If the context doesn't match the schema, the session is rejected.
</Note>

## Task sessions

A task session is a short-lived, scoped token that an agent uses while performing a task. It connects an identity to a task with specific context.

```bash theme={null}
# Create a task session
curl -X POST https://gateway.devctrl.ai/v1/tasks/sessions \
  -H "Authorization: Bearer YOUR_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "task_abc123",
    "context": { "ticket_id": "TICKET-123", "customer_id": "cust_456" },
    "ttl": 3600
  }'
```

Task sessions are:

* **Time-limited** — they expire after the specified TTL (max 24 hours, default 1 hour)
* **Scoped** — they carry the task context that policies can reference
* **Deletable** — the agent (or your system) can explicitly end a session early

The agent includes the task token in subsequent MCP requests via the `X-Task-Token` header:

```
Authorization: Bearer YOUR_CREDENTIAL
X-Task-Token: YOUR_TASK_TOKEN
```

## Task in policy context

During policy evaluation, the task is available as:

```json theme={null}
{
  "task": {
    "name": "resolve-ticket",
    "labels": { "category": "support" },
    "context": {
      "ticket_id": "TICKET-123",
      "customer_id": "cust_456",
      "priority": "high"
    }
  }
}
```

This lets you write policies that reference the task's runtime context:

```cel theme={null}
// Only allow access to the customer in the current task
task.context.customer_id == request.tool.args.customer_id
```

## Task-level tool restrictions

Tasks can define their own allowed tools list, which **overrides** the identity-level list.

| Priority    | Source                  | Behavior                                             |
| ----------- | ----------------------- | ---------------------------------------------------- |
| 1 (highest) | Task `allowedTools`     | If set, only these tools are visible                 |
| 2           | Identity `allowedTools` | Falls back to identity-level if task doesn't specify |
| 3 (lowest)  | No restriction          | If neither is set, all project tools are visible     |

## Next steps

<CardGroup cols={2}>
  <Card title="Task sessions API" icon="code" href="/gateway/task-sessions">
    Create and manage task sessions via the API.
  </Card>

  <Card title="Define tasks" icon="plus" href="/console/define-tasks">
    Step-by-step guide to defining tasks in the console.
  </Card>
</CardGroup>