Aller au contenu

Pour les agents & LLM

Clearcote est organisé pour que les outils automatisés puissent s’y retrouver, l’intégrer et y contribuer aussi facilement qu’un humain.

Donnez tout le projet à votre agent

Un clic copie la documentation — toutes les pages de la doc, aplaties en un seul bloc prêt à servir de prompt. Collez-le dans Claude, Codex ou Cursor pour donner à l’agent tout le contexte du projet.

Voir /llms-full.txt ↗

Résumé lisible par machine

Un résumé concis du projet, en texte brut, se trouve à /llms.txt, et la documentation complète, aplatie en un seul fichier prêt pour un prompt, est à /llms-full.txt. Le dépôt contient aussi un AGENTS.md qui décrit l’organisation et les conventions à l’intention des contributeurs.

json
{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 149 (v0.1.0-pre.22), licensed build 153.0.8010.36-r28",
  "identity_model": "engine-level, coherent seed persona + per-site render noise",
  "automation": "SDK (npm/PyPI/NuGet package clearcote) returning Playwright objects; CDP endpoint for Puppeteer and others",
  "platforms": ["windows-x64", "linux-x64"],
  "license": "BSD-3-Clause (open build + SDKs); the licensed build adds unpublished patches",
  "repo": "https://github.com/clearcotelabs/clearcote-browser",
  "verify": "open build: GPG-signed SHA256SUMS + pinned key; every SDK download: SHA-256",
  "control_via": "SDK options, or chromium command-line switches (args) on the open build"
}

Recette d’intégration minimale

  1. Installez le SDK (pip install clearcote / npm i clearcote) — il télécharge et vérifie le navigateur.
  2. Dérivez une seed fingerprint déterministe à partir de l’identité sous laquelle vous agissez.
  3. Derrière un proxy, passez geoip=True pour que le fuseau horaire, la langue et WebRTC suivent la sortie du proxy.
  4. Pour les frameworks qui attendent une URL CDP (browser-use, Stagehand, Crawl4AI), utilisez plutôt serve() ou clearcote serve.
python
from clearcote import launch

task_id = "1234"
SEED = "agent:" + task_id          # stable, reproducible identity per task

browser = launch(fingerprint=SEED, geoip=True, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

Piloter directement le binaire du build ouvert avec executablePath fonctionne aussi, mais le build sous licence ne démarre que via le SDK, et un lancement brut perd les valeurs par défaut du SDK — voir Playwright & Puppeteer. Pour une identité plus fidèle, lancez un vrai profil capturé plutôt qu’une seed : launch(profile="auto") en choisit un adapté à cette machine dans la bibliothèque de profils (build sous licence), ou passez fingerprint_profile="profile.json" (Node : fingerprintProfile). Ne combinez pas un profil avec une seed fingerprint.

Agent IA intégré au navigateur

Clearcote embarque un agent IA facultatif, à activer explicitement, qui pilote une vraie page de façon autonome. Il perçoit la page en direct, demande à un LLM configuré par l’utilisateur quoi faire ensuite, et agit via le framework Actor de Chrome avec de vrais événements d’entrée de confiance (trusted) plutôt qu’avec du script injecté. Il est désactivé par défaut (inactif tant que vous ne fournissez ni clé d’agent ni flags d’agent) et fonctionne avec votre propre clé : faites-le pointer vers n’importe quel endpoint compatible OpenAI / OpenRouter. Les champs de mot de passe sont masqués avant tout envoi au modèle. Utilisez launch_agent() (un contexte persistant) — c’est la voie prise en charge.

Depuis le SDK, launch_agent (Node : launchAgent) renvoie un BrowserContext persistant, et run_agent_task(page, goal, max_steps=...) (Node : runAgentTask) le pilote et renvoie { success, finalText, steps, stepsJson }. Passez un répertoire de profil comme premier argument (userDataDir en Node) pour réutiliser un même profil ; sinon, chaque appel crée un nouveau dossier de profil temporaire qui n’est pas supprimé à la fermeture. Python & Node uniquement.

python
import os
from clearcote import launch_agent, run_agent_task

# Returns a persistent BrowserContext.
ctx = launch_agent(
    agent_llm_key=os.environ["OPENROUTER_API_KEY"],   # required: the SDK does not read env vars (the CLI does)
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(
    page,
    goal="Find the pricing page and read the cheapest plan",
    model="openai/gpt-4o-mini",                # optional per-task override
    max_steps=20,
)
print(result["success"], result["finalText"], result["steps"])

Les options de lancement de l’agent correspondent directement à des flags du binaire : agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) et agent_typing / agentTyping. Une tâche s’exécute dès que l’agent dispose d’une URL (OpenRouter par défaut), d’une clé et d’un modèle. L’agent demande au modèle une réponse JSON en texte brut : l’endpoint n’a donc pas besoin de prendre en charge les appels d’outils (tool calls) ; agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) est accepté mais n’a actuellement aucun effet.

agent_typing / agentTyping règle la cadence de frappe de l’agent : human (par défaut) tape avec un timing keydown/keyup propre à chaque touche et saisit les textes longs touche par touche, fast est la cadence rapide du moteur, et instant saisit tout d’un coup. La valeur par défaut évite les deux indices qui trahissent une frappe automatisée — un timing uniforme d’une précision mécanique, et un texte long collé instantanément (ce qui n’émet aucun événement de frappe).

La CLI clearcote-agent

Le même agent est disponible en CLI pour des exécutions rapides et scriptables. Passez un objectif ponctuel, ou ouvrez un REPL interactif. La clé du modèle provient de --key ou des variables d’environnement $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY.

bash
# One-shot: run a single goal against a URL, then exit
clearcote-agent --goal "Accept cookies and list the top 3 headlines" --url https://example.com

# Interactive REPL: keep the browser open and issue goals one at a time
clearcote-agent -i

# Use a custom endpoint/model, persistent profile, proxy and step cap
clearcote-agent --llm-url http://localhost:8000/v1 --model local/model \
  --profile ~/.clearcote/agent-profile --proxy http://user:pass@host:8080 \
  --max-steps 12 --goal "Open the dashboard" --url example.com

# Provide the key explicitly (otherwise read from the environment)
clearcote-agent --key sk-or-... --json \
  --goal "Search for 'clearcote' and open the first result" --url https://example.com

Parmi les options de la CLI : --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone et --json. Un simple nom d’hôte passé à --url est converti en HTTPS.

Où chercher

Construisez des identités déterministes : dérivez la seed d’un identifiant stable (tenant, compte, tâche) pour qu’un même acteur obtienne toujours la même empreinte de navigateur — reproductible et débogable.