Cookbook

配方：最小 runtime 启动

import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";

const runtime = await createAgentHarness("/absolute/path/to/workspace");
const result = await request(runtime, {
  agent: "orchestra",
  input: "Review the repository and propose one next change."
});

console.log(result.output);
await stop(runtime);

配方：审批驱动流程

若一次运行可能因敏感 memory 写入，或具有写入语义的 MCP 副作用而暂停，请用本模式处理审批。

const approvals = await listApprovals(runtime);

await resolveApproval(runtime, {
  sessionId: approvals[0].sessionId,
  requestId: approvals[0].requestId,
  approvalId: approvals[0].approvalId,
  decision: "approved",
  message: "Proceed"
});

配方：写入并召回 runtime memory

await memorize(runtime, {
  records: [
    {
      scope: "workspace",
      kind: "fact",
      content: "Prefer backend: deepagent for orchestration-first agent shapes."
    }
  ]
});

const recalled = await recall(runtime, {
  query: "Which backend should we prefer for orchestration?"
});

配方：operator dashboard 数据加载

const overview = await getOperatorOverview(runtime, { limit: 10 });

const [requests, sessions] = await Promise.all([
  listRequests(runtime),
  listSessions(runtime),
]);

当 dashboard 先需要一张稳定控制面快照时，优先从 getOperatorOverview(...) 开始，再在 UI 深钻时补拉 request / session 细节。

配方：导出运行证据包

const bundle = await exportEvaluationBundle(runtime, {
  sessionId,
  requestId,
});

当 CI、离线评估或支持流程需要稳定、可分享的运行证据时，优先导出 bundle，避免直接依赖底层持久化实现细节。

配方：生成 Mermaid 流程图

const mermaid = await exportFlow(runtime, {
  sessionId,
  requestId,
});

当你已经拿到持久化的 sessionId 与 requestId 时，直接使用这个 request-first helper 即可。runtime 会在一次调用里加载检查数据并输出 Mermaid 流程图。

配方：共享 MCP + agent 白名单

在 catalog 中只注册一次远程 MCP server，各 agent 按需接入，避免默认向所有 agent 暴露全部远程能力。

配方：暴露外部协议接入

await serveAcpHttp(runtime, { port: 8787 });
await serveA2aHttp(runtime, { port: 8788 });
await serveAgUiHttp(runtime, { port: 8789 });

当 runtime 需要被 IDE、UI 或其他 agent 系统接入时，使用这个模式。明确选定一条 boundary，并在 operator 文档里写清楚。

配方：agent ops remediation workflow

当安全修复、依赖清理或维护任务需要多个 agent 独立尝试同一修复，并由 operator 在接受结果前查看证据时，使用这个模式。

const attempts = await Promise.all([
  request(runtime, { agentId: "fixer-a", input: "Draft a patch and explain the test plan." }),
  request(runtime, { agentId: "fixer-b", input: "Draft an independent patch and explain the test plan." }),
]);

const overview = await getOperatorOverview(runtime, { limit: 20 });
const evidence = await Promise.all(attempts.map((attempt) =>
  exportEvaluationBundle(runtime, {
    sessionId: attempt.sessionId,
    requestId: attempt.requestId,
  })
));

这里保持为 runtime pattern，而不是 GitHub 专属集成：queueing、approvals、event history 与 evidence export 都应复用到不同 remediation 产品里。

配方：最终发布检查

1. 针对变更跑聚焦测试。
2. 核对 README、文档页与 release notes。
3. 推送到 master。
4. 在 GitHub Actions 中关注新 head commit，直至关键 workflow 全部通过。