feat(agentic): add deterministic warmup request budgets

docs/cli-options.md

@@ -1125,7 +1125,12 @@ The maximum duration in seconds for the warmup phase. If not set, it will use th
 
 #### `--agentic-cache-warmup-duration` `<float>`
 
-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.
+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. Mutually exclusive with --warmup-requests-per-lane.
+<br/>_Constraints: > 0_
+
+#### `--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. Mutually exclusive with --agentic-cache-warmup-duration.
 <br/>_Constraints: > 0_
 
 #### `--agentic-warmup-grace-period` `<float>`
@@ -2655,7 +2660,12 @@ The maximum duration in seconds for the warmup phase. If not set, it will use th
 
 #### `--agentic-cache-warmup-duration` `<float>`
 
-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.
+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. Mutually exclusive with --warmup-requests-per-lane.
+<br/>_Constraints: > 0_
+
+#### `--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. Mutually exclusive with --agentic-cache-warmup-duration.
 <br/>_Constraints: > 0_
 
 #### `--agentic-warmup-grace-period` `<float>`

docs/tutorials/agentx-mvp.md

@@ -417,6 +417,17 @@ 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, use
+`--warmup-requests-per-lane REQUESTS` instead. Each concurrency lane is allowed
+exactly that many warmup wire requests, including its initial snapshot-priming
+requests. For example, `--concurrency 16` with
+`--warmup-requests-per-lane 10` produces 160 warmup requests, with a strict
+10-request quota on every lane.
+
+`--agentic-cache-warmup-duration` and `--warmup-requests-per-lane` are mutually
+exclusive: choose a time-bounded warmup or a deterministic request-bounded
+warmup.
+
 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
+        The mutually exclusive duration and deterministic request-budget modes
+        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, "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, "warmup_requests_per_lane", None) is not None
+            and getattr(phase, "agentic_cache_warmup_duration", None) is not None
+            for phase in profiling_phases
+        ):
+            raise ValueError(
+                "--warmup-requests-per-lane and "
+                "--agentic-cache-warmup-duration are mutually exclusive."
+            )
+
         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",
+    "warmup_requests_per_lane",
     "agentic_warmup_grace_period",
 )
 

src/aiperf/config/flags/cli_config.py

@@ -2280,14 +2280,31 @@ def url(self) -> str:
             "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.",
+            "using each live stream's residual next-turn delay. Mutually exclusive "
+            "with --warmup-requests-per-lane.",
         ),
         CLIParameter(
             name=("--agentic-cache-warmup-duration",),
             group=Groups.WARMUP,
         ),
     ] = None
 
+    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. Mutually exclusive with "
+            "--agentic-cache-warmup-duration.",
+        ),
+        CLIParameter(
+            name=("--warmup-requests-per-lane",),
+            group=Groups.WARMUP,
+        ),
+    ] = None
+
     agentic_warmup_grace_period: Annotated[
         float | None,
         Field(

src/aiperf/config/phases.py

@@ -360,7 +360,21 @@ class BasePhaseConfig(AdaptiveScalePhaseMixin, BaseConfig):
             "continues the live trajectories without recorded idle delays and with "
             "one-token outputs for this long, then drains and resumes profiling "
             "from the resulting trajectory state. Read off the profiling phase by "
-            "``timing.config._build_agentic_warmup_config``. None disables it.",
+            "``timing.config._build_agentic_warmup_config``. Mutually exclusive "
+            "with warmup_requests_per_lane. None disables it.",
+        ),
+    ]
+
+    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. Mutually exclusive with agentic_cache_warmup_duration.",
         ),
     ]