@agentskit/runtime β Interfaces
API interfaces for @agentskit/runtime.
#Interface: AgentHandle<TContext>
Defined in: topologies.ts:16
Ready-made multi-agent topologies. Each builder takes a set of
AgentHandles + config and returns a single AgentHandle that
presents the ensemble as a normal agent to the rest of the system.
An AgentHandle is intentionally minimal β name + run(task, context?, signal?) => Promise<string> β so any runtime (our own
createRuntime, a LangChain Runnable, a bare HTTP endpoint) can
participate without coupling. The signal is separate from caller context;
existing two-argument handles remain compatible.
#Type Parameters
#TContext
TContext = unknown
#Properties
#abort?
optionalabort?: () =>void
Defined in: topologies.ts:25
Best-effort cancellation hook used when a topology deadline expires.
#Returns
void
#name
name:
string
Defined in: topologies.ts:17
#run
run: (
task,context?,signal?) =>Promise<string>
Defined in: topologies.ts:23
Run one task with its caller context and optional cancellation signal.
Topologies pass signal through to child work without modifying context;
omitting it preserves the existing uncancelled behavior.
#Parameters
task
string
context?
TContext
signal?
AbortSignal
#Returns
Promise<string>
#Interface: AuctionConfig
Defined in: multi-agent.ts:144
Bidders, selection criteria, and optional reserve, timeout, and fallback settings.
#Properties
#bidCriteria
readonlybidCriteria:"fastest"|"lowest-cost"|"highest-confidence"|"custom"
Defined in: multi-agent.ts:147
#bidders
readonlybidders: readonlystring[]
Defined in: multi-agent.ts:145
#fallback?
readonlyoptionalfallback?:string
Defined in: multi-agent.ts:150
#reservePrice?
readonlyoptionalreservePrice?:object
Defined in: multi-agent.ts:148
#tokens?
readonlyoptionaltokens?:number
#usd?
readonlyoptionalusd?:number
#task?
readonlyoptionaltask?:unknown
Defined in: multi-agent.ts:146
#timeout?
readonlyoptionaltimeout?:object
Defined in: multi-agent.ts:149
#ms
readonlyms:number
#Interface: BlackboardConfig<TContext>
Defined in: topologies.ts:277
Configuration for agents that coordinate through shared blackboard state.
#Type Parameters
#TContext
TContext = unknown
#Properties
#agents
agents:
AgentHandle<TContext>[]
Defined in: topologies.ts:279
#isDone?
optionalisDone?: (blackboard,iteration) =>boolean
Defined in: topologies.ts:281
Return an output when no further iterations are needed.
#Parameters
blackboard
string
iteration
number
#Returns
boolean
#maxIterations?
optionalmaxIterations?:number
Defined in: topologies.ts:283
Max iterations. Default 5.
#name?
optionalname?:string
Defined in: topologies.ts:278
#onEvent?
optionalonEvent?:TopologyObserver
Defined in: topologies.ts:284
#Interface: ChatFileUploadEvent
Defined in: chat-trigger.ts:97
File / attachment upload.
#Extends
#Properties
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#Inherited from
#contentType?
optionalcontentType?:string
Defined in: chat-trigger.ts:102
MIME type when known.
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#Inherited from
#name
name:
string
Defined in: chat-trigger.ts:100
File name as supplied by the surface.
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#Inherited from
#sizeBytes?
optionalsizeBytes?:number
Defined in: chat-trigger.ts:106
Size in bytes when reported.
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#Inherited from
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#Inherited from
#type
type:
"file_upload"
Defined in: chat-trigger.ts:98
#url?
optionalurl?:string
Defined in: chat-trigger.ts:104
URL the surface exposes for download (may require surface auth).
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Inherited from
#Interface: ChatInstallationEvent
Defined in: chat-trigger.ts:110
App installed in a workspace / guild / tenant.
#Extends
#Properties
#action
action:
"installed"|"uninstalled"
Defined in: chat-trigger.ts:113
Install / uninstall action.
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#Inherited from
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#Inherited from
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#Inherited from
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#Inherited from
#tenantId
tenantId:
string
Defined in: chat-trigger.ts:115
Tenant / workspace / guild id.
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#Inherited from
#type
type:
"installation"
Defined in: chat-trigger.ts:111
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Inherited from
#Interface: ChatMentionEvent
Defined in: chat-trigger.ts:70
A direct mention of the bot or a slash command.
#Extends
#Properties
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#Inherited from
#command?
optionalcommand?:string
Defined in: chat-trigger.ts:74
Slash command name without leading '/' (when applicable).
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#Inherited from
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#Inherited from
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#Inherited from
#text
text:
string
Defined in: chat-trigger.ts:72
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#Inherited from
#type
type:
"mention"
Defined in: chat-trigger.ts:71
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Inherited from
#Interface: ChatMessageEvent
Defined in: chat-trigger.ts:64
A plain text message addressed to nobody in particular.
#Extends
#Properties
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#Inherited from
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#Inherited from
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#Inherited from
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#Inherited from
#text
text:
string
Defined in: chat-trigger.ts:66
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#Inherited from
#type
type:
"message"
Defined in: chat-trigger.ts:65
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Inherited from
#Interface: ChatReactionEvent
Defined in: chat-trigger.ts:86
Emoji reaction added or removed on a message.
#Extends
#Properties
#added
added:
boolean
Defined in: chat-trigger.ts:93
True when the reaction was added; false when removed.
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#Inherited from
#emoji
emoji:
string
Defined in: chat-trigger.ts:91
Emoji shortcode, e.g. thumbsup.
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#Inherited from
#messageId
messageId:
string
Defined in: chat-trigger.ts:89
Reacted-to message id.
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#Inherited from
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#Inherited from
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#Inherited from
#type
type:
"reaction"
Defined in: chat-trigger.ts:87
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Inherited from
#Interface: ChatReplyEvent
Defined in: chat-trigger.ts:78
Reply inside an existing thread.
#Extends
#Properties
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#Inherited from
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#Inherited from
#parentId
parentId:
string
Defined in: chat-trigger.ts:82
Required: parent message id being replied to.
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#Inherited from
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#Inherited from
#text
text:
string
Defined in: chat-trigger.ts:80
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#Inherited from
#type
type:
"reply"
Defined in: chat-trigger.ts:79
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Inherited from
#Interface: ChatSurfaceAdapter
Defined in: chat-trigger.ts:141
Surface adapter contract. An adapter wraps a provider SDK (Bolt,
discord.js, Bot Framework) and turns raw inbound events into the
normalized ChatSurfaceEvent. Returning null from parse is a
deliberate skip β the trigger emits a 'skipped' observer event
and returns a 200 so the surface stops retrying.
#Properties
#parse
parse: (
req) =>ChatSurfaceEvent|Promise<ChatSurfaceEvent | null> |null
Defined in: chat-trigger.ts:144
Parse an inbound webhook into a normalized event. Return null to ignore.
#Parameters
req
#Returns
ChatSurfaceEvent | Promise<ChatSurfaceEvent | null> | null
#reply?
optionalreply?: (event,text) =>void|Promise<void>
Defined in: chat-trigger.ts:158
Optional reply hook β used when the agent's output should post back.
#Parameters
event
text
string
#Returns
void | Promise<void>
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:142
#verify?
optionalverify?: (req) =>boolean|Promise<boolean>
Defined in: chat-trigger.ts:156
Verify the request signature. Return false to reject with 401.
The factory refuses to construct without verify unless
\{ strict: false \} is passed β explicit opt-out so unverified
webhook handlers cannot ship by accident.
Replay protection (eventId dedup, timestamp window) is the
adapter's responsibility β the trigger does not enforce it. The
normalized eventId and receivedAt fields exist precisely so
adapters can implement dedup against a memory backend.
#Parameters
req
#Returns
boolean | Promise<boolean>
#Interface: ChatSurfaceChannel
Defined in: chat-trigger.ts:42
Channel / room / DM identifier.
#Properties
#id
id:
string
Defined in: chat-trigger.ts:43
#kind?
optionalkind?:"dm"|"group"|"channel"|"thread"
Defined in: chat-trigger.ts:47
Whether the channel is a 1:1 DM, group DM, or shared channel.
#name?
optionalname?:string
Defined in: chat-trigger.ts:45
Optional human-readable channel name.
#Interface: ChatSurfaceMeta
Defined in: chat-trigger.ts:51
Common metadata every event carries.
#Extended by
ChatMessageEventChatMentionEventChatReplyEventChatReactionEventChatFileUploadEventChatInstallationEvent
#Properties
#channel
channel:
ChatSurfaceChannel
Defined in: chat-trigger.ts:53
#eventId
eventId:
string
Defined in: chat-trigger.ts:56
Surface-native event id (Slack event_id, Discord interaction id, etc.).
#receivedAt?
optionalreceivedAt?:string
Defined in: chat-trigger.ts:60
ISO 8601 timestamp from the surface, when available.
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:52
#threadId?
optionalthreadId?:string
Defined in: chat-trigger.ts:58
Thread / parent message id when the event is in-thread.
#user
user:
ChatSurfaceUser
Defined in: chat-trigger.ts:54
#Interface: ChatSurfaceUser
Defined in: chat-trigger.ts:33
Stable identity of a sender across surfaces.
#Properties
#id
id:
string
Defined in: chat-trigger.ts:34
#isBot?
optionalisBot?:boolean
Defined in: chat-trigger.ts:38
True when the sender is a bot (including this agent).
#name?
optionalname?:string
Defined in: chat-trigger.ts:36
Display name when available.
#Interface: ChatTrigger
Defined in: chat-trigger.ts:243
Framework-independent webhook handler and observer wiring for a chat trigger.
#Properties
#handler
handler:
WebhookHandler
Defined in: chat-trigger.ts:244
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:245
#Interface: ChatTriggerObserverEvent
Defined in: chat-trigger.ts:164
Lifecycle event emitted while a chat trigger handles a surface event.
#Properties
#event?
optionalevent?:ChatSurfaceEvent
Defined in: chat-trigger.ts:176
#reason?
optionalreason?:string
Defined in: chat-trigger.ts:178
Error or skip reason.
#surface
surface:
ChatSurface
Defined in: chat-trigger.ts:175
#type
type:
"received"|"rejected"|"handled"|"skipped"|"replied"|"reply_failed"
Defined in: chat-trigger.ts:174
receivedβ before any workskippedβ adapter parse returned null OR filter rejectedhandledβ agent ran successfullyrepliedβ adapter.reply succeeded after handled (autoReply only)reply_failedβ adapter.reply threw after handled (HTTP still 200)rejectedβ request did not produce a successful agent run (verify failed, parse threw, agent threw)
#Interface: ChatTriggerOptions<TContext>
Defined in: chat-trigger.ts:184
Adapter, agent runner, and optional observer configuration for chat triggers.
#Type Parameters
#TContext
TContext = unknown
#Properties
#adapter
adapter:
ChatSurfaceAdapter
Defined in: chat-trigger.ts:185
#agent
agent:
AgentHandle<TContext>
Defined in: chat-trigger.ts:186
#autoReply?
optionalautoReply?:boolean
Defined in: chat-trigger.ts:204
Auto-reply with the agent's output via adapter.reply when present.
#buildContext?
optionalbuildContext?: (event) =>TContext
Defined in: chat-trigger.ts:197
Build the per-event runtime context (e.g. tenant id, user id).
Default: \{ event \}.
#Parameters
event
#Returns
TContext
#buildTask?
optionalbuildTask?: (event) =>string
Defined in: chat-trigger.ts:192
Build the agent task from the parsed event. Default: pull
event.text for message / mention / reply, fall back to a
structured JSON encoding for events without text (reaction, file).
#Parameters
event
#Returns
string
#eventSchema?
optionaleventSchema?:JSONSchema7
Defined in: chat-trigger.ts:219
Opt-in JSON Schema for the parsed ChatSurfaceEvent (ADR-0011). When set
together with validateEvent, an event that fails the schema is rejected
with HTTP 400 before the agent runs β defence in depth on top of
adapter.verify. The schema type is the same JSONSchema7 accepted by
ArgsValidator.
#filter?
optionalfilter?: (event) =>boolean
Defined in: chat-trigger.ts:202
Filter events before running the agent. Return false to skip.
Useful for ignoring bot-on-bot loops or off-hours messages.
#Parameters
event
#Returns
boolean
#onEvent?
optionalonEvent?: (event) =>void
Defined in: chat-trigger.ts:226
Observability hook.
#Parameters
event
#Returns
void
#strict?
optionalstrict?:boolean
Defined in: chat-trigger.ts:211
Reject construction when adapter.verify is missing. Default
true β set to false only when you have an external auth
proxy in front of the trigger. Surfaces the footgun at author
time instead of accepting spoofed webhooks at runtime.
#validateEvent?
optionalvalidateEvent?:ArgsValidator
Defined in: chat-trigger.ts:224
Validator used with eventSchema. Use createAjvValidator() from
@agentskit/tools/validation. No-op unless eventSchema is also set.
#Interface: CompareConfig
Defined in: multi-agent.ts:102
Agent list, shared input, and result selection strategy for compare.
#Properties
#agents
readonlyagents: readonlystring[]
Defined in: multi-agent.ts:103
#input?
readonlyoptionalinput?:unknown
Defined in: multi-agent.ts:104
#selection
readonlyselection:CompareSelection
Defined in: multi-agent.ts:105
#Interface: CompiledFlow<TInput>
Defined in: flow.ts:206
Validated flow definition, node order, and durable run function.
#Type Parameters
#TInput
TInput = unknown
#Properties
#definition
definition:
FlowDefinition
Defined in: flow.ts:207
#order
order:
string[]
Defined in: flow.ts:208
#run
run: (
input?,options?) =>Promise<Record<string,unknown>>
Defined in: flow.ts:209
#Parameters
input?
TInput
options?
#Returns
Promise<Record<string, unknown>>
#Interface: CompileFlowOptions<TInput>
Defined in: flow.ts:174
Flow definition and registry used to compile an executable flow.
#Type Parameters
#TInput
TInput = unknown
#Properties
#definition
definition:
FlowDefinition
Defined in: flow.ts:175
#registry
registry:
FlowRegistry<TInput>
Defined in: flow.ts:176
#Interface: CronJob<TContext>
Defined in: background.ts:14
#Type Parameters
#TContext
TContext = unknown
#Properties
#agent
agent:
AgentHandle<TContext>
Defined in: background.ts:17
#context?
optionalcontext?:TContext
Defined in: background.ts:20
#runOnStart?
optionalrunOnStart?:boolean
Defined in: background.ts:22
Run the job exactly once on start before the first tick.
#schedule
schedule:
string
Defined in: background.ts:16
Standard 5-field cron (* * * * *) or an every:<ms> shortcut.
#task?
optionaltask?:string| ((now) =>string)
Defined in: background.ts:19
Task the agent receives each fire. Default: scheduled: <name>.
#Interface: CronScheduler
Defined in: background.ts:165
Controls for starting and stopping scheduled job execution.
#Properties
#start
start: () =>
void
Defined in: background.ts:166
#Returns
void
#stop
stop: () =>
void
Defined in: background.ts:167
#Returns
void
#tick
tick: (
now?) =>Promise<void>
Defined in: background.ts:169
Manually fire every job whose schedule matches now. Useful in tests.
#Parameters
now?
Date
#Returns
Promise<void>
#Interface: CronSchedulerOptions<TContext>
Defined in: background.ts:28
Job, schedule, context, and clock options for a cron scheduler.
#Type Parameters
#TContext
TContext = unknown
#Properties
#jobs
jobs:
CronJob<TContext>[]
Defined in: background.ts:29
#now?
optionalnow?: () =>Date
Defined in: background.ts:39
Clock override for tests.
#Returns
Date
#onEvent?
optionalonEvent?: (event) =>void
Defined in: background.ts:31
Observability hook.
#Parameters
event
error?
string
job
string
now
Date
result?
string
type
"tick" | "run:start" | "run:end" | "run:error"
#Returns
void
#scheduleTick?
optionalscheduleTick?: (fn) => () =>void
Defined in: background.ts:41
Timer override for tests β takes tick handler, returns stop fn.
#Parameters
fn
() => void
#Returns
() => void
#Interface: DebateConfig
Defined in: multi-agent.ts:131
Topic, participants, round limit, and optional early-exit behavior for a debate.
#Properties
#earlyExit?
readonlyoptionalearlyExit?:string
Defined in: multi-agent.ts:138
#format?
readonlyoptionalformat?:unknown
Defined in: multi-agent.ts:133
#judge
readonlyjudge:string
Defined in: multi-agent.ts:136
#opponent
readonlyopponent:string
Defined in: multi-agent.ts:135
#proponent
readonlyproponent:string
Defined in: multi-agent.ts:134
#rounds
readonlyrounds:number
Defined in: multi-agent.ts:137
#topic
readonlytopic:unknown
Defined in: multi-agent.ts:132
#Interface: DelegateConfig
Defined in: types.ts:18
Configuration for a named sub-agent, including its skill and optional tools or adapter.
#Properties
#adapter?
optionaladapter?:AdapterFactory
Defined in: types.ts:21
#maxSteps?
optionalmaxSteps?:number
Defined in: types.ts:22
#skill
skill:
SkillDefinition
Defined in: types.ts:19
#tools?
optionaltools?:ToolDefinition<Record<string,unknown>>[]
Defined in: types.ts:20
#Interface: DurableRunner
Defined in: durable.ts:69
Operations for executing, replaying, inspecting, and resetting steps in one run.
#Properties
#history
history: () =>
Promise<StepRecord<unknown>[]>
Defined in: durable.ts:77
Read the full log for the current run.
#Returns
Promise<StepRecord<unknown>[]>
#reset
reset: () =>
Promise<void>
Defined in: durable.ts:79
Drop the log for the current run (dangerous β breaks resume).
#Returns
Promise<void>
#step
step: <
TResult>(stepId,fn,options?) =>Promise<TResult>
Defined in: durable.ts:75
Execute fn under the name stepId. If the step has already
been recorded in the log for this runId, return the recorded
result without re-running. Otherwise run, record, return.
#Type Parameters
TResult
TResult
#Parameters
stepId
string
fn
() => TResult | Promise<TResult>
options?
name?
string
#Returns
Promise<TResult>
#Interface: DurableRunnerOptions
Defined in: durable.ts:44
Options for durable step execution, including its store and stable run identifier.
#Properties
#maxAttempts?
optionalmaxAttempts?:number
Defined in: durable.ts:48
Max attempts per step. Default 1 (fail fast).
#onEvent?
optionalonEvent?: (event) =>void
Defined in: durable.ts:54
Observability β fires on replay-hit, retry, completion.
#Parameters
event
#Returns
void
#retryDelayMs?
optionalretryDelayMs?:number
Defined in: durable.ts:50
Backoff in ms between attempts. Default 0.
#runId
runId:
string
Defined in: durable.ts:46
#signal?
optionalsignal?:AbortSignal
Defined in: durable.ts:52
Cancel an in-progress retry delay.
#store
store:
StepLogStore
Defined in: durable.ts:45
#Interface: FlowDefinition
Defined in: flow.ts:34
Named directed acyclic flow made of handler-backed nodes and dependencies.
#Properties
#description?
optionaldescription?:string
Defined in: flow.ts:37
#name
name:
string
Defined in: flow.ts:35
#nodes
nodes:
FlowNode[]
Defined in: flow.ts:38
#version?
optionalversion?:string|number
Defined in: flow.ts:36
#Interface: FlowHandlerContext<TInput>
Defined in: flow.ts:44
Input, node metadata, dependency outputs, and static values supplied to a flow handler.
#Type Parameters
#TInput
TInput = unknown
#Properties
#deps
deps:
Record<string,unknown>
Defined in: flow.ts:49
Outputs of every dependency, keyed by node id.
#input
input:
TInput
Defined in: flow.ts:47
Initial input passed to runFlow.
#node
node:
FlowNode
Defined in: flow.ts:45
#with
with:
Record<string,unknown>
Defined in: flow.ts:51
Static inputs from node.with.
#Interface: FlowNode
Defined in: flow.ts:18
#Properties
#id
id:
string
Defined in: flow.ts:20
Unique within the flow. Used as durable step id.
#name?
optionalname?:string
Defined in: flow.ts:22
Display label. Defaults to id.
#needs?
optionalneeds?:string[]
Defined in: flow.ts:28
Ids of nodes that must finish before this one starts.
#run
run:
string
Defined in: flow.ts:24
Handler key β must exist in the FlowRegistry.
#with?
optionalwith?:Record<string,unknown>
Defined in: flow.ts:26
Static inputs passed to the handler.
#Interface: FlowValidationIssue
Defined in: flow.ts:69
A validation error identifying an invalid node or flow structure.
#Properties
#code
code:
"duplicate-id"|"missing-handler"|"unknown-dependency"|"self-dependency"|"cycle"
Defined in: flow.ts:70
#message
message:
string
Defined in: flow.ts:71
#nodeId?
optionalnodeId?:string
Defined in: flow.ts:72
#Interface: FlowValidationResult
Defined in: flow.ts:78
Flow validity, validation issues, and execution order.
#Properties
#issues
issues:
FlowValidationIssue[]
Defined in: flow.ts:80
#ok
ok:
boolean
Defined in: flow.ts:79
#order
order:
string[]
Defined in: flow.ts:82
Topologically ordered ids when the flow is valid.
#Interface: HierarchicalConfig<TContext>
Defined in: topologies.ts:225
Configuration for a hierarchy of agents.
#Type Parameters
#TContext
TContext = unknown
#Properties
#maxDepth?
optionalmaxDepth?:number
Defined in: topologies.ts:231
Maximum depth. Default 5.
#name?
optionalname?:string
Defined in: topologies.ts:226
#onEvent?
optionalonEvent?:TopologyObserver
Defined in: topologies.ts:232
#root
root:
HierarchicalNode<TContext>
Defined in: topologies.ts:227
#route?
optionalroute?: (input) =>HierarchicalNode<TContext> |undefined
Defined in: topologies.ts:229
Pick which child (if any) to descend into. Return undefined to stop.
#Parameters
input
node
HierarchicalNode<TContext>
task
string
#Returns
HierarchicalNode<TContext> | undefined
#Interface: HierarchicalNode<TContext>
Defined in: topologies.ts:215
A node in a hierarchical agent topology.
#Type Parameters
#TContext
TContext = unknown
#Properties
#agent
agent:
AgentHandle<TContext>
Defined in: topologies.ts:216
#children?
optionalchildren?:HierarchicalNode<TContext>[]
Defined in: topologies.ts:219
#tags?
optionaltags?:string[]
Defined in: topologies.ts:218
Free-form tags the router can match against.
#Interface: QuotaExceededEvent
Defined in: quota.ts:41
Details of a tool quota that rejected an invocation.
#Properties
#at
at:
string
Defined in: quota.ts:50
ISO timestamp.
#kind
kind:
"perRun"|"perWindow"|"dryRun"
Defined in: quota.ts:44
Which limit fired.
#limit
limit:
number
Defined in: quota.ts:46
The configured limit (count).
#observed
observed:
number
Defined in: quota.ts:48
What we observed (count).
#tool
tool:
string
Defined in: quota.ts:42
#Interface: QuotaSnapshot
Defined in: quota.ts:85
Current per-run counters and timestamps in the sliding-window counters.
#Properties
#perRun
perRun:
Record<string,Record<string,number>>
Defined in: quota.ts:86
#perWindow
perWindow:
Record<string,number[]>
Defined in: quota.ts:87
#Interface: QuotaTracker
Defined in: quota.ts:69
Admission, accounting, reset, and inspection methods for tool quotas.
#Properties
#check
check: (
tool,runId) =>void
Defined in: quota.ts:71
Throws and reserves one admission when the tool is over budget.
#Parameters
tool
string
runId
string
#Returns
void
#record
record: (
tool,runId) =>void
Defined in: quota.ts:73
Records a successful tool invocation against the counters.
#Parameters
tool
string
runId
string
#Returns
void
#release
release: (
tool,runId) =>void
Defined in: quota.ts:75
Releases an admission when tool execution fails before it completes.
#Parameters
tool
string
runId
string
#Returns
void
#resetRun
resetRun: (
runId) =>void
Defined in: quota.ts:77
Reset per-run counters for a finished runtime.run().
#Parameters
runId
string
#Returns
void
#snapshot
snapshot: () =>
QuotaSnapshot
Defined in: quota.ts:79
Inspect counters (debugging / dashboards).
#Returns
#Interface: QuotaTrackerOptions
Defined in: quota.ts:56
Quota rules and optional environment, event sink, and clock.
#Properties
#env?
optionalenv?:string
Defined in: quota.ts:59
Active environment tag ('production', 'staging', β¦).
#now?
optionalnow?: () =>number
Defined in: quota.ts:63
Wall clock β overridable for tests.
#Returns
number
#onExceeded?
optionalonExceeded?: (event) =>void
Defined in: quota.ts:61
Sink for quota events.
#Parameters
event
#Returns
void
#quotas
quotas:
QuotaMap
Defined in: quota.ts:57
#Interface: ReadonlySharedContext
Defined in: shared-context.ts:11
Read-only view of shared context values.
#Methods
#entries()
entries():
Record<string,unknown>
Defined in: shared-context.ts:14
#Returns
Record<string, unknown>
#get()
get(
key):unknown
Defined in: shared-context.ts:12
#Parameters
key
string
#Returns
unknown
#has()
has(
key):boolean
Defined in: shared-context.ts:13
#Parameters
key
string
#Returns
boolean
#Interface: RunFlowOptions
Defined in: flow.ts:182
Run identifier, durable store, retry settings, and event callback for a flow run.
#Properties
#maxAttempts?
optionalmaxAttempts?:number
Defined in: flow.ts:188
Forwarded to createDurableRunner.
#onEvent?
optionalonEvent?: (event) =>void
Defined in: flow.ts:190
#Parameters
event
#Returns
void
#retryDelayMs?
optionalretryDelayMs?:number
Defined in: flow.ts:189
#runId?
optionalrunId?:string
Defined in: flow.ts:184
Defaults to a fresh runId per call. Reuse to resume after a crash.
#store?
optionalstore?:StepLogStore
Defined in: flow.ts:186
Defaults to an in-memory store. Use createFileStepLog for durability.
#Interface: RunOptions
Defined in: types.ts:53
Options that override runtime settings for one run.
#Properties
#delegates?
optionaldelegates?:Record<string,DelegateConfig>
Defined in: types.ts:61
#maxSteps?
optionalmaxSteps?:number
Defined in: types.ts:57
#runId?
optionalrunId?:string
Defined in: types.ts:59
Stable identifier shared by all tool calls in this run.
#sharedContext?
optionalsharedContext?:SharedContext
Defined in: types.ts:62
#signal?
optionalsignal?:AbortSignal
Defined in: types.ts:60
#skill?
optionalskill?:SkillDefinition
Defined in: types.ts:56
#systemPrompt?
optionalsystemPrompt?:string
Defined in: types.ts:55
#tools?
optionaltools?:ToolDefinition<Record<string,unknown>>[]
Defined in: types.ts:54
#Interface: RunResult
Defined in: types.ts:68
The final text, message history, step and tool-call counts, and duration for a run.
#Properties
#content
content:
string
Defined in: types.ts:69
#durationMs
durationMs:
number
Defined in: types.ts:73
#messages
messages:
Message[]
Defined in: types.ts:70
#steps
steps:
number
Defined in: types.ts:71
#toolCalls
toolCalls:
ToolCall[]
Defined in: types.ts:72
#Interface: RuntimeConfig
Defined in: types.ts:28
Configuration shared by every run of a runtime.
#Properties
#adapter
adapter:
AdapterFactory
Defined in: types.ts:29
#delegates?
optionaldelegates?:Record<string,DelegateConfig>
Defined in: types.ts:38
#maxDelegationDepth?
optionalmaxDelegationDepth?:number
Defined in: types.ts:39
#maxSteps?
optionalmaxSteps?:number
Defined in: types.ts:35
#maxTokens?
optionalmaxTokens?:number
Defined in: types.ts:37
#memory?
optionalmemory?:ChatMemory
Defined in: types.ts:32
#observers?
optionalobservers?:Observer[]
Defined in: types.ts:34
#onConfirm?
optionalonConfirm?: (toolCall) =>MaybePromise<boolean>
Defined in: types.ts:40
#Parameters
toolCall
ToolCall
#Returns
MaybePromise<boolean>
#retriever?
optionalretriever?:Retriever
Defined in: types.ts:33
#systemPrompt?
optionalsystemPrompt?:string
Defined in: types.ts:31
#temperature?
optionaltemperature?:number
Defined in: types.ts:36
#tools?
optionaltools?:ToolDefinition<Record<string,unknown>>[]
Defined in: types.ts:30
#validateArgs?
optionalvalidateArgs?:ArgsValidator
Defined in: types.ts:47
Opt-in runtime validator for tool-call arguments (ADR-0008). When set,
model-produced args are checked against each tool's JSON Schema before
execution; mismatches raise AK_TOOL_INVALID_INPUT. Use
createAjvValidator() from @agentskit/tools/validation.
#Interface: SharedContext
Defined in: shared-context.ts:2
Mutable key-value context that can be shared across tools in one run.
#Methods
#entries()
entries():
Record<string,unknown>
Defined in: shared-context.ts:6
#Returns
Record<string, unknown>
#get()
get(
key):unknown
Defined in: shared-context.ts:3
#Parameters
key
string
#Returns
unknown
#has()
has(
key):boolean
Defined in: shared-context.ts:5
#Parameters
key
string
#Returns
boolean
#readOnly()
readOnly():
ReadonlySharedContext
Defined in: shared-context.ts:7
#Returns
#set()
set(
key,value):void
Defined in: shared-context.ts:4
#Parameters
key
string
value
unknown
#Returns
void
#Interface: SpeculateInput
Defined in: speculate.ts:35
Candidates, adapter request, winner selection policy, and optional timeout.
#Properties
#candidates
candidates:
SpeculativeCandidate[]
Defined in: speculate.ts:36
#pick?
optionalpick?:"first"|"longest"|SpeculatePicker
Defined in: speculate.ts:47
Picker strategy:
- 'first' (default): first candidate to settle without error
- 'longest': the candidate with the most output text
- function: custom picker receives all results in settle order
When 'first' is used, losers are aborted as soon as the winner settles. Custom pickers wait for all candidates to finish first.
#request
request:
AdapterRequest
Defined in: speculate.ts:37
#timeoutMs?
optionaltimeoutMs?:number
Defined in: speculate.ts:49
Hard timeout in ms per candidate. Default: none.
#Interface: SpeculateOutput
Defined in: speculate.ts:55
Winning result, losing results, and the full set of speculative results.
#Properties
#all
all:
SpeculativeResult[]
Defined in: speculate.ts:58
#losers
losers:
SpeculativeResult[]
Defined in: speculate.ts:57
#winner
winner:
SpeculativeResult
Defined in: speculate.ts:56
#Interface: SpeculativeCandidate
Defined in: speculate.ts:7
Adapter candidate and cancellation policy for a speculative request.
#Properties
#abortOnLoser?
optionalabortOnLoser?:boolean
Defined in: speculate.ts:12
Cancel this candidate when another wins first. Default true.
#adapter
adapter:
AdapterFactory
Defined in: speculate.ts:10
#id
id:
string
Defined in: speculate.ts:9
Human label used in results.
#Interface: SpeculativeResult
Defined in: speculate.ts:18
Stream text, chunks, latency, and failure or abort status for one candidate.
#Properties
#aborted?
optionalaborted?:boolean
Defined in: speculate.ts:24
#chunks
chunks:
StreamChunk[]
Defined in: speculate.ts:20
#error?
optionalerror?:Error
Defined in: speculate.ts:23
#id
id:
string
Defined in: speculate.ts:19
#latencyMs
latencyMs:
number
Defined in: speculate.ts:22
#text
text:
string
Defined in: speculate.ts:21
#Interface: StepLogStore
Defined in: durable.ts:34
Persistence contract for appending, retrieving, listing, and optionally clearing step records.
#Properties
#append
append: <
T>(record) =>Promise<void>
Defined in: durable.ts:35
#Type Parameters
T
T
#Parameters
record
StepRecord<T>
#Returns
Promise<void>
#clear?
optionalclear?: (runId) =>Promise<void>
Defined in: durable.ts:38
#Parameters
runId
string
#Returns
Promise<void>
#get
get: <
T>(runId,stepId) =>Promise<StepRecord<T> |null>
Defined in: durable.ts:36
#Type Parameters
T
T
#Parameters
runId
string
stepId
string
#Returns
Promise<StepRecord<T> | null>
#list
list: (
runId) =>Promise<StepRecord<unknown>[]>
Defined in: durable.ts:37
#Parameters
runId
string
#Returns
Promise<StepRecord<unknown>[]>
#Interface: StepRecord<TResult>
Defined in: durable.ts:19
Temporal-style durable execution primitive. Wraps any side-effectful
step in a runner.step(name, fn) call; the result is appended to a
StepLogStore. When the run restarts (after a crash, a deploy, or
a retry), replayed steps short-circuit to the recorded value and
only new steps execute.
Deterministic replay requires two rules from callers:
- Step names are stable across runs (ideally derived from the
business key β e.g.
search:$\{query\}β so the log stays meaningful even as code reorders). - Steps are pure from the perspective of the log β the fn does the side effect, the result is everything later steps need.
#Type Parameters
#TResult
TResult = unknown
#Properties
#attempt
attempt:
number
Defined in: durable.ts:28
#endedAt
endedAt:
string
Defined in: durable.ts:27
#error?
optionalerror?:string
Defined in: durable.ts:25
#name
name:
string
Defined in: durable.ts:22
#result?
optionalresult?:TResult
Defined in: durable.ts:24
#runId
runId:
string
Defined in: durable.ts:20
#startedAt
startedAt:
string
Defined in: durable.ts:26
#status
status:
"success"|"failure"
Defined in: durable.ts:23
#stepId
stepId:
string
Defined in: durable.ts:21
#Interface: SupervisorConfig<TContext>
Defined in: topologies.ts:48
Configuration for the supervisor topology.
#Type Parameters
#TContext
TContext = unknown
#Properties
#maxRounds?
optionalmaxRounds?:number
Defined in: topologies.ts:54
Maximum delegation rounds. Default 1.
#onEvent?
optionalonEvent?:TopologyObserver
Defined in: topologies.ts:55
#route?
optionalroute?: (task,workers) =>AgentHandle<TContext>
Defined in: topologies.ts:52
How the supervisor picks a worker. Default: round-robin.
#Parameters
task
string
workers
AgentHandle<TContext>[]
#Returns
AgentHandle<TContext>
#supervisor
supervisor:
AgentHandle<TContext>
Defined in: topologies.ts:49
#workers
workers:
AgentHandle<TContext>[]
Defined in: topologies.ts:50
#Interface: SwarmConfig<TContext>
Defined in: topologies.ts:111
Configuration for a swarm of agents.
#Type Parameters
#TContext
TContext = unknown
#Properties
#members
members:
AgentHandle<TContext>[]
Defined in: topologies.ts:113
#merge?
optionalmerge?: (results) =>string|Promise<string>
Defined in: topologies.ts:115
Merge member outputs into a single result. Default: longest.
#Parameters
results
object[]
#Returns
string | Promise<string>
#name?
optionalname?:string
Defined in: topologies.ts:112
#onEvent?
optionalonEvent?:TopologyObserver
Defined in: topologies.ts:122
#timeoutMs?
optionaltimeoutMs?:number
Defined in: topologies.ts:121
Per-member deadline in milliseconds. Default: unset (no deadline).
When set, it must be finite, greater than 0, and no greater than 2,147,483,647.
Invalid values throw ConfigError (AK_CONFIG_INVALID) synchronously.
#Interface: ToolQuota
Defined in: quota.ts:21
Per-tool quota / blast-radius limits. Beyond rate-limiting (#163), agents need hard ceilings β "no matter what, this run cannot send more than 50 emails" β so a runaway loop cannot dump 10k messages or run a destructive query a thousand times.
Two limits per tool:
perRunβ counter resets on everyruntime.run().perWindowβ sliding window (default 60s) shared across runs.
Exceeding either raises a typed ToolError with code
AK_TOOL_QUOTA_EXCEEDED and emits a tool:quota:exceeded callback
so observers / cost-guards can react.
Closes issue #801.
#Properties
#dryRunRequiredIn?
optionaldryRunRequiredIn?:string[]
Defined in: quota.ts:30
Mark the tool as "dry-run only" in production. When the env tag is matched, the runtime throws before execute() is invoked.
#perRun?
optionalperRun?:number
Defined in: quota.ts:23
Hard cap per runtime.run() invocation.
#perWindow?
optionalperWindow?:object
Defined in: quota.ts:25
Sliding-window cap (count, window) shared across all runs.
#count
count:
number
#windowMs
windowMs:
number
#Interface: TopologyLogEvent
Defined in: topologies.ts:29
Event emitted as a topology starts or agents are assigned work.
#Properties
#agent?
optionalagent?:string
Defined in: topologies.ts:32
#iteration?
optionaliteration?:number
Defined in: topologies.ts:35
#phase
phase:
"dispatch"|"agent:start"|"agent:end"|"merge"|"done"
Defined in: topologies.ts:31
#result?
optionalresult?:string
Defined in: topologies.ts:34
#task?
optionaltask?:string
Defined in: topologies.ts:33
#topology
topology:
string
Defined in: topologies.ts:30
#Interface: Validator
Defined in: validator-guard.ts:37
Check a value and return a boolean or structured validation result.
#Properties
#check
check: (
ctx) =>ValidatorResult|Promise<ValidatorResult>
Defined in: validator-guard.ts:47
Return true (or a \{ ok: true \} object) when the output passes.
Return false (or \{ ok: false, reason \}) to fail.
Async checks are supported β useful for eval LLM-judge or RAG citation lookups.
#Parameters
ctx
#Returns
ValidatorResult | Promise<ValidatorResult>
#maxRetries?
optionalmaxRetries?:number
Defined in: validator-guard.ts:51
Cap retries per run. Default 1.
#name
name:
string
Defined in: validator-guard.ts:39
Stable id for audit logs / dashboards.
#onFail?
optionalonFail?:ValidatorAction
Defined in: validator-guard.ts:49
What to do on failure. Default 'retry' (with up to maxRetries).
#repairPrompt?
optionalrepairPrompt?: (ctx) =>string
Defined in: validator-guard.ts:56
Repair instruction appended to the regenerator on retry. Lets the agent self-correct. Receives the failure context.
#Parameters
ctx
output
string
reason?
string
#Returns
string
#Interface: ValidatorAuditEvent
Defined in: validator-guard.ts:78
Audit record for an argument or output validation decision.
#Properties
#at
at:
string
Defined in: validator-guard.ts:80
ISO timestamp.
#attempts
attempts:
number
Defined in: validator-guard.ts:84
Total attempts made.
#failures
failures:
object[]
Defined in: validator-guard.ts:86
Per-failure detail. Empty when outcome: 'accepted' on first try.
#action
action:
ValidatorAction
#attempt
attempt:
number
#reason?
optionalreason?:string
#validator
validator:
string
#outcome
outcome:
"fallback"|"accepted"|"blocked"
Defined in: validator-guard.ts:82
Outcome of the run.
#output
output:
string
Defined in: validator-guard.ts:88
Final output that left the guard.
#Interface: ValidatorCheckContext
Defined in: validator-guard.ts:27
Tool and run metadata supplied to validators.
#Properties
#attempt
attempt:
number
Defined in: validator-guard.ts:29
Attempt index (0-based) for the current run.
#output
output:
string
Defined in: validator-guard.ts:31
Output being validated.
#Interface: ValidatorGuard
Defined in: validator-guard.ts:117
Guard operations that check arguments and outputs around tool calls.
#Properties
#run
run: (
options) =>Promise<ValidatorGuardRun>
Defined in: validator-guard.ts:118
#Parameters
options
#Returns
Promise<ValidatorGuardRun>
#Interface: ValidatorGuardOptions
Defined in: validator-guard.ts:67
Validators, retry limit, and audit callback for a validator guard.
#Properties
#audit?
optionalaudit?: (event) =>void
Defined in: validator-guard.ts:72
Audit hook β receives every accepted, retried, or blocked decision.
#Parameters
event
#Returns
void
#fallback?
optionalfallback?:string
Defined in: validator-guard.ts:70
Deterministic fallback text used when onFail: 'fallback' fires.
#validators
validators:
Validator[]
Defined in: validator-guard.ts:68
#Interface: ValidatorGuardRun
Defined in: validator-guard.ts:94
Context and callbacks needed to run a guarded tool operation.
#Properties
#accepted
accepted:
boolean
Defined in: validator-guard.ts:98
True when a validator chain accepted; false when blocked / fallback.
#attempts
attempts:
number
Defined in: validator-guard.ts:100
Total attempts made.
#failures
failures:
object[]
Defined in: validator-guard.ts:101
#action
action:
ValidatorAction
#attempt
attempt:
number
#reason?
optionalreason?:string
#validator
validator:
string
#output
output:
string
Defined in: validator-guard.ts:96
Output that survived the gauntlet (or the fallback).
#Interface: ValidatorGuardRunOptions
Defined in: validator-guard.ts:107
Per-run overrides for validator guard execution.
#Properties
#regenerate
regenerate: (
repair?) =>Promise<string>
Defined in: validator-guard.ts:109
Regenerate the output. Receives the optional repair prompt.
#Parameters
repair?
string
#Returns
Promise<string>
#seed?
optionalseed?:string
Defined in: validator-guard.ts:111
Initial output to validate (skips first regenerate call).
#Interface: VoteConfig
Defined in: multi-agent.ts:120
Agent list, input, ballot policy, and tie-breaking behavior for vote.
#Properties
#agents
readonlyagents: readonlystring[]
Defined in: multi-agent.ts:121
#ballot
readonlyballot:VoteBallot
Defined in: multi-agent.ts:123
#input?
readonlyoptionalinput?:unknown
Defined in: multi-agent.ts:122
#judgeAgent?
readonlyoptionaljudgeAgent?:string
Defined in: multi-agent.ts:125
#onTie
readonlyonTie:"first"|"judge"|"human"
Defined in: multi-agent.ts:124
#Interface: WebhookOptions<TContext>
Defined in: background.ts:265
Configuration for adapting incoming webhook requests to agent execution.
#Type Parameters
#TContext
TContext = unknown
#Properties
#agent
agent:
AgentHandle<TContext>
Defined in: background.ts:266
#context?
optionalcontext?:TContext| ((req) =>TContext)
Defined in: background.ts:273
Pass-through context for the agent.
#extractTask?
optionalextractTask?: (req) =>string
Defined in: background.ts:271
Extract the task string from the webhook body. Default:
body.task for JSON bodies, or the raw string.
#Parameters
req
#Returns
string
#onEvent?
optionalonEvent?: (event) =>void
Defined in: background.ts:278
#Parameters
event
error?
string
type
"received" | "rejected" | "handled"
#Returns
void
#strict?
optionalstrict?:boolean
Defined in: background.ts:277
Refuse construction without verification. Defaults to true.
#verify?
optionalverify?: (req) =>boolean|Promise<boolean>
Defined in: background.ts:275
Verify the incoming request (signature, token, etc.).
#Parameters
req
#Returns
boolean | Promise<boolean>
#Interface: WebhookRequest
Defined in: background.ts:248
Normalized incoming webhook method, headers, and body.
#Properties
#body?
optionalbody?:string|Record<string,unknown>
Defined in: background.ts:250
#headers?
optionalheaders?:Record<string,string|string[] |undefined>
Defined in: background.ts:249
#Interface: WebhookResponse
Defined in: background.ts:256
HTTP status, headers, and body returned by a webhook handler.
#Properties
#body
body:
string
Defined in: background.ts:258
#headers?
optionalheaders?:Record<string,string>
Defined in: background.ts:259
#status
status:
number
Defined in: background.ts:257