From b003614064f98b2d07e5cc2fa8b9ad59d673e776 Mon Sep 17 00:00:00 2001 From: Pierre Tachoire Date: Tue, 16 Jun 2026 17:49:03 +0200 Subject: [PATCH] removed in favor of https://lightpanda.io/docs/usage/agent --- docs/agent.md | 530 -------------------------------------------------- 1 file changed, 530 deletions(-) delete mode 100644 docs/agent.md diff --git a/docs/agent.md b/docs/agent.md deleted file mode 100644 index 9a82187ca..000000000 --- a/docs/agent.md +++ /dev/null @@ -1,530 +0,0 @@ -# Agent mode - -`lightpanda agent` lets you drive a headless browser by talking to it. - -You tell it where to go and what to extract, in plain English or with slash -commands, and it controls a real browser to do the work. Think of it as a -robot you're directing to use the web, not a chatbot you're having a -conversation with. - -Every session starts by navigating to a page, either by -saying so ("go to news.ycombinator.com") or by typing `/goto `. There's -no window to look at; the browser runs headlessly and you see its output -(extracted data, the agent's answer) in your terminal. - -## How to think about it - -The agent stacks three layers: - -1. **The browser.** Loads pages, runs JavaScript, tracks cookies, follows - redirects. The same engine that powers `lightpanda serve` and - `lightpanda fetch`. -2. **A set of tools.** Things the browser knows how to do: `goto`, `click`, - `fill`, `extract`, `evaluate`, `search`, and more. Each is available as a - slash command (`/goto`, `/click`, ...). -3. **An LLM.** Reads your plain-English request and decides which tools to - call. Optional. The agent can also run without it. - -You can talk to any of the three layers. Type `/goto example.com` and you -call the browser tool directly. Type "find me the cheapest flight from NYC -to Tokyo" and the LLM picks the tools to use. Save what worked to a `.js` -file and you can replay the whole flow later without ever calling the LLM -again. - -## Quick start - -Set an API key for your preferred provider: - -```bash -export ANTHROPIC_API_KEY=sk-ant-... -``` - -(Or `OPENAI_API_KEY` / `GOOGLE_API_KEY`. Without a key the agent runs in a -slash-commands-only mode without natural language.) - -Launch the REPL: - -```bash -./lightpanda agent -``` - -Tell it what you want: - -``` -❯ go to news.ycombinator.com and get me the top story title and points -``` - -The agent navigates, extracts, prints the answer. When you're happy with -the result, save it and replay it right away to check it holds up without -the LLM: - -``` -❯ /save hn-top-story.js -❯ /load hn-top-story.js -❯ /quit -``` - -You now have a `.js` file that does the same job deterministically: - -```bash -./lightpanda agent hn-top-story.js -``` - -No LLM call, no API key needed at replay time, sub-second to run. - -For a longer worked example (logging into a site, extracting structured -data across pages), see the [tutorial](agent-tutorial.md). - -### Other ways to launch - -```bash -# Force a specific provider, ignoring auto-detection -./lightpanda agent --provider anthropic - -# REPL without an LLM: /goto, /extract, ... work; plain English doesn't -./lightpanda agent --no-llm - -# One-shot: ask a question, print the answer to stdout, exit -./lightpanda agent --task "what is on the front page of hn?" -``` - -## Tips for getting useful saved scripts - -The whole value of a saved script is that it keeps working after you walk away. - -- **Ask for the data you want, not the conversation about it.** "Get me the - top 5 HN story titles and points, print them to stdout" beats "show me - what's on Hacker News today." The synthesizer captures the data you asked - for as a `page.extract()` call; vague prompts produce vague recordings. -- **Be specific about the page.** "Go to news.ycombinator.com" is much - better than "find me what's on Hacker News". -- **Check the file with `cat your-script.js` before running it.** The - script holds the *calls*, not the data, so look for a `page.extract(...)` - whose schema covers the fields you asked for. If there isn't one, the - recording missed something — try rewording your prompt. -- **When the page changes and a saved script breaks**, re-run with the LLM, - get an updated answer, save again. You only pay the LLM when something - genuinely changed. - -## Providers and API keys - -The agent needs an LLM to interpret natural language. Set the relevant API -key as an environment variable, or pass `--provider` explicitly. - -| Provider | Flag | API key env | -|-----------|------------------------|--------------------------------------| -| Anthropic | `--provider anthropic` | `ANTHROPIC_API_KEY` | -| OpenAI | `--provider openai` | `OPENAI_API_KEY` | -| Gemini | `--provider gemini` | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | -| Ollama | `--provider ollama` | none (local) | - -`--model` falls back to a sensible per-provider default. `--base-url` -overrides the API endpoint (Ollama defaults to `http://localhost:11434/v1`). -`--list-models` prints what the resolved provider offers and exits. -`--system-prompt` swaps in your own system prompt. `--verbosity -` tunes how much progress detail goes to stderr (`--task` -defaults to `low`, escalating to `high` when stderr is piped or redirected -so harnesses capture the full `[tool/result]` trace). - -### How a provider gets picked - -Without `--provider`, the agent picks one in this order: - -1. **Remembered** - whatever you last selected with `/provider` or `/model`, - persisted per-directory in `.lp-agent.zon`, as long as its key is still - set. -2. **Auto-detected** - the first key found in priority order - (`ANTHROPIC_API_KEY` → `GOOGLE_API_KEY`/`GEMINI_API_KEY` → - `OPENAI_API_KEY`). With several keys on a TTY, you'll be prompted to - pick. -3. **Local Ollama** - if no cloud key is set, the agent probes - `http://localhost:11434/v1` and uses it if there's at least one model - pulled. -4. **No provider at all** - falls back to the basic REPL (slash commands - only). Natural language and LLM-driven commands (`/login`, `/logout`, - `/acceptCookies`) will reject. - -`--no-llm` is the explicit override. It forces the basic REPL even when an -API key is present. Useful for testing slash commands without burning -tokens. - -### Reasoning effort - -`--effort ` sets the per-turn reasoning -budget for thinking models. It maps to each provider's native -reasoning-effort knob and is ignored by non-thinking models. The REPL -defaults to `low` so turns stay snappy. `--task` defaults to `medium` -where answer quality matters more than per-turn latency. Higher -effort can mean fewer tool calls per task (the model plans better), so it's -a real tradeoff rather than a pure slowdown. Change it live in the REPL -with `/effort`; selection persists in `.lp-agent.zon`. Script replay makes -no LLM calls, so effort doesn't apply there. - -The default depends on how you launched, which is easy to miss: - -| Context | Default effort | Why | -|----------------|----------------|--------------------------------------| -| REPL | `low` | Keeps turns snappy | -| `--task` | `medium` | Answer quality matters more | - -## Slash commands - -The REPL uses a small slash-command language for browser actions. Each line -you type at the prompt is either a slash command, a `#` comment, a blank -line, or (when an LLM is configured) a natural-language prompt. - -Slash commands accept: - -- A single positional value, when the tool has exactly one required field. - `/goto 'https://example.com'`. The value can itself be quoted JSON when - that's what the field takes: `/extract '{"karma":"#karma"}'` passes the - string to extract's one required field, `schema`. -- `key=value` pairs. Values may be bare or quoted; strings with whitespace - must be quoted. `/fill selector='#email' value='user@x.com'`. A positional - and `key=value` pairs can be mixed, but the positional must come first: - `/extract '{"karma":"#karma"}' save=me`. -- A raw `{json}` blob, handed straight to the tool. - `/findElement {"role":"button"}`. - -Tools whose selector is optional (`/click`, `/hover`, `/findElement`) take -no positional and must use `key=value` form: `/click selector='a.login'`. -`/help ` prints any tool's JSON schema — required fields, optional -fields, and types. - -Quoting is content-aware: `'…'`, `"…"`, and triple-quoted `'''…'''` / -`"""…"""` for values that mix quote styles or span multiple lines. Paste a -multi-line command and the REPL keeps the whole paste as one input; typed -line by line, Enter submits at each newline. - -### LLM-driven helpers - -Three slash commands trigger an LLM turn rather than a direct tool call: - -| Command | What it does | -|------------------|-------------------------------------------------------| -| `/login` | Fills credentials from `$LP_*` env vars. | -| `/logout` | Finds the logout control and signs out. | -| `/acceptCookies` | Dismisses the consent banner. | - -All three require an LLM. `--no-llm` rejects them. - -### Meta commands - -These don't drive the browser, they control the REPL itself: - -| Command | What it does | -|--------------------------|----------------------------------------------------| -| `/help` | Lists tools. `/help ` prints the JSON schema.| -| `/provider [name]` | Lists or switches provider. | -| `/model [name]` | Lists or switches model for the active provider. | -| `/effort ` | Sets reasoning budget. Saved to `.lp-agent.zon`. | -| `/verbosity ` | Tunes the log level. Levels: low, medium, high. | -| `/usage` | Prints cumulative token usage and cache hit rate. | -| `/save [file] [prompt]` | Writes the session to a script. `.js` is appended to the name if missing; trailing words guide the synthesizer.| -| `/load ` | Runs a script from disk against the current session.| -| `/clear` | Forgets the conversation (history, usage, recorded actions, node IDs); keeps the page and cookies.| -| `/reset` | Full reset: everything `/clear` does, plus a fresh browser session, dropping the page, cookies, and storage.| -| `/quit` | Exits the REPL. | - -Meta commands are never recorded. - -Use `/clear` when you want to test a new prompt against the current -page without losing your login or cookies. Use `/reset` when you need -a completely clean browser (no cookies, no current page, no storage). - -## REPL features - -- **Ghost hints.** There's no separate status line; guidance renders as dim - ghost text after the cursor and disappears as you type over it. It - previews the rest of the first matching command name, the argument shape - of the tool you're typing (`/evaluate ` shows - `