Distillation Labs

Distillation Labs / Agentyc / Dokumentation

Agentyc Docs

Installation, Shared Browser Setup, State Handling, deterministische Extraktion und Debugging Hinweise fur den Einsatz von Agentyc als Browser MCP Runtime in echten Entwickler Workflows.

Produktseite GitHub ↗

Uberblick

Agentyc ist eine deterministische Browser MCP Runtime fur Coding Agents. Sie stellt einen offentlichen stdio MCP Server bereit, spricht uber CDP mit Chrome oder Chromium und liefert kompakten Browser State mit stabilen Refs, damit Agenten ohne fragile Selektoren oder Voll DOM Dumps arbeiten konnen.

Die Produktgeschichte ist bewusst eng: Browser Automatisierung fur Coding Agents, kein autonomes Agenten Framework. Der Standard Browser Pfad verlasst sich nicht auf einen LLM Fallback und halt zentrale Workflows local first.

Ohne Agentyc

Agenten lesen grosse DOM Payloads, rekonstruieren Selektoren wiederholt und verlieren Zeit beim Debuggen des Browsers uber indirekte Abstraktionen.

Mit Agentyc

Agenten inspizieren kompakten State, zielen auf stabile Refs, warten auf echte Netzwerkaktivitat und debuggen den Live Browser uber eine deterministische MCP Surface.

Installation

Der Standardpfad ist einfach: mit `uv` installieren, `agentyc` ausfuhren und dann Ihren MCP fahigen Agenten auf den lokalen Befehl zeigen lassen. Fur die Standard Browser Runtime ist kein API Key erforderlich. 

uv tool install agentyc
agentyc
agentyc init

Kompatibilitat

  • 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

Schnellstart

01

Installieren

uv tool install agentyc

02

MCP Server starten

agentyc

03

Server registrieren

claude mcp add agentyc -- agentyc

04

Seite inspizieren

browser_get_state(mode="min")

Client Konfiguration

Claude Code

claude mcp add agentyc -- agentyc

Claude Desktop / Cursor / Windsurf

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

OpenCode

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

Shared Browser

Agentyc unterstutzt ein Shared Browser Modell fur parallele Agentenarbeit. Ein primarer Agent startet einen Browser, dann hangen sich weitere Runtimes an dasselbe Browserprofil und beanspruchen automatisch ihren eigenen Collaboration Tab. 

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"

Betriebsmodell

  • 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 und 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 Extraktion

`browser_extract_content` bleibt in der offentlichen MCP Runtime deterministisch. Wenn die Anfrage zu einer unterstutzten Route passt, kann Agentyc Links, Link Sammlungen, Bilder, Tabellen, Listen, Formularfelder oder Key Value Panels extrahieren, ohne die Seite an ein LLM zu ubergeben.

Gute Queries

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

Observability und 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.

Konfiguration

Die offentliche Runtime liest vor allem `AGENTYC_` Umgebungsvariablen. Die Defaults sind fur lokale Browser Automatisierung praktisch, wahrend CI und Shared Browser Setups meist explizite Headless oder Reuse Einstellungen hinzufugen.

Variable Beispiel Zweck
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.

Tool Referenz

Agentyc liefert 66 MCP Tools. Das sind die Werkzeuge, zu denen Entwickler zuerst greifen, wenn sie einen Coding Agenten mit echter Browser Arbeit 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

Fehlersuche

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()`.