Creating a task

A task is a DAG of task steps. Each step does one thing, such as deploying an env, prompting an agent or grading what it did, and its depends_on names the steps it waits for. You create a task by composing it from task steps, written as a JSON list: no code. Pick a task to see its task.json, and follow a run of it one wave at a time:

Write task.jsonCopy Anchor Link

A task file is a JSON list with one object per step, like each task.json above. Each object has an id, unique within the task, a type, which selects the step's class, that class's fields, and depends_on, the steps it waits for. What is a task step covers the keys every step has. This is reply-to-dana:

[
  {"id": "email", "type": "deploy_env", "env_id": "email", "depends_on": []},
  {"id": "inbox", "type": "load_artifact", "env_id": "email", "artifact_id": "inbox", "depends_on": [{"task_step_id": "email"}]},
  {"id": "assistant", "type": "deploy_agent", "env_ids": ["email"], "a2a_agent_id": "claude-code", "agent_name": "assistant", "depends_on": [{"task_step_id": "email"}]},
  {"id": "reply", "type": "prompt_agent", "agent_name": "assistant", "prompt_id": "reply", "prompt": "Reply to Dana.", "depends_on": [{"task_step_id": "inbox"}, {"task_step_id": "assistant"}]},
  {"id": "check", "type": "env_outcome_verifier", "env_id": "email", "file_artifact_id": "check-reply", "verifier_id": "sent", "depends_on": [{"task_step_id": "reply"}]}
]

Create itCopy Anchor Link

agent-env task create task.json --id reply-to-dana --project-id <project-id>

The command checks the file, saves each step and then the task, and ends with Created task: id=reply-to-dana version=1 steps=5. --project-id is required: it names the project the task's model spend is attributed to.

VersionsCopy Anchor Link

Each create under an existing id stores a new version and never changes an earlier one. agent-env task get --id reply-to-dana --version 1 prints a stored version, and a run uses the latest unless you pass --version.

PlaceholdersCopy Anchor Link

Any string field can hold <name> placeholders, which each run fills from its seed: with the seed {"sender": "Dana"}, Reply to <sender>. runs as Reply to Dana.. agent-env task run-batch runs a task once per row of a CSV file; see Task run options.