Skip to main content
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.
FieldPurpose
NameA descriptive name (e.g., resolve-ticket, generate-report)
LabelsKey-value metadata used in policies (e.g., category: support)
Context schemaA JSON Schema that defines what context the agent must provide when starting this task
Allowed toolsOptional 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.
PrioritySourceBehavior
1 (highest)Task allowedToolsIf set, only these tools are visible
2Identity allowedToolsFalls back to identity-level if task doesn’t specify
3 (lowest)No restrictionIf neither is set, all project tools are visible

​
Next steps

Task sessions API

Create and manage task sessions via the API.

Define tasks

Step-by-step guide to defining tasks in the console.