agentx402-ai/agentscout

Compétence AgentScout

AgentScout transforme le Web en direct en entrée exploitable par un agent : donnez-lui une URL et il retourne du markdown propre (read), du JSON structuré validé selon votre schéma (extract), une estimation de prix gratuite (quote), ou une exploration complète de site (crawl). Chaque appel payé est réglé en USDC réel sur Base via le protocole x402 — pas de comptes, pas de clés API, pas de signature PAYMENT-SIGNATURE maison. Le service est accessible à https://api.agentx402.ai/v1/scout/*.

Vous détenez une seule identité AgentScout, sous l'une des deux formes suivantes (détectée automatiquement par le client) :

• Portefeuille payeur (par défaut) : un portefeuille EVM signable paie chaque appel en ligne via x402. AgentScout crée et gère un portefeuille local lors du premier usage — approvisionnez-le et c'est parti, pas d'inscription.
• Clé de compte : pour un portefeuille géré qui ne peut pas signer, un jeton opaque ak_… (bearer token) identifie le compte et débite des crédits prépayés. Les crédits sont approvisionnés hors bande via AgentKV (voir Mode clé de compte et financement ci-dessous).

Le contenu N'EST PAS chiffré. Contrairement à AgentKV — qui chiffre les valeurs côté client pour que le serveur soit à connaissance nulle — AgentScout retourne le contenu web récupéré en clair. Il s'agit par définition de données web publiques ; il n'y a pas de clé de chiffrement et rien de « connaissance nulle » dans une réponse de scout. Ne traitez pas un résultat de scout comme privé.

---

Quand utiliser AgentScout

Utilisez AgentScout lorsque vous avez besoin de :

• Ancrage dans du contenu web vivant — récupérez une page en markdown propre (read) pour la résumer, la citer ou raisonner dessus, sans navigateur headless ni analyseur HTML maison.
• Extraction structurée — transformez une page en JSON validé selon un schéma JSON que vous fournissez (extract), par exemple le tableau prix/spécifications d'un produit ou le titre/auteur/date d'un article.
• Découverte gratuite des prix — appelez d'abord quote pour connaître le coût exact d'une URL avant de dépenser quoi que ce soit ; quote ne signe jamais et ne dépense jamais.
• Explorations de site — parcourez un site jusqu'à max_pages (crawl) et récupérez un manifeste de résultats plus des liens vers les artefacts ; les longues explorations reprennent via jobId.

N'utilisez PAS AgentScout pour :

• Secrets ou identifiants. Scout récupère du contenu public ; ce n'est pas un coffre-fort de secrets (utilisez les outils sécurisés d'AgentKV pour cela).
• Pages privées derrière authentification. AgentScout opère comme un client anonyme — il ne peut pas se connecter, transporter vos cookies de session, ni accéder à quoi que ce soit protégé par un mur de connexion.
• Contextes sans budget. read, extract, et crawl coûtent chacun de l'USDC réel ; appelez quote et vérifiez votre plafond de dépenses avant une boucle ou une exécution en masse.

---

Outils MCP disponibles

Le serveur MCP agentscout expose cinq outils — une sonde gratuite, trois verbes de récupération payants et une vérification d'état d'exploration gratuite :

Outil	Description	Coût
scout_quote	Sonde gratuite du coût d'une URL — retourne les prix en USDC atomique et un avis would_pay. Ne signe jamais, ne dépense jamais.	Gratuit
scout_read	Récupère une URL et retourne du markdown propre. fresh contourne le cache de lecture (~6h) ; max_tokens tronque le résultat.	~0,003 $ USDC + droit d'éditeur
scout_extract	Récupère une URL et extrait du JSON structuré validé selon un schéma JSON que vous passez, avec des instructions optionnelles en langage naturel.	~0,012 $ USDC + droit d'éditeur
scout_crawl	Explore un site jusqu'à max_pages (OBLIGATOIRE, détermine le prix) et retourne un manifeste de résultats avec des liens vers les artefacts. Les longues explorations retournent un jobId.	~0,002 $ USDC × max_pages + droits
scout_crawl_status	Vérifie l'état d'une exploration par jobId — retourne le manifeste une fois terminée, ou l'état en cours.	Gratuit

Les droits d'éditeur sont réservés au mode portefeuille. Une page peut comporter un droit d'éditeur en plus des frais de base — un supplément en USDC que la récupération avance au site. max_toll_usd plafonne ce droit, mais cela ne s'applique qu'en mode portefeuille : un appelant avec ak_ (clé de compte) ne peut pas avancer un droit, donc définir max_toll_usd en mode clé de compte est refusé côté client (tolls_require_x402) avant même l'envoi de toute requête.

---

Paiement et plafonds de dépenses

Trois limites bornent ce qu'une session scout peut dépenser. Définissez-les dans la configuration du plugin (exécutez /plugin pour modifier) ou comme variables d'environnement pour la CLI :

• maxSpendUsd (AGENTSCOUT_MAX_SPEND_USD) — refuse toute unique récupération qui coûterait plus que ce montant.
• maxSessionSpendUsd (AGENTSCOUT_MAX_SESSION_SPEND_USD) — refuse toute récupération supplémentaire une fois que les dépenses cumulées sur l'ensemble de la session dépassent ce montant.
• maxTollUsd (AGENTSCOUT_MAX_TOLL_USD) — plafonne le droit d'éditeur sur une récupération payée. Mode portefeuille uniquement (voir l'avertissement ci-dessus).

Les plafonds refusent — un outil payé qui dépasse la limite lève une SpendCapError plutôt que de plafonner silencieusement et de dépenser moins. Le SDK signe toujours le montant exact du défi 402 du serveur, jamais un montant auto-calculé, et applique chaque plafond avant de signer. scout_quote est gratuit et n'est jamais compté dans un plafond, donc sondez d'abord, puis dépensez dans les limites du budget.

---

Mode clé de compte et financement

Le mode clé de compte utilise un jeton ak_… au lieu d'un portefeuille signant et débite des crédits prépayés. Deux choses sont spécifiques à scout :

• Scout n'a pas de route de dépôt. AgentScout ne crée ni ne finance des comptes — il n'y a pas de point de terminaison scout/deposit. Les crédits ak_ sont approvisionnés hors bande via AgentKV, qui partage le même grand livre de comptes :

  # Financer le compte ak_ depuis N'IMPORTE QUEL portefeuille signant (via la route de dépôt d'AgentKV) :
  awal x402 pay https://api.agentx402.ai/v1/account/deposit \
    --headers '{"Authorization":"Bearer ak_..."}'
  

  Les crédits achetés par ce dépôt sont ensuite dépensables par AgentScout sous le même jeton ak_.

• Les droits sont refusés en mode clé de compte. Un compte géré ne peut pas avancer un droit d'éditeur, donc définir max_toll_usd (maxTollUsd) avec un identifiant ak_ échoue rapidement côté client avec une erreur tolls_require_x402 — avant qu'aucune requête ne soit émise. Utilisez le mode portefeuille si vous devez payer des droits.

---

Exploration : travaux repris

Une exploration peut dépasser la durée d'une seule requête. Si elle ne se termine pas dans timeout_ms, scout_crawl retourne un handle en attente portant un jobId au lieu de bloquer :

1. scout_crawl { url, max_pages, timeout_ms } → soit un manifeste terminé, soit { jobId, … }.
2. Interrogez scout_crawl_status { job_id } (gratuit) jusqu'à ce qu'il retourne le manifeste terminé.
3. Récupérez les artefacts de page individuels référencés dans le manifeste via le SDK/CLI (agentscout crawl artifact <jobId> <key>).

Étant donné que max_pages détermine le prix, l'exploration règle son coût total d'avance (max_pages × prix par page) ; la reprise d'un travail par jobId est gratuite.

---

Configuration unique

Installez le plugin depuis la place de marché de Claude Code — les commandes exactes /plugin marketplace add et /plugin install se trouvent dans le README.md du plugin (plugin/README.md). Après l'installation, Claude Code vous invite à saisir la configuration et l'intègre dans le serveur MCP pour vous.

1. Identifiants (saisis lors de l'installation, pas via l'environnement shell)

Configuration	Requis	Description
Clé privée du portefeuille	Non	Optionnel — laissez vide et AgentScout crée + gère un portefeuille local lors du premier usage (approvisionnez-le ensuite). Pour apporter le vôtre : une clé privée EVM (hexadécimale), le portefeuille qui paie.
Clé de compte	Non	Un jeton ak_… pour le mode portefeuille géré (crédits). Approvisionné hors bande via AgentKV. Mutuellement exclusif avec une clé de portefeuille.
Point de terminaison AgentScout	Non	L'API hébergée ; valeur par défaut https://api.agentx402.ai.
Réseau	Non	eip155:8453 (Base mainnet, valeur par défaut) ou eip155:84532 (Base Sepolia testnet).
Dépense max par opération (USD)	Non	Refuse toute récupération unique qui coûterait plus que ce montant ; vide = pas de plafond par opération.
Dépense max par session (USD)	Non	Refuse les récupérations lorsque les dépenses cumulées de la session dépassent ce montant ; vide = pas de plafond.
Droit d'éditeur max (USD)	Non	Plafonne le droit sur une récupération payée. Mode portefeuille uniquement ; rejeté en mode clé de compte.

Ré-exécutez /plugin pour modifier ces paramètres ultérieurement. Vérifiez que le serveur est chargé avec /mcp (vous devriez voir le serveur agentscout et ses cinq outils).

2. Financer le payeur

• Mode portefeuille : envoyez de l'USDC à l'adresse de votre portefeuille sur Base — les lectures/extractions/explorations sont ensuite payées en ligne par récupération via x402. Pas de portefeuille ? Laissez la configuration de la clé privée vide — AgentScout crée et gère un portefeuille local lors du premier usage — puis approvisionnez l'adresse qu'il affiche.
• Mode clé de compte : déposez via /v1/account/deposit d'AgentKV avec votre jeton ak_ (voir Mode clé de compte et financement ci-dessus) — scout débite ces crédits partagés.