browser

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxSearchesPerRequest = 2

MaxSearchesPerRequest is the hard limit on browser_search calls per request. The agent gets one initial search plus one reformulation (total 2). The 3rd attempt is blocked with a structured stop response.

Variables

View Source 
var ErrBlockedURL = errors.New("URL targets a blocked internal/private network address")

ErrBlockedURL is returned when a URL targets an internal or private network address.

View Source 
var ErrBrowserPanic = errors.New("browser panic recovered")

ErrBrowserPanic is returned when a rod/CDP panic is recovered.

View Source 
var ErrEvalBlockedP2P = errors.New("eval action is not permitted for remote peer requests")

ErrEvalBlockedP2P is returned when eval is attempted from a P2P peer context.

View Source 
var ErrSearchLimitReached = errors.New(
	"browser_search is no longer available: search limit (2) reached — " +
		"present your existing results to the user, do NOT call browser_search again",
)

ErrSearchLimitReached is returned when browser_search exceeds MaxSearchesPerRequest. The error message instructs the model to stop searching and use existing results.

Functions

func BuildTools added in v0.7.0 

func BuildTools(sm *SessionManager) []*agent.Tool

BuildTools creates browser agent tools backed by the given SessionManager.

func ValidateURLForP2P added in v0.7.0 

func ValidateURLForP2P(rawURL string) error

ValidateURLForP2P checks that a URL is safe for navigation in a P2P context. It blocks file:// schemes and URLs that resolve to internal/private network addresses.

func WithRequestState added in v0.7.0 

func WithRequestState(ctx context.Context, state *RequestState) context.Context

Types

type ActionCandidate added in v0.7.0 

type ActionCandidate struct {
	Selector    string `json:"selector"`
	Tag         string `json:"tag"`
	Type        string `json:"type,omitempty"`
	Role        string `json:"role,omitempty"`
	Text        string `json:"text,omitempty"`
	Href        string `json:"href,omitempty"`
	Placeholder string `json:"placeholder,omitempty"`
}

ActionCandidate is an actionable element discovered on the current page.

type ArticleResult added in v0.7.0 

type ArticleResult struct {
	PageType string   `json:"pageType"`
	Title    string   `json:"title"`
	URL      string   `json:"url"`
	Headings []string `json:"headings,omitempty"`
	Content  string   `json:"content"`
	Empty    bool     `json:"empty"`
}

ArticleResult contains structured article-like content from the current page.

type Config 

type Config struct {
	Headless       bool
	BrowserBin     string
	SessionTimeout time.Duration
}

Config holds browser tool configuration

type ElementInfo 

type ElementInfo struct {
	TagName   string `json:"tagName"`
	ID        string `json:"id,omitempty"`
	ClassName string `json:"className,omitempty"`
	InnerText string `json:"innerText,omitempty"`
	InnerHTML string `json:"innerHTML,omitempty"`
	Href      string `json:"href,omitempty"`
	Value     string `json:"value,omitempty"`
}

ElementInfo holds element information

type LinksResult added in v0.7.0 

type LinksResult struct {
	Title string     `json:"title"`
	URL   string     `json:"url"`
	Links []PageLink `json:"links,omitempty"`
}

LinksResult contains extracted links from the current page. 

type PageLink struct {
	Text     string `json:"text"`
	URL      string `json:"url"`
	Selector string `json:"selector,omitempty"`
}

PageLink is a structured link extracted from the current page.

type PageSnapshot added in v0.7.0 

type PageSnapshot struct {
	PageType      string            `json:"pageType"`
	Title         string            `json:"title"`
	URL           string            `json:"url"`
	Snippet       string            `json:"snippet"`
	ResultCount   int               `json:"resultCount"`
	Empty         bool              `json:"empty"`
	Headings      []string          `json:"headings,omitempty"`
	Links         []PageLink        `json:"links,omitempty"`
	Actions       []ActionCandidate `json:"actions,omitempty"`
	SearchResults []SearchResult    `json:"searchResults,omitempty"`
}

PageSnapshot is a structured summary of the current page.

type RequestState added in v0.7.0 

type RequestState struct {
	ID string
	// contains filtered or unexported fields
}

RequestState tracks browser-search churn for a single agent request.

func NewRequestState added in v0.7.0 

func NewRequestState() *RequestState

func RequestStateFromContext added in v0.7.0 

func RequestStateFromContext(ctx context.Context) *RequestState

func (*RequestState) CurrentURL added in v0.7.0 

func (s *RequestState) CurrentURL() string

func (*RequestState) IsLimitReached added in v0.7.0 

func (s *RequestState) IsLimitReached() bool

IsLimitReached reports whether the search limit has already been reached without recording a new search attempt.

func (*RequestState) RecordSearch added in v0.7.0 

func (s *RequestState) RecordSearch(query, currentURL string) (count int, queries []string, shouldWarn bool, limitReached bool)

type ScreenshotResult 

type ScreenshotResult struct {
	Data     string `json:"data"` // base64 encoded
	MimeType string `json:"mimeType"`
	Width    int    `json:"width"`
	Height   int    `json:"height"`
}

ScreenshotResult holds screenshot data

type SearchResponse added in v0.7.0 

type SearchResponse struct {
	PageType     string         `json:"pageType"`
	Query        string         `json:"query,omitempty"`
	Title        string         `json:"title"`
	URL          string         `json:"url"`
	ResultCount  int            `json:"resultCount"`
	Empty        bool           `json:"empty"`
	Results      []SearchResult `json:"results,omitempty"`
	LimitReached bool           `json:"limitReached,omitempty"`
	NextStep     string         `json:"nextStep,omitempty"`
	Warning      string         `json:"warning,omitempty"`
}

SearchResponse is a structured response for browser-based web search.

type SearchResult added in v0.7.0 

type SearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"snippet,omitempty"`
}

SearchResult is a structured web search result item.

type Session 

type Session struct {
	ID        string
	Page      *rod.Page
	CreatedAt time.Time
}

Session represents a browser session with a page

type SessionManager 

type SessionManager struct {
	// contains filtered or unexported fields
}

SessionManager provides implicit session management. It auto-creates a session on first use and reuses it for subsequent calls.

func NewSessionManager 

func NewSessionManager(tool *Tool) *SessionManager

NewSessionManager creates a SessionManager that wraps the given Tool.

func (*SessionManager) Close 

func (sm *SessionManager) Close() error

Close closes the underlying browser tool and clears the session.

func (*SessionManager) EnsureSession 

func (sm *SessionManager) EnsureSession() (string, error)

EnsureSession returns the active session ID, creating one if none exists. On ErrBrowserPanic, it closes and reconnects once before returning an error.

func (*SessionManager) Tool 

func (sm *SessionManager) Tool() *Tool

Tool returns the underlying browser Tool.

type Tool 

type Tool struct {
	// contains filtered or unexported fields
}

Tool provides browser automation

func New 

func New(cfg Config) (*Tool, error)

New creates a new browser tool

func (*Tool) Click 

func (t *Tool) Click(ctx context.Context, sessionID, selector string) error

Click clicks on an element

func (*Tool) Close 

func (t *Tool) Close() error

Close closes all sessions and the browser

func (*Tool) CloseSession 

func (t *Tool) CloseSession(sessionID string) error

CloseSession closes a browser session

func (*Tool) CurrentURL added in v0.7.0 

func (t *Tool) CurrentURL(sessionID string) (string, error)

CurrentURL returns the current page URL for the given session.

func (*Tool) Eval 

func (t *Tool) Eval(sessionID, script string) (interface{}, error)

Eval executes JavaScript on the page

func (*Tool) Extract added in v0.7.0 

func (t *Tool) Extract(sessionID, mode string, limit int) (interface{}, error)

Extract returns structured data from the current page.

func (*Tool) GetElementInfo 

func (t *Tool) GetElementInfo(sessionID, selector string) (*ElementInfo, error)

GetElementInfo gets information about an element

func (*Tool) GetSnapshot 

func (t *Tool) GetSnapshot(sessionID string) (map[string]string, error)

GetSnapshot returns basic page info (title and snippet)

func (*Tool) GetText 

func (t *Tool) GetText(sessionID, selector string) (string, error)

GetText gets text content of an element

func (*Tool) HasSession 

func (t *Tool) HasSession(sessionID string) bool

HasSession reports whether a session with the given ID exists.

func (*Tool) Navigate 

func (t *Tool) Navigate(ctx context.Context, sessionID, url string) error

Navigate navigates to a URL

func (*Tool) NewSession 

func (t *Tool) NewSession() (string, error)

NewSession creates a new browser session

func (*Tool) Observe added in v0.7.0 

func (t *Tool) Observe(sessionID string, limit int) ([]ActionCandidate, error)

Observe returns actionable elements from the current page.

func (*Tool) Screenshot 

func (t *Tool) Screenshot(sessionID string, fullPage bool) (*ScreenshotResult, error)

Screenshot captures a screenshot

func (*Tool) Search added in v0.7.0 

func (t *Tool) Search(ctx context.Context, sessionID, query string, limit int) (*SearchResponse, error)

Search performs browser-native web search and returns structured results.

func (*Tool) Snapshot added in v0.7.0 

func (t *Tool) Snapshot(sessionID string, linkLimit, actionLimit int) (*PageSnapshot, error)

Snapshot returns a structured summary of the current page.

func (*Tool) Type 

func (t *Tool) Type(ctx context.Context, sessionID, selector, text string) error

Type types text into an element

func (*Tool) WaitForSelector 

func (t *Tool) WaitForSelector(ctx context.Context, sessionID, selector string, timeout time.Duration) error

WaitForSelector waits for an element to appear

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.