Agent System¶

PitLane-AI's agent system is built on the Claude Agent SDK, providing an agentic framework for F1 data analysis with tool access, permission controls, and workspace management.

Architecture Overview¶

The core agent architecture consists of three main components:

graph TB
    subgraph F1Agent["F1Agent"]
        WM[Workspace Management]
        TC[Temporal Context]
    end

    F1Agent --> SDK[ClaudeSDKClient]
    F1Agent --> Perms[Tool Permissions]
    F1Agent --> Skills[Skills System]
    F1Agent --> WS[Workspace]

    subgraph Perms[Tool Permissions]
        Bash["Bash (pitlane CLI only)"]
        RW["Read/Write (workspace only)"]
        Web["WebFetch (F1 domains only)"]
    end

    subgraph Skills[Skills]
        analyst[f1-analyst]
        drivers[f1-drivers]
        schedule[f1-schedule]
        rc[race-control]
    end

F1Agent Class¶

The F1Agent class is the primary interface for interacting with the AI agent.

Initialization¶

from pitlane_agent import F1Agent

# Auto-generated workspace
agent = F1Agent()

# Explicit workspace ID
agent = F1Agent(workspace_id="my-workspace-123")

# With tracing enabled
agent = F1Agent(enable_tracing=True)

# Without temporal context
agent = F1Agent(inject_temporal_context=False)

Parameters:

• workspace_id (optional): Workspace identifier. Auto-generated UUID if not provided.
• workspace_dir (optional): Explicit workspace path. Derived from workspace_id if None.
• enable_tracing (optional): Enable OpenTelemetry tracing. Uses PITLANE_TRACING_ENABLED env var if None.
• inject_temporal_context (optional): Inject F1 calendar context into system prompt. Default: True.

Note: The workspace ID (for data isolation) is distinct from the agent session ID (for conversation resumption).

Chat Methods¶

The agent provides two methods for interaction:

Streaming Response¶

async for chunk in agent.chat("Who won the Monaco Grand Prix?"):
    print(chunk, end="", flush=True)

Yields text chunks as they're generated, enabling real-time display.

Full Response¶

response = await agent.chat_full("Analyze lap times for Hamilton in Bahrain 2024")
print(response)

Returns the complete response as a single string.

Agent Configuration¶

System Prompt¶

The agent uses the claude_code preset system prompt with optional temporal context appended:

options = ClaudeAgentOptions(
    cwd=str(PACKAGE_DIR),
    setting_sources=["project"],
    allowed_tools=["Skill", "Bash", "Read", "Write", "WebFetch"],
    can_use_tool=can_use_tool_with_context,
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": temporal_prompt,  # F1 calendar awareness
    }
)

Allowed Tools¶

The agent has access to five tools:

See Tool Permissions for detailed restrictions.

Skills Integration¶

Skills are discovered and loaded from the .claude/skills/ directory:

packages/pitlane-agent/src/pitlane_agent/.claude/skills/
├── f1-analyst/
│   ├── skill.md           # Skill definition
│   ├── lap_times.py       # Lap time analysis
│   └── tyre_strategy.py   # Tyre strategy visualization
├── f1-drivers/
│   └── drivers.py         # Driver information via Ergast API
└── f1-schedule/
    └── schedule.py        # Event calendar queries

Each skill provides specialized functionality with its own prompt, scripts, and dependencies.

Workspace Management¶

Workspace Isolation¶

Each agent operates in an isolated workspace for data storage:

~/.pitlane/workspaces/<workspace-id>/
├── .metadata.json         # Workspace metadata
├── data/                  # Workspace-specific data
└── charts/                # Generated visualizations

The workspace ID is passed to skills via the PITLANE_WORKSPACE_ID environment variable, enabling workspace-scoped operations.

Note: This workspace ID is distinct from the agent session ID used for conversation resumption.

Workspace Lifecycle¶

1. Creation: Workspace created on first agent initialization
2. Access: last_accessed timestamp updated on each agent init
3. Cleanup: Old workspaces cleaned via pitlane workspace clean

Tracing and Observability¶

The agent supports OpenTelemetry tracing through hooks:

hooks = {
    "PreToolUse": [HookMatcher(matcher=None, hooks=[pre_tool_use_hook])],
    "PostToolUse": [HookMatcher(matcher=None, hooks=[post_tool_use_hook])],
}

Enable tracing to observe:

• Tool invocations and results
• Permission checks and denials
• Skill executions
• Decision flows

See Agent CLI: Tracing for configuration.

Related Documentation¶

• Temporal Context - F1 calendar awareness
• Skills - Skill system architecture
• Tool Permissions - Tool restriction system
• Workspace Management - Session isolation