# browserbase/stagehand architecture

> Architecture diagram of the GitHub repository browserbase/stagehand, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/browserbase/stagehand
- Repository: https://github.com/browserbase/stagehand

## Overview

Stagehand is a cross-language SDK and runtime for browser agents. The principal workflow is an agent request entering the extension’s Stagehand controller, which dispatches act, observe, or extract operations; model-backed operations use the configured LLM path and browser operations are exposed through page control. The repository also includes a CLI, language and agent-framework integrations, and cloud-management commands. The README establishes the user-facing workflow; sampled source confirms controller and model dispatch, but does not establish every service-to-browser implementation link.

Main entry points: [`packages/extension/controllers/stagehandController.ts`](https://github.com/browserbase/stagehand/blob/main/packages/extension/controllers/stagehandController.ts) (Stagehand API), [`packages/extension/services/llmService.ts`](https://github.com/browserbase/stagehand/blob/main/packages/extension/services/llmService.ts) (LLM dispatch), [`packages/extension/understudy/page.ts`](https://github.com/browserbase/stagehand/blob/main/packages/extension/understudy/page.ts) (Browser control), [`packages/cli/src/commands`](https://github.com/browserbase/stagehand/tree/main/packages/cli/src/commands) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_ops["Agent operations"]
  node_stagehand_api["Stagehand API"]
  node_act["Act service<br/>[actService.ts]"]
  node_observe["Observe service<br/>[observeService.ts]"]
  node_extract["Extract service<br/>[extractService.ts]"]
  node_llm_service["LLM dispatch<br/>[llmService.ts]"]
  node_llm_clients["LLM clients<br/>[LLMClient.ts]"]
end

subgraph group_browser_runtime["Browser runtime"]
  node_page_controller["Page controller<br/>[pageController.ts]"]
  node_runtime["Extension runtime<br/>[runtime.ts]"]
  node_understudy["Browser control<br/>[page.ts]"]
  node_network["Network tracking<br/>[networkManager.ts]"]
  node_protocol["Shared protocol<br/>[types.ts]"]
end

subgraph group_developer_tools["Developer tools"]
  node_cli_commands["CLI commands"]
  node_driver_session["Driver session<br/>[session-manager.ts]"]
  node_cloud_api["Cloud API<br/>[api.ts]"]
end

subgraph group_sdk_integrations["SDKs and integrations"]
  node_sdk_go["Go SDK<br/>[stagehand.go]"]
  node_sdk_python["Python SDK<br/>[browser.py]"]
  node_agent_integrations["Agent integrations"]
end

node_agent(("Browser agent"))
node_browser(("Browser"))
node_cli(("CLI user"))

node_agent -->|"requests operation"| node_stagehand_api
node_stagehand_api -->|"dispatches act"| node_act
node_stagehand_api -->|"dispatches observe"| node_observe
node_stagehand_api -->|"dispatches extract"| node_extract
node_act -->|"generates with model"| node_llm_service
node_observe -->|"generates with model"| node_llm_service
node_extract -->|"generates with model"| node_llm_service
node_llm_service -->|"uses client"| node_llm_clients
node_agent -->|"requests page control"| node_page_controller
node_page_controller -->|"calls page operation"| node_runtime
node_runtime -->|"uses browser control"| node_understudy
node_understudy -->|"controls"| node_browser
node_understudy -->|"tracks network"| node_network
node_stagehand_api -->|"uses typed contracts"| node_protocol
node_cli -->|"runs command"| node_cli_commands
node_cli_commands -->|"executes browser command"| node_driver_session
node_driver_session -->|"connects browser"| node_browser
node_cli_commands -->|"calls cloud operations"| node_cloud_api
node_agent -.->|"uses SDK"| node_sdk_go
node_agent -.->|"uses SDK"| node_sdk_python
node_agent -.->|"uses adapter"| node_agent_integrations

click node_stagehand_api "https://github.com/browserbase/stagehand/blob/main/packages/extension/controllers/stagehandController.ts"
click node_act "https://github.com/browserbase/stagehand/blob/main/packages/extension/services/actService.ts"
click node_observe "https://github.com/browserbase/stagehand/blob/main/packages/extension/services/observeService.ts"
click node_extract "https://github.com/browserbase/stagehand/blob/main/packages/extension/services/extractService.ts"
click node_llm_service "https://github.com/browserbase/stagehand/blob/main/packages/extension/services/llmService.ts"
click node_llm_clients "https://github.com/browserbase/stagehand/blob/main/packages/extension/llm/LLMClient.ts"
click node_page_controller "https://github.com/browserbase/stagehand/blob/main/packages/extension/controllers/pageController.ts"
click node_runtime "https://github.com/browserbase/stagehand/blob/main/packages/extension/runtime.ts"
click node_understudy "https://github.com/browserbase/stagehand/blob/main/packages/extension/understudy/page.ts"
click node_network "https://github.com/browserbase/stagehand/blob/main/packages/extension/understudy/networkManager.ts"
click node_protocol "https://github.com/browserbase/stagehand/blob/main/packages/protocol/types.ts"
click node_cli_commands "https://github.com/browserbase/stagehand/tree/main/packages/cli/src/commands"
click node_driver_session "https://github.com/browserbase/stagehand/blob/main/packages/cli/src/lib/driver/session-manager.ts"
click node_cloud_api "https://github.com/browserbase/stagehand/blob/main/packages/cli/src/lib/cloud/api.ts"
click node_sdk_go "https://github.com/browserbase/stagehand/blob/main/packages/sdk-go/stagehand.go"
click node_sdk_python "https://github.com/browserbase/stagehand/blob/main/packages/sdk-python/src/stagehand/browser.py"
click node_agent_integrations "https://github.com/browserbase/stagehand/tree/main/packages/integrations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stagehand_api,node_act,node_observe,node_extract,node_llm_service,node_llm_clients,node_agent,node_browser,node_cli toneBlue
class node_page_controller,node_runtime,node_understudy,node_network,node_protocol toneAmber
class node_cli_commands,node_driver_session,node_cloud_api toneMint
class node_sdk_go,node_sdk_python,node_agent_integrations toneRose
```

## Components

### Agent operations

- [Stagehand API](https://github.com/browserbase/stagehand/blob/main/packages/extension/controllers/stagehandController.ts): `packages/extension/controllers/stagehandController.ts`
- [Act service](https://github.com/browserbase/stagehand/blob/main/packages/extension/services/actService.ts): `packages/extension/services/actService.ts`
- [Observe service](https://github.com/browserbase/stagehand/blob/main/packages/extension/services/observeService.ts): `packages/extension/services/observeService.ts`
- [Extract service](https://github.com/browserbase/stagehand/blob/main/packages/extension/services/extractService.ts): `packages/extension/services/extractService.ts`
- [LLM dispatch](https://github.com/browserbase/stagehand/blob/main/packages/extension/services/llmService.ts): `packages/extension/services/llmService.ts`
- [LLM clients](https://github.com/browserbase/stagehand/blob/main/packages/extension/llm/LLMClient.ts): `packages/extension/llm/LLMClient.ts`

### Browser runtime

- [Page controller](https://github.com/browserbase/stagehand/blob/main/packages/extension/controllers/pageController.ts): `packages/extension/controllers/pageController.ts`
- [Extension runtime](https://github.com/browserbase/stagehand/blob/main/packages/extension/runtime.ts): `packages/extension/runtime.ts`
- [Browser control](https://github.com/browserbase/stagehand/blob/main/packages/extension/understudy/page.ts): `packages/extension/understudy/page.ts`
- [Network tracking](https://github.com/browserbase/stagehand/blob/main/packages/extension/understudy/networkManager.ts): `packages/extension/understudy/networkManager.ts`
- [Shared protocol](https://github.com/browserbase/stagehand/blob/main/packages/protocol/types.ts): `packages/protocol/types.ts`

### Developer tools

- [CLI commands](https://github.com/browserbase/stagehand/tree/main/packages/cli/src/commands): `packages/cli/src/commands`
- [Driver session](https://github.com/browserbase/stagehand/blob/main/packages/cli/src/lib/driver/session-manager.ts): `packages/cli/src/lib/driver/session-manager.ts`
- [Cloud API](https://github.com/browserbase/stagehand/blob/main/packages/cli/src/lib/cloud/api.ts): `packages/cli/src/lib/cloud/api.ts`

### SDKs and integrations

- [Go SDK](https://github.com/browserbase/stagehand/blob/main/packages/sdk-go/stagehand.go): `packages/sdk-go/stagehand.go`
- [Python SDK](https://github.com/browserbase/stagehand/blob/main/packages/sdk-python/src/stagehand/browser.py): `packages/sdk-python/src/stagehand/browser.py`
- [Agent integrations](https://github.com/browserbase/stagehand/tree/main/packages/integrations): `packages/integrations`

### Other components

- **Browser agent**
- **Browser**
- **CLI user**

## Connections

- Browser agent → Stagehand API: requests operation
- Stagehand API → Act service: dispatches act
- Stagehand API → Observe service: dispatches observe
- Stagehand API → Extract service: dispatches extract
- Act service → LLM dispatch: generates with model
- Observe service → LLM dispatch: generates with model
- Extract service → LLM dispatch: generates with model
- LLM dispatch → LLM clients: uses client
- Browser agent → Page controller: requests page control
- Page controller → Extension runtime: calls page operation
- Extension runtime → Browser control: uses browser control
- Browser control → Browser: controls
- Browser control → Network tracking: tracks network
- Stagehand API → Shared protocol: uses typed contracts
- CLI user → CLI commands: runs command
- CLI commands → Driver session: executes browser command
- Driver session → Browser: connects browser
- CLI commands → Cloud API: calls cloud operations
- Browser agent → Go SDK: uses SDK
- Browser agent → Python SDK: uses SDK
- Browser agent → Agent integrations: uses adapter
