Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/v1/agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ the final assistant message's text.

A prompted task speaks first through a bare `turn()`; a prompt-less task starts
with `turn(message)`. Leaving the context closes the exchange as `user_closed`
and finishes scoring. `interaction(mask_prompt=True)` keeps a scenario prompt
available to the task while hiding it from the assistant.
and finishes scoring. To keep a scenario away from the assistant (the user-sim
shape), hand the interaction a task whose `data.prompt` is None and score off
non-prompt fields.

## Borrowed Resources

Expand Down
2 changes: 1 addition & 1 deletion skills/create-environments/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ Choose placement from the tool's lifetime and filesystem needs:

## User simulation

There is one mechanism: the interaction — `agents.<name>.interaction(task)` in the env's `run()`; whoever calls `turn()` is the run's user, one harness segment per turn (the program yields, the caller answers, the next segment resumes the exchange with the answer). A prompt-less task is opened by the first `turn(message)`; a prompted task speaks first (bare `turn()`); `interaction(mask_prompt=True)` hides a scenario prompt from the wire while the task still scores the real row. There is no user server to declare or place; who computes the turns is env control flow:
There is one mechanism: the interaction — `agents.<name>.interaction(task)` in the env's `run()`; whoever calls `turn()` is the run's user, one harness segment per turn (the program yields, the caller answers, the next segment resumes the exchange with the answer). A prompt-less task is opened by the first `turn(message)`; a prompted task speaks first (bare `turn()`); to hide a scenario prompt from the wire, hand the interaction a task copy with `prompt=None` and keep scoring on non-prompt fields (the user-sim shape). There is no user server to declare or place; who computes the turns is env control flow:

- **Scripted user** (replay pre-generated turns, step a game engine): a plain loop inside an `Env.run()` override — see `environments/alphabet_sort_v1` or the bundled `textarena` taskset.
- **Modeled user** (an LLM playing the user): another agent role, driven live via `agents.user.interaction(...)` and relayed into the assistant's run — or just use the bundled `user-sim` env (`--env.id user-sim`), which does exactly this from the task's prompt-as-scenario.
Expand Down
8 changes: 4 additions & 4 deletions tests/v1/test_e2e.py
Original file line number Diff line number Diff line change
Expand Up @@ -479,10 +479,10 @@ async def test_env_id_user_sim(run_v1, tmp_path):
assert user.agent.trainable is False
assert user.num_turns >= 1 # the modeled user actually spoke
assert assistant.metrics["user_turns"] >= 1
# `mask_prompt`: the scenario is hidden from the assistant's harness (the run's
# visible data) while the task's own rewards still scored the real row. The
# masked view is what persists (provenance is the row's idx); both sides land
# as ONE durable episode.
# The env nulls the assistant task's prompt: the scenario is hidden from the
# assistant's harness while the task's rewards score off non-prompt fields
# (`answer`). The nulled row is what persists (provenance is the row's idx);
# both sides land as ONE durable episode.
assert assistant.task.data.prompt is None
assert "echoed" in assistant.rewards
from verifiers.v1.cli.output import read_episodes
Expand Down
39 changes: 14 additions & 25 deletions verifiers/v1/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,11 @@
resolve_client,
)
from verifiers.v1.configs.agent import AgentConfig, TimeoutConfig
from verifiers.v1.dialects import parse_message
from verifiers.v1.harness import Harness
from verifiers.v1.interception import Interception, InterceptionServer
from verifiers.v1.mcp import SharedToolServer
from verifiers.v1.rollout import RolloutRun, RolloutTimeouts, _as_messages
from verifiers.v1.rollout import Rollout, RolloutTimeouts
from verifiers.v1.runtimes import (
NetworkPolicyConfig,
Runtime,
Expand Down Expand Up @@ -150,9 +151,7 @@ class Interaction:
rewards after close. Leaving the `interaction()` context closes the exchange
as `user_closed` and finishes the rollout — hooks and scoring included."""

def __init__(
self, run: "RolloutRun", gate: asyncio.Semaphore | None = None
) -> None:
def __init__(self, run: "Rollout", gate: asyncio.Semaphore | None = None) -> None:
self._run = run
self._gate = gate
self._over = False # a terminated segment was already delivered
Expand Down Expand Up @@ -188,14 +187,16 @@ async def _turn(self, message: str | Messages | None) -> Segment:
if message is not None and prompted:
raise ValueError(
"the task's prompt opens this exchange: take its first reply with "
"a bare turn() before answering (or mask the prompt with "
"interaction(mask_prompt=True) to open the conversation yourself)"
"a bare turn() before answering (or hand the interaction a task "
"with `prompt=None` to open the conversation yourself)"
)
messages: Messages | None = None
if isinstance(message, str):
messages = [UserMessage(content=message)]
elif message is not None:
messages = _as_messages(message)
# A turn's messages may arrive typed or as wire dicts (env code naturally
# writes `{"role": "user", ...}`); the trace speaks typed, so normalize.
messages = [parse_message(m) if isinstance(m, dict) else m for m in message]
self._started = True
turns_before = self.trace.num_turns
nodes_before = len(self.trace.nodes)
Expand Down Expand Up @@ -411,7 +412,7 @@ async def _run_once(
on_trace: Callable[[Trace], None] | None,
) -> Trace:
params = self._rollout_params(task, runtime, dict(shared_tools or {}))
run = RolloutRun(task=task, on_trace=on_trace, **params)
run = Rollout(task=task, on_trace=on_trace, **params)
try:
if await run.open():
await run.step()
Expand All @@ -434,7 +435,6 @@ async def interaction(
*,
runtime: Runtime | None = None,
tools: Mapping[str, SharedToolServer] | None = None,
mask_prompt: bool = False,
on_trace: Callable[[Trace], None] | None = None,
) -> AsyncIterator[Interaction]:
"""Interact with this agent turn-by-turn: a full rollout of `task` where
Expand All @@ -446,11 +446,10 @@ async def interaction(

The task's shape says who speaks first: a prompt-less task is opened by
the first `turn(message)`; a prompted task speaks first — take its opening
reply with a bare `turn()` before answering. `mask_prompt` says a prompted
task's prompt belongs to the USER side (a scenario the caller pursues, not
the assistant's seed): the wire hides it — the caller opens — while the
task object keeps the full row, so its hooks, rewards, and judges score
the real question (the user-sim env's contract).
reply with a bare `turn()` before answering. A prompt that belongs to the
USER side (a scenario the caller pursues, not the assistant's seed) is the
caller's to hide: hand the interaction a task whose `data.prompt` is None
and keep the scenario on a scoring-side field (the user-sim env's contract).

`runtime` and `tools` borrow live resources from their owners, just as
they do for `run()`; an env supplies its taskset's shared tools
Expand All @@ -466,17 +465,9 @@ async def interaction(
if self._closed:
raise RuntimeError("Agent is closed; create a new agent")
self._check_resume_support()
if mask_prompt and task.data.prompt is None:
raise ValueError(
"mask_prompt hides a prompt the task doesn't have; a prompt-less "
"task is already opened by the first turn()"
)
params = self._rollout_params(task, runtime, dict(tools or {}))
run = RolloutRun(
run = Rollout(
task=task,
wire_data=(
task.data.model_copy(update={"prompt": None}) if mask_prompt else None
),
has_user=True,
on_trace=on_trace,
**params,
Expand Down Expand Up @@ -665,7 +656,6 @@ async def interaction(
*,
runtime: Runtime | None = None,
tools: Mapping[str, SharedToolServer] | None = None,
mask_prompt: bool = False,
on_trace: Callable[[Trace], None] | None = None,
) -> AsyncIterator[Interaction]:
"""The agent's `interaction`, with every trace stamped with its standing
Expand All @@ -687,7 +677,6 @@ def remember(current: Trace) -> None:
task,
runtime=runtime,
tools=tools if tools is not None else self._shared_for(task),
mask_prompt=mask_prompt,
on_trace=self._watch(remember),
) as interaction:
yield interaction
Expand Down
29 changes: 14 additions & 15 deletions verifiers/v1/configs/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,44 +11,43 @@


class TimeoutConfig(BaseConfig):
"""Per-agent wall-clock timeouts per rollout stage, in seconds (None = no
limit); each stage falls back to the task's own `TaskTimeout` when unset. An
interaction's rollout budget is cumulative across its active harness segments
and pauses while the caller computes the next user turn."""
"""Timeout (in seconds) for different phases of an agent's run."""

setup: float | None = None # one shared budget: task setup + provisioning
"""Timeout (in seconds) for the task + harness setup hooks."""
rollout: float | None = None
"""Timeout (in seconds) for the agent's solve attempt."""
finalize: float | None = None
"""Timeout (in seconds) for the task + harness finalize hooks."""
scoring: float | None = None
"""Timeout (in seconds) for the task + harness metrics + scoring hooks."""


class AgentConfig(BaseConfig):
"""One env agent: who plays it, and its per-run caps. It pins only what
makes it a different actor; everything unpinned falls back — the model context
to the run's own, the harness to the taskset's default."""

harness: SerializeAsAny[HarnessConfig] | None = None
"""The agent's program (None = the taskset's default harness)."""
runtime: RuntimeConfig = SubprocessConfig()
"""Runtime for the harness program — the policy each run provisions its box
from; tool servers choose their placement separately."""

model: str | None = None
"""Model id (None = the run's model, i.e. the policy under evaluation/training)."""
client: ClientConfig | None = None
"""Endpoint override (None = the run's client)."""
sampling: SamplingConfig | None = None
"""Sampling override (None = the run's sampling)."""
timeout: TimeoutConfig = TimeoutConfig()
retries: RetryConfig = RetryConfig()
"""Whole-run retries: rerun this agent's rollout while its trace ends with a
retryable error (never into a borrowed box)."""

max_turns: int | None = None
"""Max model turns per run (None = no limit). Framework-enforced (the
interception server refuses turns past it), so it applies to any harness."""
"""Max model turns per run (None = no limit)."""
max_input_tokens: int | None = None
"""Max input tokens per run (None = no limit)."""
max_output_tokens: int | None = None
"""Max output tokens per run (None = no limit)."""
max_total_tokens: int | None = None
"""Token caps per run (None = no limit); framework-enforced between turns."""
"""Max total tokens per run (None = no limit)."""

timeout: TimeoutConfig = TimeoutConfig()
retries: RetryConfig = RetryConfig()

@model_validator(mode="before")
@classmethod
Expand Down
23 changes: 13 additions & 10 deletions verifiers/v1/envs/user_sim/env.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@
The generic two-sided conversation (`--env.id user-sim` over any taskset) — the
substrate a tau2-style benchmark builds on. The taskset's row is read as the USER's
side of the world: its prompt text becomes the scenario in the user's system prompt
(`--env.persona`), and the assistant plays the same task with a masked prompt — it
is hidden from its harness, so it learns the user's goal only through
conversation (its own instructions stay in `system_prompt`), while the task's
rewards and judges still score the real row. The user agent rides the tool-less
(`--env.persona`), and the assistant plays the same task with its prompt nulled — the
scenario is the user's knowledge, so the assistant learns the goal only through
conversation (its own instructions stay in `system_prompt`). The task's rewards and
judges score that nulled row, so they must read scoring-side fields (`answer`, a
judge's `question_field`), never the prompt. The user agent rides the tool-less
`null` harness by default (untrainable — `setup()`), opens the conversation, and
ends it with the done marker; the assistant's trace is then judged by the task's
own rewards, exactly as in any eval.
Expand Down Expand Up @@ -64,14 +65,16 @@ async def run(self, task, agents):
)
)
# Two interactions, relayed: the user is just another agent, and the env is
# the control flow between them. The assistant plays the SAME task with a
# masked prompt: the scenario is the user's knowledge, so the wire seeds
# nothing and the user opens — while the task's hooks, rewards, and plugged
# judges still score the real row (they read the task object, not the
# run's masked view).
# the control flow between them. The assistant plays the SAME task with its
# prompt nulled: the scenario is the user's knowledge, so the wire seeds
# nothing and the user opens. Scoring runs on the nulled row — a user-sim
# taskset keeps its scoring on non-prompt fields.
assistant_task = type(task)(
task.data.model_copy(update={"prompt": None}), task.config
)
Comment thread
mikasenghaas marked this conversation as resolved.
Resolved
async with (
agents.user.interaction(user_task) as sim,
agents.assistant.interaction(task, mask_prompt=True) as assistant,
agents.assistant.interaction(assistant_task) as assistant,
):
# The tau convention: the assistant "answers the phone", the user
# states the goal. The greeting exists only on the user's side. A
Expand Down
2 changes: 1 addition & 1 deletion verifiers/v1/errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
3. Surfacing (`session.RolloutSession.error`): a model or tool call fails behind the harness
subprocess and comes back as HTTP, so the interception server stashes the real error there and
the rollout re-raises it once the harness returns — not a secondary `HarnessError`.
4. Capture (`RolloutRun`, mirrored by the env-server): the one place that records a failure (typed
4. Capture (`Rollout`, mirrored by the env-server): the one place that records a failure (typed
or not) onto the trace and never lets it cancel sibling rollouts. A bad rollout is data, not a
crash.

Expand Down
37 changes: 35 additions & 2 deletions verifiers/v1/interception/__init__.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
from collections.abc import Iterable
from collections.abc import AsyncIterator, Iterable
from contextlib import asynccontextmanager
from typing import TYPE_CHECKING, Annotated

from pydantic import Field
Expand All @@ -15,7 +16,8 @@
InterceptionServer,
InterceptionServerConfig,
)
from verifiers.v1.runtimes import runtime_is_local
from verifiers.v1.runtimes import Runtime, runtime_is_local
from verifiers.v1.session import RolloutSession

if TYPE_CHECKING:
from verifiers.v1.mcp import SharedToolServer
Expand Down Expand Up @@ -69,6 +71,36 @@ def make_interception(
return ElasticInterceptionPool(config, requires_tunnel, state_service_secrets)


@asynccontextmanager
async def serve_interception(
interception: Interception | None,
runtime: Runtime,
session: RolloutSession,
servers: list,
shared_tools: "dict[str, SharedToolServer]",
) -> AsyncIterator[Slot]:
"""A slot on the shared interception when one was injected (its owner keeps the
lifecycle), else on a per-rollout `InterceptionServer` owned — brought up and torn
down — by the caller's context."""
if interception is not None:
async with interception.acquire(session) as slot:
yield slot
return
tunneled = requires_tunnel(
runtime.is_local,
[server.config for server in servers],
shared_tools.values(),
)
server = InterceptionServer(
requires_tunnel=tunneled,
state_service_secrets=tuple(
tool.state_secret for tool in shared_tools.values() if tool.state_secret
),
)
async with server, server.acquire(session) as slot:
yield slot


__all__ = [
"BaseInterceptionConfig",
"ElasticInterceptionPool",
Expand All @@ -82,4 +114,5 @@ def make_interception(
"StaticInterceptionPoolConfig",
"make_interception",
"requires_tunnel",
"serve_interception",
]
Loading
Loading