> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.base_responses_api_agent

## Module Contents

### Classes

| Name                                                                                            | Description                                                                    |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`AgentCloseSessionRequest`](#nemo_gym-base_responses_api_agent-AgentCloseSessionRequest)       | Close agent-server state.                                                      |
| [`AgentCloseSessionResponse`](#nemo_gym-base_responses_api_agent-AgentCloseSessionResponse)     | Confirm closure and return captured observations.                              |
| [`AgentSeedSessionRequest`](#nemo_gym-base_responses_api_agent-AgentSeedSessionRequest)         | Idempotently initialize agent-server state under a caller-assigned identifier. |
| [`AgentSeedSessionResponse`](#nemo_gym-base_responses_api_agent-AgentSeedSessionResponse)       | Confirm the caller-assigned agent session identifier.                          |
| [`AgentSessionSetupError`](#nemo_gym-base_responses_api_agent-AgentSessionSetupError)           | Retain incomplete setup for close while propagating the original setup error.  |
| [`AgentSessionState`](#nemo_gym-base_responses_api_agent-AgentSessionState)                     | Harness-owned session state with the immutable caller-assigned seed binding.   |
| [`BaseResponsesAPIAgent`](#nemo_gym-base_responses_api_agent-BaseResponsesAPIAgent)             | -                                                                              |
| [`BaseResponsesAPIAgentConfig`](#nemo_gym-base_responses_api_agent-BaseResponsesAPIAgentConfig) | -                                                                              |
| [`SimpleResponsesAPIAgent`](#nemo_gym-base_responses_api_agent-SimpleResponsesAPIAgent)         | -                                                                              |
| [`_AgentSessionRecord`](#nemo_gym-base_responses_api_agent-_AgentSessionRecord)                 | -                                                                              |

### Data

[`AGENT_SESSION_COOKIE_KEY`](#nemo_gym-base_responses_api_agent-AGENT_SESSION_COOKIE_KEY)

### API

```python
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')`

---

```python
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`

---

```python
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)`

---

```python
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

```python
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')`

---

```python
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.

```python
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`

---

```python
class nemo_gym.base_responses_api_agent.BaseResponsesAPIAgent()
```

**Bases:** [BaseServer](/nemo/gym/nemo-gym/nemo_gym/server_utils#nemo_gym-server_utils-BaseServer)

**`config`** `BaseResponsesAPIAgentConfig`

---

```python
class nemo_gym.base_responses_api_agent.BaseResponsesAPIAgentConfig()
```

**Bases:** [BaseRunServerInstanceConfig](/nemo/gym/nemo-gym/nemo_gym/config_types#nemo_gym-config_types-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)`

---

```python
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

```python
class nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent()
```

**Bases:** [BaseResponsesAPIAgent](#nemo_gym-base_responses_api_agent-BaseResponsesAPIAgent), [AggregateMetricsMixin](/nemo/gym/nemo-gym/nemo_gym/reward_profile#nemo_gym-reward_profile-AggregateMetricsMixin), [SimpleServer](/nemo/gym/nemo-gym/nemo_gym/server_utils#nemo_gym-server_utils-SimpleServer)

**`_closed_session_records`** `OrderedDict[str, _AgentSessionRecord] = PrivateAttr(default_factory=OrderedDict)`

---

**`_session_records`** `dict[str, _AgentSessionRecord] = PrivateAttr(default_factory=dict)`

---

**`config`** `BaseResponsesAPIAgentConfig`

---

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._agent_session_id_from_request(
    request: fastapi.Request | None
) -> str | None
```

staticmethod

```python
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.

```python
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.

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._locked_agent_session(
    session_id: str
) -> collections.abc.AsyncIterator[nemo_gym.base_responses_api_agent._AgentSessionRecord]
```

async

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._model_call_capture_enabled() -> bool
```

Whether evaluation model-call observability is enabled.

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent._require_agent_session(
    agent_session_id: str
) -> nemo_gym.base_responses_api_agent.AgentSessionState
```

```python
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.

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

Whether this agent explicitly opted into training-token capture.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.responses(
    body: nemo_gym.openai_utils.NeMoGymResponseCreateParamsNonStreaming = Body()
) -> nemo_gym.openai_utils.NeMoGymResponse
```

async

abstract

```python
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.

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.run(
    body: nemo_gym.base_resources_server.BaseRunRequest = Body()
) -> nemo_gym.base_resources_server.BaseVerifyResponse
```

async

abstract

```python
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.

```python
nemo_gym.base_responses_api_agent.SimpleResponsesAPIAgent.setup_webserver() -> fastapi.FastAPI
```

```python
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.

```python
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.

```python
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`

---

```python
nemo_gym.base_responses_api_agent.AGENT_SESSION_COOKIE_KEY = 'agent_session_id'
```