Tasks

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.

{
  "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:

{
  "ticket_id": "TICKET-123",
  "customer_id": "cust_456",
  "priority": "high"
}

Context validation happens at task session creation time. If the context doesn’t match the schema, the session is rejected.

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.

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

{
  "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:

// 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

Get Started

Core Concepts

Console Guide

Gateway

Policies

Task definitions

Context schema

Task sessions

Task in policy context

Task-level tool restrictions

Next steps

Task sessions API

Define tasks

​Task definitions

​Context schema

​Task sessions

​Task in policy context

​Task-level tool restrictions

​Next steps

Task sessions API

Define tasks

Task definitions

Context schema

Task sessions

Task in policy context

Task-level tool restrictions

Next steps