Distillation Labs

Distillation Labs / Agentyc / Documentatie

Agentyc docs

Installatie, gedeelde browser setup, state handling, deterministische extractie en debuggingrichtlijnen voor Agentyc als browser MCP runtime in echte developer workflows.

Productpagina GitHub ↗

Overzicht

Agentyc is een deterministische browser MCP runtime voor coding agents. Het biedt een publieke stdio MCP server, praat met Chrome of Chromium via CDP en geeft compacte browserstate met stabiele refs terug zodat agents kunnen inspecteren en handelen zonder broze selectors of volledige DOM dumps.

Het productverhaal is bewust smal: browserautomatisering voor coding agents, geen autonoom agentframework. Het standaard browserpad vertrouwt niet op een LLM fallback en houdt kernworkflows local first.

Zonder Agentyc

Agents lezen grote DOM payloads, reconstrueren selectors herhaaldelijk en verliezen tijd aan browserdebugging via indirecte abstracties.

Met Agentyc

Agents inspecteren compacte state, richten op stabiele refs, wachten op echte netwerkactiviteit en debuggen de live browser vanaf een deterministisch MCP oppervlak.

Installatie

Het standaardpad is eenvoudig: installeer met `uv`, voer `agentyc` uit en laat daarna je MCP geschikte agent naar het lokale commando wijzen. Voor de standaard browserruntime is geen API key nodig. 

uv tool install agentyc
agentyc
agentyc init

Compatibiliteit

  • Python 3.11 or newer
  • Local Chrome or Chromium, or an existing browser exposed over CDP
  • stdio MCP runtime with direct CDP browser control
  • No Playwright dependency in the public browser path

Snelstart

01

Installeren

uv tool install agentyc

02

MCP server starten

agentyc

03

Server registreren

claude mcp add agentyc -- agentyc

04

Pagina inspecteren

browser_get_state(mode="min")

Client configuratie

Claude Code

claude mcp add agentyc -- agentyc

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "agentyc": {
      "command": "agentyc"
    }
  }
}

OpenCode

{
  "mcp": {
    "agentyc": {
      "type": "local",
      "command": ["agentyc"]
    }
  }
}

Gedeelde browser

Agentyc ondersteunt een gedeeld browsermodel voor parallel agentwerk. Een primaire agent start een browser, daarna koppelen extra runtimes aan hetzelfde browserprofiel en claimen automatisch hun eigen samenwerkingstab. 

agentyc browser --port 9222 --detach
agentyc mcp --reuse-local-browser --runtime-label "Agent-1"
agentyc mcp --cdp-url ws://127.0.0.1:9222/devtools/browser/... --runtime-label "Agent-2"

Werkmodel

  • Each runtime gets its own owned tab by default
  • Cookies and local storage stay shared with the browser profile
  • State snapshots, refs, and logs stay scoped to the owned tab
  • `browser_new_tab` is the right next step when one runtime needs another surface

State en refs

Primary primitive

`browser_get_state` returns structured browser state instead of a raw DOM dump.

Stable refs

Interactive elements get refs like `e123`, which are the preferred targeting contract.

Compact modes

Start with `mode="min"` and escalate only when compact state omitted something you need.

Since hash

Use `since_hash` for follow-up polling so unchanged pages return metadata only.

Deterministische extractie

`browser_extract_content` blijft deterministisch in de publieke MCP runtime. Wanneer de query overeenkomt met een ondersteunde route kan Agentyc links, linkcollecties, afbeeldingen, tabellen, lijsten, formuliervelden of key value panels extraheren zonder de pagina aan een LLM te geven.

Goede queries

  • `table rows`
  • `all links`
  • `form fields`
  • `key value pairs`

Observability en debugging

  1. Step 01

    Read browser console output through `browser_get_console_logs()`.

  2. Step 02

    Inspect recent traffic with `browser_get_network_log()`.

  3. Step 03

    Wait for one precise request or response before continuing.

  4. Step 04

    Inspect or replay one captured request when an app is API-heavy.

  5. Step 05

    Apply narrow mocks or throttling per tab instead of faking the whole browser.

  6. Step 06

    Export one debug bundle with state, logs, network, trace summary, and optional screenshot.

  7. Step 07

    Use `browser_set_intent` and the optional HUD surfaces for short operator-facing progress labels.

  8. Step 08

    Capture traces when browser performance itself is the debugging target.

Configuratie

De publieke runtime leest vooral `AGENTYC_` omgevingsvariabelen. De defaults zijn praktisch voor lokale browserautomatisering, terwijl CI en gedeelde browser setups vaak expliciete headless of reuse instellingen toevoegen.

Variabele Voorbeeld Doel
AGENTYC_HEADLESS false Run the browser headless when you need CI or background automation.
AGENTYC_ALLOWED_DOMAINS example.com,*.example.org Restrict navigation to an allowlist when you want tighter runtime safety.
AGENTYC_REUSE_LOCAL_BROWSER 1 Auto-attach to the latest locally launched Agentyc browser without copying a CDP URL.
AGENTYC_ACTION_TIMEOUT_S 180 Per-action timeout enforced by the runtime for browser operations.
AGENTYC_HUD_OVERLAY 1 Mirror sanitized runtime activity in the optional desktop HUD window.
AGENTYC_LOGGING_LEVEL info Set Agentyc logging verbosity for local debugging and support.

Toolreferentie

Agentyc levert 66 MCP tools. Dit zijn de tools waar ontwikkelaars meestal het eerst naar grijpen wanneer ze een coding agent met echt browserwerk verbinden.

Start here

browser_get_state(mode="min")

Primary browser inspection primitive. Returns compact page state with stable refs.

browser_navigate(url="https://example.com")

Navigate to a URL, optionally in a new tab.

browser_wait_for_stable_dom()

Let client-rendered pages settle before you inspect or act again.

browser_search_page(pattern="pricing")

Search long pages without manually scrolling or dumping the whole document.

Interaction

browser_click(ref="e123")

Click by stable ref, index, or coordinates.

browser_type(ref="e145", text="hello")

Clear and type into a field.

browser_select_option(ref="e212", text="Enterprise")

Pick a select option by visible label.

browser_new_tab(url="https://example.com")

Open a new working surface without disturbing another runtime.

Debugging & extraction

browser_extract_content(query="table rows")

Deterministically extract common page structures without LLM fallback.

browser_wait_for_response(url_substring="/api", status=200)

Synchronize precisely against API activity.

browser_inspect_network_entry(url_substring="/api/orders")

Inspect one request or response, including bodies when needed.

browser_export_debug_bundle(include_screenshot=true)

Return a compact artifact with state, logs, network, trace summary, and optional screenshot.

Benchmarks

Import time

194.4 ms

Cold session init

1027.4 ms

Average tool latency

43.3 ms

P95 tool latency

161.6 ms

Screenshot reduction

8.3× smaller

Tool surface

66 MCP tools

Probleemoplossing

Command not found after install

Verify `uv tool install agentyc` completed and that your uv tool bin directory is on `PATH`. If needed, run the server from an activated environment instead.

Agent loses refs after a re-render

Call `browser_get_state()` again and use the fresh `e123` refs. Stable refs survive normal re-renders, but a changed DOM still means you should re-read state before retrying.

Need multiple agents in the same authenticated browser

Start one shared browser with `agentyc browser --port 9222 --detach`, then attach additional runtimes with `agentyc mcp --reuse-local-browser` or `--cdp-url ...`.

Need browser debugging data after a failure

Use `browser_export_debug_bundle()` for a compact state-plus-logs artifact, or wait for a precise request and inspect it with `browser_inspect_network_entry()`.