Skip to main content
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

1

Navigate to Tasks

Open your project and click Tasks in the sidebar.
2

Click Create Task

Click the Create Task button.
3

Set the name

Choose a descriptive name — e.g., resolve-ticket, process-refund, generate-report.
4

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

Define the context schema

Write a JSON Schema that describes what context the agent must provide when starting this task.
{
  "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
6

Set allowed tools (optional)

Optionally restrict which tools this task can use. This overrides identity-level tool restrictions when a task session is active.

​
Context schema design

Design your context schema around the data your policies need to evaluate. Support task — scope access to a specific customer: 
{
  "type": "object",
  "properties": {
    "customer_id": { "type": "string" },
    "ticket_id": { "type": "string" }
  },
  "required": ["customer_id", "ticket_id"]
}
Deployment task — control which environment is targeted: 
{
  "type": "object",
  "properties": {
    "environment": { "type": "string", "enum": ["staging", "production"] },
    "service": { "type": "string" },
    "version": { "type": "string" }
  },
  "required": ["environment", "service"]
}
Data analysis task — restrict queryable tables: 
{
  "type": "object",
  "properties": {
    "dataset": { "type": "string" },
    "allowed_tables": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["dataset", "allowed_tables"]
}
Include an enum constraint for fields like environment to prevent agents from using arbitrary values.

​
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 toolsTask toolsEffective tools
Not setNot setAll 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

Write policies

Author policies that reference task context.

Task sessions API

Learn how agents create task sessions at runtime.