The AI Browser Automation Framework
Read the Docs
If you're looking for other languages, you can find them here
Stagehand is a browser automation framework used to control web browsers with natural language and code. By combining the power of AI with the precision of code, Stagehand makes web automation flexible, maintainable, and actually reliable.
Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language (and bridging the gap between the two) Stagehand is the natural choice for browser automations in production.
-
Choose when to write code vs. natural language: use AI when you want to navigate unfamiliar pages, and use code when you know exactly what you want to do.
-
Go from AI-driven to repeatable workflows: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens.
-
Write once, run forever: Stagehand's auto-caching combined with self-healing remembers previous actions, runs without LLM inference, and knows when to involve AI whenever the website changes and your automation breaks.
Install the package from NuGet:
dotnet add package StagehandThis library requires .NET Standard 2.0 or later.
This mirrors examples/remote_browser_playwright_example.cs.
using System;
using System.Collections.Generic;
using System.Text.Json;
using System.Threading.Tasks;
using Stagehand;
using Stagehand.Models.Sessions;
namespace Stagehand.Examples
{
class RemoteBrowserPlaywrightExample
{
static async Task Main(string[] args)
{
Env.Load();
// Uses environment variables: STAGEHAND_API_URL, BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY
StagehandClient client = new();
// Start a new remote Browserbase session (Playwright-backed)
var startResponse = await client.Sessions.Start(new SessionStartParams
{
ModelName = "anthropic/claude-sonnet-4-6",
Browser = new Browser { Type = Type.Browserbase }
});
Console.WriteLine($"Session started: {startResponse.Data.SessionID}");
var sessionID = startResponse.Data.SessionID;
// Navigate to Hacker News
await client.Sessions.Navigate(sessionID, new SessionNavigateParams
{
URL = "https://news.ycombinator.com"
});
Console.WriteLine("Navigated to Hacker News");
// Observe with SSE streaming to find possible actions
var observeResponse = await CollectStreamingResult<SessionObserveResponse>(
client.Sessions.ObserveStreaming(sessionID, new SessionObserveParams
{
Instruction = "find the link to view comments for the top post",
XStreamResponse = SessionObserveParamsXStreamResponse.True
}),
"observe"
);
if (observeResponse == null || observeResponse.Data.Result.Count == 0)
{
Console.WriteLine("No actions found");
await client.Sessions.End(sessionID, new SessionEndParams());
return;
}
// Use the first action
var action = observeResponse.Data.Result[0];
Console.WriteLine($"Acting on: {action.Description}");
// Pass the action to Act (streaming)
var actResponse = await CollectStreamingResult<SessionActResponse>(
client.Sessions.ActStreaming(sessionID, new SessionActParams
{
Input = new Input(new Action
{
Description = action.Description,
Selector = action.Selector,
Method = action.Method,
Arguments = action.Arguments
}),
XStreamResponse = XStreamResponse.True
}),
"act"
);
if (actResponse != null)
{
Console.WriteLine($"Act completed: {actResponse.Data.Result.Message}");
}
// Extract data from the page (streaming)
var extractResponse = await CollectStreamingResult<SessionExtractResponse>(
client.Sessions.ExtractStreaming(sessionID, new SessionExtractParams
{
Instruction = "extract the text of the top comment on this page",
Schema = new Dictionary<string, JsonElement>
{
["type"] = JsonSerializer.SerializeToElement("object"),
["properties"] = JsonSerializer.SerializeToElement(
new Dictionary<string, object>
{
["commentText"] = new Dictionary<string, string>
{
["type"] = "string",
["description"] = "The text content of the top comment"
},
["author"] = new Dictionary<string, string>
{
["type"] = "string",
["description"] = "The username of the comment author"
}
}
),
["required"] = JsonSerializer.SerializeToElement(new[] { "commentText" })
},
XStreamResponse = SessionExtractParamsXStreamResponse.True
}),
"extract"
);
if (extractResponse == null)
{
Console.WriteLine("No extract response received");
await client.Sessions.End(sessionID, new SessionEndParams());
return;
}
Console.WriteLine($"Extracted data: {extractResponse.Data.Result}");
var extractedData = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
extractResponse.Data.Result.ToString()
);
var author = extractedData != null && extractedData.ContainsKey("author")
? extractedData["author"].GetString()
: null;
if (string.IsNullOrWhiteSpace(author))
{
Console.WriteLine("No author found in extracted data");
await client.Sessions.End(sessionID, new SessionEndParams());
return;
}
Console.WriteLine($"Looking up profile for author: {author}");
// Use the Agent to find the author's profile (streaming)
var executeResponse = await CollectStreamingResult<SessionExecuteResponse>(
client.Sessions.ExecuteStreaming(sessionID, new SessionExecuteAgentParams
{
ExecuteOptions = new ExecuteOptions
{
Instruction =
$"Find any personal website, GitHub, LinkedIn, or other best profile URL for the Hacker News user '{author}'. " +
"Click on their username to go to their profile page and look for any links they have shared. " +
"Use Google Search with their username or other details from their profile if you dont find any direct links.",
MaxSteps = 15
},
AgentConfig = new AgentConfig
{
Model = new Model(new ModelConfig
{
ModelName = "anthropic/claude-opus-4-6",
APIKey = Environment.GetEnvironmentVariable("MODEL_API_KEY")
}),
Cua = false
},
XStreamResponse = SessionExecuteParamsXStreamResponse.True
}),
"agent"
);
if (executeResponse != null)
{
Console.WriteLine($"Agent completed: {executeResponse.Data.Result.Message}");
Console.WriteLine($"Agent success: {executeResponse.Data.Result.Success}");
Console.WriteLine($"Agent actions taken: {executeResponse.Data.Result.Actions.Count}");
}
// End the session to clean up resources
await client.Sessions.End(sessionID, new SessionEndParams());
Console.WriteLine("Session ended");
}
static async Task<T?> CollectStreamingResult<T>(
IAsyncEnumerable<StreamEvent> stream,
string label
)
{
T? result = default;
await foreach (var streamEvent in stream)
{
PrintStreamEvent(label, streamEvent);
if (!TryGetFinishedResult(streamEvent, out var resultElement))
{
continue;
}
try
{
result = JsonSerializer.Deserialize<T>(resultElement.GetRawText());
}
catch (JsonException)
{
Console.WriteLine($"[{label}] Warning: unable to parse finished result.");
}
}
return result;
}
static bool TryGetFinishedResult(StreamEvent streamEvent, out JsonElement resultElement)
{
resultElement = default;
if (
streamEvent.Data.TryPickStreamEventSystemDataOutput(out var systemData)
&& systemData.Result is { } result
&& systemData.Status.Value() == Status.Finished
)
{
resultElement = result;
return true;
}
return false;
}
static void PrintStreamEvent(string label, StreamEvent streamEvent)
{
if (streamEvent.Data.TryPickStreamEventLogDataOutput(out var logData))
{
Console.WriteLine($"[{label}] log: {logData.Message}");
return;
}
if (streamEvent.Data.TryPickStreamEventSystemDataOutput(out var systemData))
{
var status = systemData.Status.Value();
var error = string.IsNullOrWhiteSpace(systemData.Error)
? string.Empty
: $" error={systemData.Error}";
Console.WriteLine($"[{label}] system: {status}{error}");
return;
}
Console.WriteLine($"[{label}] event: {streamEvent.Data.Json}");
}
}
}Set your environment variables (from examples/.env.example):
STAGEHAND_API_URLMODEL_API_KEYBROWSERBASE_API_KEYBROWSERBASE_PROJECT_ID
cp examples/.env.example examples/.env
# Edit examples/.env with your credentials.The examples load examples/.env automatically.
The examples live at:
examples/remote_browser_playwright_example.csexamples/local_browser_playwright_example.cs
Multiregion support: see examples/local_server_multiregion_browser_example.cs.
Install the example dependencies:
examples/remote_browser_playwright_example.cs:Microsoft.Playwright+ Playwright browsersexamples/local_browser_playwright_example.cs:Microsoft.Playwright+ Playwright browsers
dotnet build examples
pwsh examples/bin/Debug/net8.0/playwright.ps1 install
# or: bash examples/bin/Debug/net8.0/playwright.sh installRun the example:
dotnet run --project examples -- remoteTo run the local Playwright example:
dotnet run --project examples -- localConfigure the client using environment variables:
using Stagehand;
// Configured using the BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY and STAGEHAND_BASE_URL environment variables
StagehandClient client = new();Or manually:
using Stagehand;
StagehandClient client = new()
{
BrowserbaseApiKey = "My Browserbase API Key",
BrowserbaseProjectID = "My Browserbase Project ID",
ModelApiKey = "My Model API Key",
};Or using a combination of the two approaches.
See this table for the available options:
| Property | Environment variable | Required | Default value |
|---|---|---|---|
BrowserbaseApiKey |
BROWSERBASE_API_KEY |
true | - |
BrowserbaseProjectID |
BROWSERBASE_PROJECT_ID |
true | - |
ModelApiKey |
MODEL_API_KEY |
true | - |
BaseUrl |
STAGEHAND_BASE_URL |
true | "https://api.stagehand.browserbase.com" |
To temporarily use a modified client configuration, while reusing the same connection and thread pools, call WithOptions on any client or service:
using System;
var response = await client
.WithOptions(options =>
options with
{
BaseUrl = "https://example.com",
Timeout = TimeSpan.FromSeconds(42),
}
)
.Sessions.Start(parameters);
Console.WriteLine(response);Using a with expression makes it easy to construct the modified options.
The WithOptions method does not affect the original client or service.
To send a request to the Stagehand API, build an instance of some Params class and pass it to the corresponding client method. When the response is received, it will be deserialized into an instance of a C# class.
For example, client.Sessions.Act should be called with an instance of SessionActParams, and it will return an instance of Task<SessionActResponse>.
The SDK defines methods that return response "chunk" streams, where each chunk can be individually processed as soon as it arrives instead of waiting on the full response. Streaming methods generally correspond to SSE or JSONL responses.
Some of these methods may have streaming and non-streaming variants, but a streaming method will always have a Streaming suffix in its name, even if it doesn't have a non-streaming variant.
These streaming methods return IAsyncEnumerable:
using System;
using Stagehand.Models.Sessions;
SessionActParams parameters = new()
{
ID = "00000000-your-session-id-000000000000",
Input = "click the first link on the page",
};
await foreach (var response in client.Sessions.ActStreaming(parameters))
{
Console.WriteLine(response);
}The SDK defines methods that deserialize responses into instances of C# classes. However, these methods don't provide access to the response headers, status code, or the raw response body.
To access this data, prefix any HTTP method call on a client or service with WithRawResponse:
var response = await client.WithRawResponse.Sessions.Start(parameters);
var statusCode = response.StatusCode;
var headers = response.Headers;The raw HttpResponseMessage can also be accessed through the RawMessage property.
For non-streaming responses, you can deserialize the response into an instance of a C# class if needed:
using System;
using Stagehand.Models.Sessions;
var response = await client.WithRawResponse.Sessions.Start(parameters);
SessionStartResponse deserialized = await response.Deserialize();
Console.WriteLine(deserialized);For streaming responses, you can deserialize the response to an IAsyncEnumerable if needed:
using System;
var response = await client.WithRawResponse.Sessions.ActStreaming(parameters);
await foreach (var item in response.Enumerate())
{
Console.WriteLine(item);
}The SDK throws custom unchecked exception types:
StagehandApiException: Base class for API errors. See this table for which exception subclass is thrown for each HTTP status code:
| Status | Exception |
|---|---|
| 400 | StagehandBadRequestException |
| 401 | StagehandUnauthorizedException |
| 403 | StagehandForbiddenException |
| 404 | StagehandNotFoundException |
| 422 | StagehandUnprocessableEntityException |
| 429 | StagehandRateLimitException |
| 5xx | Stagehand5xxException |
| others | StagehandUnexpectedStatusCodeException |
Additionally, all 4xx errors inherit from Stagehand4xxException.
-
StagehandSseException: thrown for errors encountered during SSE streaming after a successful initial HTTP response. -
StagehandIOException: I/O networking errors. -
StagehandInvalidDataException: Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response. -
StagehandException: Base class for all exceptions.
The SDK automatically retries 2 times by default, with a short exponential backoff between requests.
Only the following error types are retried:
- Connection errors (for example, due to a network connectivity problem)
- 408 Request Timeout
- 409 Conflict
- 429 Rate Limit
- 5xx Internal
The API may also explicitly instruct the SDK to retry or not retry a request.
To set a custom number of retries, configure the client using the MaxRetries method:
using Stagehand;
StagehandClient client = new() { MaxRetries = 3 };Or configure a single method call using WithOptions:
using System;
var response = await client
.WithOptions(options =>
options with { MaxRetries = 3 }
)
.Sessions.Start(parameters);
Console.WriteLine(response);Requests time out after 1 minute by default.
To set a custom timeout, configure the client using the Timeout option:
using System;
using Stagehand;
StagehandClient client = new() { Timeout = TimeSpan.FromSeconds(42) };Or configure a single method call using WithOptions:
using System;
var response = await client
.WithOptions(options =>
options with { Timeout = TimeSpan.FromSeconds(42) }
)
.Sessions.Start(parameters);
Console.WriteLine(response);To route requests through a proxy, configure your client with a custom HttpClient:
using System.Net;
using System.Net.Http;
using Stagehand;
var httpClient = new HttpClient
(
new HttpClientHandler
{
Proxy = new WebProxy("https://example.com:8080")
}
);
StagehandClient client = new() { HttpClient = httpClient };The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.
To set undocumented parameters, a constructor exists that accepts dictionaries for additional header, query, and body values. If the method type doesn't support request bodies (e.g. GET requests), the constructor will only accept a header and query dictionary.
using System.Collections.Generic;
using System.Text.Json;
using Stagehand.Models.Sessions;
SessionActParams parameters = new
(
rawHeaderData: new Dictionary<string, JsonElement>()
{
{ "Custom-Header", JsonSerializer.SerializeToElement(42) }
},
rawQueryData: new Dictionary<string, JsonElement>()
{
{ "custom_query_param", JsonSerializer.SerializeToElement(42) }
},
rawBodyData: new Dictionary<string, JsonElement>()
{
{ "custom_body_param", JsonSerializer.SerializeToElement(42) }
}
)
{
// Documented properties can still be added here.
// In case of conflict, these parameters take precedence over the custom parameters.
ID = "c4dbf3a9-9a58-4b22-8a1c-9f20f9f9e123"
};The raw parameters can also be accessed through the RawHeaderData, RawQueryData, and RawBodyData (if available) properties.
This can also be used to set a documented parameter to an undocumented or not yet supported value, as long as the parameter is optional. If the parameter is required, omitting its init property will result in a compile-time error. To work around this, the FromRawUnchecked method can be used:
using System.Collections.Generic;
using System.Text.Json;
using Stagehand.Models.Sessions;
var parameters = SessionActParams.FromRawUnchecked
(
rawHeaderData: new Dictionary<string, JsonElement>(),
rawQueryData: new Dictionary<string, JsonElement>(),
rawBodyData: new Dictionary<string, JsonElement>
{
{
"input",
JsonSerializer.SerializeToElement("custom value")
}
}
);Undocumented properties, or undocumented values of documented properties, on nested parameters can be set similarly, using a dictionary in the constructor of the nested parameter.
using System.Collections.Generic;
using System.Text.Json;
using Stagehand.Models.Sessions;
SessionActParams parameters = new()
{
Options = new
(
new Dictionary<string, JsonElement>
{
{ "custom_nested_param", JsonSerializer.SerializeToElement(42) }
}
)
};Required properties on the nested parameter can also be changed or omitted using the FromRawUnchecked method:
using System.Collections.Generic;
using System.Text.Json;
using Stagehand.Models.Sessions;
SessionActParams parameters = new()
{
Options = Options.FromRawUnchecked
(
new Dictionary<string, JsonElement>
{
{ "required_property", JsonSerializer.SerializeToElement("custom value") }
}
)
};To access undocumented response properties, the RawData property can be used:
using System.Text.Json;
var response = client.Sessions.Act(parameters)
if (response.RawData.TryGetValue("my_custom_key", out JsonElement value))
{
// Do something with `value`
}RawData is a IReadonlyDictionary<string, JsonElement>. It holds the full data received from the API server.
In rare cases, the API may return a response that doesn't match the expected type. For example, the SDK may expect a property to contain a string, but the API could return something else.
By default, the SDK will not throw an exception in this case. It will throw StagehandInvalidDataException only if you directly access the property.
If you would prefer to check that the response is completely well-typed upfront, then either call Validate:
var response = client.Sessions.Act(parameters);
response.Validate();Or configure the client using the ResponseValidation option:
using Stagehand;
StagehandClient client = new() { ResponseValidation = true };Or configure a single method call using WithOptions:
using System;
var response = await client
.WithOptions(options =>
options with { ResponseValidation = true }
)
.Sessions.Act(parameters);
Console.WriteLine(response);This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:
- Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals.)
- Changes that we do not expect to impact the vast majority of users in practice.
We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
We are keen for your feedback; please open an issue with questions, bugs, or suggestions.