Client Methods

This page documents every method available on the AgentRuntime client, organized by resource namespace.

`runtime.health()`

Check the health of the Stevora API server.

async health(): Promise<{ status: string; checks: Record<string, string> }>

Example:

const health = await runtime.health();
console.log(health);
// { status: 'healthy', checks: { database: 'ok', redis: 'ok' } }

Workflows

Accessed via runtime.workflows. Methods for creating, monitoring, and controlling workflow runs.

`workflows.create(input)`

Start a new workflow run from a definition.

async create(input: CreateRunInput): Promise<WorkflowRun>

Parameter	Type	Required	Description
`input.definitionId`	`string`	Yes	ID of the workflow definition to run
`input.input`	`Record<string, unknown>`	No	Input data passed to the workflow
`input.idempotencyKey`	`string`	No	Prevents duplicate runs when retrying requests
`input.supersessionKey`	`string`	No	Correlation key used to cancel stale live runs
`input.supersedeExisting`	`boolean`	No	Marks older live runs with the same `supersessionKey` as `SUPERSEDED`

Example:

const run = await runtime.workflows.create({
  definitionId: 'def_abc123',
  input: {
    prospectName: 'Sarah Chen',
    company: 'TechFlow AI',
    email: 'sarah@techflow.ai',
  },
  idempotencyKey: 'onboard-sarah-v1',
  supersessionKey: 'prospect-sarah-chen',
  supersedeExisting: true,
});

console.log(run.id);     // 'run_xyz789'
console.log(run.status); // 'PENDING'

`workflows.get(id)`

Retrieve a workflow run by ID, including its step runs.

async get(id: string): Promise<WorkflowRun>

Example:

const run = await runtime.workflows.get('run_xyz789');

console.log(run.status);          // 'RUNNING'
console.log(run.currentStepName); // 'enrich_lead'
console.log(run.stepRuns);        // array of StepRun objects

`workflows.list(params?)`

List workflow runs with optional pagination and filters.

async list(params?: ListRunsParams): Promise<{
  data: WorkflowRun[];
  meta: PaginationMeta;
}>

Parameter	Type	Required	Description
`params.page`	`number`	No	Page number (1-based)
`params.pageSize`	`number`	No	Number of results per page
`params.status`	`WorkflowRunStatus`	No	Filter by run status
`params.definitionId`	`string`	No	Filter by workflow definition

Example:

// List running workflows
const { data: runs, meta } = await runtime.workflows.list({
  status: 'RUNNING',
  page: 1,
  pageSize: 20,
});

console.log(`${meta.total} total runs across ${meta.totalPages} pages`);

`workflows.cancel(id)`

Cancel a running or paused workflow.

async cancel(id: string): Promise<WorkflowRun>

Example:

const cancelled = await runtime.workflows.cancel('run_xyz789');
console.log(cancelled.status); // 'CANCELLED'

`workflows.resume(id, input)`

Resume a workflow paused at an external_event step. The signal type must exactly match the step definition; timed waits and approvals cannot be bypassed through this method.

async resume(id: string, input: ResumeRunInput): Promise<{ resumed: boolean }>

Parameter	Type	Required	Description
`input.signalType`	`string`	Yes	The signal type the workflow is waiting for
`input.payload`	`Record<string, unknown>`	No	Data to pass to the resumed step

Example:

const result = await runtime.workflows.resume('run_xyz789', {
  signalType: 'payment_received',
  payload: { amount: 499, currency: 'USD' },
});

console.log(result.resumed); // true

`workflows.retry(id)`

Retry a failed workflow from its last failed step.

async retry(id: string): Promise<{ retried: boolean; stepName: string }>

Example:

const result = await runtime.workflows.retry('run_xyz789');
console.log(result.stepName); // 'send_email' — the step being retried

`workflows.getEvents(id, params?)`

Get the event timeline for a workflow run.

async getEvents(
  id: string,
  params?: { page?: number; pageSize?: number },
): Promise<{
  data: WorkflowEvent[];
  meta: PaginationMeta;
}>

Parameter	Type	Required	Description
`params.page`	`number`	No	Page number (1-based)
`params.pageSize`	`number`	No	Number of results per page

Example:

const { data: events } = await runtime.workflows.getEvents('run_xyz789');

for (const event of events) {
  console.log(`[${event.createdAt}] ${event.eventType}`, event.payload);
}

`workflows.getCost(id)`

Get the cost breakdown for a specific workflow run, including individual LLM calls.

async getCost(id: string): Promise<RunCost>

Example:

const cost = await runtime.workflows.getCost('run_xyz789');

console.log(`Total: $${cost.totalCostDollars}`);
for (const call of cost.calls) {
  console.log(`  ${call.model}: ${call.inputTokens}in / ${call.outputTokens}out`);
}

`workflows.getTraces(id)`

Get LLM call and tool execution traces for a workflow run.

async getTraces(id: string): Promise<LlmCall[]>

Example:

const traces = await runtime.workflows.getTraces('run_xyz789');

for (const call of traces) {
  console.log(`${call.provider}/${call.model} — ${call.durationMs}ms`);
  for (const tool of call.toolTraces ?? []) {
    console.log(`  tool: ${tool.toolName} [${tool.status}]`);
  }
}

`workflows.waitForCompletion(id, options?)`

Poll a workflow run until it reaches a terminal state (COMPLETED, FAILED, CANCELLED, or SUPERSEDED). Returns the final WorkflowRun.

async waitForCompletion(
  id: string,
  options?: { pollIntervalMs?: number; timeoutMs?: number },
): Promise<WorkflowRun>

Option	Type	Default	Description
`pollIntervalMs`	`number`	`2000`	Milliseconds between polling requests
`timeoutMs`	`number`	`3600000`	Maximum wait time in milliseconds (default: 1 hour)

Throws an Error if the workflow does not reach a terminal state before the timeout.

Example:

const run = await runtime.workflows.create({
  definitionId: 'def_abc123',
  input: { query: 'Summarize Q4 metrics' },
});

const completed = await runtime.workflows.waitForCompletion(run.id, {
  pollIntervalMs: 5000,
  timeoutMs: 120000, // 2 minutes
});

if (completed.status === 'COMPLETED') {
  console.log('Output:', completed.output);
} else {
  console.log('Failed:', completed.error);
}

Definitions

Accessed via runtime.definitions. Methods for managing reusable workflow definitions.

`definitions.create(input)`

Create a new workflow definition.

async create(input: CreateDefinitionInput): Promise<WorkflowDefinition>

Parameter	Type	Required	Description
`input.name`	`string`	Yes	Human-readable name for the definition
`input.version`	`string`	Yes	Version string (e.g., `"1.0.0"`)
`input.description`	`string`	No	Description of what this workflow does
`input.steps`	`Record<string, unknown>[]`	Yes	Array of step configuration objects

Example:

const def = await runtime.definitions.create({
  name: 'Lead Enrichment',
  version: '1.0.0',
  description: 'Enrich and score inbound leads',
  steps: [
    { name: 'enrich', type: 'LLM', model: 'gpt-4o', prompt: '...' },
    { name: 'score', type: 'TASK', handler: 'scoreLead' },
    { name: 'review', type: 'APPROVAL', assignee: 'sales-team' },
  ],
});

console.log(def.id); // 'def_abc123'

`definitions.get(id)`

Retrieve a workflow definition by ID.

async get(id: string): Promise<WorkflowDefinition>

Example:

const def = await runtime.definitions.get('def_abc123');
console.log(`${def.name} v${def.version} — active: ${def.isActive}`);

`definitions.list()`

List all active workflow definitions in the workspace.

async list(): Promise<WorkflowDefinition[]>

Example:

const definitions = await runtime.definitions.list();

for (const def of definitions) {
  console.log(`${def.name} (v${def.version})`);
}

Approvals

Accessed via runtime.approvals. Methods for managing human-in-the-loop approval requests.

`approvals.list(options?)`

List approval requests, optionally filtering to only pending requests.

async list(options?: { pending?: boolean }): Promise<ApprovalRequest[]>

Option	Type	Required	Description
`pending`	`boolean`	No	When `true`, only returns undecided approval requests

Example:

const pending = await runtime.approvals.list({ pending: true });

for (const req of pending) {
  console.log(`Approval ${req.id} for run ${req.workflowRunId}`);
  console.log('Content:', req.content);
}

`approvals.decide(id, input)`

Submit a decision on an approval request. This is the general-purpose method that supports all three decision types.

async decide(
  id: string,
  input: DecideApprovalInput,
): Promise<{ decided: boolean }>

Parameter	Type	Required	Description
`input.decision`	`'approved' \| 'rejected' \| 'edited'`	Yes	The decision
`input.editedContent`	`Record<string, unknown>`	No	Modified content (for `'edited'` decisions)
`input.decidedBy`	`string`	No	Identifier of the person or system making the decision

Example:

// Approve with edits
await runtime.approvals.decide('apr_123', {
  decision: 'edited',
  editedContent: { subject: 'Updated subject line', body: '...' },
  decidedBy: 'ops@example.com',
});

`approvals.approve(id, decidedBy?)`

Shorthand to approve a request. Equivalent to calling decide() with decision: 'approved'.

async approve(id: string, decidedBy?: string): Promise<{ decided: boolean }>

Example:

await runtime.approvals.approve('apr_123', 'ops@example.com');

`approvals.reject(id, decidedBy?)`

Shorthand to reject a request. Equivalent to calling decide() with decision: 'rejected'.

async reject(id: string, decidedBy?: string): Promise<{ decided: boolean }>

Example:

await runtime.approvals.reject('apr_123', 'ops@example.com');

Costs

Accessed via runtime.costs. Methods for querying aggregated cost data.

`costs.summary(options?)`

Get an aggregated cost summary for the workspace, optionally scoped to a date range.

async summary(options?: { from?: string; to?: string }): Promise<CostSummary>

Option	Type	Required	Description
`from`	`string`	No	Start date in ISO 8601 format (e.g., `'2025-01-01'`)
`to`	`string`	No	End date in ISO 8601 format (e.g., `'2025-01-31'`)

Example:

const summary = await runtime.costs.summary({
  from: '2025-03-01',
  to: '2025-03-31',
});

console.log(`March total: $${summary.totalCostDollars}`);
console.log(`${summary.totalCalls} LLM calls`);
console.log(`${summary.totalInputTokens} input tokens`);
console.log(`${summary.totalOutputTokens} output tokens`);

for (const model of summary.byModel) {
  console.log(`  ${model.model}: ${model.calls} calls, $${(model.costCents / 100).toFixed(2)}`);
}

Remote tools

Accessed via runtime.remoteTools. Register HTTPS endpoints that LLM steps can call through Stevora.

`remoteTools.create(input)`

async create(input: CreateRemoteToolInput): Promise<RemoteTool & { secret: string }>

const tool = await runtime.remoteTools.create({
  name: 'lookup_customer',
  url: 'https://api.example.com/stevora-tools/customer',
  timeoutMs: 10000,
});

console.log(tool.secret); // shown once; use it to verify Stevora signatures

Names must start with a letter and may contain letters, numbers, _, or - (maximum 64 characters). URLs must be public HTTPS endpoints. timeoutMs must be between 100 and 30,000.

`remoteTools.list()`

async list(): Promise<RemoteTool[]>

const tools = await runtime.remoteTools.list();

Secrets are never returned by this method.

`remoteTools.delete(id)`

async delete(id: string): Promise<{ deleted: boolean }>

await runtime.remoteTools.delete(tool.id);

Client Methods

On this page