docs: rewrite Configure Agents index and document external agent harnesses

[ananthsub]

Closes #1132.

The Configure Agents index page described the Agent server's role in a rollout but did not say that the Agent server is where an environment's agent harness lives, or that NeMo Gym ships agent servers that wrap external harnesses. Integrate Existing Agents was a stub naming two agents.

index.mdx: lead with the Agent server as the home of the agent harness, add a section on why the harness is a separate server, and replace the prose pointer with cards to the three sub-pages and the agent server configuration reference. This keeps the rollout lifecycle pseudocode.

integrate-existing-agents.mdx: list the built-in agent servers, then the agent servers that run external harnesses, grouped as coding CLIs, agent frameworks, benchmark-native harnesses, and the agent-agnostic task runners. Adds the four responsibilities every wrapper has, and the requirements a wrapper must meet for its rollouts to be trainable (route through the model server, carry token IDs, leave sampling parameters alone, keep the trajectory monotonic).

ecosystem.mdx: point the Agent Harnesses are listed in the catalog

[github-actions]

🌿 Preview your docs: https://nvidia-preview-ananthsub-docs-agent-server-index.docs.buildwithfern.com/nemo/gym

Here are the markdown pages you've updated:

• nemo/gym/about/ecosystem
• nemo/gym/agent-server
• nemo/gym/agent-server/integrate-existing-agents

[ffrujeri]

| non_executing_simple_agent | The tool call itself is the answer. Forwards one request to the model and passes the response to the verifier without executing anything.

That is a weird name and functionality, we should probably review in a future github issue if you want to create it

[ffrujeri]

Also very weird distinction. We should revisit and understand why this is implemented. Please fire a future github issue

[sephmard]

Missing notes/description

[sephmard]

Nit: can we rename Notes to Description or Summary?

[sephmard]

Coding CLIs is a bit misleading. A few other options to consider, but we should ensure we are consistent -- and using CLI could also be confusing. Suggestions:

1. External Agent Harness — emphasizes they're third-party, but "External" is already covered by the parent section heading.
2. External Harnesses — most accurate: all six run their own agentic loop as a subprocess. Captures both the CLI and agentic nature without implying "coding."

[ffrujeri]

In the “Rollout Lifecycle” paragraph, could we make it explicit that, in the typical implementation shown below, the agent loop runs in responses()? For example:

In the typical implementation shown below, the agent loop runs in the responses() method. It sends the conversation to the model, receives a response, routes any tool calls to the Resources server, and feeds the results back to the model.

The “typical implementation” qualification avoids implying this is universal, since some agent servers implement the loop directly in run().

[ffrujeri]

The next sentence could also be more precise. “Turns” is ambiguous in this pseudocode because the loop is specifically iterating over model responses and tool calls, and reaching the model’s maximum sequence length may result in truncation or an error rather than a clean loop stop. Suggested wording:

The loop continues while the model returns tool calls, stopping when it returns no tool calls or the harness reaches its configured step limit. Other harnesses may define additional stopping conditions.

[ffrujeri]

Could we make the rollout-collection behavior explicit here? “Drive it remotely” could sound as though rollout collection itself runs remotely. Suggested wording:

Suggested change

	NeMo Gym ships agent servers implemented in Gym and adapters for third-party harnesses. If neither fits, you can keep your agent in your own repo and [drive it remotely](/agent-server/remote-agent).
	NeMo Gym ships agent servers implemented in Gym and adapters for third-party harnesses. If neither fits, keep your agent in your own repository, expose it through a Responses-compatible endpoint, and collect episodes from it using NeMo Gym’s rollout collection.

[ffrujeri]

Could we create a follow-up issue to reconsider this agent’s name? non_executing_simple_agent is ambiguous because the agent does execute a model call and verification; it only skips the tool-execution loop. A name such as single_model_call_agent would describe its defining behavior more directly. The issue could also cover backward-compatible config migration and whether this agent should remain separate from tool_simulation_agent, given their overlapping behavior.

[ffrujeri]

The current description makes it sound as though this agent simulates tool results, but the implementation does not perform any simulation. Its core behavior overlaps with non_executing_simple_agent, although their lifecycle handling differs: non_executing_simple_agent calls /seed_session, preserves session cookies through verification, normalizes string input, and proxies aggregate metrics; tool_simulation_agent takes the smaller stateless path and also supports skipped verification.

Could we reword this row to describe that behavior directly?

Suggested change

| [`tool_simulation_agent`](https://github.com/NVIDIA-NeMo/Gym/tree/main/responses_api_agents/tool_simulation_agent) | Makes one model call and passes the response to the verifier. Does not execute tool calls. Used with datasets that supply simulated tool results. |

| [`tool_simulation_agent`](https://github.com/NVIDIA-NeMo/Gym/tree/main/responses_api_agents/tool_simulation_agent) | Makes one model call and sends the response directly to the verifier without executing tool calls or initializing a Resources server session. Intended for stateless, single-step datasets where the model’s proposed next action is compared with an expected action. |

Could we also create a follow-up issue to reconsider both agents’ names and whether these overlapping implementations should be consolidated? That issue could cover the stateful/stateless lifecycle distinction and a backward-compatible config migration.

[ffrujeri]

Could we make this exception more concrete? Suggested wording:

Suggested change

In these, the external harness owns the agent loop and keeps its own prompts and tools. NeMo Gym usually seeds the session, translates the resulting trajectory into Responses API format, and verifies it against the Resources server; a few whose benchmark harness owns scoring compute the reward themselves.

In these integrations, the external harness owns the agent loop and keeps its own prompts and tools. NeMo Gym usually seeds the session, translates the resulting trajectory into Responses API format, and sends it to the Resources server for verification. Some benchmark-specific Agent servers instead bypass the Resources server’s `/verify` endpoint: they run the benchmark’s native evaluator and return the reward from its result.

Examples include mini_swe_agent, which maps the SWE-bench evaluation report’s resolved field to a binary reward; tau2, which reads result.reward_info.reward; and harbor_agent, which extracts the Harbor verifier result.

Could we also create a follow-up architecture issue to consider decoupling these native evaluators from the Agent server—for example, by exposing them behind a Resources server or shared verifier interface? That would keep rollout orchestration and scoring separable even when integrating benchmark-native harnesses.

[ffrujeri]

Could we reword this paragraph to make the integration boundary and the benchmark-coupled exceptions clearer?

Suggested change

Because verification stays on the NeMo Gym side, an agent harness that brings its own tools can often run in an existing environment by adding a `<benchmark>_<agent>` config, leaving the dataset and verifier unchanged — only the Resources server's task data and `/verify` are used. This is how `hermes_agent` is used with the math, coding, reasoning_gym, MCQA, and instruction-following benchmarks. It does not hold for every harness: agent servers such as `swe_agents`, `osworld_agent`, and `tau2` are tied to specific benchmarks.

Harnesses that execute their own tools do not need to use the Resources server’s tool endpoints. They can often be paired with an existing environment through configuration: NeMo Gym seeds the task session, the harness runs its interaction loop, and the existing Resources server verifies the resulting trajectory. `hermes_agent`, for example, is paired this way with math, coding, Reasoning Gym, MCQA, and instruction-following environments. Benchmark-coupled harnesses such as `swe_agents`, `osworld_agent`, and `tau2` instead depend on benchmark-specific task schemas, runtimes, or evaluators.

This also avoids implying that /verify is the only Resources-server endpoint involved—hermes_agent calls /seed_session as well.

[ffrujeri]

Would it make sense to merge “Command-Line Harnesses” and “External Frameworks” into one “Reusable Third-Party Harnesses” section? They appear to follow the same architectural pattern—the harness owns its interaction loop and tools, while the Agent server translates the trajectory and usually coordinates Resources-server verification. The main difference is only how the harness is invoked.

One possible introduction:

Reusable Third-Party Harnesses

These Agent servers adapt third-party harnesses that own their interaction loops and tools. They differ mainly in how the harness is invoked:

• Command-line integrations launch the harness as a subprocess and reconstruct its trajectory from CLI output, event streams, session databases, or files.
• Library integrations import the harness as a Python dependency and invoke it in-process, although the framework may use separate execution backends for its tools.

In both cases, the Agent server translates the resulting trajectory into Responses API items and usually sends it to the Resources server for verification. Harness-owned tools do not normally call Resources-server tool endpoints or mutate its task state.

The two tables could then become one table with an Integration column (Subprocess or Python library). This would preserve the useful implementation distinction without presenting them as separate architectural models.

[ffrujeri]

For example, the combined table could use this shape:

Agent Server	Harness	Integration	Summary
claude_code_agent	Claude Code	Subprocess	Launches the Claude Code CLI and translates its output into a NeMo Gym trajectory.
hermes_agent	Hermes Agent	Python library	Invokes Hermes in-process and translates its trajectory for Resources-server verification.
simple_strands_agent	Simple Strands Agent	Subprocess	Runs the Python harness in a child process and reads back its result.

The Integration column makes the small operational difference explicit while keeping all reusable third-party harnesses under the same conceptual model.

[ffrujeri]

A broader concern is that the current hierarchy mixes several different classification axes: who implemented the harness (“Gym-native” versus “third-party”), how it is invoked (“command-line” versus “framework”), where it runs (“Resources server sandbox”), and how tightly it is coupled to a benchmark. That makes it difficult to understand the user-facing intent of each section.

Would it be clearer to organize primarily around composability—essentially, “Can I reuse this Agent server with my environment?” For example:

1. Gym-native reusable agents
2. Reusable third-party harnesses — with invocation (subprocess, Python library, or sandbox), tool location, and training support represented as properties rather than subsections
3. Remotely hosted agents — remote_agent
4. Benchmark-coupled integrations — task schema, runtime, or evaluator is benchmark-specific
5. Agent-agnostic task runners — run another Agent server rather than implementing the harness

The shared material could then follow the catalog under “How third-party harnesses are adapted,” “Tools and Resources-server state,” “Evaluation versus online-RL support,” and “Configure and run.” This would keep one primary organizing principle while still documenting the smaller implementation differences.

[ffrujeri]

For the entries currently under “External Frameworks,” another possible taxonomy would be based on what is actually being integrated:

• Reusable agent harnesses: langgraph_agent, hermes_agent, simple_strands_agent, and terminus_2_agent. These primarily provide an agent loop and tools that can potentially be paired with different environments.
• Harness abstraction: nemo_fabric_agent. This is effectively an adapter-of-adapters that provides a common lifecycle over several installed harnesses.
• External environment ecosystems: aviary_agent, verifiers_agent, harbor_agent, and stirrup_agent. These bring broader environment, task-lifecycle, execution, or evaluation concepts in addition to an agent.

Would columns such as Agent Server, Upstream Project, Integration Role, and Compatibility / Constraints make these differences clearer? Invocation (Python import, subprocess, container, or sandbox) could then be documented as a separate property rather than being treated as the integration’s primary identity.

[ffrujeri]

Could we replace “every one” with an explicit subject? It is unclear whether this refers to every model, provider, or Model server implementation. Suggested wording:

Suggested change

| [`claude_code_agent`](https://github.com/NVIDIA-NeMo/Gym/tree/main/responses_api_agents/claude_code_agent) | Claude Code (`claude -p`) | Runs against Anthropic, or against any NeMo Gym Model server, since every one serves [Anthropic Messages](/model-server/anthropic-messages) on `POST /v1/messages`. Reference implementation for [Agent Skills](/agent-server/agent-skills). |

| [`claude_code_agent`](https://github.com/NVIDIA-NeMo/Gym/tree/main/responses_api_agents/claude_code_agent) | Claude Code (`claude -p`) | Runs against Anthropic directly or through any NeMo Gym Model server, because NeMo Gym Model servers expose an Anthropic Messages-compatible [`POST /v1/messages`](/model-server/anthropic-messages) endpoint regardless of the underlying inference backend. Reference implementation for [Agent Skills](/agent-server/agent-skills). |

[ffrujeri]

Could we avoid implying that these benchmarks intrinsically require an inseparable agent scaffold? Repository provisioning, workspace state, patch extraction, and benchmark evaluation can conceptually live in a Resources server, while the Agent server owns prompts, model calls, tool selection, and stopping. The current coupling appears to be an implementation choice inherited from runners that bundle those phases.

Would wording like this be more precise?

Currently Benchmark-Coupled Agent Servers

These Agent server implementations currently bundle a benchmark-specific interaction protocol, runtime, or evaluation lifecycle. This reflects their present integration structure rather than a fundamental requirement that the agent harness and environment remain coupled.

This leaves room to move environment state and evaluation behind a Resources-server or shared sandbox interface later.