nemo_gym.agents.base_responses_api_agent
nemo_gym.agents.base_responses_api_agent
Module Contents
Classes
Functions
Data
_HOST_NETWORK_SANDBOX_PROVIDERS
_LOCAL_DOCKER_SANDBOX_PROVIDERS
API
Bases: BaseModel
Close agent-server state.
Bases: BaseModel
Confirm closure and return captured observations.
Bases: HTTPException, ValueError
Refuse an agent session seed this agent cannot serve, such as a grant or sandbox it does not support.
FastAPI answers it with HTTP 422, which an Environment Server treats as terminal, so a configuration error
fails the episode once with this message instead of being retried as if it were transient. It is also a
ValueError, so code that validates a seed outside a request (a checkpoint restore, a direct call in a test)
keeps catching it as before.
Bases: BaseModel
Idempotently initialize agent-server state under a caller-assigned identifier.
Repeating the same identifier and episode must return the existing session. Closing an unknown identifier must prevent a racing seed within the close retry window. The shared implementation fences each closed session and keeps its close’s saved reply for session_close_retry_window_seconds, so callers must use unique IDs and finish retries within that window. External resources should use provider TTLs when available; there is no active-session expiry timer.
Bases: BaseModel
Confirm the caller-assigned agent session identifier and declare what the harness can use.
Bases: BaseModel
What this adapter’s sessions can do, asked before any session is seeded.
An environment server reads it to refuse a run before provisioning anything: a multi-step task whose turns
must continue one harness session needs continuation, as Harbor’s multi-step trial refuses
resume_trajectory for an agent without SUPPORTS_RESUME before any environment spend.
Bases: HTTPException, ValueError
Refuse an agent session request that conflicts with what this agent recorded for the session.
Examples: an agent_session_id already bound to another seed request, a close that names another episode,
or a seed for a closed session. FastAPI answers it with HTTP 409, which an environment server treats as
terminal. It is also a ValueError for direct callers.
Bases: Exception
Retain incomplete setup for close while propagating the original setup error.
Harness-owned session state with the immutable caller-assigned seed binding.
Bases: BaseServer
An agent server: the harness Gym runs against the model for each task.
calls_model_from_sandbox: declare True on the class the entrypoint runs when the harness calls the
model server from inside the task sandbox, where the loopback address is the container itself. A Harbor run
(gym eval run <target> --agent <name>) reads that literal from the entrypoint source, as Gym reads
ray_enabled, and advertises a reachable host (use_absolute_ip) by default for such a harness. It is
not read through inheritance: each such class declares it itself.
Bases: BaseRunServerInstanceConfig
The OpenAI-compatible endpoint a harness sends its model calls to.
base_url ends in the API version (for example /v1).
model is set only when the endpoint dictates the model name; otherwise the harness keeps its own.
Bases: BaseModel
Body of POST /rollouts/{rollout_id}/stop; the reason is recorded on the stopped run’s response.
Bases: BaseModel
stopped is false when the rollout’s run already ended or a stop was already requested.
Bases: BaseResponsesAPIAgent, AggregateMetricsMixin, SimpleServer
The checkpoint participant, or None when checkpointing is off for this agent.
Own the rollout’s key on this worker, so a stop that names only the rollout reaches its session.
Run one input delta with the retained harness session and sandbox.
Read the existing 1-based header for checkpointed or multi-turn continuation sessions.
Opt into multi-turn continuation; existing one-activation adapters stay unchanged.
Return whether this agent needs rollout correlation.
Evaluation uses /ng-rollout/<id>/... for every agent.
Training capture uses /ng-rollout/<id>/training-token-capture/....
Training capture requires token_id_capture.enabled.
It also requires the static agent flag or run-level all_agents.
Partial-rollout checkpointing also needs it for this agent.
Missing global configuration disables correlation.
Release harness state, or raise without losing the handle needed for another close.
Stop the session’s activation, then release its state with the close hook.
A close cancelled while it stops the activation leaves the hook to its retry, so the hook runs once. A retire can release the session while the close awaits. The close then stops there and leaves the session to the retire.
Return the adapter’s configured bound for stopping an active continuation.
Install a session restored from a checkpoint, as its replacement attempt’s seed would have.
Keep a failed seed’s state for the caller’s close, for as long as a fence lasts.
Whether evaluation model-call observability is enabled.
The record of the open session, seeded or still seeding, that runs the rollout.
Run the close hook on a failed seed’s state that no close reached, then drop the record.
The hook runs under the session’s own rollout, as it would for the caller’s close. If it fails, the record keeps its state for a later close, and the release is tried again a window later.
Release a retired session that has no fence: its episode’s close then finds nothing to release.
Release ownership of the rollout’s key once its session is no longer open here; a no-op while it is.
The sandbox session that runs state’s harness; an agent returns it to support rollout stops.
Validate grants and initialize harness state.
Raise AgentSeedRejectedError for a seed this agent cannot serve, such as a sandbox or a required grant it does not support: the seed answers a terminal 422 and binds nothing. An HTTPException keeps its explicit status; any other, unexpected exception answers 500, which an Environment Server retries as transient. If setup fails and cleanup cannot finish, raise AgentSessionSetupError with the partial state and original error. The base retains it for close, never activation.
The open state of a session, or None; checkpoint hooks export it.
Whether this agent explicitly opted into training-token capture.
Release a seeded session’s state with the close hook, or keep it as a failed seed if the hook fails.
Validate a delta without mutating the session or consuming its index.
Run or replay one header-indexed delta in a seeded harness session.
Declare the session capabilities a seed would confirm, without seeding: the task-tool context and the
multi-turn continuation this adapter supports (None for one-activation adapters and for agents that
implement no sessions at all).
Default: same RewardProfiler aggregation as resources server. Override to proxy.
Apply this run’s capture path to a model-server root URL.
Append the API-version suffix after this method returns. While traces export, the URL also
names this run’s current span, so the model server parents calls that arrive without a
traceparent header (a harness in a sandbox) to it.
Override to classify native failures; the environment decides grading and retry eligibility.
Fence the session and keep the close’s saved reply, observations included, for the close retry window.
Failed release keeps state for retry. Closing an unknown ID prevents a delayed seed within the same window. No timer cancels active sessions: the environment server that drives the episode and the sandbox provider retain responsibility for normal and crash cleanup.
Overlay episode-scoped tool access onto configured declarations by name.
Drop the fences that expired, and release the failed seeds nobody closed.
Return the state of every session in session_keys for a checkpoint.
Whether this worker keeps any record of the session: open, failed and awaiting close, or closed.
For a rollout’s key, /rollouts/<rollout id>, whether this worker runs the rollout’s open session.
Choose the endpoint for a harness’s model calls.
In order: session_endpoint, an endpoint the episode’s session supplies (for example a component
that records model calls from inside the task sandbox); the Gym model server, with this rollout’s
capture prefix; the agent’s configured base_url, used verbatim because it has no prefix routing.
Attach validated evidence through the existing string-valued response metadata.
Mark the response of a run that POST /rollouts/{rollout_id}/stop ended.
The response keeps a timeout’s incomplete status, so it is verified like one, and gains the
ng_rollout_stop marker that tells it apart from a timeout or a cancellation. A stop is not a
failure, so the response carries no failure kind.
Resolve a model-server URL with an optional rollout prefix (and trace context, as base_url_for_run).
Pass trace_context=False for a URL that a client cached across rollouts will keep using.
Validate every session, then install all of them; never install a partial set.
Discard a session whose attempt was retired.
The default releases the session with the agent’s close hook, without a fence, so a restart-only agent’s retire stops the sandbox a seed started.
Return the capture id for a run request.
Return None when capture is disabled.
Return None when the body has no usable identity.
Seed once per caller ID; identical retries reuse the same harness state.
Install this agent’s checkpoint participant on app, once.
End a rollout’s harness as at its time limit, so the episode is verified and graded as a timeout.
For a caller that enforces its own budget (agent time, tokens, cost) or an operator’s cancel.
rollout_id is the id in /ng-rollout/<id>. A stop that arrives while the session is still
seeding takes effect when the harness would launch. With several workers, the request reaches the
worker running the rollout without the session cookie (see nemo_gym.server_runtime.request_handling.session_routing).
Whether this harness uses the task’s own tool declarations.
Harbor tasks declare [[environment.mcp_servers]] and skills_dir. A harness that drives them
from inside the sandbox answers True, and the seed response carries the answer to the environment
server, which refuses such a task to a harness that would run it without its tools.
Carry an inbound capture path onto a downstream URL path.
Prefixed self-calls expose the rollout id as a path parameter. Training-capture requests preserve their dedicated path segment. Unprefixed requests remain unchanged.
Apply this run’s capture path to a downstream URL path.
Evaluation uses /ng-rollout/<id>/....
Training capture uses /ng-rollout/<id>/training-token-capture/....
Calls without a rollout id remain unchanged.
Release ownership of a session when this worker drops its last record.
See nemo_gym.server_runtime.request_handling.session_routing.
endpoint with its failures raised as one agent route failure caused by them.
A model reply that confirms a policy response timeout makes agent.responses raise the typed
model_policy_response_timeout failure instead.
The reply body and status stay those of the original error. HTTPException, cancellation and any error
app has a handler for (such as a checkpoint ControlError, answered 409) pass through to that
handler. A failure an agent boundary already reported (/run calling this server’s /v1/responses)
is not wrapped again.
Whether app registers a handler for error’s type or a base of it, as Starlette dispatches.
Refuse a model URL that a sandboxed agent could not reach.
Agents that run inside a sandbox (Hermes, mini-SWE) hand the Model Server URL to code in the container. Inside a container on a remote provider (OpenSandbox, E2B, Daytona, …), a loopback host is the container itself, so every model call fails and the episode silently scores 0.
Raises:
ValueError: whenurlis loopback andprovider_nameis not a host-network or local Docker provider. Local Docker only logs a warning: loopback works there only when the daemon shares the host network.
Whether url points at the caller’s own loopback interface (127.0.0.0/8, ::1, localhost).