Agents API Reference

Module location

All agents live in src/agents/. Each file is extracted from its corresponding notebook (N25–N31).

Entry points

Every agent has two entry points:

N25 is the odd one out: it takes no laps_df. Everything it needs must already be in the lap_state, which is why the stint fuel baseline is carried there rather than derived from a frame. The adapters are not uniform, so check the signature before assuming.

Only the RAG agent (N30) exposes a module-level get_rag_react_agent() factory returning a compiled LangGraph CompiledGraph, for callers that want to drive the graph directly — it is genuinely invoked (the chat backend calls it). N25-N28 (pace, tire, race situation, pit strategy) used to have an equivalent free function each; all four were confirmed dead (zero callers anywhere in the repo) and removed in the 2026-08-01 cleanup pass. Tire, race situation and pit strategy still have their own get_react_agent() instance method, called internally from each agent's own _run_core — only the redundant module-level wrapper was removed for those three. The radio agent (N29) never had one: its pipeline is a fixed sequence of model calls rather than a ReAct loop, so there is no graph to compile.

N25 (pace) is deliberately deterministic — no ReAct loop at all. Unlike its three siblings above, pace's run()/run_from_state() call the N06 XGBoost model directly; there is no LLM step to invoke and no category field (warning_level/action/threat_level) for an LLM to decide. pace_agent.py used to carry a complete but never-wired LangGraph ReAct scaffold (tools, system prompt, get_react_agent()) from the moment the module was first extracted — confirmed by archaeology to have been a deliberate per-agent choice made in the same commit that wired tire/pit/race_situation, not a wiring gap. It was formally retired (deleted, not left dead) in #781; see #778 for the full decision record.

Output dataclasses

PaceOutput (N25)

TireOutput (N26)

RaceSituationOutput (N27)

PitStrategyOutput (N28)

RadioOutput (N29)

RegulationContext (N30)

StrategyRecommendation (N31)

The v2 schema (frozen at 14 fields) surrounds the primary action with execution detail, driver-side instructions and a contingency list, see Multi-agent system for the full rationale.

RaceState input (N31)

The orchestrator accepts a RaceState Pydantic model:

class RaceState(BaseModel):
    driver: str           # Three-letter driver code
    lap: int              # Current lap number
    total_laps: int       # Total race laps
    position: int         # Current race position
    compound: str         # Current tire compound
    tyre_life: int        # Current tire age (laps)
    gap_ahead_s: float    # Gap to car ahead (seconds)
    pace_delta_s: float   # Pace delta vs car ahead
    air_temp: float       # Air temperature (C)
    track_temp: float     # Track temperature (C)
    rainfall: bool = False
    radio_msgs: list = []   # RadioMessage dicts for current lap window
    rcm_events: list = []   # RCMEvent dicts for current lap window
    risk_tolerance: float = 0.5  # 0=conservative, 1=aggressive

Model artifacts

LLM tool-level input validation

Every LangChain tool the LLM can call takes free-text arguments (driver, lap_number, gp_name, year, ...) with no server-side roster or range check other than what the tool itself enforces. A hardening pass (#476) closed the gap where a hallucinated or long-retired driver code, or a lap outside the loaded session, produced a confident but meaningless prediction instead of a visible failure:

N25 Pace originally had an equivalent guard on its own predict_pace_tool (#476), but that tool was deleted along with the rest of pace's unreachable LangGraph scaffold in #781 — pace has no LLM-facing tool left to guard, so the class of bug #476 fixed cannot occur for it anymore.

The refusal is a plain string return (e.g. "error: 'HAM' is not on track at lap 12; valid: [...]" or "... REFUSED — {driver} is not on track ..."), not an exception, the LLM sees a normal-looking tool result it can react to, rather than a traceback. predict_pit_duration_tool additionally cross-checks the LLM-supplied under_sc flag against the RCM-confirmed sc_currently_active ground truth when a real orchestrator run has set it, and trusts the confirmed value over the guess (logging a warning) rather than the other way round.

"On track" is a presence check (the driver has a row in the live roster for this lap), the same convention RaceStateManager uses for rivals, see Race replay engine → who counts as a rival. An age/lap-count cutoff cannot substitute for it: a finisher can go 20 laps without a row, and a retirement can surface as few as 9 laps in, so the ranges overlap.

The MCP-facing tools one layer up (src/telemetry/backend/mcp_tools.py, consumed by chat) apply an equivalent guard on gp/driver/lap/year before they even reach these agent-level tools, see Backend API reference → Tool risk tiers and the chat allowlist.

Testing examples

Tool-level (no LLM needed):

from src.agents.radio_agent import process_radio_tool
result = process_radio_tool.invoke({
    "driver": "NOR", "lap": 18, "text": "Box this lap."
})

Agent-level (no LLM needed):

Whatever else a *_from_state entry point takes, its lap_state must be the real nested dict (driver / rivals / weather / session_meta), not a flat one. Most of them take a laps_df alongside it; the table above has the exact shapes, and they are not uniform. Build it with RaceStateManager rather than by hand: it is the component that owns the contract, and hand-rolling one is how the second, buggy implementation of this got written.

from pathlib import Path
from itertools import islice
from src.simulation.replay_engine import RaceReplayEngine
from src.agents.pace_agent import run_pace_agent_from_state

replay = RaceReplayEngine(Path("data/raw/2025/Lusail"), driver_code="PIA", team="McLaren")
lap_state = next(islice(replay.replay(), 19, 20))   # lap 20
output = run_pace_agent_from_state(lap_state)

print(output.lap_time_pred, output.ci_p10, output.ci_p90)

Take the lap_state from replay(), not from rsm.get_lap_state(lap) directly. get_lap_state's weather_df argument is optional, and replay() is what passes it. Call the RSM bare and the weather dict comes back with only track_status, so consumers fall through to their hardcoded defaults (the arcade's are 25.0 C air / 35.0 C track) and never say so. At Lusail the real values are 23.7 C and 29.8 C, and track temperature is a live input to tire degradation.

See Race replay engine for the full lap_state schema.

Full orchestrator (requires LM Studio or OpenAI):

from pathlib import Path
from itertools import islice
import pandas as pd
from src.simulation.replay_engine import RaceReplayEngine
from src.agents.strategy_orchestrator import RaceState
from src.strategy.inference.engine import run_lap

race_dir = Path("data/raw/2025/Lusail")
laps_df = pd.read_parquet(race_dir / "laps.parquet")
replay = RaceReplayEngine(race_dir, driver_code="PIA", team="McLaren")
lap_state = next(islice(replay.replay(), 19, 20))   # lap 20

driver = lap_state["driver"]
ahead = [r for r in lap_state["rivals"] if r["position"] == driver["position"] - 1]
race_state = RaceState(
    driver=driver["driver"], lap=20, total_laps=replay.total_laps,
    position=driver["position"], compound=driver["compound"],
    tyre_life=driver["tyre_life"],
    # rivals ahead report a NEGATIVE interval; RaceState wants a magnitude
    gap_ahead_s=abs(ahead[0]["interval_to_driver_s"]) if ahead else 0.0,
    pace_delta_s=0.0,
    air_temp=lap_state["weather"]["air_temp"],
    track_temp=lap_state["weather"]["track_temp"],
)

rec, agent_outputs, timings = run_lap(race_state, laps_df, lap_state, profile="no-llm")
print(rec.action, rec.confidence, rec.reasoning)

Prefer run_lap over calling run_strategy_orchestrator_from_state directly: it is the same pipeline (parity-tested), and it also hands back the per-agent outputs and stage timings. Pass profile="no-llm" to run the deterministic path with no provider at all.

Pass the lap_state, and make sure it carries session_meta. The laps_df is scoped to the Grand Prix named there. Without it, the engine falls back to the whole frame and logs a warning, and the agents then look up rivals by driver and lap number across the entire season: the Zandvoort grid can end up deciding a race at Lusail. The fallback is loud on purpose, but the fix is to supply the session_meta, not to ignore the warning.