HUD Documentation - Evaluations and RL Environments.

v6 is a leaner spec. The environment is no longer an MCP server that hands tools to the agent - it’s a small control channel that exposes capabilities (connections the agent drives itself) and tasks (prompt then reward). The agent’s harness owns the tools, so the environment side gets noticeably smaller.

Upgrade boundary

The v6 SDK does not run environments written against the v5 surface. Convert @env.scenario, @env.tool / env.add_tool, env("scenario"), and env.run(...) before upgrading the environment to v6. The removed hud.tools, hud.native, hud.services, and hud.server modules are not importable in v6.

v6 serves a control channel instead of MCP stdio/http, so old v5 agents cannot run v6 environments. Upgrade the environment source and the side that runs agents together.

The v6 spec removes most of the tool-wiring boilerplate. The conversion below maps each removed surface to its v6 owner.

At a glance

v5	v6	Notes
`Environment("name")`	`Environment(name="name", capabilities=[...])`	positional name still works; declare capabilities up front
`@env.scenario("count")`	`@env.template()`	same `yield prompt` then `yield reward` generator
`@env.tool` / `env.add_tool(ComputerTool())`	a capability (`ssh` / `mcp` / `cdp` / `rfb` / `robot`)	the agent’s harness brings the tools now
`env("count", word=...)`	`count(word=...)`	keep the `@env.template` return value; calling it builds a `Task`
`task.run("claude")` / `hud.eval(task)`	`await task.run(agent)`	or just `hud eval tasks.py claude`
`env.run(transport=...)`	`await env.serve()` / `hud serve` / `hud deploy`	v6 serves a control channel, not MCP
`.slug`, `.columns` on a task	`.slug`, `.columns` on the `Task`	unchanged

The CLI you already use is stable: hud init, hud deploy, hud eval, and hud sync tasks all carry over. Replace hud dev with hud serve.

Walk through a conversion

Here’s a small v5 coding environment - a couple of tools and one scenario:

env.py (v5)

from hud import Environment
from hud.tools import BashTool, EditTool
from hud.native import BashGrader

env = Environment("coder")
env.add_tool(BashTool())
env.add_tool(EditTool())

@env.scenario("fix-tests")
async def fix_tests(target: str = "tests/"):
    answer = yield f"Make the tests in {target} pass."
    yield await BashGrader.grade(command=f"pytest {target} -q")

Replace tools with a capability

This is the biggest change. In v5 you registered tools and the environment forwarded them, translating per provider. In v6 you declare a capability - a connection - and the agent’s harness attaches its own tools to it. Shell and file tools become a Workspace: the environment starts the sandboxed workspace and publishes its ssh capability when it serves:

env.py (v6)

from hud.environment import Environment

env = Environment(name="coder")
env.workspace("/workspace")

Other tool kinds map the same way: a browser becomes cdp, full computer-use becomes rfb, a robot becomes robot, and any custom MCP tools become an mcp capability via Capability.mcp(name=..., url=...). You no longer hand-wire ComputerTool() / BashTool() or call env.as_claude_tools() - the harness does that.

Rename @env.scenario to @env.template

The generator body is identical - yield a prompt, receive the answer, yield a reward. Just swap the decorator and keep a reference to the returned Task:

env.py (v6)

from hud.graders import BashGrader

@env.template()
async def fix_tests(target: str = "tests/"):
    answer = yield f"Make the tests in {target} pass."
    yield await BashGrader.grade(command=f"pytest {target} -q")

@env.template() also accepts id=, description=, and optional input= / returns= types (surfaced as JSON schemas in the manifest). The decorated function is a template that mints Task rows when called. Removed v5 scenario options such as chat, exclude_tools, and allowed_tools have no direct v6 equivalent; express agent and tool policy in the harness that owns it.

Build tasks by calling the task function

env("fix-tests", target="tests/") becomes a direct call on the task function. It returns a Task - the runnable unit - and .slug / .columns work exactly as before:

tasks.py (v6)

from env import fix_tests

easy = fix_tests(target="tests/unit")
easy.slug = "fix-unit-tests"
easy.columns = {"suite": "unit"}

Run it

Locally, hud eval is unchanged:

hud eval tasks.py claude

Programmatically, the hud.eval(task) context manager and task.run(model) are replaced by handing an agent to the task - it returns a Job holding the graded runs:

from hud.agents import create_agent

agent = create_agent("claude-sonnet-4-5")
job = await fix_tests(target="tests/").run(agent)
print(job.reward)

create_agent routes any model (claude-..., gpt-..., gemini-..., grok-...) through the HUD gateway and wires the tools for whichever capabilities the environment exposes.

Serve and deploy

v5 served an MCP server via env.run(transport=...). v6 serves its control channel - use hud serve while iterating and hud deploy to publish (it builds and publishes in one step). await env.serve(host, port) is the in-code equivalent.

Converting with an agent

The conversion is mechanical, so the fastest path is to let your coding agent do it. Add the HUD docs to your agent - they’re available as an MCP server at docs.hud.ai/mcp, or use the Copy / Claude / ChatGPT buttons at the top of any docs page - then point it at this guide and the Environment reference and ask it to adapt your env.py. A prompt like:

Convert this v5 HUD environment to v6 using the migration guide at docs.hud.ai. Rename scenarios to tasks, replace registered tools with the capability they imply (shell/files → ssh, browser → cdp, computer-use → rfb, custom tools → mcp), switch env("name", ...) to calling the task, and fix the hud.tools imports below.

Make the conversion while the environment still uses the v5 SDK, then upgrade it to v6 and run its task tests. Old imports and registered tools do not have runtime fallbacks in v6.

Imports to update

In v6, hud.tools and the other v5 compatibility modules were removed entirely. Update every old import before upgrading:

v5 import	v6 replacement	What to do
`AgentTool`, `BaseTool`	none	drop the class; expose a sub-agent as a plain function on a FastMCP server and attach it as an `mcp` capability - see Subagents as tools
Result types: `EvaluationResult`, `ScenarioResult`, `SubScore`, `AgentAnswer`, `Citation`	`hud.graders` (`ScenarioResult` becomes `EvaluationResult`), `hud.environment.Answer`, and `hud.agents.types.Citation`	import each type from its v6 module
`ContentResult`	supported in v6 at `hud.agents.types`	`from hud.agents.types import ContentResult` - `.to_content_blocks()` builds a tool’s `list[ContentBlock]` from text + an optional image
`ToolError`	removed (no v6 counterpart)	return an error result (`ContentResult(error=...).to_content_blocks()`) or raise an ordinary exception - the loop surfaces it to the agent and continues
`hud.server.MCPServer`	`fastmcp.FastMCP`	import `FastMCP` directly and manage its lifecycle with `@env.initialize` / `@env.shutdown`
Shell/edit tools: `BashTool`, `EditTool`, `ShellTool`, `ApplyPatchTool`, …	`ssh` capability	call `env.workspace(root)` instead
Computer tools: `HudComputerTool`, `AnthropicComputerTool`, `OpenAIComputerTool`, `GeminiComputerTool`, `QwenComputerTool`, …	`rfb` or `cdp` capability	declare the capability explicitly
Anything else under `hud.tools`: `PlaywrightTool`, `JupyterTool`, `MemoryTool`, filesystem tools, executors, `SubmitTool`, `BaseHub`	no automatic replacement	remove it - declare a capability (`cdp` for browser) or serve your own tool over `mcp`
Graders: `hud.native` (`BashGrader`, `LLMJudgeGrader`, `exact_match`, …)	`hud.graders`	change the import to `from hud.graders import ...`
Chat: `hud.services.Chat`	`hud.Chat`	change the import to `from hud import Chat`
`hud.services.ChatService`	removed - the A2A executor left the SDK	copy the reference server in `cookbooks/a2a-chat/server.py` (a thin A2A adapter over `Chat`)
`hud.shared.*` (`exceptions`, `requests`, …)	merged into `hud.utils` (no alias - no environment imported it)	change the import to `from hud.utils... import ...`

The rule of thumb: grading types move to hud.graders, tools become capabilities, and removed v5 modules must be gone before the v6 upgrade.

Next steps

Environment reference

Define capabilities, lifecycle hooks, and tasks.

Tasks & Tasksets

Define tasks, collect tasksets, and grade runs.

Package & deploy

Publish with hud deploy and run at scale.

Start here

Guides

Reference

Advanced

Experimental

Cookbooks

Internals

More

Migrate to v6

Upgrade boundary

At a glance

Walk through a conversion

Converting with an agent

Imports to update

Next steps

Environment reference

Tasks & Tasksets

Package & deploy

​Upgrade boundary

​At a glance

​Walk through a conversion

​Converting with an agent

​Imports to update

​Next steps

Environment reference

Tasks & Tasksets

Package & deploy

Upgrade boundary

At a glance

Walk through a conversion

Converting with an agent

Imports to update

Next steps