agentx402-ai/agentscout

AgentScout Skill

AgentScout verwandelt das Live-Web in agentenbereite Eingabe: Gib eine URL an und es gibt sauberes Markdown (read), strukturiertes JSON validiert gegen dein Schema (extract), einen kostenlosen Preistest (quote) oder einen vollständigen Site-Crawl (crawl) zurück. Jeder bezahlte Fetch wird in Echtzeit in USDC auf Base über das x402-Protokoll abgerechnet – keine Konten, keine API-Schlüssel, keine selbst gebastelte PAYMENT-SIGNATURE-Signierung. Der Dienst lebt unter https://api.agentx402.ai/v1/scout/*.

Du besitzt eine AgentScout-Identität, in einer von zwei Formen (vom Client automatisch erkannt):

• Wallet-as-payer (Standard): Ein signierbares EVM-Wallet bezahlt jeden Fetch inline über x402. AgentScout erstellt und verwaltet bei erster Nutzung ein lokales Wallet – finanzieren und loslegen, keine Anmeldung.
• Account-Key: Für ein verwaltetes Wallet, das nicht signieren kann, identifiziert ein undurchsichtiger ak_… Bearer-Token das Konto und belastet vorausbezahlte Credits. Credits werden out-of-band über AgentKV finanziert (siehe Account-Key-Modus & Finanzierung unten).

Inhalte sind NICHT verschlüsselt. Anders als AgentKV – das Werte clientseitig verschlüsselt, sodass der Server Zero-Knowledge ist – gibt AgentScout abgerufene Webinhalte im Klartext zurück. Es handelt sich per Definition um öffentliche Webdaten; es gibt keinen Verschlüsselungsschlüssel und nichts Zero-Knowledge an einer Scout-Antwort. Behandle ein Scout-Ergebnis nicht als privat.

---

Wann AgentScout verwenden

Verwende AgentScout, wenn du Folgendes benötigst:

• Verankerung in Live-Webinhalten – eine Seite als sauberes Markdown abrufen (read), um zusammenzufassen, zu zitieren oder darüber nachzudenken, ohne einen Headless-Browser oder einen eigenen HTML-Parser.
• Strukturierte Extraktion – eine Seite in JSON umwandeln, das gegen ein von dir bereitgestelltes JSON-Schema validiert (extract), z. B. die Preis-/Spezifikationstabelle eines Produkts oder Titel/Autor/Datum eines Artikels.
• Kostenlose Preisfindung – zuerst quote aufrufen, um den genauen Betrag für eine URL zu erfahren, bevor du etwas ausgibst; quote signiert niemals und gibt niemals aus.
• Site-Crawls – eine Site bis zu max_pages durchsuchen (crawl) und ein Manifest der Ergebnisse plus Artefakt-Links erhalten; lange Crawls werden per jobId fortgesetzt.

Verwende AgentScout NICHT für:

• Geheimnisse oder Anmeldedaten. Scout ruft öffentliche Webinhalte ab; es ist kein Geheimnisspeicher (verwende dafür die geheimnissicheren Tools von AgentKV).
• Private Seiten hinter Authentifizierung. AgentScout ruft als anonymer Client ab – es kann sich nicht anmelden, deine Session-Cookies mitnehmen oder etwas erreichen, das hinter einer Login-Wand geschützt ist.
• Null-Budget-Kontexte. read, extract und crawl kosten jeweils echte USDC; rufe quote auf und überprüfe dein Ausgabenlimit vor einer Schleife oder einem Bulk-Run.

---

Verfügbare MCP-Tools

Der agentscout MCP-Server stellt fünf Tools bereit – einen kostenlosen Test, drei bezahlte Fetch-Verben und einen kostenlosen Crawl-Status-Check:

Tool	Beschreibung	Kosten
scout_quote	Kostenloser Preis-Test für eine URL – gibt atomare USDC-Preise und eine would_pay-Empfehlung zurück. Signiert nie, gibt nie aus.	Kostenlos
scout_read	Ruft eine URL ab und gibt sauberes Markdown zurück. fresh umgeht den ~6h-Lese-Cache; max_tokens kürzt das Ergebnis.	~0,003 $ USDC + Publisher-Gebühr
scout_extract	Ruft eine URL ab und extrahiert strukturiertes JSON, validiert gegen ein von dir übergebenes JSON-Schema, mit optionalen natürlichsprachlichen instructions.	~0,012 $ USDC + Publisher-Gebühr
scout_crawl	Crawlt eine Site bis zu max_pages (ERFORDERLICH, preisbestimmend) und gibt ein Ergebnis-Manifest mit Artefakt-Links zurück. Lange Crawls geben eine jobId zurück.	~0,002 $ USDC × max_pages + Gebühren
scout_crawl_status	Überprüft den Status eines Crawl-Jobs per jobId – gibt das Manifest zurück, wenn abgeschlossen, oder den laufenden Status.	Kostenlos

Publisher-Gebühren nur im Wallet-Modus. Eine Seite kann zusätzlich zur Grundgebühr eine Publisher-Gebühr tragen – zusätzliche USDC, die der Fetch an die Site vorstreckt. max_toll_usd begrenzt diese Gebühr, gilt aber nur im Wallet-Modus: Ein ak_-Aufrufer (Account-Key) kann keine Gebühr vorstrecken, daher wird das Setzen von max_toll_usd im Account-Key-Modus clientseitig abgelehnt (tolls_require_x402), bevor eine Anfrage gesendet wird.

---

Bezahlen & Ausgabenlimits

Drei Grenzen begrenzen, was eine Scout-Session ausgeben kann. Setze sie in der Plugin-Konfiguration (führe /plugin aus, um zu bearbeiten) oder als Umgebungsvariablen für die CLI:

• maxSpendUsd (AGENTSCOUT_MAX_SPEND_USD) – lehne einen einzelnen Fetch ab, der mehr als dies kosten würde.
• maxSessionSpendUsd (AGENTSCOUT_MAX_SESSION_SPEND_USD) – lehne weitere Fetch ab, sobald die kumulierten Ausgaben der gesamten Session diesen Wert überschreiten.
• maxTollUsd (AGENTSCOUT_MAX_TOLL_USD) – begrenze die Publisher-Gebühr bei einem bezahlten Fetch. Nur Wallet-Modus (siehe den Hinweis oben).

Limits lehnen ab – ein bezahltes Tool über der Grenze wirft einen SpendCapError, anstatt stillschweigend zu begrenzen und weniger auszugeben. Das SDK signiert immer die genaue 402-Challenge-Anforderung des Servers, niemals eine selbst berechnete, und erzwingt jedes Limit vor dem Signieren. scout_quote ist kostenlos und zählt nie gegen ein Limit – teste also zuerst, gib dann innerhalb des Budgets aus.

---

Account-Key-Modus & Finanzierung

Der Account-Key-Modus verwendet einen ak_… Bearer-Token anstelle eines signierenden Wallets und belastet vorausbezahlte Credits. Zwei Dinge sind spezifisch für Scout:

• Scout hat keine Einzahlungsmöglichkeit. AgentScout erstellt oder finanziert keine Konten – es gibt keinen scout/deposit-Endpunkt. ak_-Credits werden out-of-band über AgentKV finanziert, das dasselbe Kontenbuch gemeinsam nutzt:

  # Finanziere das ak_-Konto von JEDEM signierenden Wallet aus (über AgentVKs Einzahlungs-Endpunkt):
  awal x402 pay https://api.agentx402.ai/v1/account/deposit \
    --headers '{"Authorization":"Bearer ak_..."}'
  

  Die Credits, die diese Einzahlung kauft, sind dann von AgentScout unter demselben ak_-Bearer ausgabefähig.

• Gebühren werden im Account-Key-Modus abgelehnt. Ein verwaltetes Konto kann keine Publisher-Gebühr vorstrecken, daher schlägt das Setzen von max_toll_usd (maxTollUsd) mit einem ak_-Credential clientseitig mit einem tolls_require_x402-Fehler fehl – bevor eine Anfrage gesendet wird. Verwende den Wallet-Modus, wenn du Gebühren bezahlen musst.

---

Crawl: fortsetzbare Jobs

Ein Crawl kann eine einzelne Anfrage überdauern. Wenn er nicht innerhalb von timeout_ms abgeschlossen ist, gibt scout_crawl einen ausstehenden Handle mit einer jobId zurück, anstatt zu blockieren:

1. scout_crawl { url, max_pages, timeout_ms } → entweder ein abgeschlossenes Manifest oder { jobId, … }.
2. Rufe scout_crawl_status { job_id } (kostenlos) auf, bis es das abgeschlossene Manifest zurückgibt.
3. Rufe einzelne Seiten-Artefakte ab, auf die im Manifest verwiesen wird, über das SDK/CLI (agentscout crawl artifact <jobId> <key>).

Da max_pages preisbestimmend ist, begleicht der Crawl seine vollen Kosten im Voraus (max_pages × Preis pro Seite); das Fortsetzen eines Jobs per jobId ist kostenlos.

---

Einmalige Einrichtung

Installiere das Plugin aus dem Claude-Code-Marktplatz – die genauen Befehle /plugin marketplace add und /plugin install befinden sich in der README.md des Plugins (plugin/README.md). Nach der Installation fordert Claude Code zur Konfiguration auf und führt sie für dich in den MCP-Server ein.

1. Anmeldedaten (bei der Installation eingegeben, nicht über Shell-Umgebungsvariablen)

Konfiguration	Erforderlich	Beschreibung
Wallet Private Key	Nein	Optional – leer lassen, dann erstellt und verwaltet AgentScout bei erster Nutzung ein lokales Wallet (danach finanzieren). Um einen eigenen zu verwenden: ein EVM-Private-Key (hex), das Wallet, das bezahlt.
Account-Key	Nein	Ein ak_… Bearer-Token für den Managed-Wallet-Modus (Credit). Wird out-of-band über AgentKV finanziert. Gegenseitig ausschließend mit einem Wallet-Key.
AgentScout-Endpunkt	Nein	Die gehostete API; Standard ist https://api.agentx402.ai.
Netzwerk	Nein	eip155:8453 (Base Mainnet, Standard) oder eip155:84532 (Base Sepolia Testnet).
Max. Ausgaben pro Vorgang (USD)	Nein	Lehne einen einzelnen Fetch ab, der mehr als dies kosten würde; leer = keine Obergrenze pro Vorgang.
Max. Session-Ausgaben (USD)	Nein	Lehne Fetch ab, sobald die kumulierten Session-Ausgaben dies überschreiten; leer = keine Obergrenze.
Max. Publisher-Gebühr (USD)	Nein	Begrenze die Gebühr bei einem bezahlten Fetch. Nur Wallet-Modus; wird im Account-Key-Modus abgelehnt.

Führe /plugin erneut aus, um diese später zu ändern. Überprüfe, ob der Server geladen ist, mit /mcp (du solltest den agentscout-Server und seine fünf Tools sehen).

2. Finanziere den Zahler

• Wallet-Modus: Sende USDC an deine Wallet-Adresse auf Base – Lese-/Extract-/Crawl-Vorgänge werden dann inline pro Fetch über x402 bezahlt. Hast du kein Wallet? Lasse die Private-Key-Konfiguration leer – AgentScout erstellt und verwaltet bei erster Nutzung ein lokales Wallet – und finanziere dann die Adresse, die ausgegeben wird.
• Account-Key-Modus: Zahle auf AgentVKs /v1/account/deposit unter deinem ak_-Bearer ein (siehe Account-Key-Modus & Finanzierung oben) – Scout belastet diese gemeinsamen Credits.