optimize-agent-prompt

优化 Agent 提示词

在保持任务、结果架构、变量和评估标准不变的前提下，优化 Browserbase Agent 的 systemPrompt。将外层 Agent 视为教师，将每次 Browserbase Agent 运行视为一次内层 Agent rollout。

使用 Node.js 18 或更高版本，并设置 BROWSERBASE_API_KEY。此测试框架仅使用 Node.js 内置模块。

设置实验

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

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。

运行基线

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，启动运行，轮询消息和状态，并写入：

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。

根据可观察证据诊断

先查看简明的执行轨迹：

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。

改进一条启发式规则

找出最早造成显著影响的失败，并陈述一个反事实：

如果系统提示词指示 Agent 执行 X，Agent 就会避免 Y，工具结果 Z 可以证明这一点。

将当前提示词复制到 prompts/iteration-NNN.md，并做出一项可归因的更改。常见改进包括：

• 遇到重复拦截或相同错误时限制重试次数；
• 区分公开标识符与私有／内部 ID；
• 在不需要交互时，优先搜索／抓取，再启动浏览器；
• 区分当前快照与带日期的历史事件；
• 明确何时可将带条件的回退方案视为已完成；
• 要求使用 null，而不是猜测值；
• 添加工具调用或证据预算。

保留有效改进。如果新运行的表现退步，就恢复之前的提示词，并测试不同假设，而不是不断叠加规则。

评判并收敛

每次运行后生成对比表：

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

评判时不应只看字段完整度。还需满足以下要求：

• 终止状态为 COMPLETED；
• 必填字段已填写，或明确标记为可空；
• 在可用时通过已知事实检查；
• 未匹配任何事实性警告；
• 保留来源信息和安全约束；
• 在质量不下降的情况下减少消息数或缩短持续时间。

提示词胜出后，使用新的标签，不作任何更改，再运行一次。只有在最近三次运行中至少两次通过，且其中一次为未经更改的确认运行后，才能认为结果已收敛。不要根据单个任务声称提示词普遍最优；应将其描述为针对已测试任务分布的最佳提示词。

迈向演示阶段

将确认后的提示词用作 Agent 的生产 systemPrompt。保留严格的结果架构和每次运行的变量。保留实验工作区或其报告，以便审阅者审核每条指令存在的原因。

在最终交接中，报告：

• 基线与获胜方案的分数、耗时和消息数量；
• 每次提示词更改修复的第一个错误步骤；
• 会话日志是否提供了额外证据；
• 获胜提示词的路径；
• 确认运行的结果；
• 局限性及下一组留出测试矩阵。