> ## 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.

# Define Tasks

> Create task definitions with context schemas and tool restrictions for scoped access.

Tasks define the types of work your agents perform. Each task has a context schema that describes the runtime data an agent provides when starting a task session.

## Create a task

<Steps>
  <Step title="Navigate to Tasks">
    Open your project and click **Tasks** in the sidebar.
  </Step>

  <Step title="Click Create Task">
    Click the **Create Task** button.
  </Step>

  <Step title="Set the name">
    Choose a descriptive name — e.g., `resolve-ticket`, `process-refund`, `generate-report`.
  </Step>

  <Step title="Add labels (after creation)">
    Once the task is created, go to its **settings page** to add labels. Labels are available in policy expressions as `task.labels`.

    Common labels: `category: support`, `priority: high`, `department: finance`.
  </Step>

  <Step title="Define the context schema">
    Write a JSON Schema that describes what context the agent must provide when starting this task.

    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "ticket_id": {
          "type": "string",
          "description": "The ticket being resolved"
        },
        "customer_id": {
          "type": "string",
          "description": "The customer who filed the ticket"
        }
      },
      "required": ["ticket_id", "customer_id"]
    }
    ```

    The context schema serves two purposes:

    1. **Validation** — the gateway rejects task sessions with invalid context
    2. **Policy input** — the context is available as `task.context` in CEL expressions
  </Step>

  <Step title="Set allowed tools (optional)">
    Optionally restrict which tools this task can use. This overrides identity-level tool restrictions when a task session is active.
  </Step>
</Steps>

## Context schema design

Design your context schema around the data your policies need to evaluate.

**Support task** — scope access to a specific customer:

```json theme={null}
{
  "type": "object",
  "properties": {
    "customer_id": { "type": "string" },
    "ticket_id": { "type": "string" }
  },
  "required": ["customer_id", "ticket_id"]
}
```

**Deployment task** — control which environment is targeted:

```json theme={null}
{
  "type": "object",
  "properties": {
    "environment": { "type": "string", "enum": ["staging", "production"] },
    "service": { "type": "string" },
    "version": { "type": "string" }
  },
  "required": ["environment", "service"]
}
```

**Data analysis task** — restrict queryable tables:

```json theme={null}
{
  "type": "object",
  "properties": {
    "dataset": { "type": "string" },
    "allowed_tables": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["dataset", "allowed_tables"]
}
```

<Tip>
  Include an `enum` constraint for fields like `environment` to prevent agents from using arbitrary values.
</Tip>

## Task-level tool restrictions

If a task defines allowed tools, they take priority over the identity's tool restrictions when a session for this task is active.

| Identity tools    | Task tools   | Effective tools               |
| ----------------- | ------------ | ----------------------------- |
| Not set           | Not set      | All project tools             |
| `["a", "b", "c"]` | Not set      | `["a", "b", "c"]`             |
| `["a", "b", "c"]` | `["x", "y"]` | `["x", "y"]` (task overrides) |
| Not set           | `["x", "y"]` | `["x", "y"]`                  |

## Next steps

<CardGroup cols={2}>
  <Card title="Write policies" icon="pencil" href="/console/write-policies">
    Author policies that reference task context.
  </Card>

  <Card title="Task sessions API" icon="code" href="/gateway/task-sessions">
    Learn how agents create task sessions at runtime.
  </Card>
</CardGroup>