API ReferenceFull Library ReferenceNemo GymNemo Gym

nemo_gym.base_responses_api_agent

View as Markdown

Module Contents

Classes

NameDescription
AgentCloseSessionRequestClose agent-server state.
AgentCloseSessionResponseConfirm closure and return captured observations.
AgentSeedSessionRequestIdempotently initialize agent-server state under a caller-assigned identifier.
AgentSeedSessionResponseConfirm the caller-assigned agent session identifier.
AgentSessionSetupErrorRetain incomplete setup for close while propagating the original setup error.
AgentSessionStateHarness-owned session state with the immutable caller-assigned seed binding.
BaseResponsesAPIAgent-
BaseResponsesAPIAgentConfig-
SimpleResponsesAPIAgent-
_AgentSessionRecord-

Data

AGENT_SESSION_COOKIE_KEY

API

class nemo_gym.base_responses_api_agent.AgentCloseSessionRequest()

Bases: BaseModel

Close agent-server state.

agent_session_id
str
episode_id
EpisodeId
model_config
= ConfigDict(extra='forbid')
class nemo_gym.base_responses_api_agent.AgentCloseSessionResponse()

Bases: BaseModel

Confirm closure and return captured observations.

agent_observations
AgentObservationBundle | None = None
agent_session_id
str
model_config
= ConfigDict(extra='forbid')
resources_cookies
dict[str, str] | None = None
class nemo_gym.base_responses_api_agent.AgentSeedSessionRequest()

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 retry window. The shared implementation retains close responses for session_close_retry_window_seconds; 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.

agent_session_id
str = Field(min_length=1)
episode_id
EpisodeId
model_config
= ConfigDict(extra='forbid')
sandbox_access
SandboxAccess | None = None
task_id
TaskId
tool_accesses
list[ToolAccess] = Field(default_factory=list)
nemo_gym.base_responses_api_agent.AgentSeedSessionRequest.require_unique_tool_names(
    tool_accesses: list[nemo_gym.tool_access.ToolAccess]
) -> list[nemo_gym.tool_access.ToolAccess]
classmethod
class nemo_gym.base_responses_api_agent.AgentSeedSessionResponse()

Bases: BaseModel

Confirm the caller-assigned agent session identifier.

agent_session_id
str
model_config
= ConfigDict(extra='forbid')
class nemo_gym.base_responses_api_agent.AgentSessionSetupError(
    state: nemo_gym.base_responses_api_agent.AgentSessionState,
    error: BaseException
)
Exception

Bases: Exception

Retain incomplete setup for close while propagating the original setup error.

class nemo_gym.base_responses_api_agent.AgentSessionState(
    request: nemo_gym.base_responses_api_agent.AgentSeedSessionRequest
)
Dataclass

Harness-owned session state with the immutable caller-assigned seed binding.

request
AgentSeedSessionRequest
class nemo_gym.base_responses_api_agent.BaseResponsesAPIAgent()

Bases: BaseServer

config
BaseResponsesAPIAgentConfig
class nemo_gym.base_responses_api_agent.BaseResponsesAPIAgentConfig()

Bases: BaseRunServerInstanceConfig

session_close_retry_window_seconds
float
skip_verification
bool = False
skip_verification_reward
float = 0.0
token_id_capture
bool = False
tool_accesses
list[ToolAccess] = Field(default_factory=list)
nemo_gym.base_responses_api_agent.BaseResponsesAPIAgentConfig.require_unique_tool_names(
    tool_accesses: list[nemo_gym.tool_access.ToolAccess]
) -> list[nemo_gym.tool_access.ToolAccess]
classmethod
class nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent()

Bases: BaseResponsesAPIAgent, AggregateMetricsMixin, SimpleServer

_closed_session_records
OrderedDict[str, _AgentSessionRecord] = PrivateAttr(default_factory=OrderedDict)
_session_records
dict[str, _AgentSessionRecord] = PrivateAttr(default_factory=dict)
config
BaseResponsesAPIAgentConfig
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._agent_session_id_from_request(
    request: fastapi.Request | None
) -> str | None
staticmethod
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._capture_correlation_enabled() -> bool

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. Missing global configuration disables correlation.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._close_agent_session_state(
    state: nemo_gym.base_responses_api_agent.AgentSessionState
) -> nemo_gym.base_responses_api_agent.AgentCloseSessionResponse
async

Release harness state, or raise without losing the handle needed for another close.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._locked_agent_session(
    session_id: str
) -> collections.abc.AsyncIterator[nemo_gym.base_responses_api_agent._AgentSessionRecord]
async
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._model_call_capture_enabled() -> bool

Whether evaluation model-call observability is enabled.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._require_agent_session(
    agent_session_id: str
) -> nemo_gym.base_responses_api_agent.AgentSessionState
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._seed_agent_session_state(
    body: nemo_gym.base_responses_api_agent.AgentSeedSessionRequest
) -> nemo_gym.base_responses_api_agent.AgentSessionState
async

Validate grants and initialize harness state.

If setup fails and cleanup cannot finish, raise AgentSessionSetupError with the partial state and original error. The base retains it for close, never activation.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._token_id_capture_enabled() -> bool

Whether this agent explicitly opted into training-token capture.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.aggregate_metrics(
    body: nemo_gym.base_resources_server.AggregateMetricsRequest = Body()
) -> nemo_gym.base_resources_server.AggregateMetrics
async

Default: same RewardProfiler aggregation as resources server. Override to proxy.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.base_url_for_run(
    base_url: str,
    body: typing.Any
) -> str

Apply this run’s capture path to a model-server root URL.

Append the API-version suffix after this method returns.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.close_agent_session(
    request: fastapi.Request,
    body: nemo_gym.base_responses_api_agent.AgentCloseSessionRequest
) -> nemo_gym.base_responses_api_agent.AgentCloseSessionResponse
async

Retain successful close responses for a bounded retry window, including observations.

Failed cleanup keeps state for retry. Closing an unknown ID prevents a delayed seed within the same window. No timer cancels active sessions: the episode owner and sandbox provider retain responsibility for normal and crash cleanup.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.effective_tool_accesses(
    request: nemo_gym.base_responses_api_agent.AgentSeedSessionRequest
) -> list[nemo_gym.tool_access.ToolAccess]

Overlay episode-scoped tool access onto configured declarations by name.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.resolve_model_base_url(
    model_server_name: str,
    rollout_id: typing.Optional[str] = None
) -> str

Resolve a model-server URL with an optional rollout prefix.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.responses(
    body: nemo_gym.openai_utils.NeMoGymResponseCreateParamsNonStreaming = Body()
) -> nemo_gym.openai_utils.NeMoGymResponse
asyncabstract
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.rollout_id_from_run(
    body: typing.Any
) -> typing.Optional[str]

Return the capture id for a run request.

Return None when capture is disabled. Return None when the body has no usable identity.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.run(
    body: nemo_gym.base_resources_server.BaseRunRequest = Body()
) -> nemo_gym.base_resources_server.BaseVerifyResponse
asyncabstract
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.seed_agent_session(
    request: fastapi.Request,
    body: nemo_gym.base_responses_api_agent.AgentSeedSessionRequest
) -> nemo_gym.base_responses_api_agent.AgentSeedSessionResponse
async

Seed once per caller ID; identical retries reuse the same harness state.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.setup_webserver() -> fastapi.FastAPI
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.url_path_for_request(
    url_path: str,
    request: typing.Optional[fastapi.Request]
) -> str

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.

nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.url_path_for_run(
    url_path: str,
    body: typing.Any
) -> str

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.

class nemo_gym.base_responses_api_agent._AgentSessionRecord(
    lock: asyncio.Lock = asyncio.Lock(),
    state: nemo_gym.base_responses_api_agent.AgentSessionState | None = None,
    closing: bool = False,
    episode_id: nemo_gym.episode_types.EpisodeId | None = None,
    close_response: nemo_gym.base_responses_api_agent.AgentCloseSessionResponse | None = None,
    expires_at: float = float('inf')
)
Dataclass
close_response
AgentCloseSessionResponse | None = None
closing
bool = False
episode_id
EpisodeId | None = None
expires_at
float = float('inf')
lock
Lock = field(default_factory=(asyncio.Lock))
state
AgentSessionState | None = None
nemo_gym.base_responses_api_agent.AGENT_SESSION_COOKIE_KEY = 'agent_session_id'