release: 3.5.1

[stainless-app]

Automated Release PR

3.5.1 (2026-01-29)

Full Changelog: v3.5.0...v3.5.1

Chores

• sync repo (033e0ba)

---

This pull request is managed by Stainless's GitHub App.

The semver version number is based on included commit messages. Alternatively, you can manually set the version number in the title of this pull request.

For a better experience, it is recommended to use either rebase-merge or squash-merge when merging this pull request.

🔗 Stainless website
📚 Read the docs
🙋 Reach out for help or questions

---

Summary by cubic

Release 3.5.1 promotes the Python package to stable “stagehand” (now MIT-licensed), streamlines the Sessions API, and updates release tooling to publish wheels with the embedded server. It also adds execute-result caching and a new replay response type.

• New Features

  • Execute: support should_cache and cacheEntry in responses.
  • Added SessionReplayResponse for session replay data.
  • frame_id is now optional across act/extract/observe/navigate.
  • Added pydoll_tab_example; client supports raw/streaming request bodies.

• Migration

  • Install from PyPI as stagehand (not stagehand-alpha).
  • Use client.sessions.start(...) instead of client.sessions.create(...).
  • End now takes no body; SessionEndParams and x-sent-at are removed.
  • For act options.model, pass an object like {"model_name": "openai/gpt-5-nano"}.
  • GitHub Releases trigger PyPI publish; wheels bundle the server (no manual binary download).

^{Written for commit 05e24f7. Summary will update on new commits. Review in cubic}

[stainless-app]

🧪 Testing

To try out this version of the SDK, run:

pip install 'https://pkg.stainless.com/s/stagehand-python/e2175ce490155828bf80031e43cb2b6879faf31c/stagehand_alpha-3.5.0-py3-none-any.whl'

Expires at: Sat, 28 Feb 2026 21:23:54 GMT
Updated at: Thu, 29 Jan 2026 21:23:54 GMT

[cubic-dev-ai]

No issues found across 47 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 Code
    participant SDK as Stagehand Python SDK
    participant LocalSvr as Local Server (Embedded SEA Binary)
    participant RemoteAPI as Remote Stagehand API
    participant Browser as Browser Instance (via CDP)
    participant LLM as AI Model Provider

    Note over User,RemoteAPI: Initialization & Session Lifecycle

    User->>SDK: AsyncStagehand(server="local" | "remote")
    
    User->>SDK: CHANGED: sessions.start(model_config, ...)
    alt server == "local"
        SDK->>LocalSvr: NEW: Launch & proxy request
    else server == "remote"
        SDK->>RemoteAPI: POST /v1/sessions/start
    end
    RemoteAPI-->>SDK: Session data (id, cdp_url)
    SDK-->>User: Session instance

    Note over User,LLM: Execution with Caching & CDP Integration

    opt If using Playwright/Pydoll
        User->>Browser: Connect via cdp_url
        SDK->>Browser: Internal: Page.getFrameTree
        Browser-->>SDK: frame_id
    end

    User->>SDK: session.execute(instruction, should_cache=True)
    SDK->>RemoteAPI: POST /v1/sessions/{id}/agentExecute (with frame_id)
    RemoteAPI->>LLM: Reasoning & tool selection
    RemoteAPI->>Browser: Perform DOM actions
    
    alt NEW: should_cache is true
        RemoteAPI->>RemoteAPI: Compute & store cache key
        RemoteAPI-->>SDK: result + NEW: cacheEntry
    else
        RemoteAPI-->>SDK: result
    end
    SDK-->>User: SessionExecuteResponse

    Note over User,RemoteAPI: Observability & Cleanup

    User->>SDK: NEW: sessions.replay(id)
    SDK->>RemoteAPI: GET /v1/sessions/{id}/replay
    RemoteAPI-->>User: SessionReplayResponse (Token usage/Actions)

    User->>SDK: CHANGED: session.end()
    SDK->>RemoteAPI: POST /v1/sessions/{id}/end (Body removed)
    RemoteAPI-->>User: 200 OK

Loading