sapiom runtime

Run agents that
wait, then resume.

Deploy typed agents that pause for signals, resume at named steps, and stay inspectable from local test to cloud run.

Start building free Read the runtime guide

defineAgentpauseUntilSignalrun_local

sapiom runtime lifecycle

$ npx @sapiom/cli agents run

Checksapiom_dev_agents_check

Run localsapiom_dev_agents_run_local

Deploysapiom_dev_agents_deploy

Runsapiom_dev_agents_run

Inspectsapiom_dev_agents_inspect

Schedulesapiom_dev_agents_schedule

run inspector waiting

prepcompleted

enrichcompleted

approvalwaiting

finalizeresume step

signalmy.approval scopectx.executionId

The runtime follows the graph you wrote.

Each step names its allowed destinations, and its returned directive chooses the next action. Unexpected errors and explicit retries share a bounded attempt budget.

Make every transition explicit.

goto, terminate, fail, retry, and pauseUntilSignal describe the complete result of a step.

Read the directive reference

Step directives@sapiom/agent

Continuegoto

Completeterminate

Stop with errorfail

Try againretry

WaitpauseUntilSignal

Use the attempt budget deliberately.

The attempt count is zero-based. Unexpected errors and explicit retry directives share the runtime cap; return fail for a known terminal case.

canFail: true,
async run(_input, ctx) {
  if (ctx.attempts + 1 < 3) {
    return retry({ delayMs: 1000 })
  }

  return fail("too many attempts")
}

Pause until the signal arrives.

A step declares the signal and its resume step. The runtime suspends the execution, then delivers the result payload to the declared step when the signal fires.

Read pause and resume

return pauseUntilSignal({
  signal: "my.approval",
  resumeStep: "finalize",
  correlationId: ctx.executionId
})

Use one lifecycle from local to cloud.

Run real step bodies with Sapiom capability calls served by local stubs, then link, deploy, run, inspect, and schedule the deployed agent with the developer tools.

Follow the lifecycle

Runtime lifecyclesapiom-dev MCP

Checksapiom_dev_agents_check

Run localsapiom_dev_agents_run_local

Deploysapiom_dev_agents_deploy

Runsapiom_dev_agents_run

Inspectsapiom_dev_agents_inspect

Schedulesapiom_dev_agents_schedule

A runtime with an explicit contract.

Define the graph

Export one defineAgent with an entry step and the complete map of typed steps.

Prove it locally

Bundle and validate the graph, then execute real step bodies with Sapiom capability calls served by stubs.

Deploy and observe

Start or schedule a cloud run, deliver signals when needed, and inspect steps or errors.

Run the agent you can explain.

Start with a typed graph, validate it locally, and keep every transition explicit.