Build

Web Tools

Search the web, read pages, and interact with websites in a browser.

Last updated October 17, 2026

web_search

€0.015 per search

Search the web for current information

How it works

web_search returns relevant titles, URLs, and content snippets. Results can be targeted by country and can include recent news articles.

agents/researcher.yaml

version: "1.0"

name: researcher
model: connic/gpt-5.6-sol
description: "Research agent with web search"
system_prompt: |
  You are a research assistant with web search capabilities.
  Search the web to find current information and cite sources.

tools:
  - web_search

Parameters

Parameter	Type	Default	Description
query	string	required	Search query
max_results	int	5	Number of results, up to 10
country	string	None	ISO 3166-1 alpha-2 country code, such as DE, US, or FR
include_news	bool	false	Also search recent news and merge it into the results list

Return value

Returns a results list. Each result contains:

title: page title
url: page URL
content: page-content snippet

web_read_page

€0.015 per page

Fetch a page and return its content as Markdown

How it works

web_read_page fetches a web page and converts its full content to clean Markdown. Use it after web_search when the agent needs more than a search snippet.

URLs on x.com, twitter.com, and their subdomains are not supported. These requests return an error.

agents/reader.yaml

version: "1.0"

name: reader
model: connic/gemini-3.7-flash
description: "Agent that reads and summarizes web pages"
system_prompt: |
  You can fetch web pages and summarize their content.
  Use web_search to find pages, then web_read_page to read them.

tools:
  - web_search
  - web_read_page

Parameters

Parameter	Type	Default	Description
url	string	required	Page URL to fetch
follow_redirects	boolean	true	Follow redirects and read the final page. When false, a redirect returns an error and the target in `redirect_url`.

Return value

Returns a dictionary containing:

markdown: converted page content
url: final fetched URL after redirects
error: included only on timeout, fetch failure, blocked redirect, or unsupported URL
redirect_url: target returned when a redirect is blocked

Browser tools

€0.03 per minute

Browser tools keep a page open across tool calls. Add web_browser_* to enable all browser tools. The agent calls these tools directly as needed. Each run has one current browser, used automatically by every browser tool. The snippets below show the equivalent Python calls.

agents/browser-agent.yaml

version: "1.0"

name: browser-agent
model: connic/gpt-5.6-sol
session: true
description: "Agent that interacts with websites"
system_prompt: |
  Open the requested website and inspect its available controls.
  Use the browser tools to complete the requested task.
  Close the browser when finished.

tools:
  - web_browser_*

See the pricing page for browser pricing and environment limits by plan.

On failure, tools return an error dictionary, sometimes with an error_code. If outcome_unknown is true, inspect the current page before repeating an action.

Sessions and page state

web_browser_open

Open a browser session

How it works

Open a public HTTP or HTTPS URL in the run’s browser. If a browser is already open, the tool returns Browser already open without navigating. To change the page, use web_browser_act with action="navigate".

With session: true, browser cookies and local storage persist across the agent’s runs. For configured sessions, session.browser defaults to true; setting it to false starts each browser with fresh state. When browser persistence is enabled, closing the browser, including at run end, saves its profile for the same connic session. Runs of the same session can use a browser at the same time: the first one saves the profile, and the others open it read-only (profile_mode: read_only). Their changes, including new logins, are not saved. Browser time is billed only while the browser is open.

tools/browser.py

from connic.tools import web_browser_open

await web_browser_open("https://example.com")

Parameters

Parameter	Type	Default	Description
url	string	required	Public HTTP or HTTPS URL to open.
country	string	`"EU"`	ISO 3166-1 alpha-2 country code the browser browses from, such as DE or US, or `EU` for a location in the EU. Applies when the browser opens. If no page loads from that country, the browser reopens from the EU, then without a location. The result’s `country` is the location used, or `null` without one.
timezone	string	`None`	IANA timezone that pages use for dates and times, such as Europe/Berlin or America/Chicago. Defaults to the main timezone of `country`, and to Europe/Berlin for `EU`. Applies to every page and tab until the browser closes. The result’s `timezone` is the timezone in use, or `null` if it could not be set.

Return value

Returns a dictionary containing:

status: active while the session is open.
url, snapshot: Initial page URL, text, and element references when a browser is opened.
message: Browser already open when reusing an open browser.

web_browser_observe

Read the current page

How it works

Read the page and refresh its element references. Use references from the latest snapshot when interacting with elements. Snapshots are cut off at 32,000 characters, so narrow long pages to interactive elements or one region.

tools/browser.py

from connic.tools import web_browser_observe

await web_browser_observe()

Parameters

Parameter	Type	Default	Description
interactive_only	bool	`False`	Include only buttons, links, inputs, and other elements the agent can act on.
selector	string \| None	`None`	CSS selector, such as `main` or `form`, that limits the snapshot to one region.
include_urls	bool	`False`	Include the URL of each link.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
snapshot: Page text and current element references.

web_browser_read

Read the current page as Markdown

How it works

Convert the page as rendered in the run’s browser to Markdown, including content behind a login. Use it to read text; use web_browser_observe for element references.

tools/browser.py

from connic.tools import web_browser_read

await web_browser_read()

Parameters

None.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
content: Page content as Markdown.
content_truncated: When present, the content exceeded 32,000 characters and was cut off.

web_browser_close

Close a browser session

How it works

Close the session when the task is finished. This ends browser usage and removes its downloaded files. Sessions also close when the run ends.

tools/browser.py

from connic.tools import web_browser_close

await web_browser_close()

Parameters

None.

Return value

Returns a dictionary containing:

status: closed when closure is confirmed.

Elements and keyboard

web_browser_act

Interact with page elements

How it works

Click or hover over controls, enter text, use the keyboard, navigate, or wait for the page. target is an element reference such as @e1 from the latest snapshot, not a CSS selector. Each action returns the updated page.

tools/browser.py

from connic.tools import web_browser_act

await web_browser_act(
    "fill", target="@e1", value="Berlin"
)

Parameters

Parameter	Type	Default	Description
action	string	required	Action to perform. See the supported actions below.
target	string \| None	`None`	Element reference. Required for element actions such as `click`, `hover`, `fill`, and `check`; optional for typing and keyboard actions.
value	string \| None	`None`	Text, option, key, direction, URL, selector, or wait duration, depending on `action`. Wait durations are strings, for example `"1000"`.

Supported actions

action	target	value
click, double_click, hover	Required	Omit.
check, uncheck	Required	Omit. The target is a checkbox or radio button.
scroll_into_view	Required	Omit.
fill	Required	Text that replaces the field contents.
select	Required	Option value to select.
type	Optional	Nonempty text to insert. Without `target`, uses the focused field.
press	Optional	Key or chord, for example `Enter` or `Control+A`.
keydown, keyup	Optional	Single key, for example `Shift`. `keydown` holds it until `keyup`.
scroll	Omit	`up`, `down`, `left`, or `right`.
navigate	Omit	Public HTTP or HTTPS URL.
back, forward, reload	Omit	Omit.
wait	Omit	Milliseconds from 100 to 10,000 as a string, for example `"1000"`.
wait_for_text	Omit	Text to appear on the page.
wait_for_url	Omit	URL or pattern, for example `**/dashboard`.
wait_for_selector	Omit	CSS selector of an element to appear.
wait_for_network_idle	Omit	Omit.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
snapshot: Page text and current element references.

An error can include a fresh snapshot of the blocked page. action_completed=true means the action ran even if reading the resulting page failed. The wait_for_* actions give up after 10 seconds and return an error with the current page.

Screenshots and mouse

web_browser_screenshot

Capture the visible browser page

How it works

Capture the viewport as a PNG image that the model can see. Text and voice models need image-input support. Take a new screenshot after scrolling or navigation.

tools/browser.py

from connic.tools import web_browser_screenshot

await web_browser_screenshot()

Parameters

Parameter	Type	Default	Description
full_page	bool	`False`	Capture the whole scrollable page instead of the viewport. Full-page images can’t be used for mouse coordinates, and very long pages can exceed the 10 MB image limit.

Return value

Returns a list containing a metadata dictionary and a PNG file attachment. Metadata includes:

status: Session status.
width, height: Image dimensions in pixels.
viewport_width, viewport_height: Visible viewport dimensions in CSS pixels.
url, snapshot: Current page URL and text snapshot when page observation succeeds.

For mouse input, convert image coordinates with round(image_x * viewport_width / width) and round(image_y * viewport_height / height). An unsuccessful capture returns an error dictionary instead of an attachment.

web_browser_mouse

Control the mouse with coordinates

How it works

Move, click, drag, or scroll within the visible viewport. Coordinates use CSS pixels measured from its top-left corner. Use the dimensions returned by web_browser_screenshot to convert image coordinates.

tools/browser.py

from connic.tools import web_browser_mouse

await web_browser_mouse(
    "click", x=320, y=240
)

Parameters

Parameter	Type	Default	Description
action	string	required	`move`, `click`, `double_click`, `down`, `up`, `drag`, or `scroll`.
x	int \| None	`None`	Horizontal CSS coordinate. Supply with `y`; required except for `down` and `up`. Integer from 0 to 16,384 within the viewport.
y	int \| None	`None`	Vertical CSS coordinate. Supply with `x`, with the same range and requirements.
to_x	int \| None	`None`	Horizontal destination for `drag`, from 0 to 16,384. Required for `drag`; omit for other actions.
to_y	int \| None	`None`	Vertical destination for `drag`, from 0 to 16,384. Required for `drag`; omit for other actions.
button	string	`"left"`	`left`, `middle`, or `right` for clicks, `down`, `up`, and `drag`. Leave at the default for `move` and `scroll`.
delta_x	int	`0`	Horizontal scroll distance, −10,000 to 10,000 CSS pixels. Positive scrolls right. Only for `scroll`; at least one delta must be nonzero.
delta_y	int	`0`	Vertical scroll distance, −10,000 to 10,000 CSS pixels. Positive scrolls down. Only for `scroll`.
modifiers	list[string] \| None	`None`	Up to four entries from `Alt`, `Control`, `Meta`, and `Shift`. For `click`, `double_click`, `drag`, or `scroll` only; applies to this action.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
snapshot: Page text and current element references.

The result is a text snapshot. Call web_browser_screenshot to see the visual result.

Tabs and dialogs

web_browser_tabs

Manage tabs and popups

How it works

List, open, switch, or close tabs within the same browser session. List tabs after a popup opens to find its ID. Switching refreshes the page and its element references.

tools/browser.py

from connic.tools import web_browser_tabs

await web_browser_tabs(
    "new", url="https://example.com"
)

Parameters

Parameter	Type	Default	Description
action	string	`"list"`	`list`, `new`, `switch`, or `close`. `list` does not accept `tab_id` or `url`.
tab_id	string \| None	`None`	ID from the returned `tabs` list. Required for `switch`. Optional for `close`; omission closes the active tab. Omit for `list` and `new`.
url	string \| None	`None`	Public HTTP or HTTPS URL for `new`. Omit to open a blank tab. Not used with other actions.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
snapshot: Page text and current element references.
tabs: List of tabs, each with tab_id, title, url, and active.

web_browser_dialog

Respond to JavaScript dialogs

How it works

Accept or dismiss a pending alert, confirmation, or prompt. Browser observations include dialog details when a JavaScript dialog blocks the page.

tools/browser.py

from connic.tools import web_browser_dialog

await web_browser_dialog(
    "accept", text="Report name"
)

Parameters

Parameter	Type	Default	Description
action	string	required	`accept` confirms the dialog; `dismiss` rejects it.
text	string \| None	`None`	Optional response when accepting a prompt. Omit for `dismiss`.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
snapshot: Page text and current element references.
dialog: When available: pending and optional type, message, and default fields describing any remaining dialog.

JavaScript, console, and network

web_browser_eval

Run JavaScript in the page

How it works

Evaluate a JavaScript expression in the active tab and return its value. Promises are awaited. To use return or await, wrap the code in (async () => { ... })(). For longer scripts, store them in project files and pass script_path. Set save_to to store the full result there instead of returning it.

tools/browser.py

from connic.tools import web_browser_eval

await web_browser_eval(
    "[...document.querySelectorAll('h2')].map(h => h.textContent.trim())"
)

await web_browser_eval(
    script_path="scripts/collect-rows.js", save_to="exports/rows.json"
)

Parameters

Parameter	Type	Default	Description
script	string	None	JavaScript expression of up to 16,384 characters. The value of the last expression is returned. Pass exactly one of `script` or `script_path`.
include_snapshot	bool	`False`	Wait for the page to settle and return a fresh snapshot as well.
script_path	string	None	Path of a JavaScript file in project files, up to 8 MiB, evaluated like `script`.
save_to	string	None	Project files path to store the full result at, up to 100 MiB. Strings are saved as text, other values as JSON. A path ending in `/` is a folder that keeps the name `result.txt` or `result.json`.

Return value

Returns a dictionary containing:

status: active while the session is open.
result: The expression’s value as JSON. Return plain data such as strings, numbers, arrays, or objects rather than DOM nodes.
result_truncated: When present, the result exceeded 32,000 characters and was cut off. Non-string values are then returned as JSON text. Use save_to to keep the whole result.
saved_path, size: Path in project files and size in bytes when save_to is set. These replace result.
url: Current page URL.
snapshot: Page text and current element references, only with include_snapshot.

If the script throws, error contains its message and error_code is script_error.

web_browser_console

Read console messages and JavaScript errors

How it works

Return the most recent console messages and uncaught JavaScript errors. Entries accumulate while the browser is open, with the newest last.

tools/browser.py

from connic.tools import web_browser_console

await web_browser_console()

Parameters

None.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
console_messages: Up to 50 entries with type, such as log or error, and text.
page_errors: Up to 20 entries with text, line, and column.
console_truncated: When present, older entries or long text were cut off.

web_browser_network

Record requests and read their responses

How it works

Record the requests the page makes, such as the JSON its own front end loads, and read their responses. Start recording before the page loads the data, for example before navigating or clicking. Recording continues across tool calls until stop or until the browser closes.

Authorization, Cookie, Set-Cookie, and Proxy-Authorization header values are replaced with [redacted] in everything the tool returns or saves, including cookies in HAR files. Request and response bodies are not redacted. Custom code that must send its own authenticated requests can pass include_credentials=True with get to receive these values unredacted; it cannot be combined with save_to, and the values must never be returned to the model or stored.

tools/browser.py

from connic.tools import web_browser_network

await web_browser_network("start")
await web_browser_network("list", filter="/api/")
await web_browser_network(
    "get", request_id=request_id, save_to="exports/"
)

Parameters

Parameter	Type	Default	Description
action	string	required	`start` begins recording and clears earlier requests. `list` returns recorded requests. `get` returns one request with its response body. `stop` ends recording.
filter	string	None	URL substring that limits `list`, such as `/api/`.
request_id	string	None	Request ID from `list`, required for `get`.
save_to	string	None	With `get`, the project files path to store the full response body at. With `stop`, the path to store the recording at as a HAR file. A path ending in `/` is a folder that keeps the name `response.json` (or the matching extension) or `network.har`.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
recording: true after start, false after stop.
requests: For list, entries with id, method, url, status, type, and size (from Content-Length when the server sends it), newest last.
request_count: Number of recorded requests that match the filter, or that the recording contains after stop.
requests_truncated: When present, only the most recent requests that fit in 32,000 characters are listed. Narrow them with filter.
request: For get, the request with method, url, status, mime_type, request_headers, response_headers, post_data, and body. Bodies over 32,000 characters are cut off and set body_truncated. body is null when the browser no longer holds it, such as after navigating away, or for binary responses.
saved_path, size: Path in project files and size in bytes when save_to is set. If the path was taken, the file gets a numbered name.

The HAR file keeps text response bodies of up to 2 MB each, including those of pages the browser has since left.

Downloads, PDFs, and uploads

web_browser_download

Download a file from the page

How it works

Click a link or button that starts a file download. Set include_content to choose whether the agent receives the file as an attachment or only its ID and metadata. Files remain available in this browser session until it closes; each file can be up to 25 MiB. Set save_to to also keep the file in project files, which allows files up to 100 MiB.

tools/browser.py

from connic.tools import web_browser_download

await web_browser_download(
    target="@e1", include_content=True
)

Parameters

Parameter	Type	Default	Description
target	string	required	Element reference such as `@e1` from the latest snapshot. Use the reference of the download link or button.
include_content	bool	required	`true` attaches the file for the agent to read. `false` returns only its ID and metadata. This flag has no default.
save_to	string	None	Project files path to store the download at. A path ending in `/` is a folder that keeps the downloaded name. Files over 25 MiB are saved without an attachment.

Return value

With include_content=false, returns a metadata dictionary. With true, returns a list containing that dictionary and a file attachment. Metadata includes:

download_id: File ID accepted by web_browser_upload in the same session.
name: Downloaded filename.
mime_type: File media type.
size: File size in bytes.
saved_path: Path in project files when save_to is set. If the path was taken, the file gets a numbered name.
status: Browser status.
url, snapshot: Current page URL and text snapshot when page observation succeeds.

web_browser_pdf

Save the current page as a PDF

How it works

Print the current page to a PDF of up to 25 MiB, or 100 MiB with save_to. The PDF is stored like a download, so its ID works with web_browser_upload until the browser session closes.

tools/browser.py

from connic.tools import web_browser_pdf

await web_browser_pdf(include_content=True)

Parameters

Parameter	Type	Default	Description
include_content	bool	required	`true` attaches the PDF for the agent to read. `false` returns only its ID and metadata.
save_to	string	None	Project files path to store the PDF at. A path ending in `/` is a folder and keeps the name `page.pdf`.

Return value

Same as web_browser_download: a metadata dictionary with download_id, name, and mime_type (application/pdf), plus the PDF attachment when include_content=true.

web_browser_upload

Upload a downloaded or stored file

How it works

Select a file in a file input: one downloaded earlier in this browser session by its download_id, or one from project files by its path, up to 100 MiB. Pass exactly one of the two; local deployment paths are not accepted. Submit the form separately if the page requires it.

tools/browser.py

from connic.tools import web_browser_upload

await web_browser_upload(
    target="@e2", download_id=download_id
)

Parameters

Parameter	Type	Default	Description
target	string	required	File-input reference such as `@e2` from the latest snapshot.
download_id	string	None	File ID returned by `web_browser_download` or `web_browser_pdf` in this session.
path	string	None	Path of a file in project files.

Return value

Returns a dictionary containing:

status: active while the session is open.
url: Current page URL.
snapshot: Page text and current element references.
download_id: ID of the selected file.

Explore more tools

Orchestration ToolsTrigger another agent now or later ToolsBuild tools for specialized use cases Agent ConfigurationAttach web tools to an agent Runs & TracesInspect web tool calls in production