Skip to content
AgentsKit

@agentskit/runtime β€” Functions

API functions for @agentskit/runtime.

#Function: blackboard()

blackboard<TContext>(config): AgentHandle<TContext>

Defined in: topologies.ts:292

Create a blackboard topology that lets agents coordinate through shared state.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#config

BlackboardConfig<TContext>

Agent and blackboard settings.

#Returns

AgentHandle<TContext>

A handle for running and managing the topology.


#Function: compileFlow()

compileFlow<TInput>(options): CompiledFlow<TInput>

Defined in: flow.ts:218

Validate and compile a flow into a durable DAG runner.

#Type Parameters

#TInput

TInput = unknown

#Parameters

#options

CompileFlowOptions<TInput>

Flow definition and handler registry.

#Returns

CompiledFlow<TInput>

Compiled flow with its execution order and run method.

#Throws

When the definition has validation issues.


#Function: createAuctionHandler()

createAuctionHandler<Ctx>(opts): (node, input, ctx) => Promise<TopologyOutcome>

Defined in: multi-agent-auction.ts:70

Create a handler that collects bids and selects one according to configured criteria.

#Type Parameters

#Ctx

Ctx

#Parameters

#opts

AuctionHandlerOptions<Ctx>

Agent runner and auction configuration.

#Returns

An async handler resolving to an ok, failed, or paused outcome.

(node, input, ctx) => Promise<TopologyOutcome>


#Function: createChatTrigger()

createChatTrigger<TContext>(options): ChatTrigger

Defined in: chat-trigger.ts:253

Build a unified chat-surface trigger. Wire the returned handler into your HTTP framework (Express / Hono / Next route handler) at the surface's webhook URL.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#options

ChatTriggerOptions<TContext>

#Returns

ChatTrigger


#Function: createCompareHandler()

createCompareHandler<Ctx>(opts): (node, input, ctx) => Promise<TopologyOutcome>

Defined in: multi-agent-compare.ts:107

Create a fan-out handler that runs agents and selects or combines their results.

#Type Parameters

#Ctx

Ctx

#Parameters

#opts

CompareHandlerOptions<Ctx>

Agent runner, comparison configuration, and optional selection helpers.

#Returns

An async handler resolving to an ok, failed, or paused outcome.

(node, input, ctx) => Promise<TopologyOutcome>


#Function: createCronScheduler()

createCronScheduler<TContext>(options): CronScheduler

Defined in: background.ts:177

Create a scheduler that dispatches a job when its cron or interval schedule is due.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#options

CronSchedulerOptions<TContext>

Schedule, job callback, clock, and error handling options.

#Returns

CronScheduler

A scheduler with start and stop controls.


#Function: createDebateHandler()

createDebateHandler<Ctx>(opts): (node, input, ctx) => Promise<TopologyOutcome>

Defined in: multi-agent-debate.ts:20

Create a handler that alternates proponent and opponent agents before a judge decides.

#Type Parameters

#Ctx

Ctx

#Parameters

#opts

DebateHandlerOptions<Ctx>

Agent runner and debate configuration.

#Returns

An async handler resolving to an ok, failed, or paused outcome.

(node, input, ctx) => Promise<TopologyOutcome>


#Function: createDurableRunner()

createDurableRunner(options): DurableRunner

Defined in: durable.ts:103

Create a runner that records step results and replays completed steps for a run.

#Parameters

#options

DurableRunnerOptions

Store, run identifier, retry policy, abort signal, and event callback.

#Returns

DurableRunner

A runner with step, history, and reset operations.

#Throws

When a recorded step failed or an operation is aborted.


#Function: createFileStepLog()

createFileStepLog(path): Promise<StepLogStore>

Defined in: durable.ts:243

File-backed StepLogStore β€” persists every step as one JSONL line.

#Parameters

#path

string

#Returns

Promise<StepLogStore>


#Function: createInMemoryStepLog()

createInMemoryStepLog(): StepLogStore

Defined in: durable.ts:218

In-memory StepLogStore β€” tests, single-process demos, examples.

#Returns

StepLogStore


#Function: createQuotaTracker()

createQuotaTracker(options): QuotaTracker

Defined in: quota.ts:95

Create per-run and sliding-window quota counters for tools.

#Parameters

#options

QuotaTrackerOptions

Quota limits, environment, event callback, and optional clock.

#Returns

QuotaTracker

Tracker methods for admission checks, recording, release, reset, and snapshots.


#Function: createRuntime()

createRuntime(config): object

Defined in: runner.ts:96

Create a headless agent runtime.

#Parameters

#config

RuntimeConfig

Runtime defaults, overridden by supported run options.

#Returns

object

A run(task, options?) agent runner.

#run()

run(task, options?): Promise<RunResult>

#Parameters

task

string

options?

RunOptions

#Returns

Promise<RunResult>

#Example

`const result = await createRuntime({ adapter }).run('Summarize this report')`

#Function: createSharedContext()

createSharedContext(initial?): SharedContext

Defined in: shared-context.ts:18

Create shared context initialized from an optional object.

#Parameters

#initial?

Record<string, unknown>

Initial key-value pairs.

#Returns

SharedContext

Context with read and write operations.

#Example

`const context = createSharedContext({ userId: 'u1' })`

#Function: createValidatorGuard()

createValidatorGuard(options): ValidatorGuard

Defined in: validator-guard.ts:132

Create a guard that validates tool inputs and outputs and applies configured retry or block actions.

#Parameters

#options

ValidatorGuardOptions

Validators, retry settings, and audit callback.

#Returns

ValidatorGuard

A guard for wrapping tool execution.

#Throws

When validation blocks a tool call.


#Function: createVoteHandler()

createVoteHandler<Ctx>(opts): (node, input, ctx) => Promise<TopologyOutcome>

Defined in: multi-agent-vote.ts:116

Create a fan-out handler that collects ballots and resolves a vote.

#Type Parameters

#Ctx

Ctx

#Parameters

#opts

VoteHandlerOptions<Ctx>

Agent runner, ballot policy, and optional tie-break judge.

#Returns

An async handler resolving to an ok, failed, or paused outcome.

(node, input, ctx) => Promise<TopologyOutcome>


#Function: createWebhookHandler()

createWebhookHandler<TContext>(options): WebhookHandler

Defined in: background.ts:297

Build a framework-agnostic webhook handler. Wire into Express / Hono / Next API routes by passing in the parsed request and piping the returned response.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#options

WebhookOptions<TContext>

#Returns

WebhookHandler


#Function: cronMatches()

cronMatches(schedule, now): boolean

Defined in: background.ts:150

Check whether a parsed cron schedule matches a date.

#Parameters

#schedule

ParsedCron

Parsed five-field cron schedule.

#now

Date

Date to check.

#Returns

boolean

Whether every cron field matches the date.


#Function: denyPattern()

denyPattern(pattern, name?): Validator

Defined in: validator-guard.ts:231

Regex-deny validator. Fails when the pattern matches.

#Parameters

#pattern

RegExp

#name?

string = 'deny-pattern'

#Returns

Validator


#Function: flowToMermaid()

flowToMermaid(def): string

Defined in: flow.ts:292

Render a FlowDefinition as a Mermaid flowchart TD. Used by the visual editor's preview pane and by agentskit flow render.

#Parameters

#def

FlowDefinition

#Returns

string


#Function: hierarchical()

hierarchical<TContext>(config): AgentHandle<TContext>

Defined in: topologies.ts:240

Create a hierarchical topology with parent and child agents.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#config

HierarchicalConfig<TContext>

The root and child hierarchy configuration.

#Returns

AgentHandle<TContext>

A handle for running and managing the hierarchy.


#Function: invokeStructured()

invokeStructured<T>(opts): Promise<T>

Defined in: structured.ts:22

Run a skill that must produce STRUCTURED output, and return it validated β€” the first-class version of the pattern every pipeline agent hand-rolls (offer one submit_* tool, run, read it back from result.toolCalls, parse).

The model's only job is to call tool once; execute just acknowledges. The parse callback validates the args (e.g. (a) => MySchema.parse(a) with Zod) so this stays dependency-free β€” the runtime never imports Zod.

const cls = await invokeStructured({
  adapter, skill: classifier, task,
  tool: submitClassificationTool,
  parse: (args) => Classification.parse(args),
})

#Type Parameters

#T

T

#Parameters

#opts

#adapter

AdapterFactory

#maxSteps?

number

#memory?

ChatMemory

#observers?

Observer[]

#onConfirm?

(toolCall) => boolean | Promise<boolean>

#parse

(args) => T

Validate + shape the tool args (throws on invalid).

#signal?

AbortSignal

#skill?

SkillDefinition

#task

string

#tool

ToolDefinition

The submit tool the skill must call exactly once.

#tools?

ToolDefinition<Record<string, unknown>>[]

Extra tools available during the run (besides tool).

#Returns

Promise<T>


#Function: isJson()

isJson(options?): Validator

Defined in: validator-guard.ts:261

JSON-parse validator. Fails when the output is not valid JSON.

#Parameters

#options?

#maxRetries?

number

#name?

string

#repairPrompt?

string

#Returns

Validator


#Function: lengthRange()

lengthRange(options): Validator

Defined in: validator-guard.ts:248

Length-bounds validator. Useful for token-budget guarantees.

#Parameters

#options

#max?

number

#min?

number

#name?

string

#Returns

Validator


#Function: parseSchedule()

parseSchedule(schedule): ParsedSchedule

Defined in: background.ts:111

Parse a five-field cron expression or every:&lt;milliseconds> schedule.

#Parameters

#schedule

string

Schedule string to parse.

#Returns

ParsedSchedule

Parsed schedule fields for matching.

#Throws

When the schedule syntax is invalid.


#Function: piiDenyValidator()

piiDenyValidator(opts?): Validator

Defined in: pii-validator.ts:18

A Validator that FAILS when the agent's output still contains PII β€” the bridge between @agentskit/core/security's redactor and the createValidatorGuard chain. Use it as a deterministic last-line gate on agents that must not leak PII (redaction, summarization, anything exporting cross-tenant), instead of trusting the system prompt to do it.

import { createValidatorGuard, piiDenyValidator } from '@agentskit/runtime'
const guard = createValidatorGuard({ validators: [piiDenyValidator()] })

Default onFail: 'block' β€” a PII leak is not something to silently retry past.

#Parameters

#opts?

#name?

string

#onFail?

ValidatorAction

#rules?

PIIRule[]

#Returns

Validator


#Function: resolveConcurrency()

resolveConcurrency(limit): number

Defined in: multi-agent.ts:154

Resolve a concurrency limit from optional opts, falling back to the default.

#Parameters

#limit

number | undefined

#Returns

number


#Function: settleWithConcurrency()

settleWithConcurrency<I, T>(items, limit, fn): Promise<PromiseSettledResult<T>[]>

Defined in: multi-agent.ts:40

Run fn over items with at most limit calls in flight at once, returning a PromiseSettledResult per item in input order β€” a concurrency-bounded drop-in for Promise.allSettled(items.map(fn)).

#Type Parameters

#I

I

#T

T

#Parameters

#items

readonly I[]

#limit

number

#fn

(item, index) => Promise<T>

#Returns

Promise<PromiseSettledResult<T>[]>


#Function: speculate()

speculate(input): Promise<SpeculateOutput>

Defined in: speculate.ts:101

Fan out a request to N adapters in parallel, then pick the winner. Common pattern: run a cheap+fast model alongside a slow+accurate one and take whichever finishes first, or use a custom picker to score results (e.g. pick longest, most-on-topic, lowest cost).

#Parameters

#input

SpeculateInput

#Returns

Promise<SpeculateOutput>


#Function: supervisor()

supervisor<TContext>(config): AgentHandle<TContext>

Defined in: topologies.ts:63

Create a supervisor topology that delegates work to configured agents.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#config

SupervisorConfig<TContext>

Agent definitions and supervisor behavior.

#Returns

AgentHandle<TContext>

A handle for running and managing the topology.


#Function: swarm()

swarm<TContext>(config): AgentHandle<TContext>

Defined in: topologies.ts:136

Run every member and merge successful results. With timeoutMs, each member receives a cancellation signal; its optional legacy abort hook is also called once when that member's deadline expires. At least one successful member preserves partial-success behavior; zero successes raise RuntimeError (AK_RUNTIME_DELEGATE_FAILED) with the first failure as its cause.

#Type Parameters

#TContext

TContext = unknown

#Parameters

#config

SwarmConfig<TContext>

#Returns

AgentHandle<TContext>

#Throws

with AK_CONFIG_INVALID for an invalid timeoutMs.

#Throws

with AK_RUNTIME_DELEGATE_FAILED when every member fails.


#Function: validateFlow()

validateFlow(def, registry?): FlowValidationResult

Defined in: flow.ts:91

Validate flow node identifiers, handlers, dependencies, and cycles.

#Parameters

#def

FlowDefinition

Flow definition to inspect.

#registry?

FlowRegistry<unknown>

Optional handler registry used to check handler names.

#Returns

FlowValidationResult

Validation status, issues, and topological node order when valid.


#Function: withQuotas()

withQuotas(tools, tracker, runIdFor?): ToolDefinition<Record<string, unknown>>[]

Defined in: quota.ts:259

Wrap a list of tools so every execute call is gated by the quota tracker. Drop-in replacement for the raw tool array passed to createRuntime(\{ tools \}).

#Parameters

#tools

ToolDefinition<Record<string, unknown>>[]

#tracker

QuotaTracker

#runIdFor?

(context) => string

#Returns

ToolDefinition<Record<string, unknown>>[]

Explore nearby

On this page

Function: blackboard()Type ParametersTContextParametersconfigReturnsFunction: compileFlow()Type ParametersTInputParametersoptionsReturnsThrowsFunction: createAuctionHandler()Type ParametersCtxParametersoptsReturnsFunction: createChatTrigger()Type ParametersTContextParametersoptionsReturnsFunction: createCompareHandler()Type ParametersCtxParametersoptsReturnsFunction: createCronScheduler()Type ParametersTContextParametersoptionsReturnsFunction: createDebateHandler()Type ParametersCtxParametersoptsReturnsFunction: createDurableRunner()ParametersoptionsReturnsThrowsFunction: createFileStepLog()ParameterspathReturnsFunction: createInMemoryStepLog()ReturnsFunction: createQuotaTracker()ParametersoptionsReturnsFunction: createRuntime()ParametersconfigReturnsrun()Parameterstaskoptions?ReturnsExampleFunction: createSharedContext()Parametersinitial?ReturnsExampleFunction: createValidatorGuard()ParametersoptionsReturnsThrowsFunction: createVoteHandler()Type ParametersCtxParametersoptsReturnsFunction: createWebhookHandler()Type ParametersTContextParametersoptionsReturnsFunction: cronMatches()ParametersschedulenowReturnsFunction: denyPattern()Parameterspatternname?ReturnsFunction: flowToMermaid()ParametersdefReturnsFunction: hierarchical()Type ParametersTContextParametersconfigReturnsFunction: invokeStructured()Type ParametersTParametersoptsadaptermaxSteps?memory?observers?onConfirm?parsesignal?skill?tasktooltools?ReturnsFunction: isJson()Parametersoptions?maxRetries?name?repairPrompt?ReturnsFunction: lengthRange()Parametersoptionsmax?min?name?ReturnsFunction: parseSchedule()ParametersscheduleReturnsThrowsFunction: piiDenyValidator()Parametersopts?name?onFail?rules?ReturnsFunction: resolveConcurrency()ParameterslimitReturnsFunction: settleWithConcurrency()Type ParametersITParametersitemslimitfnReturnsFunction: speculate()ParametersinputReturnsFunction: supervisor()Type ParametersTContextParametersconfigReturnsFunction: swarm()Type ParametersTContextParametersconfigReturnsThrowsThrowsFunction: validateFlow()Parametersdefregistry?ReturnsFunction: withQuotas()ParameterstoolstrackerrunIdFor?Returns