Important Task Steps

Most tasks are built from the same six steps, used in the same order. A task deploys an env, loads its data and deploys an agent next to it, prompts the agent, grades the reply, and keeps what the agent made:

1. deploy_env starts an env instance.
2. load_artifact loads data into the instance, while deploy_agent starts the agent and connects it to the instance.
3. prompt_agent gives the agent its task.
4. rubrics_verifier has a judge grade the reply.
5. collect_artifacts copies files out of the agent's sandbox.

Each step finds what an earlier step made in the run's context by a name: an instance by env_id, an agent by agent_name, a reply by prompt_id. This page covers the six in that order, with reply-to-dana, a rubric named tone in place of its check, and a collect step:

[
  {"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": "tone", "type": "rubrics_verifier", "prompt_id": "reply", "verifier_id": "tone", "criteria": [{"id": "polite", "criterion": "The email to Dana is polite and signed.", "weight": 1}, {"id": "explains", "criterion": "The email tells Dana what was done with the Q3 numbers.", "weight": 1}], "depends_on": [{"task_step_id": "reply"}]},
  {"id": "collect", "type": "collect_artifacts", "agent_name": "assistant", "depends_on": [{"task_step_id": "reply"}]}
]

inbox and assistant run at the same time, as do tone and collect. Each section opens with a run of its step, then lists the fields a task author sets, required first, then the useful optional ones with their defaults, then names any fields it leaves out. The fields every step has, such as depends_on and fail_task_on_error, are on What is a task step.

deploy_envCopy Anchor Link

deploy_env deploys a registered env as a new env instance, as agent-env env deploy does. Each run of the task deploys its own instance.

Omitted: env_state_type, env_state_instance_id, priority and metadata.

deploy_env reads nothing from the context. It adds a DeployedEnv to deployed_envs: the env_id, the version it deployed, the instance's instance_id and its mcp_url. Every later step that names the env by env_id finds the instance there. A run deploys an env once: a second deploy_env with the same env_id fails with Env 'email' is already deployed.

{"id": "email", "type": "deploy_env", "env_id": "email", "depends_on": []}

load_artifactCopy Anchor Link

load_artifact loads a stored artifact into a running env instance or into an agent's sandbox, so every run starts from the same data. An environment artifact loaded into an env goes through the env's data plane: the step calls data/reset and then data/add with the artifact's file. Its environment_name must match the env's, as The name must match shows. A file artifact, or a file artifact universe, loaded into an agent is copied into its sandbox.

Omitted: collected_artifacts_step_id, the older name of artifact_from_step_id, still accepted; env_step_id, sandbox_name, container_name and snapshot_after_load.

load_artifact reads deployed_envs by env_id, or deployed_agents by agent_name. Loading an environment artifact into an env writes nothing to the context: the data is in the instance. Files copied into an agent are listed, with the agent's name and folder, in metadata["loaded_file_artifact_universes"], which is how a judge learns what it can open.

{"id": "inbox", "type": "load_artifact", "env_id": "email", "artifact_id": "inbox", "depends_on": [{"task_step_id": "email"}]}

deploy_agentCopy Anchor Link

deploy_agent deploys a registered A2A agent in its own sandbox and gives it a name for the rest of the run. For each env in env_ids, it posts the instance's MCP URL to the agent's MCP-config extension, which is when the agent gets the env's tools, email_search and send. It then registers the step's skills and sets its system_prompt, if it has them.

Omitted: env_step_id, agent_description, litellm_base_url, priority, network_policy, sandbox_name, enable_docker, metadata, and the snapshot and changelog fields that restore an agent's earlier state.

deploy_agent reads deployed_envs by each id in env_ids before it deploys anything. It adds a DeployedAgent to deployed_agents: the agent_name, the agent's A2A URL, its sandbox and its instance_id. It also sets the run's default agent model from [model.roles] agent or [model] default, unless an earlier step set it. A second agent with the same agent_name fails with Agent with name 'assistant' is already deployed.

{"id": "assistant", "type": "deploy_agent", "env_ids": ["email"], "a2a_agent_id": "claude-code", "agent_name": "assistant", "depends_on": [{"task_step_id": "email"}]}

prompt_agentCopy Anchor Link

prompt_agent sends a prompt to a deployed agent over A2A and waits for it to finish. It stores the agent's reply, where the agent's trajectory is stored, and the number of tool calls it made. That is a single turn, the default. With max_conversation_turns above 1, it runs a conversation instead: each reply goes to the user, and the user's answer comes back as the next turn. The user is the agent named user_agent_name, which answers {message, done} and ends the conversation with done: true, or a person at user_a2a_url, as Human agents shows, whose text is the next prompt as it is. Every turn lands in the conversation store.

Omitted: system_prompt, max_turns, model_params, effort, max_thinking_tokens, harness, agentenv_tools, context_id, poll_interval_seconds, trajectory_output_prefix, snapshot_config, and the other user_* fields of a conversation.

prompt_agent reads deployed_agents by agent_name, and fails with Agent with name 'assistant' not found in context.deployed_agents when no step deployed it. It adds a PromptResponse with its prompt_id to prompt_responses: the reply's text, the prompt, where the trajectory is stored, the tool-call count, the model, and the error, if the agent failed. A failed agent still leaves its PromptResponse, and then the step fails.

{"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"}]}

rubrics_verifierCopy Anchor Link

rubrics_verifier grades a reply against criteria you write in plain language. A judge reads the prompt, the reply and, by default, the trajectory, and marks each criterion passed or failed; the step folds those rows into one score from 0 to 1. By default the judge is an agent: with no agent_name, the step deploys one for the grading and stops it afterwards.

Omitted: trajectory_filter, grading_policy_prompt, context_facts_for_judge, effort, max_thinking_tokens, judge_sandbox_type, judge_priority, default_model_api_base, and the other values of output_format.

rubrics_verifier reads prompt_responses by prompt_id, and deployed_agents by agent_name when it has one. It writes metadata["verifications"][<verifier_id>]: format; results, one row per criterion with the judge's result, score and justification; the score; and where the judge's own trajectory is stored. When the PromptResponse carries an error, the step skips the judge and stores a score of 0 with one row, prompt_error.

{"id": "tone", "type": "rubrics_verifier", "prompt_id": "reply", "verifier_id": "tone", "criteria": [
  {"id": "polite", "criterion": "The email to Dana is polite and signed.", "weight": 1},
  {"id": "explains", "criterion": "The email tells Dana what was done with the Q3 numbers.", "weight": 1}
], "depends_on": [{"task_step_id": "reply"}]}

With all_pass, tone scores 1.0 only when the judge passes both criteria. A judge you name in agent_name can be any registered agent, and its prompt lists the files a load_artifact step copied into it, as the collect_artifacts example shows.

collect_artifactsCopy Anchor Link

collect_artifacts copies files out of a deployed agent's sandbox into the object store, registers each as a file artifact, and puts them together in one file artifact universe, so they outlast the sandbox. With no artifact_paths, it collects every file under base_path, and an empty folder collects nothing without failing. When you name files and none of them can be read, the step fails.

Omitted: env_id, sandbox_name and container_name, which collect from a desktop env's controller, a sandbox's host or a container instead of an agent.

collect_artifacts reads deployed_agents by agent_name. It writes metadata["collected_artifacts"][<step id>]: each file's object URL under artifacts, and the {id, version} of the universe under file_artifact_universe. A load_artifact step whose artifact_from_step_id is the collect step's id loads that universe, which is how one agent hands its files to another.

In chart-q3, the first example on Core concepts, an analyst agent saves a chart as /app/artifact/q3.png. These three steps collect it, copy it into the sandbox of a judge agent deployed beside the analyst, and have that judge grade the analyst's reply:

[
  {"id": "collect", "type": "collect_artifacts", "agent_name": "analyst", "artifact_paths": ["q3.png"], "depends_on": [{"task_step_id": "chart"}]},
  {"id": "handoff", "type": "load_artifact", "agent_name": "judge", "artifact_from_step_id": "collect", "depends_on": [{"task_step_id": "collect"}, {"task_step_id": "judge"}]},
  {"id": "grade", "type": "rubrics_verifier", "agent_name": "judge", "prompt_id": "chart", "verifier_id": "chart", "criteria": [{"id": "bars", "criterion": "q3.png is a bar chart with one bar per month of Q3.", "weight": 1}], "depends_on": [{"task_step_id": "handoff"}]}
]

handoff copies q3.png into the judge's /tmp/file_artifacts, and grade's prompt tells the judge the file is there, so it checks the chart itself rather than the analyst's description of it.

These six steps make up most tasks. More task steps covers the other built-in steps, from env_outcome_verifier, which checks an env's end state with your code, and teardown_sandboxes, which stops what a run deployed, to the steps that set an env's clock and triggers.