agentx402-ai/agentscout

Skill de AgentScout

AgentScout convierte la web en vivo en entrada lista para agentes: dale una URL y devuelve markdown limpio (read), JSON estructurado validado contra tu esquema (extract), una sonda de precio gratuita (quote), o un rastreo completo del sitio (crawl). Cada solicitud pagada se liquida en USDC real en Base mediante el protocolo x402, sin cuentas, sin claves API, sin firmas PAYMENT-SIGNATURE hechas a mano. El servicio está en https://api.agentx402.ai/v1/scout/*.

Tienes una identidad de AgentScout, en una de dos formas (detectada automáticamente por el cliente):

• Wallet como pagador (por defecto): una billetera EVM firmable paga cada solicitud en línea vía x402. AgentScout crea y gestiona una billetera local en el primer uso: fúndala y continúa, sin registro.
• Clave de cuenta: para una billetera gestionada que no puede firmar, un token portador ak_… opaco identifica la cuenta y debita créditos prepagados. Los créditos se financian externamente a través de AgentKV (ver Modo clave de cuenta y financiación más abajo).

El contenido NO está encriptado. A diferencia de AgentKV — que encripta los valores del lado del cliente para que el servidor sea de conocimiento cero — AgentScout devuelve el contenido web obtenido en texto claro. Por definición son datos web públicos; no hay clave de encriptación y nada es de conocimiento cero en una respuesta de scout. No trates un resultado de scout como privado.

---

Cuándo usar AgentScout

Usa AgentScout cuando necesites:

• Fundamentación en contenido web en vivo — extrae una página como markdown limpio (read) para resumir, citar o razonar sobre ella, sin un navegador sin cabeza ni tu propio analizador HTML.
• Extracción estructurada — convierte una página en JSON que se valida contra un esquema JSON que tú proporcionas (extract), por ejemplo, la tabla de precios/especificaciones de un producto o el título/autor/fecha de un artículo.
• Descubrimiento gratuito de precios — llama a quote primero para conocer el costo exacto de una URL antes de gastar nada; quote nunca firma ni gasta.
• Rastreo de sitios — recorre un sitio hasta max_pages (crawl) y obtén un manifiesto de resultados más enlaces a artefactos; los rastreos largos se reanudan mediante jobId.

NO uses AgentScout para:

• Secretos o credenciales. Scout obtiene contenido web público; no es un almacén de secretos (usa las herramientas seguras de AgentKV para eso).
• Páginas privadas detrás de autenticación. AgentScout actúa como un cliente anónimo — no puede iniciar sesión, llevar tus cookies de sesión ni acceder a nada protegido por un muro de inicio de sesión.
• Contextos sin presupuesto. read, extract y crawl cuestan USDC real; llama a quote y revisa tu límite de gasto antes de un bucle o una ejecución masiva.

---

Herramientas MCP disponibles

El servidor MCP de agentscout expone cinco herramientas — una sonda gratuita, tres verbos de pago y una verificación gratuita de estado de rastreo:

Herramienta	Descripción	Costo
scout_quote	Sonda gratuita del costo de una URL — devuelve precios en USDC atómico y un aviso would_pay. Nunca firma ni gasta.	Gratis
scout_read	Obtiene una URL y devuelve markdown limpio. fresh omite la caché de lectura de ~6h; max_tokens trunca el resultado.	~$0.003 USDC + tarifa del editor
scout_extract	Obtiene una URL y extrae JSON estructurado validado contra un esquema JSON que proporcionas, con instructions opcionales en lenguaje natural.	~$0.012 USDC + tarifa del editor
scout_crawl	Rastrea un sitio hasta max_pages (REQUERIDO, determina el precio) y devuelve un manifiesto de resultados con enlaces a artefactos. Los rastreos largos devuelven un jobId.	~$0.002 USDC × max_pages + tarifas
scout_crawl_status	Verifica el estado de un trabajo de rastreo mediante jobId — devuelve el manifiesto cuando está completo, o el estado en curso.	Gratis

Las tarifas del editor son solo en modo wallet. Una página puede tener una tarifa de editor adicional además de la tarifa base — USDC extra que la solicitud adelanta al sitio. max_toll_usd limita esa tarifa, pero solo aplica en modo wallet: un llamante con ak_ (clave de cuenta) no puede adelantar una tarifa, por lo que establecer max_toll_usd en modo clave de cuenta es rechazado del lado del cliente (tolls_require_x402) antes de enviar cualquier solicitud.

---

Límites de gasto

Tres techos limitan lo que una sesión de scout puede gastar. Establécelos en la configuración del plugin (ejecuta /plugin para editar) o como variables de entorno para la CLI:

• maxSpendUsd (AGENTSCOUT_MAX_SPEND_USD) — rechaza cualquier solicitud individual que cueste más que esto.
• maxSessionSpendUsd (AGENTSCOUT_MAX_SESSION_SPEND_USD) — rechaza solicitudes adicionales una vez que el gasto acumulado de toda la sesión supere esto.
• maxTollUsd (AGENTSCOUT_MAX_TOLL_USD) — limita la tarifa del editor en una solicitud pagada. Solo modo wallet (ver la advertencia anterior).

Los límites rechazan — una herramienta pagada por encima del techo lanza un SpendCapError en lugar de limitar silenciosamente y gastar menos. El SDK siempre firma el monto exacto del desafío 402 del servidor, nunca uno calculado por sí mismo, y aplica cada límite antes de firmar. scout_quote es gratuito y nunca cuenta contra un límite, así que primero prueba, luego gasta dentro del presupuesto.

---

Modo clave de cuenta y financiación

El modo clave de cuenta usa un token portador ak_… en lugar de una billetera firmante y debita créditos prepagados. Dos cosas son específicas de scout:

• Scout no tiene ruta de depósito. AgentScout no crea ni financia cuentas — no hay un endpoint scout/deposit. Los créditos ak_ se financian externamente a través de AgentKV, que comparte el mismo libro de cuentas:

  # Financia la cuenta ak_ desde CUALQUIER billetera firmante (a través de la ruta de depósito de AgentKV):
  awal x402 pay https://api.agentx402.ai/v1/account/deposit \
    --headers '{"Authorization":"Bearer ak_..."}'
  

  Los créditos que compra ese depósito son luego gastables por AgentScout bajo el mismo portador ak_.

• Las tarifas son rechazadas en modo clave de cuenta. Una cuenta gestionada no puede adelantar una tarifa de editor, por lo que establecer max_toll_usd (maxTollUsd) con una credencial ak_ falla rápidamente del lado del cliente con un error tolls_require_x402 — antes de que se emita cualquier solicitud. Usa el modo wallet si necesitas pagar tarifas.

---

Rastreo: trabajos reanudables

Un rastreo puede durar más que una sola solicitud. Si no termina dentro de timeout_ms, scout_crawl devuelve un manejador pendiente con un jobId en lugar de bloquear:

1. scout_crawl { url, max_pages, timeout_ms } → ya sea un manifiesto completo o { jobId, … }.
2. Consulta scout_crawl_status { job_id } (gratis) hasta que devuelva el manifiesto completo.
3. Obtén artefactos de páginas individuales referenciados en el manifiesto a través del SDK/CLI (agentscout crawl artifact <jobId> <key>).

Como max_pages determina el precio, el rastreo liquida su costo total por adelantado (max_pages × precio por página); reanudar un trabajo mediante jobId es gratuito.

---

Configuración única

Instala el plugin desde el marketplace de Claude Code — los comandos exactos /plugin marketplace add y /plugin install están en el README.md del plugin (plugin/README.md). Después de la instalación, Claude Code solicita la configuración y la integra en el servidor MCP por ti.

1. Credenciales (ingresadas en la instalación, no mediante variables de entorno)

Configuración	Requerido	Descripción
Clave privada de wallet	No	Opcional — déjalo en blanco y AgentScout crea + gestiona una billetera local en el primer uso (luego fúndala). Para traer la tuya: una clave privada EVM (hex), la billetera que paga.
Clave de cuenta	No	Un token portador ak_… para modo wallet gestionado (créditos). Financiado externamente a través de AgentKV. Mutuamente excluyente con una clave de wallet.
Endpoint de AgentScout	No	La API alojada; por defecto https://api.agentx402.ai.
Red	No	eip155:8453 (Base mainnet, por defecto) o eip155:84532 (Base Sepolia testnet).
Gasto máximo por operación (USD)	No	Rechaza cualquier solicitud individual que cueste más que esto; vacío = sin límite por operación.
Gasto máximo de sesión (USD)	No	Rechaza solicitudes una vez que el gasto acumulado de la sesión supere esto; vacío = sin límite.
Tarifa máxima del editor (USD)	No	Limita la tarifa en una solicitud pagada. Solo modo wallet; rechazado en modo clave de cuenta.

Vuelve a ejecutar /plugin para cambiar estos valores después. Verifica que el servidor cargó con /mcp (deberías ver el servidor agentscout y sus cinco herramientas).

2. Financiar el pagador

• Modo wallet: envía USDC a la dirección de tu wallet en Base — las lecturas/extracciones/rastreos se pagan en línea por solicitud vía x402. ¿No tienes wallet? Deja la configuración de clave privada en blanco — AgentScout crea y gestiona una billetera local en el primer uso — luego financia la dirección que imprime.
• Modo clave de cuenta: deposita en /v1/account/deposit de AgentKV bajo tu portador ak_ (ver Modo clave de cuenta y financiación arriba) — scout debita esos créditos compartidos.