feat: add deterministic agentic warmup budget

Signed-off-by: Cam Quilici <cjquilici@gmail.com>

Author: cquil11

docs/cli-options.md

@@ -1128,6 +1128,11 @@ The maximum duration in seconds for the warmup phase. If not set, it will use th
 Additional agentic replay warmup duration in seconds. After the normal snapshot warmup drains, AIPerf continues the live trajectories without recorded idle delays and with one-token outputs, then drains and resumes profiling from the resulting trajectory state using each live stream's residual next-turn delay.
 <br/>_Constraints: > 0_
 
+#### `--agentic-cache-warmup-requests-per-lane` `<int>`
+
+Deterministic agentic cache-pressure warmup request budget per concurrency lane. For example, 10 with concurrency 16 caps warmup at 160 wire requests, including initial snapshot priming. Requires --agentic-cache-warmup-duration, which remains the safety deadline.
+<br/>_Constraints: > 0_
+
 #### `--agentic-warmup-grace-period` `<float>`
 
 AGENTIC_REPLAY only: grace period in seconds the auto-synthesized warmup barrier waits for in-flight priming requests after the warmup burst sends. The agentic warmup is synthesized from the profiling phase rather than a user-declared warmup phase, so it does NOT honor `--warmup-grace-period` (which requires `--warmup-duration`). If not set, the warmup barrier waits indefinitely until every primed trajectory returns.
@@ -2658,6 +2663,11 @@ The maximum duration in seconds for the warmup phase. If not set, it will use th
 Additional agentic replay warmup duration in seconds. After the normal snapshot warmup drains, AIPerf continues the live trajectories without recorded idle delays and with one-token outputs, then drains and resumes profiling from the resulting trajectory state using each live stream's residual next-turn delay.
 <br/>_Constraints: > 0_
 
+#### `--agentic-cache-warmup-requests-per-lane` `<int>`
+
+Deterministic agentic cache-pressure warmup request budget per concurrency lane. For example, 10 with concurrency 16 caps warmup at 160 wire requests, including initial snapshot priming. Requires --agentic-cache-warmup-duration, which remains the safety deadline.
+<br/>_Constraints: > 0_
+
 #### `--agentic-warmup-grace-period` `<float>`
 
 AGENTIC_REPLAY only: grace period in seconds the auto-synthesized warmup barrier waits for in-flight priming requests after the warmup burst sends. The agentic warmup is synthesized from the profiling phase rather than a user-declared warmup phase, so it does NOT honor `--warmup-grace-period` (which requires `--warmup-duration`). If not set, the warmup barrier waits indefinitely until every primed trajectory returns.

docs/tutorials/agentx-mvp.md

@@ -417,6 +417,16 @@ duration expires, it stops issuing new requests, drains requests already on
 the wire, snapshots each live root, subagent, and unresolved join, and starts
 profiling from that exact state.
 
+For repeatable warmup depth, also set
+`--agentic-cache-warmup-requests-per-lane REQUESTS`. Each concurrency lane is
+then allowed exactly that many warmup wire requests, including its initial
+snapshot-priming requests. For example, `--concurrency 16` with
+`--agentic-cache-warmup-requests-per-lane 10` targets 160 warmup requests,
+with a strict 10-request quota on every lane. The duration is still required as
+a safety deadline: issuance stops at the per-lane quotas or the duration,
+whichever comes first. If the duration wins, a slow run sends fewer than the
+configured request budget.
+
 These requests remain part of warmup, so they are excluded from exported
 request metrics.
 

src/aiperf/config/config.py

@@ -609,7 +609,8 @@ def validate_cache_bust_compatibility(self) -> Self:
     def validate_agentic_cache_warmup(self) -> Self:
         """Restrict accelerated cache warmup to the agentic_replay timing mode.
 
-        ``--agentic-cache-warmup-duration`` is consumed solely by
+        ``--agentic-cache-warmup-duration`` and its optional deterministic
+        request budget are consumed solely by
         ``aiperf.timing.config._build_agentic_warmup_config``, which only runs
         when the profiling phases resolve to AGENTIC_REPLAY. On any other run
         the value is silently dropped, so an unguarded flag is a no-op the user
@@ -630,27 +631,42 @@ def validate_agentic_cache_warmup(self) -> Self:
         from aiperf.timing.config import _is_agentic_replay
 
         profiling_phases = self.get_profiling_phases()
-        if not any(
+        has_duration = any(
             getattr(phase, "agentic_cache_warmup_duration", None) is not None
             for phase in profiling_phases
-        ):
+        )
+        has_request_budget = any(
+            getattr(phase, "agentic_cache_warmup_requests_per_lane", None) is not None
+            for phase in profiling_phases
+        )
+        if not has_duration and not has_request_budget:
             return self
 
+        if any(
+            getattr(phase, "agentic_cache_warmup_requests_per_lane", None) is not None
+            and getattr(phase, "agentic_cache_warmup_duration", None) is None
+            for phase in profiling_phases
+        ):
+            raise ValueError(
+                "--agentic-cache-warmup-requests-per-lane requires "
+                "--agentic-cache-warmup-duration as a safety deadline."
+            )
+
         if self.scenario is not None:
             from aiperf.common.scenario.registry import get_scenario
 
             scenario_timing_mode = get_scenario(self.scenario).timing_mode
             if scenario_timing_mode != TimingMode.AGENTIC_REPLAY:
                 raise ValueError(
-                    "--agentic-cache-warmup-duration requires the agentic_replay "
+                    "agentic cache warmup requires the agentic_replay "
                     f"timing mode; scenario {self.scenario!r} locks "
                     f"timing_mode={scenario_timing_mode}."
                 )
             return self
 
         if not _is_agentic_replay(profiling_phases):
             raise ValueError(
-                "--agentic-cache-warmup-duration requires the agentic_replay "
+                "agentic cache warmup requires the agentic_replay "
                 "timing mode (set today by --scenario inferencex-agentx-mvp); "
                 "the profiling phase(s) are not agentic_replay."
             )

src/aiperf/config/flags/_converter_profiling.py

@@ -54,6 +54,7 @@
     "burst_phase_starts",
     "system_idle_gap_cap_seconds",
     "agentic_cache_warmup_duration",
+    "agentic_cache_warmup_requests_per_lane",
     "agentic_warmup_grace_period",
 )
 

src/aiperf/config/flags/cli_config.py

@@ -2288,6 +2288,22 @@ def url(self) -> str:
         ),
     ] = None
 
+    agentic_cache_warmup_requests_per_lane: Annotated[
+        int | None,
+        Field(
+            gt=0,
+            description="Deterministic agentic cache-pressure warmup request "
+            "budget per concurrency lane. For example, 10 with concurrency 16 "
+            "caps warmup at 160 wire requests, including initial snapshot "
+            "priming. Requires --agentic-cache-warmup-duration, which remains "
+            "the safety deadline.",
+        ),
+        CLIParameter(
+            name=("--agentic-cache-warmup-requests-per-lane",),
+            group=Groups.WARMUP,
+        ),
+    ] = None
+
     agentic_warmup_grace_period: Annotated[
         float | None,
         Field(

src/aiperf/config/phases.py

@@ -364,6 +364,20 @@ class BasePhaseConfig(AdaptiveScalePhaseMixin, BaseConfig):
         ),
     ]
 
+    agentic_cache_warmup_requests_per_lane: Annotated[
+        int | None,
+        Field(
+            default=None,
+            gt=0,
+            description="AGENTIC_REPLAY only: deterministic cache-pressure "
+            "warmup request budget per concurrency lane. The total warmup "
+            "wire-request cap is this value multiplied by the number of live "
+            "trajectory lanes, including the initial snapshot-priming "
+            "requests. Requires agentic_cache_warmup_duration, which remains "
+            "the safety deadline; warmup stops when either limit is reached.",
+        ),
+    ]
+
     agentic_warmup_grace_period: Annotated[
         float | None,
         Field(