Terminal
Terminal/Skill
Tunes a Browserbase Agent's system prompt by running a fixed task, scoring the results, and changing one rule per round.
By Browserbase
Works with
npx skills add browserbase/skills --skill optimize-agent-promptOptimize a Browserbase Agent's systemPrompt while holding its task, result schema, variables, and evaluation criteria fixed. Treat the outer agent as the teacher and each Browserbase Agent run as an inner-agent rollout.
Use Node.js 18 or later and set BROWSERBASE_API_KEY. The harness uses only Node.js built-in modules.
Choose a short experiment name and create an isolated workspace inside the demo or POC repository:
node <skill-dir>/scripts/optimize_agent_prompt.mjs init \
--workspace ./agent-prompt-optimization/<experiment-name> \
--name <experiment-name>
Edit the generated files:
task.json: keep task, resultSchema, variables, browser settings, and evaluation oracle stable across iterations.prompts/iteration-001.md: write the minimal baseline system prompt. Include irreversible-action guardrails when applicable.Use concrete success criteria. Prefer a strict JSON Schema with required fields and null for unavailable facts. Add known-field regexes and factuality-warning regexes under evaluation when a truth oracle exists. Read references/evaluation.md when designing the task or score.
node <skill-dir>/scripts/optimize_agent_prompt.mjs run \
--workspace ./agent-prompt-optimization/<experiment-name> \
--prompt prompts/iteration-001.md \
--label iteration-001
The harness creates one reusable Browserbase Agent, updates its systemPrompt on later iterations, starts the run, polls messages and status, and writes:
runs/<label>/
├── system-prompt.md
├── created-run.json
├── run.json
├── messages.json
├── session-logs.json
└── summary.json
It stops a run after the configured message budget instead of paying for an unproductive spiral. Use --max-messages, --timeout-ms, --proxies, or --verified only when the task needs different values from task.json.
Start with the compact trajectory:
node <skill-dir>/scripts/optimize_agent_prompt.mjs inspect \
--workspace ./agent-prompt-optimization/<experiment-name> \
--label iteration-001
Then read summary.json and drill into messages.json at the first wrong or wasted turn. Agent messages expose ordered tool calls, tool results, errors, and final output. A reasoning part may contain no readable text; never require hidden chain-of-thought for the teacher loop.
Read session-logs.json only when browser-level evidence can distinguish the cause—for example, a redirect, 403, failed request, console error, or hidden endpoint. Empty session logs can mean the Agent completed with search/fetch tools and never drove its browser.
See references/api.md for endpoint shapes, pagination, result normalization, and trace caveats.
Find the earliest consequential failure and state one counterfactual:
If the system prompt had instructed X, the Agent would have avoided Y, as shown by tool result Z.
Copy the current prompt to prompts/iteration-NNN.md and make one attributable change. Typical improvements are:
null instead of guessed values;Keep wins. If the new run regresses, restore the previous prompt and test a different hypothesis rather than stacking more rules.
Generate the comparison table after each run:
node <skill-dir>/scripts/optimize_agent_prompt.mjs report \
--workspace ./agent-prompt-optimization/<experiment-name>
Judge more than field completeness. Require:
COMPLETED;Once a prompt wins, run it again unchanged with a new label. Converge only after it passes at least two of the last three runs and one pass is an unchanged confirmation. Do not call a prompt globally optimal from one task; describe it as the best prompt for the tested task distribution.
Use the confirmed prompt as the Agent's production systemPrompt. Keep the strict result schema and per-run variables. Preserve the experiment workspace or its report so reviewers can audit why each instruction exists.
In the final handoff, report: