Cookbook

Recipe: minimal runtime bootstrap

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);

Recipe: approval-driven workflow

Use this when a run may pause for sensitive memory writes or for MCP side effects that behave like writes.

const approvals = await listApprovals(runtime);

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

Recipe: runtime memory write and recall

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?"
});

Recipe: operator dashboard data fetch

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

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

Start with getOperatorOverview(...) when the dashboard needs one control-plane snapshot first, then load deeper request or session views only where the UI actually drills in.

Recipe: export runtime evidence for offline review

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

Export bundles when CI, offline evaluators, or support workflows need durable, shareable evidence of a run.

Recipe: render a Mermaid flow

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

Use the request-first helper when you already know the persisted sessionId and requestId. The runtime loads the stored inspection data and renders the Mermaid flow in one call.

Recipe: shared MCP plus narrow agent whitelist

Register the remote MCP server once in the catalog YAML; each agent can opt in only when it needs that capability.

Recipe: serve an external protocol surface

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

Use this when the runtime should be reachable from an IDE, UI, or another agent system. Pick one boundary on purpose and document it for operators.

Recipe: agent-ops remediation workflow

Use this shape for security remediation, dependency cleanup, or maintenance work where multiple agents may attempt the same fix and an operator needs evidence before accepting a result.

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,
  })
));

Keep this as a runtime pattern, not a GitHub-specific integration: queueing, approvals, event history, and evidence export stay reusable across remediation products.

Recipe: final release check

1. Run focused tests for the changed behavior.
2. Review README, docs pages, and release notes.
3. Push to master.
4. Watch GitHub Actions on the new head commit until critical workflows pass.