> 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.agent_registry

Registry of agent harnesses under `responses_api_agents/<name>/`.

An agent harness is one *component* of an environment (an environment = dataset + agent harness +
resources server \[verifier and state] + model). This module maps an agent's short `<name>` (the
directory name) to its config variant(s) so it can be enumerated by name (`gym list agents`) and
classified by how it composes. Resolving an agent name to a config for *running* belongs to the
config composer (via the CLI's generic asset selectors), so this module is intentionally
discovery-only. The `self_contained` flag records only what the agent's *own* config reveals about
its resources-server wiring:

* **Wires a resources server itself (Pattern A, `self_contained=False`):** the config sets
  `responses_api_agents.<type>.resources_server`, so the registry can see it pairs with a separate
  resources server + dataset (e.g. the `simple_agent` tool-use pattern).
* **Does not wire one in its own config (Pattern B, `self_contained=True`):** the agent declares
  its own `agent_framework` (e.g. `swe_agents`), drives an external LLM loop (e.g.
  `claude_code_agent` via its own model key), or ships only an entrypoint whose resources-server
  pairing is supplied by a separate paired/benchmark config (e.g. `gymnasium_agent` + the
  `blackjack` resources server). These agents are still composable — but *within* a type
  (gymnasium↔gymnasium-style, simple\_agent↔simple\_agent-style), not across types. Which pairings are
  actually compatible is the config composer's call, not inferable from the agent config alone.

Discovery only reads config files; it never resolves interpolations or missing values and never
starts servers, so it is safe to call when secrets/API keys referenced by a config are unset.

## Module Contents

### Classes

| Name                                                | Description                                                                            |
| --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [`AgentEntry`](#nemo_gym-agent_registry-AgentEntry) | A discovered agent: its name, where it lives, its config variants, and how it's wired. |

### Functions

| Name                                                                | Description                                                                                        |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`_classify`](#nemo_gym-agent_registry-_classify)                   | Return `(self_contained, description)` for an agent from its config variants.                      |
| [`_is_agent_config`](#nemo_gym-agent_registry-_is_agent_config)     | True if the file is a NeMo Gym agent config (a top-level block with `responses_api_agents`).       |
| [`_iter_agent_blocks`](#nemo_gym-agent_registry-_iter_agent_blocks) | Yield each `responses_api_agents.<type>` mapping in a config (resolution-safe, best effort). |
| [`discover_agents`](#nemo_gym-agent_registry-discover_agents)       | Map agent name -> :class:`AgentEntry` for every agent dir under `responses_api_agents/`.           |

### Data

[`AGENTS_DIR`](#nemo_gym-agent_registry-AGENTS_DIR)

[`AGENT_CONFIGS_SUBDIR`](#nemo_gym-agent_registry-AGENT_CONFIGS_SUBDIR)

### API

```python
class nemo_gym.agent_registry.AgentEntry(
    name: str,
    path: pathlib.Path,
    config_paths: typing.Tuple[pathlib.Path, ...],
    self_contained: bool,
    description: typing.Optional[str] = None
)
```

Dataclass

A discovered agent: its name, where it lives, its config variants, and how it's wired.

Map variant name (config filename stem) -> config path.

```python
nemo_gym.agent_registry._classify(
    config_paths: typing.Tuple[pathlib.Path, ...]
) -> typing.Tuple[bool, typing.Optional[str]]
```

Return `(self_contained, description)` for an agent from its config variants.

A harness is NOT self-contained (Pattern A) when some variant references a separate resources
server, none declares an `agent_framework`, and none drives an external LLM loop (e.g. its own
Anthropic key) — it must be wired to a compatible resources server. Otherwise it is
self-contained (Pattern B). Agents with no parseable config are treated as Pattern A (their
wiring lives in a paired benchmark/resources-server config).

```python
nemo_gym.agent_registry._is_agent_config(
    config_path: pathlib.Path
) -> bool
```

True if the file is a NeMo Gym agent config (a top-level block with `responses_api_agents`).

Filters out non-agent YAML that happens to live in an agent's `configs/` dir (e.g. a raw
harness config or an empty stub).

```python
nemo_gym.agent_registry._iter_agent_blocks(
    config_path: pathlib.Path
)
```

Yield each `responses_api_agents.<type>` mapping in a config (resolution-safe, best effort).

```python
nemo_gym.agent_registry.discover_agents(
    agents_dir: pathlib.Path = AGENTS_DIR
) -> typing.Dict[str, nemo_gym.agent_registry.AgentEntry]
```

Map agent name -> :class:`AgentEntry` for every agent dir under `responses_api_agents/`.

The name is the directory name. A directory is an agent if it has an `app.py` or at least one
agent config. Returns an empty dict if the directory is missing.

```python
nemo_gym.agent_registry.AGENTS_DIR = PARENT_DIR / 'responses_api_agents'
```

```python
nemo_gym.agent_registry.AGENT_CONFIGS_SUBDIR = 'configs'
```