Distillation Labs

Distillation Labs / Agentyc / Documentation

Docs Agentyc

Installation, configuration du navigateur partage, gestion de l etat, extraction deterministe et guide de debug pour executer Agentyc comme runtime MCP navigateur dans de vrais workflows.

Produit GitHub ↗

Vue d ensemble

Agentyc est un runtime MCP navigateur deterministe pour les agents de code. Il expose un serveur MCP public sur stdio, parle a Chrome ou Chromium via CDP et retourne un etat compact avec des refs stables afin que les agents puissent inspecter et agir sans dependre de selecteurs fragiles ou de dumps DOM complets.

L histoire du produit est volontairement etroite: automatisation navigateur pour agents de code, pas framework agent autonome. Il ne repose pas sur un fallback LLM dans le runtime par defaut et garde ses workflows essentiels en local first.

Sans Agentyc

Les agents lisent de gros payloads DOM, reconstruisent les selecteurs a repetition et perdent du temps a debugger le navigateur a travers des abstractions indirectes.

Avec Agentyc

Les agents inspectent un etat compact, ciblent des refs stables, attendent la vraie activite reseau et debugguent le navigateur live depuis une seule surface MCP deterministe.

Installation

Le chemin par defaut est simple: installez avec `uv`, lancez `agentyc`, puis pointez votre agent compatible MCP vers la commande locale. Aucune cle API n est requise pour le runtime navigateur par defaut. 

uv tool install agentyc
agentyc
agentyc init

Compatibilite

  • 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

Demarrage rapide

01

Installer

uv tool install agentyc

02

Lancer le serveur MCP

agentyc

03

Enregistrer le serveur

claude mcp add agentyc -- agentyc

04

Inspecter la page

browser_get_state(mode="min")

Configuration client

Claude Code

claude mcp add agentyc -- agentyc

Claude Desktop / Cursor / Windsurf

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

OpenCode

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

Navigateur partage

Agentyc prend en charge un modele de navigateur partage pour le travail parallele des agents. Un agent principal lance un navigateur, puis des runtimes additionnels s attachent au meme profil et reclament automatiquement leur propre onglet de collaboration. 

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"

Modele operatoire

  • 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

Etat et 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.

Extraction deterministe

`browser_extract_content` reste deterministe dans le runtime MCP public. Quand la requete correspond a une route supportee, Agentyc peut extraire liens, collections de liens, images, tableaux, listes, champs de formulaire ou panneaux cle-valeur sans donner la page a un LLM.

Bonnes requetes

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

Observabilite et debug

  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.

Configuration

Le runtime public lit surtout les variables `AGENTYC_`. Les valeurs par defaut sont pratiques pour l automatisation locale, tandis que les setups CI et navigateur partage ajoutent souvent des reglages headless ou de reuse explicites.

Variable Exemple But
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.

Reference des outils

Agentyc expose 66 outils MCP. Ce sont ceux que les developpeurs utilisent le plus souvent lorsqu ils connectent un agent de code a un vrai travail navigateur.

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

Depannage

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