agentx402-ai/agentscout

Habilidade AgentScout

O AgentScout transforma a web ao vivo em entrada pronta para agentes: forneça uma URL e ele retorna markdown limpo (read), JSON estruturado validado contra seu schema (extract), uma sonda gratuita de preço (quote) ou um rastreamento completo do site (crawl). Cada requisição paga é liquidada em USDC real na Base através do protocolo x402 — sem contas, sem chaves de API, sem assinatura manual de PAYMENT-SIGNATURE. O serviço está disponível em https://api.agentx402.ai/v1/scout/*.

Você mantém uma identidade AgentScout, em uma de duas formas (detectada automaticamente pelo cliente):

• Carteira como pagador (padrão): uma carteira EVM que pode assinar paga cada requisição inline via x402. O AgentScout cria e gerencia uma carteira local no primeiro uso — deposite fundos e vá, sem cadastro.
• Chave de conta: para uma carteira gerenciada que não pode assinar, um token portador ak_… opaco identifica a conta e debita créditos pré-pagos. Os créditos são financiados externamente via AgentKV (veja Modo chave de conta e financiamento abaixo).

O conteúdo NÃO é criptografado. Diferente do AgentKV — que criptografa valores no lado do cliente para que o servidor seja de conhecimento zero — o AgentScout retorna o conteúdo web obtido em texto claro. São dados públicos da web por definição; não há chave de criptografia e nada de conhecimento zero em uma resposta de scout. Não trate um resultado de scout como privado.

---

Quando usar o AgentScout

Use o AgentScout quando precisar de:

• Fundamentação em conteúdo web ao vivo — obtenha uma página como markdown limpo (read) para resumir, citar ou raciocinar sobre, sem um navegador headless ou um analisador HTML próprio.
• Extração estruturada — transforme uma página em JSON validado contra um JSON Schema que você fornece (extract), por exemplo, a tabela de preço/especificações de um produto ou título/autor/data de um artigo.
• Descoberta gratuita de preços — chame quote primeiro para saber o custo exato de uma URL antes de gastar qualquer coisa; quote nunca assina e nunca gasta.
• Rastreamentos de sites — percorra um site até max_pages (crawl) e receba um manifesto de resultados mais links para artefatos; rastreamentos longos são retomados por jobId.

NÃO use o AgentScout para:

• Segredos ou credenciais. O Scout obtém conteúdo público da web; não é um cofre de segredos (use as ferramentas seguras do AgentKV para isso).
• Páginas privadas atrás de autenticação. O AgentScout busca como um cliente anônimo — ele não pode fazer login, carregar seus cookies de sessão ou acessar qualquer conteúdo protegido por login.
• Contextos sem orçamento. read, extract e crawl custam USDC real; chame quote e verifique seu limite de gastos antes de um loop ou execução em lote.

---

Ferramentas MCP Disponíveis

O servidor MCP agentscout expõe cinco ferramentas — uma sonda gratuita, três verbos de busca pagos e uma verificação gratuita de status de rastreamento:

Ferramenta	Descrição	Custo
scout_quote	Sonda gratuita de custo para uma URL — retorna preços em USDC atômico e um aviso would_pay. Nunca assina, nunca gasta.	Gratuito
scout_read	Busca uma URL e retorna markdown limpo. fresh ignora o cache de leitura de ~6h; max_tokens trunca o resultado.	~$0,003 USDC + taxa do editor
scout_extract	Busca uma URL e extrai JSON estruturado validado contra um JSON Schema que você passa, com instructions opcionais em linguagem natural.	~$0,012 USDC + taxa do editor
scout_crawl	Rastreia um site até max_pages (OBRIGATÓRIO, determinante de preço) e retorna um manifesto de resultados com links para artefatos. Rastreamentos longos retornam um jobId.	~$0,002 USDC × max_pages + taxas
scout_crawl_status	Verifica o status de um trabalho de rastreamento por jobId — retorna o manifesto quando concluído ou o status em andamento.	Gratuito

Taxas do editor são apenas no modo carteira. Uma página pode ter uma taxa do editor além da taxa base — USDC extra que a busca adianta para o site. max_toll_usd limita essa taxa, mas ela só se aplica no modo carteira: um chamador com ak_ (chave de conta) não pode adiantar uma taxa, então definir max_toll_usd no modo chave de conta é recusado no lado do cliente (tolls_require_x402) antes de qualquer requisição ser enviada.

---

Pagamento e limites de gastos

Três tetos limitam o quanto uma sessão de scout pode gastar. Defina-os na configuração do plugin (execute /plugin para editar) ou como variáveis de ambiente para o CLI:

• maxSpendUsd (AGENTSCOUT_MAX_SPEND_USD) — recusa qualquer única busca que custaria mais que isso.
• maxSessionSpendUsd (AGENTSCOUT_MAX_SESSION_SPEND_USD) — recusa novas buscas quando o gasto cumulativo em toda a sessão exceder isso.
• maxTollUsd (AGENTSCOUT_MAX_TOLL_USD) — limita a taxa do editor em uma busca paga. Apenas modo carteira (veja a ressalva acima).

Os limites recusam — uma ferramenta paga acima do teto lança um SpendCapError em vez de limitar silenciosamente e gastar menos. O SDK sempre assina o valor exato do desafio 402 do servidor, nunca um valor calculado por si, e aplica cada limite antes de assinar. scout_quote é gratuito e nunca conta contra um limite, então sonde primeiro, depois gaste dentro do orçamento.

---

Modo chave de conta e financiamento

O modo chave de conta usa um token portador ak_… em vez de uma carteira com assinatura e debita créditos pré-pagos. Duas coisas são específicas do scout:

• Scout não possui rota de depósito. O AgentScout não cria nem financia contas — não há endpoint scout/deposit. Créditos ak_ são financiados externamente via AgentKV, que compartilha o mesmo razão de contas:

  # Financie a conta ak_ a partir de QUALQUER carteira com assinatura (via rota de depósito do AgentKV):
  awal x402 pay https://api.agentx402.ai/v1/account/deposit \
    --headers '{"Authorization":"Bearer ak_..."}'
  

  Os créditos que esse depósito compra são então gastáveis pelo AgentScout sob o mesmo portador ak_.

• Taxas são recusadas no modo chave de conta. Uma conta gerenciada não pode adiantar uma taxa do editor, então definir max_toll_usd (maxTollUsd) com uma credencial ak_ falha rapidamente no lado do cliente com um erro tolls_require_x402 — antes de qualquer requisição ser emitida. Use o modo carteira se precisar pagar taxas.

---

Rastreamento: trabalhos retomáveis

Um rastreamento pode durar mais que uma única requisição. Se não terminar dentro de timeout_ms, scout_crawl retorna um identificador pendente carregando um jobId em vez de bloquear:

1. scout_crawl { url, max_pages, timeout_ms } → ou um manifesto concluído ou { jobId, … }.
2. Consulte scout_crawl_status { job_id } (gratuito) até que retorne o manifesto concluído.
3. Obtenha artefatos de página individuais referenciados no manifesto via SDK/CLI (agentscout crawl artifact <jobId> <key>).

Como max_pages determina o preço, o rastreamento liquida seu custo total antecipadamente (max_pages × preço por página); retomar um trabalho por jobId é gratuito.

---

Configuração Única

Instale o plugin do mercado do Claude Code — os comandos exatos /plugin marketplace add e /plugin install estão no README.md do plugin (plugin/README.md). Após a instalação, o Claude Code solicita a configuração e a insere no servidor MCP para você.

1. Credenciais (inseridas na instalação, não via variáveis de ambiente do shell)

Configuração	Obrigatório	Descrição
Chave privada da carteira	Não	Opcional — deixe em branco e o AgentScout cria + gerencia uma carteira local no primeiro uso (então deposite fundos). Para trazer a sua: uma chave privada EVM (hex), a carteira que paga.
Chave de conta	Não	Um token portador ak_… para modo carteira gerenciada (crédito). Financiado externamente via AgentKV. Mutuamente exclusivo com uma chave de carteira.
Endpoint do AgentScout	Não	A API hospedada; padrão é https://api.agentx402.ai.
Rede	Não	eip155:8453 (Base mainnet, padrão) ou eip155:84532 (Base Sepolia testnet).
Gasto máximo por operação (USD)	Não	Recusa qualquer única busca que custaria mais que isso; vazio = sem limite por operação.
Gasto máximo da sessão (USD)	Não	Recusa novas buscas quando o gasto cumulativo da sessão exceder isso; vazio = sem limite.
Taxa máxima do editor (USD)	Não	Limita a taxa em uma busca paga. Apenas modo carteira; recusado no modo chave de conta.

Execute /plugin novamente para alterar esses valores posteriormente. Verifique se o servidor carregou com /mcp (você deve ver o servidor agentscout e suas cinco ferramentas).

2. Financie o pagador

• Modo carteira: envie USDC para o endereço da sua carteira na Base — leituras/extrações/rastreamentos são então pagos inline por busca via x402. Não tem uma carteira? Deixe a configuração da chave privada em branco — o AgentScout cria e gerencia uma carteira local no primeiro uso — então deposite fundos no endereço que ele imprimir.
• Modo chave de conta: deposite no /v1/account/deposit do AgentKV sob seu portador ak_ (veja Modo chave de conta e financiamento acima) — o scout debita esses créditos compartilhados.