Running a task

agent-env task run loads a stored task and runs it in the terminal's own process:

Terminal

agent-env task run --id reply-to-dana --output-dir out --project-id <project-id>

Output (banner and most step results left out)

Fetching task: id=reply-to-dana version=latest...
Found task: id=reply-to-dana version=2 steps=5
Task instance: reply-to-dana-gbgs1yub
Running step [1/5]: deploy_env (id=email)...
Completed step [1/5]: deploy_env (id=email) [42.9s]

Running step [2/5]: load_artifact (id=inbox)...

Running step [3/5]: deploy_agent (id=assistant)...
Completed step [2/5]: load_artifact (id=inbox) [1.9s]
Completed step [3/5]: deploy_agent (id=assistant) [23.7s]

Running step [4/5]: prompt_agent (id=reply)...
Completed step [4/5]: prompt_agent (id=reply) [63.3s]

Running step [5/5]: env_outcome_verifier (id=check)...
Completed step [5/5]: env_outcome_verifier (id=check) [0.4s]
score (verifier_id=sent): 1.0

Task completed!
Task context written to: out/reply-to-dana_811f14b9.json

The run loads the latest version unless you pass --version. A step starts as soon as the steps in its depends_on have finished. Runs of the same task go at once with --k, each with its own task instance and context:

--k 3 starts three runs of reply-to-dana at once. Each registers its own task instance and deploys its own email.Each run follows the DAG on its own clock: run 3’s inbox and assistant start together while run 2’s env is still deploying.Runs 1 and 3 are prompting their agents while run 2’s agent is still starting. No run waits for another.Run 3 finishes first: its check finds its own env instance in its own context and scores it 1.0.Run 1 finishes too. Its agent answered without emailing Dana, so check scores 0.0, and the run still completes.Run 2 finishes, and the command prints All 3 runs completed!: three instances, three contexts, three files.

The `TaskStepContext`

task run makes one TaskStepContext for the run: empty lists, and metadata with the task id and the run’s options.email deploys the env and adds its DeployedEnv to deployed_envs: the env_id, the instance and its MCP URL.Both find email by its env_id. inbox adds nothing; assistant adds its DeployedAgent and the default model.reply finds its agent by agent_name and adds the agent’s answer to prompt_responses under prompt_id: reply.check reads email’s MCP URL, runs verify() there and writes its rows and score to metadata.verifications.sent.The final context goes to out/reply-to-dana_811f14b9.json, with litellm_api_key and the other secrets removed.

The TaskStepContext is a ledger of what has happened during a task run. When the run completes, the command writes it to --output-dir as <task id>_<8 hex>.json, with secrets such as litellm_api_key removed.

The task run instance

Each run is a task instance, with a record in the document store: the task id and version, status, and current_step of total_steps. After each step the run writes to the record only what that step changed, so steps that finish together don't overwrite each other. agent-env task get-instance --id reply-to-dana-gbgs1yub reads it back, during the run or after it:

task run registers a task instance in task_instances: its id, the task version, status: running and 0 of 5 steps.When email finishes, the record gets only what it changed: its DeployedEnv, its entry in completed_steps, 1 of 5.inbox and assistant finish together. Each writes only its own paths, so neither overwrites the other: 3 of 5.reply adds the agent’s answer to the record’s context, and the count reaches 4 of 5.At 5 of 5 the record’s status becomes completed, and completed_at_utc is set.agent-env task get-instance reads the record from the document store, during the run or after it.--k 3 registers three instances at once, each with its own id, record and file.

Task run options

Option	Default	Meaning
`--version`	the latest	The task version to run
`--output-dir`	a new directory under `/tmp`	Where the context file goes
`--k`	`1`	How many runs to start at once
`--agent-model`	none	The model every `prompt_agent` step asks for, over the step's `model`
`--a2a-agent-id`	none	The agent every `deploy_agent` step deploys, over its `a2a_agent_id`
`--env-sandbox`, `--agent-sandbox`	none	The sandbox for every `deploy_env` or `deploy_agent` step, over its `sandbox_type`
`--start-step`, `--context-json`	`0`, none	The 0-based index of the first step to run, and a JSON file to start the context from
`--litellm-api-key`	none	The model API key for this run

agent-env task run-batch --id <task id> --seeds seeds.csv runs a task once per row of a CSV file, and each row's columns fill the task's placeholders of the same names: a sender column fills <sender> in Reply to <sender>.. Without a sandbox option or sandbox_type, envs and agents run in [sandbox] default and [sandbox] agent_default, both local Docker unless config.toml says otherwise. agent-env task run --help lists the rest.

Task run failures

A step that raises adds an entry to metadata.failed_steps. With fail_task_on_error: true, the default, no further step starts and the record ends failed, with the error:

Output (last lines)

Running step [5/5]: env_outcome_verifier (id=check)...
Step check failed (fatal): Artifact check-reply not found
Error: Artifact check-reply not found

With false, the steps that wait for it run anyway, so read failed_steps before you trust the score. A step with a retry_config first runs part of the task again; see When a step fails.

Resume a task run

A failed run leaves its env instance and agent running, so you can pick it up at the failed step. Fix what failed, then save the failed run's context from its record, without its failed_steps:

save_context.py

import json

from agent_env.task import Task

context = Task.get_instance("reply-to-dana-dvbt79er").context
context["metadata"].pop("failed_steps", None)
with open("context.json", "w") as f:
    json.dump(context, f, indent=2)

Then run from check, index 4 of the step list:

Terminal

agent-env task run --id reply-to-dana --start-step 4 --context-json context.json --output-dir out --project-id <project-id>

The steps before the index are recorded as succeeded without running, and every step from it on runs again. The resumed run is a new task instance.

Running a task

Running a taskCopy Anchor Link

The TaskStepContextCopy Anchor Link

The task run instanceCopy Anchor Link

Task run optionsCopy Anchor Link

Task run failuresCopy Anchor Link

Resume a task runCopy Anchor Link

On this page

Running a task

The `TaskStepContext`

The task run instance

Task run options

Task run failures

Resume a task run