@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
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
#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
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
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
Store, run identifier, retry policy, abort signal, and event callback.
#Returns
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
#Function: createQuotaTracker()
createQuotaTracker(
options):QuotaTracker
Defined in: quota.ts:95
Create per-run and sliding-window quota counters for tools.
#Parameters
#options
Quota limits, environment, event callback, and optional clock.
#Returns
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
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?
#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
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
Validators, retry settings, and audit callback.
#Returns
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
#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
#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
#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
#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
#Function: parseSchedule()
parseSchedule(
schedule):ParsedSchedule
Defined in: background.ts:111
Parse a five-field cron expression or every:<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?
#rules?
PIIRule[]
#Returns
#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
#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
Flow definition to inspect.
#registry?
FlowRegistry<unknown>
Optional handler registry used to check handler names.
#Returns
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
#runIdFor?
(context) => string
#Returns
ToolDefinition<Record<string, unknown>>[]