Core Concepts

from hud import Environment

env = Environment("my-env")

@env.scenario("count")
async def count(word: str, letter: str):
    # ---- PROMPT ----
    # The first yield sends a prompt to the agent.
    # The agent receives this prompt, runs its reasoning loop,
    # and returns its final answer as a string.
    answer = yield f"How many '{letter}' in '{word}'?"

    # ---- SCORING ----
    # After the agent responds, we check if the answer is correct.
    # The second yield returns a reward: 1.0 for correct, 0.0 for wrong.
    correct = str(word.lower().count(letter.lower()))
    yield 1.0 if answer and correct in answer else 0.0

env("count", word="strawberry", letter="r")  # one task (answer: 3)
env("count", word="banana", letter="a")      # another task (answer: 3)
env("count", word="mississippi", letter="s") # another task (answer: 4)

@env.tool()
def count_letter(text: str, letter: str) -> int:
    """Count occurrences of a letter in text."""
    return text.lower().count(letter.lower())

from hud import Environment
from hud.tools import AnthropicComputerTool, BashTool, EditTool

env = Environment("desktop-agent")

# Add computer control -- the agent can click, type, scroll, and take screenshots.
# HUD automatically adapts these to each model's native format
# (Claude's computer_20250124, OpenAI's computer_use_preview, etc.)
env.add_tool(AnthropicComputerTool())

# Add a shell -- the agent can run bash commands in a persistent session.
env.add_tool(BashTool())

# Add a file editor -- the agent can view and edit files with str_replace.
env.add_tool(EditTool())

from hud import Environment
from hud.tools import PlaywrightTool
from hud.tools.hosted import WebSearchTool
from hud.tools.filesystem import ReadTool, GrepTool

env = Environment("web-researcher")

# Add a browser -- the agent can navigate pages, click elements, fill forms.
env.add_tool(PlaywrightTool())

# Add web search -- Claude's native search, executed server-side by Anthropic.
env.add_tool(WebSearchTool())

# Add file reading -- the agent can read files and search their contents.
env.add_tool(ReadTool())
env.add_tool(GrepTool())

# Connect a FastAPI app -- all its routes become agent-callable tools.
env.connect_fastapi(app)

# Connect an OpenAPI spec -- the spec's endpoints become tools.
env.connect_openapi("https://api.example.com/openapi.json")

# Connect another HUD environment -- its tools become available in yours.
env.connect_hub("hud-evals/browser")

task = env("count", word="strawberry", letter="r")

import hud
from hud.agents import create_agent

task = env("count", word="strawberry", letter="r")
agent = create_agent("claude-sonnet-4-5")

async with hud.eval(task) as ctx:
    result = await agent.run(ctx)

print(f"Reward: {result.reward}")  # 1.0 if agent answers "3"

async with hud.eval(task) as ctx:
    # ctx.prompt         -- the prompt from the scenario's first yield
    # ctx.call_tool()    -- execute a tool call
    # ctx.submit()       -- submit the agent's final answer, triggers scoring
    # ctx.as_openai_chat_tools()  -- tools in OpenAI format
    # ctx.as_claude_tools()       -- tools in Anthropic format

    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": ctx.prompt}],
        tools=ctx.as_openai_chat_tools()
    )
    # ... handle tool calls in your own loop ...
    await ctx.submit(response.choices[0].message.content)

print(ctx.reward)