Distillation Labs

Distillation Labs / Agentyc / Documentacion

Docs de Agentyc

Instalacion, configuracion de navegador compartido, manejo de estado, extraccion determinista y guia de depuracion para usar Agentyc como runtime MCP de navegador en flujos reales.

Producto GitHub ↗

Resumen

Agentyc es un runtime MCP de navegador determinista para agentes de codigo. Expone un servidor MCP publico por stdio, habla con Chrome o Chromium por CDP y devuelve estado compacto con refs estables para que los agentes inspeccionen y actuen sin depender de selectores fragiles o dumps completos del DOM.

La historia del producto es intencionalmente estrecha: automatizacion de navegador para agentes de codigo, no un framework autonomo. No depende de fallback LLM en la ruta de runtime por defecto y mantiene los flujos centrales local-first.

Sin Agentyc

Los agentes leen payloads grandes del DOM, reconstruyen selectores repetidamente y pierden tiempo depurando comportamiento del navegador a traves de abstracciones indirectas.

Con Agentyc

Los agentes inspeccionan estado compacto, apuntan a refs estables, esperan actividad real de red y depuran el navegador vivo desde una sola superficie MCP determinista.

Instalacion

La ruta por defecto es simple: instala con `uv`, ejecuta `agentyc` y luego apunta tu agente compatible con MCP al comando local. No hace falta API key para el runtime por defecto. 

uv tool install agentyc
agentyc
agentyc init

Compatibilidad

  • Python 3.11 o superior
  • Chrome o Chromium local, o un navegador expuesto por CDP
  • Runtime MCP por stdio con control de navegador por CDP directo
  • Sin dependencia de Playwright en la ruta publica del navegador

Inicio rapido

01

Instalar

uv tool install agentyc

02

Ejecutar el servidor MCP

agentyc

03

Registrar el servidor

claude mcp add agentyc -- agentyc

04

Inspeccionar la pagina

browser_get_state(mode="min")

Configuracion de clientes

Claude Code

claude mcp add agentyc -- agentyc

Claude Desktop / Cursor / Windsurf

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

OpenCode

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

Navegador compartido

Agentyc soporta un modelo de navegador compartido para trabajo paralelo de agentes. Un agente primario lanza un navegador y luego otros runtimes se adjuntan al mismo perfil y reclaman automaticamente su propia tab de colaboracion. 

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"

Modelo operativo

  • 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

Estado y 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.

Extraccion determinista

`browser_extract_content` se mantiene determinista en el runtime MCP publico. Cuando la consulta coincide con una ruta soportada, Agentyc puede extraer enlaces, colecciones de enlaces, imagenes, tablas, listas, campos de formulario o paneles clave-valor sin pasar la pagina a un LLM.

Buenas consultas

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

Observabilidad y depuracion

  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.

Configuracion

El runtime publico lee principalmente variables `AGENTYC_`. Los defaults son practicos para automatizacion local, mientras que CI y navegador compartido suelen agregar headless o reuse explicitos.

Variable Ejemplo Proposito
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.

Referencia de herramientas

Agentyc trae 66 herramientas MCP. Estas son las que los desarrolladores suelen usar primero al conectar un agente de codigo con trabajo real de navegador.

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

Resolucion de problemas

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