| name | run-load-test |
| description | Run the Omnigent load test and produce a results file explaining the latencies. Load when the user wants to load-test / stress-test / benchmark Omnigent under concurrency ("load test omnigent", "stress test the server", "how many hosts/sessions/turns can it handle", "load test real agent turns / conversations", "run a load test"). The test makes each simulated user a real omnigent host that creates host-bound sessions and drives real multi-turn conversations with a mocked LLM; it boots its own local stack (dev/loadtest/run.py). Gather inputs, run it, then read the generated summary.md and explain the latency distribution (avg/median/p95/p99, throughput, failures). NOT for single-request latency micro-benchmarks (that is dev/benchmarks/). |
Run the Omnigent load test
Drives dev/loadtest/ end to end: collect inputs → run → read summary.md →
explain the latencies. Each Locust user is a real omnigent host that
registers over the host tunnel, creates host-bound sessions, and drives real
multi-turn conversations — every turn is a genuine post→idle loop through the
host's runner, with the LLM mocked (zero latency) so the numbers are
Omnigent's own overhead. -u N scales the number of hosts.
It boots its own local stack (server + mock LLM), so there is no server to
point at, and it runs from a repo checkout only. For single-request latency
micro-benchmarks (not concurrency), that is a different tool: dev/benchmarks/.
1. Ensure deps (repo checkout)
uv sync --extra loadtest --extra agents-sdk
Run with that same interpreter (e.g. .venv/bin/python), from the repo root.
2. Gather inputs
Ask the user (AskUserQuestion when several are unknown); all have defaults.
| Input | Flag | Default | Notes |
|---|
| Hosts | --users | 4 | Concurrent hosts (N) — the main scale knob. |
| Spawn rate | --spawn-rate | 1 | Hosts started per second. |
| Run time | --run-time | 120s | 40s / 5m / 1h. |
| Sessions/host | --sessions-per-user | 2 | Host-bound sessions each host drives. |
| Turns/session | --turns-per-session | 4 | Turns per session — history grows across them. |
| Reply length | --reply-words | 60 | Words in the mocked (streamed) reply per turn. |
Capacity caveat — say this to the user if they ask for large N: turns run on
real host + runner subprocesses, so N hosts × M sessions = N×M runner processes
on this box. It is capacity-limited by design (real turns, not faked). Start at
--users 2 --sessions-per-user 1 --turns-per-session 2 --run-time 40s to confirm
the stack boots (~10-30s), then ramp to a few dozen hosts at most. At high N the
load box saturates before the server (Locust warns about CPU).
3. Run
python dev/loadtest/run.py \
--users <N> --spawn-rate <R> --run-time <T> \
--sessions-per-user <S> --turns-per-session <TU>
It boots the stack, prints the server URL + registered agent, runs Locust, and
writes dev/loadtest/results/omnigent_load_test-<timestamp>/.
4. Read and explain
Read the summary.md and relay it. Focus on:
- Outcome / failures first. Exit 0 + 0 failures = PASS. Non-zero failures are
the headline — check
console.log and, for a host that failed to register,
the per-host results/.../host-workspaces/<name>/host.log. At high N, failures
usually mean the load box saturated, not the server.
- turn — the headline latency: one full post→idle agent turn on a host's
runner (mocked LLM), so it is Omnigent's per-turn overhead. It grows across a
conversation as history accumulates, so a rising p95/p99 with larger
--turns-per-session is expected and is the interesting signal.
- host online — host tunnel registration cost; session create — the
host-bound create; Ops/s — aggregate throughput at this concurrency.
If failures appeared or the tail looks high, suggest a concrete next step (lower
N if the load box is saturated, raise --turns-per-session to study history
growth, lengthen --run-time for steady state, or check server logs/metrics).
Notes
- Scenario file:
dev/loadtest/omnigent_load_test.py; driver + report:
dev/loadtest/run.py. Full reference: dev/loadtest/README.md.
