optimize-agent-prompt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Optimize Agent Prompt

优化Agent提示词

Optimize 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.

在固定任务、结果schema、变量和评估标准的前提下，优化Browserbase Agent的

systemPrompt

。将外部Agent视为教师，每次Browserbase Agent运行视为内部Agent的部署。

使用Node.js 18或更高版本，并设置

BROWSERBASE_API_KEY

。该工具仅使用Node.js内置模块。

Set up the experiment

设置实验

Choose a short experiment name and create an isolated workspace inside the demo or POC repository:

bash

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.

选择一个简短的实验名称，并在演示或POC仓库内创建一个独立工作区：

bash

node <skill-dir>/scripts/optimize_agent_prompt.mjs init \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --name <experiment-name>

编辑生成的文件：

```
task.json
```
：在迭代过程中保持
```
task
```
、
```
resultSchema
```
、变量、浏览器设置和评估规则稳定。
```
prompts/iteration-001.md
```
：编写最小化的基准系统提示词。适用时包含不可逆操作防护规则。

使用明确的成功标准。优先使用包含必填字段和

null

（用于表示不可用事实）的严格JSON Schema。当存在事实校验源时，在

evaluation

下添加已知字段正则表达式和事实性警告正则表达式。设计任务或评分规则时，请阅读references/evaluation.md。

Run the baseline

运行基准测试

bash

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:

text

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

bash

node <skill-dir>/scripts/optimize_agent_prompt.mjs run \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --prompt prompts/iteration-001.md \
  --label iteration-001

该工具会创建一个可复用的Browserbase Agent，在后续迭代中更新其

systemPrompt

，启动运行、轮询消息和状态，并生成以下文件：

text

runs/<label>/
├── system-prompt.md
├── created-run.json
├── run.json
├── messages.json
├── session-logs.json
└── summary.json

它会在达到配置的消息预算后停止运行，避免为无效的循环付费。仅当任务需要与

task.json

不同的值时，才使用

--max-messages

、

--timeout-ms

、

--proxies

或

--verified

参数。

Diagnose from observable evidence

基于可观测证据诊断问题

Start with the compact trajectory:

bash

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.

先查看简洁的运行轨迹：

bash

node <skill-dir>/scripts/optimize_agent_prompt.mjs inspect \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --label iteration-001

然后阅读

summary.json

，并深入查看

messages.json

中第一次出现错误或无效操作的节点。Agent消息会展示有序的工具调用、工具结果、错误和最终输出。

reasoning

部分可能没有可读文本；教师循环永远不需要依赖隐藏的思维链。

仅当浏览器层面的证据能区分问题原因时，才阅读

session-logs.json

——例如重定向、403错误、请求失败、控制台错误或隐藏端点。空的会话日志可能意味着Agent通过搜索/获取工具完成了任务，从未驱动浏览器。

有关端点结构、分页、结果标准化和跟踪注意事项，请参阅references/api.md。

Improve one heuristic

改进一项启发式规则

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:

cap retries after a repeated block or identical error;
distinguish public identifiers from private/internal IDs;
prefer search/fetch before launching a browser when interaction is unnecessary;
separate current snapshots from dated historical events;
define when a qualified fallback counts as completed;
require
```
null
```
instead of guessed values;
add a tool-call or evidence budget.

Keep wins. If the new run regresses, restore the previous prompt and test a different hypothesis rather than stacking more rules.

找到最早的关键失败点，并提出一个反事实假设：

如果系统提示词中包含X指令，Agent就会避免Y问题，如工具结果Z所示。

将当前提示词复制到

prompts/iteration-NNN.md

，并做出一项可归因的修改。典型的改进包括：

在重复阻塞或相同错误后限制重试次数；
区分公共标识符与私有/内部ID；
当无需交互时，优先使用搜索/获取工具而非启动浏览器；
区分当前快照与历史事件；
定义合格的回退方案何时算作任务完成；
要求使用
```
null
```
而非猜测值；
添加工具调用或证据预算。

保留有效的改进。如果新运行出现退化，恢复之前的提示词并测试不同的假设，而非叠加更多规则。

Judge and converge

评估并确认收敛

Generate the comparison table after each run:

bash

node <skill-dir>/scripts/optimize_agent_prompt.mjs report \
  --workspace ./agent-prompt-optimization/<experiment-name>

Judge more than field completeness. Require:

terminal status
```
COMPLETED
```
;
required fields populated or explicitly nullable;
known-fact checks passing when available;
no factuality-warning match;
provenance and safety constraints preserved;
fewer messages or lower duration without quality loss.

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.

每次运行后生成对比表格：

bash

node <skill-dir>/scripts/optimize_agent_prompt.mjs report \
  --workspace ./agent-prompt-optimization/<experiment-name>

评估时不要只看字段完整性，还需满足：

终端状态为
```
COMPLETED
```
；
必填字段已填充或明确标记为可空；
已知事实校验（若可用）通过；
未匹配到事实性警告；
来源和安全约束得到保留；
在不损失质量的前提下，消息数量更少或耗时更短。

一旦某个提示词胜出，使用新标签再次运行相同的提示词。仅当它在最近三次运行中至少通过两次，且其中一次是无修改的确认运行时，才确认收敛。不要仅凭一项任务就称某个提示词为全局最优；应描述为针对测试任务分布的最佳提示词。

Graduate into the demo

迁移至演示环境

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:

baseline versus winning score, duration, and message count;
the first wrong turn each prompt change fixed;
whether session logs added evidence;
the winning prompt path;
confirmation-run results;
limitations and the next holdout matrix.

将确认有效的提示词作为Agent的生产环境

systemPrompt

。保留严格的结果schema和每次运行的变量。保留实验工作区或其报告，以便审核者可以了解每条指令存在的原因。

在最终交付时，需报告：

基准与胜出提示词的评分、耗时和消息数量对比；
每次提示词修改修复的首个错误点；
会话日志是否提供了额外证据；
胜出提示词的迭代路径；
确认运行的结果；
局限性以及后续的测试矩阵。