Creating tasks
Create tasks from the dashboard, the CLI, the API, integrations and plans — with knowledge, requirements, environments and idempotency.
Where tasks come from
- Dashboard: Tasks → New task (standard, review or plan).
- CLI:
agentctl task create --project ID --title T --prompt P [--priority HIGH] [--knowledge-file FILE]. - API:
POST /api/v1/orgs/:orgId/tasks. - Integrations: GitHub and GitLab issues,
/agentcomments, pull requests, and signed webhooks. - Plans: Create N tasks on a completed plan.
- VS Code: from a selection, with an API token.
Fields
| Field | Notes |
|---|---|
projectId, title, prompt | Required. Prompts up to 100,000 characters |
knowledge | Background for the agent (up to 50,000 characters), next to organization and project knowledge |
priority | CRITICAL, HIGH, NORMAL (default), LOW |
dependencies | Up to 100 task ids that must complete first |
requirements | os, labels, tools, agentCapabilities, minContextWindow, or a specific workerId, agentId, providerId, modelId |
policy | A policy layer for this task only |
environment | An environment profile (variables and secrets for this task) |
capabilityIds | Capabilities to install at the task scope |
idempotencyKey | Same key, same organization → same task (also as the Idempotency-Key header) |
Example
Terminal
curl -X POST "$AO_SERVER/api/v1/orgs/$AO_ORG/tasks" \
-H "Authorization: Bearer $AO_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: nightly-deps" \
--data '{
"projectId": "prj_123",
"title": "Update patch-level dependencies",
"prompt": "Update dependencies to the latest patch versions and fix anything that breaks.",
"priority": "LOW",
"requirements": { "os": ["linux"], "tools": ["pnpm"] }
}'Writing good prompts
Say what should change, where, and how success is checked. Put stable context — conventions, architecture — in organization or project knowledge instead of every prompt. Never put secrets in prompts or knowledge; use environment profiles and secret references.