AI agent workflows with opp_repl

This skill is a cookbook for agents driving opp_repl. Each recipe lists the prerequisite skills, the decision tree, and the actual tool calls. Load together with opp-repl-mcp-server for MCP-based integration, or opp-repl-cli-tools for pure-shell orchestration.

Recipe 1 — "Run this simulation and report"

Prereqs: opp-repl-installation, opp-repl-opp-files, opp-repl-running-simulations, opp-repl-tasks-and-results, opp-repl-result-analysis.

1. If no .opp file exists for the target project, write one

(template from opp-repl-opp-files/templates/), OR run create_project(name, path=...) on current opp_repl.

1. Start or attach to a REPL / MCP server.
2. Run:

r = run_simulations( simulation_project=<name>_project, config_filter="...", sim_time_limit="1s")

1. Summarise r.get_error_results() and

r.is_all_results_done(). On failure, rerun a failing task in debug mode and pull print_stderr() for diagnostics.

1. On success, aggregate scalars:

df = r.get_scalars() # DataFrame merged across reps means = df.groupby("name").value.mean()

Recipe 2 — "Investigate a regression"

Prereqs: opp-repl-fingerprint-tests, opp-repl-comparing-simulations, opp-repl-tasks-and-results.

1. Reproduce the failure:

r = run_fingerprint_tests( simulation_project=<p>, config_filter=<suspect>, sim_time_limit="1s") failures = r.get_fail_results()

1. Compare HEAD against the last-known-good tag/commit:

cr = compare_simulations_between_commits( simulation_project=<p>, git_hash_1="v4.5", git_hash_2="HEAD", config_filter=<suspect>, run_number=0)

1. Inspect the divergence:

first = cr.results[0] first.fingerprint_trajectory_comparison_result first.print_different_statistical_results( include_relative_errors=True) first.show_divergence_position_in_sequence_chart()

1. Once the suspect commit is identified, leave a report

explicitly referencing the first divergent event number and simulation time.

Recipe 3 — "Tune a parameter to hit a target"

Prereqs: opp-repl-parameter-optimization, opp-repl-running-simulations.

1. Narrow to a single task with get_simulation_task(...).
2. Specify expected_result_names, expected_result_values, and

parameter_* arguments (see the skill).

1. Call optimize_simulation_parameters(...).
2. Report convergence: best values, residual error, number of

evaluations.

If the objective is noisy, lengthen sim_time_limit or use repeats before giving up.

Recipe 4 — "Release gate on a feature branch"

Prereqs: opp-repl-feature-and-release-tests, opp-repl-github-actions, opp-repl-cli-tools.

1. Locally: run_smoke_tests() on the default project.
2. If green, trigger a remote suite:

dispatch_workflow("release-tests.yml", ref="topic/my-feature")

1. In parallel, run run_fingerprint_tests() locally on the

subset of configs you actually touched (narrow filter).

1. Summarise pass/fail for both local and remote verdicts.

Recipe 5 — "Set up a new simulation project from scratch"

Prereqs: opp-repl-installation, opp-repl-project-scaffolding, opp-repl-concepts, opp-repl-running-simulations, opp-repl-result-analysis.

On current opp_repl (>= commit a17fcab, Apr 2026):

from opp_repl.simulation.project import create_project

# Generates <name>.opp, .oppbuildspec, .nedfolders, package.ned,
# omnetpp.ini; loads the project; returns the SimulationProject.
p = create_project("mm1k", path="/tmp", namespace=False)

# Now add NED + C++:
#   /tmp/mm1k/Mm1k.ned
#   /tmp/mm1k/Source.{h,cc}   Queue.{h,cc}   Sink.{h,cc}
# and edit /tmp/mm1k/omnetpp.ini to set `network = Mm1k` +
# parameter assignments.

p.build()
r = run_simulations(simulation_project=p, sim_time_limit="100s")
df = r.get_scalars()

On older opp_repl, copy templates from opp-repl-project-scaffolding/templates/ into a fresh directory instead, rename mm1k to your chosen name everywhere, then load_opp_file() + build_project() + run_simulations().

Recipe 6 — "Distribute a parameter sweep to a cluster"

Prereqs: opp-repl-ssh-cluster, opp-repl-running-simulations, opp-repl-filtering.

1. Authenticate SSH to each worker.
2. Make the built binaries reachable on every worker — via a shared

filesystem, or by building on each node (there is no auto-copy helper):

p.build(mode="release")

ensure each worker can reach the same compiled binaries

1. Launch:

c = SSHCluster(scheduler_hostname="node1", worker_hostnames=["node1", "node2"]) c.start() run_simulations(scheduler="cluster", cluster=c, config_filter="PureAlohaExperiment")

1. Watch the Dask dashboard at localhost:8797.

Recipe 7 — "Keep baselines up to date after a planned change"

Prereqs: any opp-repl-*-tests skill for the test type.

1. Confirm the CHANGE is intentional (humans have reviewed it).
2. Regenerate the relevant baseline, SCOPED to the touched area:

update_fingerprint_test_results( simulation_project=<p>, working_directory_filter="examples/ethernet", sim_time_limit="10s")

1. Commit the updated store JSON / statistics folder / media

folder alongside the code change. Never auto-update baselines in CI.

General agent guardrails

• Always verify r.is_all_results_done() / is_all_results_expected()

before reporting "green". A PASS summary can hide ERRORs in sub-sub-results.

• Never --break-system-packages; always install into a venv.
• Don't run update_*_test_results without an explicit human

instruction — that overwrites baselines.

• When an execute_python call fails, fetch the stderr via

print_stderr() before retrying; do NOT retry blindly with higher time limits.

• For a local sub-agent REPL, prefer the tokenless --mcp-socket

transport (clients connect via opp_repl_mcp_bridge). TCP (--mcp-port) needs --mcp-token-hash (or --mcp-bypass-token-hash-check) outside opp_sandbox. Keep the MCP server OFF (both flags unset) in CI. See opp-repl-mcp-server.

See also

• opp-repl-overview — skill map.
• opp-repl-mcp-server — MCP endpoint details.
• opp-repl-shared-terminal — co-drive one REPL with a human.
• opp-repl-sandbox — isolate execute_python under bubblewrap.
• opp-repl-cli-tools — shell-only alternative.
• Every task-specific opp-repl-* skill referenced above.