Documentation
¶
Overview ¶
Package browseruse is the Go client for the Python browser-use sidecar (browseruse_server.py). The sidecar runs an autonomous browsing loop driven by browser-use: it connects to a browser over CDP, snapshots the page, asks the LLM what to do next, and acts — repeating until the goal is met.
The host (fairpeer) launches the browser itself (see internal/browserlaunch) and hands the sidecar a wsURL, so there is exactly one shared browser: the agent drives it, the in-app panel mirrors it. This client speaks the sidecar's localhost HTTP+SSE protocol:
GET /health -> { "ok": bool, "browser_use_available": bool }
POST /run -> SSE stream of step events (thought/action/screenshot/done/error)
POST /stop -> cancel the current run
The protocol shape mirrors Hyper-Extract's he_client.go so the two sidecars feel uniform in the codebase.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the HTTP client for the browser-use sidecar.
func (*Client) Health ¶
func (c *Client) Health(ctx context.Context) (*HealthReport, error)
Health checks whether the server is up and the browser-use library actually loaded (BrowserUseAvail). Callers should gate real runs on BrowserUseAvail, not just OK, otherwise a server with missing Python deps will 500.
func (*Client) RunStream ¶
RunStream posts a run request and returns a channel of step events. The channel closes when the stream ends (done/error) or the context is cancelled. The first non-nil error from the stream (e.g. HTTP 500) is delivered as a StepEvent with Type=EventError and Done=true, then the channel closes — this keeps the caller's loop uniform (it never has to handle a separate error return per event).
type EventType ¶
type EventType string
EventType discriminates a StepEvent.
const ( EventThought EventType = "thought" // the model's reasoning text EventAction EventType = "action" // a parsed action description EventScreenshot EventType = "screenshot" // a base64 frame (data URL) EventDone EventType = "done" // run finished (final summary) EventError EventType = "error" // run failed (final) )
type HealthReport ¶
type HealthReport struct {
OK bool `json:"ok"`
BrowserUseAvail bool `json:"browser_use_available"`
}
HealthReport is the /health response.
type RunRequest ¶
type RunRequest struct {
// Goal is the natural-language task ("fill the login form and submit").
Goal string `json:"goal"`
// URL is an optional starting URL to navigate to before the loop begins.
URL string `json:"url,omitempty"`
// CDPURL is REQUIRED: the ws:// endpoint of the browser to drive. The
// sidecar calls connect_over_cdp(this) — it never spawns its own browser,
// so the host and the sidecar share one instance.
CDPURL string `json:"cdp_url"`
// MaxSteps caps the agentic loop (default applied by the sidecar if 0).
MaxSteps int `json:"max_steps,omitempty"`
// Model is the LLM model NAME (no provider prefix) the sidecar should use
// (e.g. "gpt-4o", "claude-sonnet-4-5"). The host resolves the fairpeer
// "provider/model" ref down to this bare name before sending.
Model string `json:"model,omitempty"`
// ProviderKind selects the LLM client family: "openai" (OpenAI-compatible,
// the default — also covers azure-compatible via BaseURL) or "anthropic".
ProviderKind string `json:"provider_kind,omitempty"`
// BaseURL overrides the LLM provider endpoint (for OpenAI-compatible gateways
// like vendor gateways). Empty = the client's default (api.openai.com / anthropic).
BaseURL string `json:"base_url,omitempty"`
// APIKeyEnv names the environment variable holding the API key. The sidecar
// reads os.environ[APIKeyEnv] — the key is never sent over the wire, matching
// fairpeer's credentials-via-env model. Empty = fall back to the standard
// OPENAI_API_KEY / ANTHROPIC_API_KEY based on ProviderKind.
APIKeyEnv string `json:"api_key_env,omitempty"`
// Proxy is an optional proxy URL for the LLM client (not the browser —
// the browser proxy is set at launch time by browserlaunch).
Proxy string `json:"proxy,omitempty"`
}
RunRequest is the body of POST /run.
type StepEvent ¶
type StepEvent struct {
Type EventType `json:"type"`
Step int `json:"step,omitempty"`
Text string `json:"text,omitempty"` // thought/action/done/error text
Image string `json:"image,omitempty"` // data URL for screenshot events
URL string `json:"url,omitempty"` // current page URL, when known
Done bool `json:"done,omitempty"` // true on the terminal done/error event
}
StepEvent is one SSE-delivered event from the agentic loop.
Source Files