Core

Running agents

Every execution — a single agent or a whole swarm — is a run. Kick one off, then read, poll, stream, or wait for it. Runs are asynchronous: kickoff returns a runId immediately.

Kick off a run#

runAgent(agentId, opts)

One-shot run of a single agent. Returns the runId immediately.

const { runId } = await bahini.runAgent("agent_123", {
  prompt: "Draft a reply to this ticket.",
  metadata: { ticketId: "T-4821" }, // your correlation data
});

runPreset(presetId, opts)

Run a saved swarm/coordinator preset with one prompt.

const { runId } = await bahini.runPreset("preset_monthly_review", {
  prompt: "Prepare the June board deck.",
  idempotencyKey: "june-2026-board",
});

Idempotency. Pass idempotencyKey and the server dedupes — a retried call returns the same run instead of firing a second one. It also makes the POST safe to auto-retry on a network blip.

Wait for the result#

waitForRun(runId, opts)

Polls until the run reaches a terminal status or WAITING_FOR_APPROVAL. Configurable interval, timeout, and an onPoll callback.

const detail = await bahini.waitForRun(runId, {
  intervalMs: 3000,
  timeoutMs: 600_000,
  onPoll: (d) => console.log(d.run.status),
});

watchRun(runId, opts)

Streams live progress — invokes onEvent for each new run event (client-side polling, no server SSE) and resolves with the final detail.

const final = await bahini.watchRun(runId, {
  onEvent: (e) => console.log(e.eventType, e.message),
});
console.log("done:", final.run.status);

runAgentAndWait(agentId, opts)

The convenience wrapper: kick off + wait in a single call.

Read a run#

Several lenses on a run, each its own endpoint:

const detail     = await bahini.getRun(runId);            // status, output, steps, approvals
const transcript = await bahini.getRunTranscript(runId);  // chronological event log
const evalResult = await bahini.getRunEval(runId);        // golden-suite verdict (CI gate)
const cost       = await bahini.getRunCost(runId);        // USD + token usage
const dag        = await bahini.getRunDag(runId);         // live swarm graph (or null)

List & filter#

listRuns returns runs newest-first. Filter by status, agent, preset, or your own correlation metadata — find every run for a customer or ticket.

const { runs } = await bahini.listRuns({
  status: "FAILED",
  clientKey: "ticketId",
  clientValue: "T-4821",
  limit: 50,
});

Approvals#

When a run parks at WAITING_FOR_APPROVAL, resolve the gate from code with decideApproval.

const detail = await bahini.waitForRun(runId);
if (detail.run.status === "WAITING_FOR_APPROVAL") {
  await bahini.decideApproval(detail.approvals[0].id, { decision: "approve" }); // or "reject"
}

Cancel#

await bahini.cancelRun(runId); // stop an in-flight run

PreviousAuthentication Next Agents as code