More task steps

The step registry holds 49 built-in step types. Six of them make up most tasks, and Important Task Steps covers them: deploy_env, load_artifact, deploy_agent, prompt_agent, rubrics_verifier and collect_artifacts. This page lists the other 43 in seven families. The last family, the 20 registration validators, is one you rarely put in a task yourself.

Each table gives a step's key fields, not all of them: required fields first, then the useful optional ones, with defaults in parentheses. Every step also takes id, type, depends_on, fail_task_on_error and retry_config, which What is a task step covers.

ProvisioningCopy Anchor Link

These steps build a machine for a task that needs one rather than an env, such as a coding task: a bare sandbox, a container built on it, and an agent installed into the container. The last one stops sandboxes, a machine's or an env's and an agent's.

install_agent reaches the agent through the sandbox's tunnel for its A2A port, so that port must be in the sandbox's exposed_ports and, for a container, in its ports too. A deploy_agent step with a sandbox_name does something else: it runs the agent in a container of its own on that sandbox, which needs port 8000 in exposed_ports.

A task without an envCopy Anchor Link

This task runs a coding agent against a repository's tests. box is the machine, repo the repository's container on it, and coder the agent installed into that container. The verifier, run_container_unit_tests_verifier, is in Code and grading:

[
  {"id": "box", "type": "deploy_sandbox", "sandbox_name": "box", "sandbox_mode": "vm", "exposed_ports": [8000], "depends_on": []},
  {"id": "repo", "type": "run_docker_container", "sandbox_name": "box", "container_name": "repo", "docker_context_url": "https://example.com/repo.zip", "ports": [8000], "keep_alive_with_base_command": true, "depends_on": [{"task_step_id": "box"}]},
  {"id": "coder", "type": "install_agent", "sandbox_name": "box", "container_name": "repo", "a2a_agent_id": "claude-code", "agent_name": "coder", "depends_on": [{"task_step_id": "repo"}]},
  {"id": "fix", "type": "prompt_agent", "agent_name": "coder", "prompt_id": "fix", "prompt": "Make the failing tests pass.", "depends_on": [{"task_step_id": "coder"}]},
  {"id": "tests", "type": "run_container_unit_tests_verifier", "sandbox_name": "box", "container_name": "repo", "command": "pytest -q", "verifier_id": "tests", "depends_on": [{"task_step_id": "fix"}]},
  {"id": "teardown", "type": "teardown_sandboxes", "sandbox_names": ["box"], "fail_task_on_error": false, "depends_on": [{"task_step_id": "tests"}]}
]

keep_alive_with_base_command starts the image's own command in the background and keeps the container running, so the agent can be installed into it. Port 8000 is the A2A port this example assumes the agent's install extension names. Preflight looks up only envs and run_code scripts, so this task is created with nothing registered:

agent-env task create fix-tests.json --id fix-the-tests --project-id <project-id>

Reading steps from fix-tests.json...
  Step 1/6: deploy_sandbox id=box version=1
  Step 2/6: run_docker_container id=repo version=1
  Step 3/6: install_agent id=coder version=1
  Step 4/6: prompt_agent id=fix version=1
  Step 5/6: run_container_unit_tests_verifier id=tests version=1
  Step 6/6: teardown_sandboxes id=teardown version=1
Creating task 'fix-the-tests' with 6 steps (project_id=<project-id>)...
Created task: id=fix-the-tests version=1 steps=6

Env controlCopy Anchor Link

These steps act on an env instance that a deploy_env step started, found by env_id, and run before the agent is prompted. apply_server_config calls extensions your MCP servers advertise on their environment cards. modify_env_tool_access, sync_env_clock and register_env_triggers call extensions the gateway advertises, so they need the gateway topology, the default.

The executor agent, the one that carries out nl actions, must be deployed with a role that is not in watch_roles; otherwise its own tool calls would fire the triggers, and the step fails.

Two of these steps give reply-to-dana a deadline. The trigger disables send for the role assistant at 17:00 on Friday, virtual time. The clock starts on Monday at 09:00 and runs 3,600 times faster than real time, so the week passes in under two minutes:

[
  {"id": "deadline", "type": "register_env_triggers", "env_id": "email", "triggers": [{"id": "lock-send", "when": {"type": "time", "at": "2026-10-02T17:00:00Z"}, "actions": [{"type": "permission", "action": "disable", "role": "assistant", "tools": ["send"]}]}], "depends_on": [{"task_step_id": "email"}]},
  {"id": "clock", "type": "sync_env_clock", "env_id": "email", "virtual_time": "2026-09-28T09:00:00Z", "virtual_seconds_per_real_second": 3600, "depends_on": [{"task_step_id": "inbox"}, {"task_step_id": "assistant"}, {"task_step_id": "deadline"}]}
]

In this variant of the task, the assistant step also sets "role": "assistant", so the trigger applies to its tool calls, and reply depends on clock instead of on inbox and assistant.

AgentsCopy Anchor Link

These steps add to an agent that a deploy_agent or install_agent step started, found by agent_name, through extensions the agent's card advertises. build_mcp_cli is the exception: it reads an env instance and makes an artifact for an agent to load.

CaptureCopy Anchor Link

These steps save a run's state as new artifacts, which outlast the sandboxes and which a later task can load. So does collect_artifacts, which saves the files an agent made.

Without snapshot_id, the universe's id is snapshot-<env_id>- followed by the run's eight-character suffix, so a retried run adds a version rather than a second universe.

Code and gradingCopy Anchor Link

run_code runs your own script. The other five are verifiers, besides rubrics_verifier on the previous page: each writes a score to metadata["verifications"][<verifier_id>], and all but aggregate_verifiers write their result rows beside it.

score_aggregator is all_pass, any_pass or weighted_average. Where the table gives no default for verifier_id, an unset one is a random id, so set it whenever something reads the result.

env_outcome_verifierCopy Anchor Link

This verify() reads the sent folder through the data plane, which the instance serves at the same base URL as /mcp, and passes when an email went to Dana:

from agentenv_protocol import DataPart, client


async def verify(mcp_url: str) -> list[dict]:
    state = await client.get_data(mcp_url.removesuffix("/mcp"))
    sent = [email for part in state.parts if isinstance(part, DataPart) for email in part.data.get("sent", [])]
    replied = any(email["to"] == "dana@example.com" for email in sent)
    return [{"id": "replied-to-dana", "description": "An email was sent to dana@example.com", "result": replied}]

No command stores a single file as a file artifact, so check-reply is stored from Python, and the check step of reply-to-dana runs it:

from agent_env.artifact import FileArtifact

FileArtifact.put(id="check-reply", description="Checks that Dana got a reply", file_path="verify.py")

{"id": "check", "type": "env_outcome_verifier", "env_id": "email", "file_artifact_id": "check-reply", "verifier_id": "sent", "depends_on": [{"task_step_id": "reply"}]}

Human in the loopCopy Anchor Link

These two bring a person into a run: one waits for a decision, the other lets the agent ask.

Core ships no screen for a review's decision. Record it from Python with get_review_store().set_decision(instance_id, step_id, "continue"), or "abort", imported from agent_env.task_step.review_store. The wait holds no sandbox, so place it after the agent's output is saved and before collect_artifacts.

Registration validatorsCopy Anchor Link

The 20 validators check that an env or an agent works with the framework: that it serves its card, answers the protocol, describes its tools, and handles what the framework sends it. The validate commands build them into a task, together with steps such as deploy_env, deploy_agent and prompt_agent, run it, and save the results to the env's or the agent's metadata:

Each run stores its task as a new version, for example validate-email-v1 for version 1 of email and validate-a2a-claude-code-v1 for version 1 of claude-code.

Listing the registryCopy Anchor Link

The registry is what a step's type is looked up in, and it can hold more than the built-ins. To see what yours holds, read it from Python:

from agent_env.task_step.registry import get_task_step_registry

registry = get_task_step_registry()
print(len(registry))
print(registry["snapshot_env"])
print(sorted(registry)[:4])

49
<class 'agent_env.task_step.task_steps.snapshot_env.SnapshotEnvTaskStep'>
['add_skills', 'agent_prompt_response_verifier', 'aggregate_verifiers', 'apply_server_config']

get_task_step_registry() builds the registry from the configuration in effect, so run it in the directory, or with the AGENT_ENV_CONFIG, that your tasks use.

Your own stepsCopy Anchor Link

A step type of your own, such as the ReplyMentionsStep that Your own step writes, joins the same registry in one of two ways: [task_steps] impls in config.toml names its class as module:Class, or an installed package registers it under the agent_env.task_steps entry point, named after its type.

[task_steps]
impls = ["mycorp.steps:ReplyMentionsStep"]

With that file in effect and mycorp importable, the same script counts one more:

50
<class 'agent_env.task_step.task_steps.snapshot_env.SnapshotEnvTaskStep'>
['add_skills', 'agent_prompt_response_verifier', 'aggregate_verifiers', 'apply_server_config']

Every process that reads or runs a task using the step needs the same registration.