Lifecycle
Start, stop, and subscribe to the runtime.
createAgentHarness(...)
stop(...)
subscribe(...)Minimal startup
import { createAgentHarness, stop } from "@botbotgo/agent-harness";
const runtime = await createAgentHarness("/absolute/path/to/workspace");
await stop(runtime);Run execution
request(...)
cancelRequest(...)
normalizeUserChatInput(...)
Use request(...) for one request against one selected host agent. Use
normalizeUserChatInput(...) when a product needs to map chat-style multimodal user input onto
the stable runtime surface.
Inspection and operator queries
Health and operator
getHealth(...)
getOperatorOverview(...)
Requests
listRequests(...)
getRequest(...)
listRequestEvents(...)
Sessions
listSessions(...)
listSessionSummaries(...)
getSession(...)
Approvals
listApprovals(...)
getApproval(...)Use listRequests and getRequest for dashboards, review queues, and request history.
Use listSessions for lightweight session identity, state, and timestamp queries.
Use listSessionSummaries when a conversation list needs title, snippet, message count, and last message role without hydrating full session records.
Use getSession for transcripts, requests, and pending approval context after a user picks one session.
Use getOperatorOverview when one operator surface needs health, queue pressure, pending approvals, active requests, and governance risk in one call.
Approvals
resolveApproval(...)Approval decisions are product-facing. Resolve them through the runtime surface instead of exposing checkpoint orchestration to the app.
Runtime memory
memorize(...)
recall(...)
listMemories(...)
updateMemory(...)
removeMemory(...)These helpers expose a stable public memory surface while keeping merge, projection rebuilds, vector indexing, and storage layout runtime-managed.
Artifacts and export packages
listArtifacts(...)
getArtifact(...)
recordArtifact(...)
exportRequestPackage(...)
exportSessionPackage(...)
exportEvaluationBundle(...)
replayEvaluationBundle(...)Use these helpers when operator tooling or offline evaluation needs stable, exported runtime evidence rather than direct access to persistence internals. Request and session packages now carry governance evidence alongside approvals, events, transcript, artifacts, and optional runtime health snapshots. `recordArtifact(...)` lets the application attach app-owned files such as product specs, sprint contracts, and QA reports to the same persisted run surface before export.
Transport and protocol adapters
createAcpServer(...)
createAcpStdioClient(...)
serveAcpStdio(...)
serveAcpHttp(...)
serveA2aHttp(...)
serveAgUiHttp(...)
createRuntimeMcpServer(...)
serveRuntimeMcpOverStdio(...)
createToolMcpServer(...)
serveToolsOverStdio(...)Use ACP, A2A, AG-UI, runtime MCP, and tool MCP adapters when an external control plane, IDE, remote client, or agent runtime needs access to the persisted runtime boundary without importing internal persistence or adapter modules.
Use createAcpStdioClient(...) for IDE or CLI sidecars that need a small reference client for
newline-delimited ACP JSON-RPC over stdio rather than custom line parsing.
Flow inspection utilities
exportFlow(...)
exportSequence(...)
createUpstreamTimelineReducer(...)These helpers are inspection utilities, not a second execution protocol. Use them to visualize persisted runtime events and optional upstream traces.
Inventory and discovery helpers
describeInventory(...)
getAgent(...)
listAgentSkills(...)Use these helpers when products need to expose what the runtime has loaded and what each agent can use.
Administrative helpers
deleteSession(...)Use deleteSession(...) when a completed session should be explicitly removed from the runtime surface.