Bedrock auth passthrough

[bbclanker]

Summary

• make model_api_key optional so hosted Bedrock usage can rely on structured model_client_options instead
• add Bedrock auth fields to the Python type surface and send modelClientOptions on session start
• persist the default session model config and resend it on follow-up act/observe/extract/execute calls

Linked PRs

• stagehand: [STG-1573] Add providerOptions for extensible model auth stagehand#1822
• core: https://github.com/browserbase/core/pull/8004

Testing

• uv run pytest tests/test_sessions_create_helper.py tests/test_client.py -k "validate_headers or preserves_default_model_config or returns_bound_session"
• .venv/bin/ruff check src/stagehand/_client.py src/stagehand/session.py src/stagehand/resources/sessions.py src/stagehand/resources/sessions_helpers.py src/stagehand/types/model_config_param.py src/stagehand/types/session_start_params.py src/stagehand/types/session_execute_params.py tests/test_client.py tests/test_sessions_create_helper.py
• .venv/bin/ruff format --check src/stagehand/_client.py src/stagehand/session.py src/stagehand/resources/sessions.py src/stagehand/resources/sessions_helpers.py src/stagehand/types/model_config_param.py src/stagehand/types/session_start_params.py src/stagehand/types/session_execute_params.py tests/test_client.py tests/test_sessions_create_helper.py

[cubic-dev-ai]

No issues found across 9 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User as User Application
    participant SDK as Stagehand Client
    participant Helpers as Sessions Helpers
    participant SessionObj as Bound Session
    participant API as Browserbase API

    Note over User,API: Initialization & Session Start
    User->>SDK: Stagehand(model_api_key=None)
    Note right of SDK: CHANGED: model_api_key is now optional<br/>to allow Bedrock auth passthrough

    User->>SDK: sessions.start(model_name, model_client_options)
    SDK->>API: POST /v1/sessions/start
    Note right of API: NEW: body contains model_client_options<br/>(accessKeyId, secretAccessKey, etc.)
    API-->>SDK: 200 OK (session_id)

    SDK->>Helpers: _build_default_model_config()
    Note right of Helpers: NEW: Captures Bedrock credentials<br/>to persist for subsequent calls
    Helpers-->>User: return Session object (with default_model)

    Note over User,API: Action Execution Flow (e.g., extract, act, observe)
    User->>SessionObj: session.extract(instruction, schema)
    
    SessionObj->>SessionObj: NEW: _merge_default_model()
    Note right of SessionObj: Injects stored Bedrock creds<br/>into request options if not provided

    SessionObj->>API: POST /v1/sessions/{id}/extract
    Note right of API: NEW: Payload includes merged<br/>model config with AWS credentials

    alt Success Path
        API-->>SessionObj: 200 OK (extracted data)
        SessionObj-->>User: return data
    else Auth Failure
        API-->>SessionObj: 401/403 Error
        SessionObj-->>User: raise APIStatusError
    end

    Note over User,API: Agent Execution Flow (execute)
    User->>SessionObj: session.execute(instruction)
    SessionObj->>SessionObj: NEW: _merge_default_agent_model()
    SessionObj->>API: POST /v1/sessions/{id}/execute
    Note right of API: Provider 'bedrock' now supported<br/>in agent_config
    API-->>User: return Agent results

Loading

[shrey150]

Closing this PR — the SDK-side model config persistence logic has been removed from the stagehand TS SDK (browserbase/stagehand#1822) in favor of server-side defaults. The server already stores modelClientOptions from session start and merges them into subsequent requests, so language SDKs don't need to reimplement this logic.

The remaining changes needed (new types for ModelClientOptions, Bedrock fields, making model_api_key optional) should come automatically via Stainless regen once the stagehand + core PRs land and the OpenAPI spec updates.