[ananthsub]

What does this PR do?

Adds compatibility Environment Servers before environment-specific Resources and Agent migrations:

• legacy_agent relays existing Agent /run and /aggregate_metrics contracts without interpreting them.
• single_agent_turn_legacy converts legacy flat rows to the single-agent-turn protocol and returns its result in the legacy result shape, adding only agent_ref.
• Config composition, Agent swapping, scaffolding, migration tooling, and repository configs route existing Agents through compatibility deployments.

Rollout collection routes each flat row to the Environment Server that fronts its Agent. The Agent-to-Environment-Server map is built once, and every Agent in a batch is resolved before any rollout is dispatched. An Agent fronted by several Environment Servers raises AmbiguousEnvironmentServerError before dispatch, instead of silently sending every row to the first one in config order. Several Environment Servers may still front one Agent when no row routes by that Agent.

Compatibility flow

This is the compatibility flow for existing single-agent environments. Other Environment Servers may coordinate different participants.

sequenceDiagram
    participant C as RolloutCollector
    participant E as LegacyEnvironmentServer
    participant A as ExistingAgentServer

    C->>E: POST /run with legacy row
    E->>A: Relay existing /run
    A-->>E: Existing result body
    E-->>C: Unchanged result body

Loading

Stack position

Part 2 of 6. Previous: #3717. Next: #3718.

No issue is linked because this is one layer of the Environment Server stack.

Validation

• uv run pytest tests/unit_tests/test_global_config.py tests/unit_tests/test_rollout_collection.py -q
• uv run pytest environment_servers/single_agent_turn_legacy/tests/test_app.py -q
• uv run pytest environment_servers/legacy_agent/tests/test_app.py -q
• The rollout collection tests check that an ambiguous Agent fails before any request is sent, and that twin Environment Servers for an Agent no row uses do not interfere.

Rollouts

example_single_tool_call with Simple Agent was run through legacy_agent against a real model. The relay returned the same status, result fields, and Set-Cookie as calling the Agent's /run directly, and passed a malformed request's 422 through unchanged. End-to-end evidence for the whole stack is on #3722.

Compatibility and migration impact

Every runnable Agent instance now needs an Environment Server in front of it. Out-of-tree configurations, including NeMo RL configurations, must add a legacy_agent deployment or run scripts/add_legacy_agent_environment_servers.py. Legacy request and result bodies do not change.

A run whose rows route by an Agent that several Environment Servers front now fails before dispatch with an error naming the candidates.

[github-actions]

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/36548336483