Skip to content

armgit / ax

Public Imported from GitHub
0

Agent Executor (AX) is Google's open agentic orchestration runtime

Go

Introduce browser local agent (#44)

Jaana Dogan9234a2f035c6
diff --git a/go.mod b/go.mod
index 7316b1d..2784d6a 100644
--- a/go.mod
+++ b/go.mod
@@ -3,8 +3,8 @@ module github.com/google/gar
go 1.24.0
require (
+ github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0
github.com/charmbracelet/huh v0.8.0
- github.com/charmbracelet/huh/spinner v0.0.0-20260216111231-bffc99a26329
github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
github.com/google/uuid v1.6.0
github.com/spf13/cobra v1.10.2
@@ -12,12 +12,14 @@ require (
google.golang.org/grpc v1.78.0
google.golang.org/protobuf v1.36.11
gopkg.in/yaml.v3 v3.0.1
+ mvdan.cc/xurls/v2 v2.6.0
)
require (
cloud.google.com/go v0.116.0 // indirect
cloud.google.com/go/auth v0.9.3 // indirect
cloud.google.com/go/compute/metadata v0.9.0 // indirect
+ github.com/JohannesKaufmann/dom v0.2.0 // indirect
github.com/atotto/clipboard v0.1.4 // indirect
github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
github.com/catppuccin/go v0.3.0 // indirect
@@ -28,6 +30,8 @@ require (
github.com/charmbracelet/x/cellbuf v0.0.13 // indirect
github.com/charmbracelet/x/exp/strings v0.0.0-20240722160745-212f7b056ed0 // indirect
github.com/charmbracelet/x/term v0.2.1 // indirect
+ github.com/clipperhouse/stringish v0.1.1 // indirect
+ github.com/clipperhouse/uax29/v2 v2.3.0 // indirect
github.com/dustin/go-humanize v1.0.1 // indirect
github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
@@ -37,10 +41,10 @@ require (
github.com/gorilla/websocket v1.5.3 // indirect
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/kr/pretty v0.3.1 // indirect
- github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
+ github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
github.com/mattn/go-localereader v0.0.1 // indirect
- github.com/mattn/go-runewidth v0.0.16 // indirect
+ github.com/mattn/go-runewidth v0.0.19 // indirect
github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
github.com/muesli/cancelreader v0.2.2 // indirect
diff --git a/go.sum b/go.sum
index 7951ffe..b9fba2d 100644
--- a/go.sum
+++ b/go.sum
@@ -6,6 +6,10 @@ cloud.google.com/go/auth v0.9.3/go.mod h1:7z6VY+7h3KUdRov5F1i8NDP5ZzWKYmEPO842Bg
cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
+github.com/JohannesKaufmann/dom v0.2.0 h1:1bragmEb19K8lHAqgFgqCpiPCFEZMTXzOIEjuxkUfLQ=
+github.com/JohannesKaufmann/dom v0.2.0/go.mod h1:57iSUl5RKric4bUkgos4zu6Xt5LMHUnw3TF1l5CbGZo=
+github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0 h1:mklaPbT4f/EiDr1Q+zPrEt9lgKAkVrIBtWf33d9GpVA=
+github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0/go.mod h1:D56Cl9r8M5i3UwAchE+LlLc5hPN3kJtdZNVJn06lSHU=
github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
@@ -25,8 +29,6 @@ github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc h1:4p
github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc/go.mod h1:X4/0JoqgTIPSFcRA/P6INZzIuyqdFY5rm8tb41s9okk=
github.com/charmbracelet/huh v0.8.0 h1:Xz/Pm2h64cXQZn/Jvele4J3r7DDiqFCNIVteYukxDvY=
github.com/charmbracelet/huh v0.8.0/go.mod h1:5YVc+SlZ1IhQALxRPpkGwwEKftN/+OlJlnJYlDRFqN4=
-github.com/charmbracelet/huh/spinner v0.0.0-20260216111231-bffc99a26329 h1:0qvbszNGxDNsLfktnN6eFngemvxTzKWyL2ER1AEmawM=
-github.com/charmbracelet/huh/spinner v0.0.0-20260216111231-bffc99a26329/go.mod h1:OMqKat/mm9a/qOnpuNOPyYO9bPzRNnmzLnRZT5KYltg=
github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 h1:ZR7e0ro+SZZiIZD7msJyA+NjkCNNavuiPBLgerbOziE=
github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834/go.mod h1:aKC/t2arECF6rNOnaKaVU6y4t4ZeHQzqfxedE/VkVhA=
github.com/charmbracelet/x/ansi v0.10.1 h1:rL3Koar5XvX0pHGfovN03f5cxLbCF2YvLeyz7D2jVDQ=
@@ -48,6 +50,10 @@ github.com/charmbracelet/x/termios v0.1.1/go.mod h1:rB7fnv1TgOPOyyKRJ9o+AsTU/vK5
github.com/charmbracelet/x/xpty v0.1.2 h1:Pqmu4TEJ8KeA9uSkISKMU3f+C1F6OGBn8ABuGlqCbtI=
github.com/charmbracelet/x/xpty v0.1.2/go.mod h1:XK2Z0id5rtLWcpeNiMYBccNNBrP2IJnzHI0Lq13Xzq4=
github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
+github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
+github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
+github.com/clipperhouse/uax29/v2 v2.3.0 h1:SNdx9DVUqMoBuBoW3iLOj4FQv3dN5mDtuqwuhIGpJy4=
+github.com/clipperhouse/uax29/v2 v2.3.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
@@ -109,14 +115,14 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
-github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
+github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
-github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc=
-github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
+github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
+github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4=
github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE=
github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
@@ -126,15 +132,19 @@ github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIf
github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
-github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/sebdah/goldie/v2 v2.8.0 h1:dZb9wR8q5++oplmEiJT+U/5KyotVD+HNGCAc5gNr8rc=
+github.com/sebdah/goldie/v2 v2.8.0/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
+github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
+github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
@@ -148,6 +158,8 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
+github.com/yuin/goldmark v1.7.13 h1:GPddIs617DnBLFFVJFgpo1aBfe/4xcvMc3SB5t/D0pA=
+github.com/yuin/goldmark v1.7.13/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
go.opencensus.io v0.24.0 h1:y73uSU6J157QMP2kn2r30vwW1A2W2WFwSCGnAVxeaD0=
go.opencensus.io v0.24.0/go.mod h1:vNK8G9p7aAivkbmorf4v+7Hgx+Zs0yY+0fOtgBfjQKo=
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
@@ -242,3 +254,5 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
+mvdan.cc/xurls/v2 v2.6.0 h1:3NTZpeTxYVWNSokW3MKeyVkz/j7uYXYiMtXRUfmjbgI=
+mvdan.cc/xurls/v2 v2.6.0/go.mod h1:bCvEZ1XvdA6wDnxY7jPPjEmigDtvtvPXAD/Exa9IMSk=
diff --git a/internal/controller/controller.go b/internal/controller/controller.go
index 0125b2c..e7ea16f 100644
--- a/internal/controller/controller.go
+++ b/internal/controller/controller.go
@@ -25,6 +25,7 @@ import (
"github.com/google/gar/agent"
"github.com/google/gar/internal/config"
"github.com/google/gar/internal/eventlog"
+ "github.com/google/gar/internal/localagent/browser"
"github.com/google/gar/proto"
)
@@ -83,6 +84,9 @@ func New(ctx context.Context, config Config) (*Controller, error) {
if err != nil {
return nil, fmt.Errorf("failed to create registry: %w", err)
}
+ if err := registerDefaultLocalAgents(registry); err != nil {
+ return nil, fmt.Errorf("failed to register default local agents: %w", err)
+ }
// Determine plan function
// If no planner builder is provided, use the default Gemini planner.
@@ -116,6 +120,15 @@ func New(ctx context.Context, config Config) (*Controller, error) {
}, nil
}
+func registerDefaultLocalAgents(r *Registry) error {
+ return r.RegisterLocal(config.LocalAgentConfig{
+ ID: "browser",
+ Name: "Browser Agent",
+ Description: "An agent that can browse the a given URL. The agent returns the content of the page as markdown.",
+ Agent: browser.NewAgent(),
+ })
+}
+
// TriggerSession triggers a new agentic loop session or resumes an existing one.
// If sessionID is empty, a UUID will be generated.
// If the session already exists, it will be resumed with optional new inputs.
diff --git a/internal/controller/session.go b/internal/controller/session.go
index 2523828..07019ea 100644
--- a/internal/controller/session.go
+++ b/internal/controller/session.go
@@ -256,7 +256,7 @@ func (s *Session) reconstructState(events []*proto.Event) error {
case *proto.Event_SessionStateEvent:
s.state = x.SessionStateEvent.State
case *proto.Event_HandoffEvent:
- return fmt.Errorf("HandoffEvent is not yet supported")
+ // TODO: Visit this section when resuming the waiting agents.
case *proto.Event_ContentEvent:
s.messageHistory = append(s.messageHistory, x.ContentEvent.Contents...)
default:
diff --git a/internal/localagent/browser/agent.go b/internal/localagent/browser/agent.go
new file mode 100644
index 0000000..3c8ea0d
--- /dev/null
+++ b/internal/localagent/browser/agent.go
@@ -0,0 +1,151 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package browser provides an agent that fetches and converts web content to text.
+package browser
+
+import (
+ "context"
+ "fmt"
+ "net/url"
+ "strings"
+
+ "github.com/google/gar/agent"
+ "github.com/google/gar/proto"
+ "github.com/google/uuid"
+ "mvdan.cc/xurls/v2"
+)
+
+// BrowserAgent takes a URL and retrieves its web contents.
+// It fetches HTML pages and converts them to plain text format.
+type BrowserAgent struct {
+ fetcher *webFetcher
+}
+
+// NewAgent creates a new browser agent with default HTTP client settings.
+func NewAgent() *BrowserAgent {
+ return &BrowserAgent{
+ fetcher: newWebFetcher(nil),
+ }
+}
+
+var _ agent.Agent = (*BrowserAgent)(nil)
+
+// Process handles incoming requests containing URLs to fetch.
+// It extracts the URL from the request, fetches the page content,
+// and streams the result back through the handler.
+func (a *BrowserAgent) Process(ctx context.Context, sessionID string, incoming *proto.ProcessRequest, handler agent.OutputHandler) error {
+ text := readUserText(incoming)
+ if text == "" {
+ return a.emit(handler, "Please provide a URL to fetch")
+ }
+
+ q, err := parseNaturalText(text)
+ if err != nil {
+ return a.emit(handler, "Invalid URL: "+err.Error())
+ }
+
+ page, err := a.fetcher.Fetch(ctx, q)
+ if err != nil {
+ return a.emit(handler, "Failed to fetch: "+err.Error())
+ }
+
+ body := page.Body
+ if body == "" {
+ body = "(empty body)"
+ }
+ return a.emit(handler,
+ fmt.Sprintf("Fetched: %s\nStatus: %d\nContent-Type: %s\n\n%s", page.URL, page.StatusCode, page.ContentType, body))
+}
+
+// HealthCheck verifies the agent is operational.
+func (a *BrowserAgent) HealthCheck(ctx context.Context) error {
+ return nil
+}
+
+// Close cleans up any resources held by the agent.
+func (a *BrowserAgent) Close() error {
+ return nil
+}
+
+// emit is a helper that sends a text response through the output handler.
+// It generates a new UUID for each response checkpoint.
+func (a *BrowserAgent) emit(handler agent.OutputHandler, text string) error {
+ return handler(&proto.ProcessResponse{
+ CheckpointId: uuid.New().String(),
+ Contents: []*proto.Content{
+ {
+ Role: "assistant",
+ Content: &proto.Content_Text{Text: &proto.TextContent{Text: text}},
+ },
+ },
+ })
+}
+
+// readUserText extracts the most recent text content from the request.
+// It searches backwards through the contents to find the latest user message.
+func readUserText(incoming *proto.ProcessRequest) string {
+ for i := len(incoming.Contents) - 1; i >= 0; i-- {
+ if c := incoming.Contents[i]; c != nil {
+ if t := c.GetText(); t != nil {
+ if txt := strings.TrimSpace(t.Text); txt != "" {
+ return txt
+ }
+ }
+ }
+ }
+ return ""
+}
+
+// parseNaturalText parses input into a URL-only browser query.
+func parseNaturalText(input string) (Query, error) {
+ relaxedRegex := xurls.Relaxed()
+ relaxedURLs := relaxedRegex.FindAllString(input, -1)
+ if len(relaxedURLs) > 0 {
+ url := relaxedURLs[len(relaxedURLs)-1]
+ if !strings.HasPrefix(url, "http") {
+ url = "https://" + url
+ }
+ return Query{URL: url}, nil
+ }
+
+ input = strings.TrimSpace(input)
+ if input == "" {
+ return Query{}, fmt.Errorf("empty request")
+ }
+ u, err := parseURL(input)
+ if err != nil {
+ return Query{}, err
+ }
+ return Query{URL: u}, nil
+}
+
+// parseURL validates and normalizes a URL string.
+// It adds https:// scheme if missing and validates the URL format.
+func parseURL(s string) (string, error) {
+ if !strings.Contains(s, "://") {
+ s = "https://" + s
+ }
+ u, err := url.ParseRequestURI(s)
+ if err != nil {
+ return "", fmt.Errorf("invalid URL")
+ }
+ if u.Scheme != "http" && u.Scheme != "https" {
+ return "", fmt.Errorf("scheme must be http or https")
+ }
+ if u.Host == "" {
+ return "", fmt.Errorf("missing host")
+ }
+ return u.String(), nil
+}
diff --git a/internal/localagent/browser/agent_test.go b/internal/localagent/browser/agent_test.go
new file mode 100644
index 0000000..1cf8344
--- /dev/null
+++ b/internal/localagent/browser/agent_test.go
@@ -0,0 +1,84 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package browser
+
+import (
+ "context"
+ "io"
+ "net/http"
+ "strings"
+ "testing"
+
+ "github.com/google/gar/proto"
+)
+
+func testFetcher(t *testing.T) *webFetcher {
+ t.Helper()
+ client := newMockClient(func(r *http.Request) (*http.Response, error) {
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Body: io.NopCloser(strings.NewReader("<html><body>Sample content</body></html>")),
+ Header: http.Header{"Content-Type": []string{"text/html"}},
+ }, nil
+ })
+ return newWebFetcher(client)
+}
+
+func newTestAgent(t *testing.T) *BrowserAgent {
+ t.Helper()
+ return &BrowserAgent{
+ fetcher: testFetcher(t),
+ }
+}
+
+func TestBrowserAgentProcess(t *testing.T) {
+ a := newTestAgent(t)
+
+ var chunks []string
+ err := a.Process(context.Background(), "s1", &proto.ProcessRequest{
+ CheckpointId: "cp1",
+ Contents: []*proto.Content{
+ {
+ Role: "user",
+ Content: &proto.Content_Text{Text: &proto.TextContent{Text: "Check out this URL: example.test/page"}},
+ },
+ },
+ }, func(out *proto.ProcessResponse) error {
+ if out.CheckpointId == "" {
+ t.Fatalf("checkpoint ID should not be empty")
+ }
+ if len(out.Contents) == 0 || out.Contents[0].GetText() == nil {
+ t.Fatalf("missing text content")
+ }
+ chunks = append(chunks, out.Contents[0].GetText().Text)
+ return nil
+ })
+ if err != nil {
+ t.Fatalf("Process() error = %v", err)
+ }
+ if len(chunks) != 1 {
+ t.Fatalf("expected 1 chunk, got %d", len(chunks))
+ }
+ last := chunks[0]
+ if !strings.Contains(last, "Fetched: https://example.test/page") {
+ t.Fatalf("missing fetched URL: %s", last)
+ }
+ if !strings.Contains(last, "Sample content") {
+ t.Fatalf("missing page body: %s", last)
+ }
+ if strings.Contains(last, "<body>") || strings.Contains(last, "<html>") {
+ t.Fatalf("expected html stripped: %s", last)
+ }
+}
diff --git a/internal/localagent/browser/fetcher.go b/internal/localagent/browser/fetcher.go
new file mode 100644
index 0000000..7ed3d4a
--- /dev/null
+++ b/internal/localagent/browser/fetcher.go
@@ -0,0 +1,86 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package browser
+
+import (
+ "context"
+ "io"
+ "net/http"
+ "strings"
+ "time"
+
+ htmltomarkdown "github.com/JohannesKaufmann/html-to-markdown/v2"
+)
+
+// Query represents a validated URL to fetch.
+type Query struct {
+ URL string
+}
+
+// PageContent contains the fetched page data including headers and converted text body.
+type PageContent struct {
+ URL string // The final URL after any redirects
+ StatusCode int // HTTP status code
+ ContentType string // Content-Type header value
+ Body string // HTML converted to plain text
+}
+
+// maxFetchBytes limits how much data can be downloaded from a single page.
+const maxFetchBytes = 256 * 1024
+
+// webFetcher retrieves and converts web pages to text.
+type webFetcher struct {
+ client *http.Client
+}
+
+// newWebFetcher creates a new web fetcher with the given HTTP client.
+// If client is nil, a default client with 15-second timeout is used.
+func newWebFetcher(client *http.Client) *webFetcher {
+ if client == nil {
+ return &webFetcher{client: &http.Client{Timeout: 15 * time.Second}}
+ }
+ return &webFetcher{client: client}
+}
+
+// Fetch retrieves the page at the given URL and converts HTML to plain text.
+// It respects the context for cancellation and enforces a maxFetchBytes limit.
+func (f *webFetcher) Fetch(ctx context.Context, q Query) (PageContent, error) {
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, q.URL, nil)
+ if err != nil {
+ return PageContent{}, err
+ }
+ resp, err := f.client.Do(req)
+ if err != nil {
+ return PageContent{}, err
+ }
+ defer resp.Body.Close()
+
+ bodyBytes, err := io.ReadAll(io.LimitReader(resp.Body, maxFetchBytes))
+ if err != nil {
+ return PageContent{}, err
+ }
+
+ markdown, err := htmltomarkdown.ConvertString(string(bodyBytes))
+ if err != nil {
+ return PageContent{}, err
+ }
+
+ return PageContent{
+ URL: q.URL,
+ StatusCode: resp.StatusCode,
+ ContentType: resp.Header.Get("Content-Type"),
+ Body: strings.TrimSpace(markdown),
+ }, nil
+}
diff --git a/internal/localagent/browser/fetcher_test.go b/internal/localagent/browser/fetcher_test.go
new file mode 100644
index 0000000..674ceb5
--- /dev/null
+++ b/internal/localagent/browser/fetcher_test.go
@@ -0,0 +1,61 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package browser
+
+import (
+ "context"
+ "io"
+ "net/http"
+ "strings"
+ "testing"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+ return f(req)
+}
+
+func newMockClient(fn roundTripFunc) *http.Client {
+ return &http.Client{Transport: fn}
+}
+
+func TestWebFetcherFetch(t *testing.T) {
+ client := newMockClient(func(r *http.Request) (*http.Response, error) {
+ if got, want := r.URL.String(), "https://example.test/path"; got != want {
+ t.Fatalf("url mismatch: got %q want %q", got, want)
+ }
+ return &http.Response{
+ StatusCode: http.StatusOK,
+ Body: io.NopCloser(strings.NewReader("<html><body>Hello world</body></html>")),
+ Header: http.Header{"Content-Type": []string{"text/html; charset=utf-8"}},
+ }, nil
+ })
+
+ f := newWebFetcher(client)
+ page, err := f.Fetch(context.Background(), Query{URL: "https://example.test/path"})
+ if err != nil {
+ t.Fatalf("Fetch() error = %v", err)
+ }
+ if got, want := page.StatusCode, http.StatusOK; got != want {
+ t.Fatalf("status mismatch: got %d want %d", got, want)
+ }
+ if !strings.Contains(page.Body, "Hello world") {
+ t.Fatalf("body mismatch: %q", page.Body)
+ }
+ if strings.Contains(page.Body, "<") {
+ t.Fatalf("expected text-only body, got %q", page.Body)
+ }
+}