Define Tasks

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

Navigate to Tasks

Open your project and click Tasks in the sidebar.

Click Create Task

Click the Create Task button.

Set the name

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

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.

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:

Validation — the gateway rejects task sessions with invalid context
Policy input — the context is available as task.context in CEL expressions

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 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"]`

Get Started

Core Concepts

Console Guide

Gateway

Policies

Create a task

Context schema design

Task-level tool restrictions

Next steps

Write policies

Task sessions API

​Create a task

​Context schema design

​Task-level tool restrictions

​Next steps

Write policies

Task sessions API

Create a task

Context schema design

Task-level tool restrictions

Next steps