Steer a running discovery

Goal

This example assumes you have completed Get started with Particle Life. Your Particle Life project, runner, commands, model, and simulation_fps benchmark should already be ready.

You will let the agent explore unguided, steer it mid-run toward using every CPU core, let the budget finish, then add one more version and steer it to combine what it has found.

This is one example of what steering a Discovery run can look like. Since each run has some randomness you may see different behaviour, but this example shows all the elements you'll need to steer it as you see fit.

1. Start with ten versions

Skill: discovery-start

artemis discovery create \
  --project <project-id> \
  --task "Maximize simulation_fps without changing simulation behavior or weakening the correctness tests." \
  --versions 10 \
  --compile-cmd "cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel" \
  --test-cmd "ctest --test-dir build --output-on-failure" \
  --benchmark-cmd "python3 tools/benchmark.py --no-visualize" \
  --runner <runner-name> \
  --mode automatic \
  --model <model-catalogue-uuid>

Capture the returned <run-id>. Wait for the baseline to finalise and at least one version to appear:

artemis discovery get <run-id>
artemis discovery versions list <run-id>

2. Redirect the search while it is active

Skill: discovery-steer

Steer around halfway, before the budget is exhausted:

artemis --output-format json discovery steer <run-id> \
  --message "You are leaving significant performance on the table. This benchmark runs on a multi-core machine and the simulation currently uses one core. Consider how to use all the available CPU cores. Preserve checksum determinism and all existing tests."

Successful output includes a resulting agentRunId and verified: true. Steering follows the child agent run created by the platform and repoints Discovery to it.

Check delivery and later behavior separately:

artemis --output-format json discovery get <run-id>
artemis chat messages <resulting-agent-run-id>
artemis discovery experiments list <run-id>
artemis discovery versions list <run-id>

The child chat should contain the instruction. Subsequent experiments and diffs—not successful delivery alone—show whether the agent followed it. Work already in flight may still finish under the original direction.

3. Let the first budget finish

Wait until the run reaches a terminal state at ten versions, then inspect how the budget was spent:

artemis discovery get <run-id>
artemis discovery versions list <run-id>
artemis discovery metrics <run-id> --stats --all

Individual versions may fail generation, compilation, testing, or scoring. Compare successful candidates by measured simulation_fps, and read their diffs to see which technique produced each result. Note which strong ideas appear in separate versions but never together—that is what step 4 acts on.

4. Add one version, then steer

The continue endpoint expands and restarts a finished run, but it cannot carry new guidance. Add budget first:

artemis discovery continue <run-id> --versions 1

Refetch until the run is active with an agentRunId, then give the added budget its focus:

artemis discovery get <run-id>

artemis --output-format json discovery steer <run-id> \
  --message "Your strongest results optimise different things and have never been combined. <name them, with their version numbers and measured simulation_fps>. These are independent and should compound. Use the additional budget to combine them rather than replace one with the other. Preserve checksum determinism and all existing tests."

Name the actual versions from your own run. A steer that cites measured results is far more likely to be followed than a generic instruction.

Do not reverse this order at the end of a run: first continue to create room for more versions, then steer to provide new guidance.

What a steered run looks like

Unguided, the agent found a spatial grid at v1. The first steer produced thread-level parallelism at v6—but the agent dropped the grid to get it. The second steer said the two were independent and should compound: v11 combined them at 1,382 fps, 42× the baseline and more than three times either technique alone.

Both steers were acted on by the very next version. Neither was guaranteed to be—judge compliance from the diffs, not from verified: true.

What to expect

• Steering cancels the parent agent turn and continues on a child run. After refreshing the Web UI, the parent may appear as Interrupted; this is expected.
• A steer changes direction but does not guarantee immediate compliance. Judge later experiments, versions, and diffs.
• The original ten-version budget becomes eleven after continue --versions 1; existing versions and metrics remain available.
• Discovery is stochastic. Your run may find different techniques, in a different order, or none that beat the baseline on your runner.

At the end, use discovery-inspect to account for every version, compare measured simulation_fps with the baseline, and read the best candidate's diff.