NeMo User Sim Integration Reference

This page describes the integration behind the NeMo User Sim rollout tutorial.

Component ownership

Preparation materializes one validation row per built-in probe before collection.
The rollout collector loads a task and dispatches an episode request to the Environment Server.
The Environment Server seeds sessions, owns the conversation runtime and tool loop, invokes participants and support models, requests verification, and returns the episode response.
The User Agent produces simulated User messages through user_model.
The Assistant Agent produces the evaluated Assistant messages and function calls through policy_model. To evaluate a different agent, point assistant_agent at an Agent Server that implements agent sessions and returns function calls without executing them; NeMo User Sim executes the tools.
The Resources Server validates the resolved row, stores its session snapshot, evaluates the completed episode, and returns Gym’s reward contract.
The support model handles structured judge, summary, tool-simulation, evaluator, and probe-scorer requests. The Environment Server invokes support roles used during the conversation; the Resources Server invokes final evaluator and probe-scorer requests through its configured probe_scorer_model.

The Resources Server does not create a second conversation runtime and does not expose probe-tool routes.

Prepared task contract

Preparation provides stable string task_id values and complete resolved_row objects. NeMo User Sim calls this resolved row a materialized row; in Gym, a materialized row is the collector’s task_id plus task_input record in rollouts_materialized_inputs.jsonl. The following row is a schematic with nested values elided; see resources_servers/nemo_user_sim/data/example.jsonl for complete rows:

{
  "task_id": "<trajectory-id>",
  "resolved_row": {
    "persona": {"first_name": "...", "last_name": "..."},
    "probe_type": "general_open_ended",
    "conversation_language": "English",
    "trajectory_id": "<trajectory-id>",
    "usersim_config": {"...": "..."},
    "usersim_provenance": "{\"code_sha\":\"<pinned-revision>\",\"nemotron_personas_version\":\"0.0.2\",\"bank_version\":{}}"
  }
}

usersim_provenance is JSON text so empty nested values remain Arrow- and Parquet-safe.

A row can also carry an optional role_request_params object next to resolved_row. It maps a role (user, assistant, judge, summary, or tool_simulation) to Responses API parameters that the Environment Server uses as the base of that role’s requests. The conversation input and NeMo User Sim’s per-activation parameters are applied on top.

At /seed_session, the Resources Server validates required fields, the configured NeMo User Sim revision, and the Nemotron-Personas version ("0.0.2", or "synthetic" for the committed example rows), and rejects guarded health rows. It then stores the resolved row and its canonical SHA-256 digest. At /verify, it rejects mismatched episode identity, task identity, resolved-row content, or trajectory identity.

The digest covers only resolved_row; task and episode identity are compared separately. It establishes that the resolved row did not change between seeding and verification. It is not a comparison with a separately stored preparation artifact.

Episode execution

The Environment Server constructs one ProbeEpisodeRuntime.from_resolved_row(...) from the resolved row. The runtime owns conversation state, probe state, tool validation and execution, semantic call indices, and episode evidence.

For tool_calling, safety_agentic, and financial_services, the Assistant Agent returns function calls without executing them. NeMo User Sim validates and executes accepted calls, appends tool messages, and requests another Assistant activation when needed. Internal API-response synthesis uses tool_simulation_model.

Unexpected runtime exceptions become failures-sidecar records with an agent stage. Failures that NeMo User Sim reports, and Assistant activation errors that the Environment Server classifies as Assistant mistakes (failure_class: assistant_activation_error), appear under usersim_result.simulation_outcome.

Model requirements and routing

user_model, policy_model, and support_model are separate Gym Model Server configurations. Their upstream URLs can be shared, but every URL must implement an OpenAI-compatible Chat Completions API. user_model_* has no default, so the simulated User never silently runs on the evaluated policy; support_model_* defaults to the policy_* values.

The support endpoint must accept JSON Schema response formats because evaluator and scorer requests require structured output. If it rejects the probe-scorer schema, verification is masked as verifier_error. If it rejects the judge schema, NeMo User Sim returns no quality axes, and a completed scenario is masked as judge_failed.

financial_services retrieval embeds queries through embedding_model. Its embedding_model_base_url, embedding_model_api_key, and embedding_model_name settings default to the support_model_* values. Embedding calls do not go through a Model Server: the Environment Server posts directly to <embedding_model_base_url>/embeddings with that endpoint’s API key. If the call fails, NeMo User Sim falls back to lexical retrieval without failing the episode, so a chat-only support endpoint quietly degrades retrieval.

The semantic invocation roles are:

user: simulated User participant.
assistant: evaluated Assistant participant.
judge: conversation-quality judge.
summary: optional context summarization.
tool_simulation: simulated tool-result generation.

Verification and reward

The Resources Server calls NeMo User Sim’s TrajectoryEvaluatorGenerator.agenerate() once, with the scorer selected for the prepared probe when one applies.

scenario_completed requires:

a completed conversation;
both User and Assistant messages; and
a passing applicable probe scorer.

When scenario_completed is true and all required axes exist, reward is the mean of normalized helpfulness, accuracy, and coherence. Otherwise, reward is 0.0.

The verification response includes:

reward: scalar Gym reward.
mask_sample: whether aggregation must exclude the reward.
failure_kind and failure_reason: normalized failure details.
reward_components: flat completion flags and quality metrics for Gym aggregation.
scenario_completed: whether the full scoring gate passed.
verifier_data: structured NeMo User Sim evaluator and probe evidence.

The Environment Server copies reward, mask_sample, failure_kind, failure_reason, and reward_components onto the top-level persisted rollout. The nested verification object retains the complete verifier response.

Saved rollout fields

usersim_result.conversation_messages: ordered User, Assistant, function-call, and tool-result messages.
usersim_result.simulation_outcome: simulation status, attribution, detail, and warnings, reported by NeMo User Sim or, for Assistant activation errors, by the Environment Server.
invocations: ordered participant and support activations made by the Environment Server.
verification.verifier_data.normalized_axis_scores: full normalized NeMo User Sim quality map.
reward_components: Gym’s flat projection of quality metrics plus completion/scoring flags.
ng_model_call_capture: provider-level calls captured through the User and Assistant Agents.
ng_trajectory: Gym’s normalized Agent execution record, including any reported gaps.
_ng_failure_*: failure-sidecar fields for attempts without a completed episode response.

reward_components repeats quality axes with a quality. prefix so Gym can aggregate them. The structured normalized_axis_scores map remains in verifier evidence for NeMo User Sim-specific inspection.

Masking rules

Assistant-attributed simulation failure: measured zero, mask_sample: false.
Failed applicable probe check: measured zero, mask_sample: false.
Simulation failure that NeMo User Sim attributes outside the Assistant: zero, mask_sample: true.
Scorer/evaluator error or timeout: zero, mask_sample: true.
Inconclusive scorer or missing required judge quality: zero, mask_sample: true.
Resources Server session unknown, closed, or expired at verification: zero, mask_sample: true, with failure_kind session_lost or session_expired.

Infrastructure failures, such as transport errors, participant timeouts, session 404 and 409 responses, and 408, 425, 429, and 5xx responses, produce no reward. They are written to rollouts_failures.jsonl without a scored row.

For commands and examples, see Troubleshoot NeMo User Sim Rollouts.