openvibe-sdk/agents
Generated at from
openvibe-contracts v0.419.0 and
openvibe-sdk v0.161.0.
From types/agents.d.ts (both). Declarations are shown verbatim.
type AgentRunStatus
One agent system: agents.run@1, agents.step@1, agents.approval@1, the AG-UI stream and the plugin interfaces.
export type AgentRunStatus = 'planning' | 'running' | 'waiting' | 'done' | 'failed' | 'stopped';type AgentsStepKind
export type AgentsStepKind = 'think' | 'tool' | 'message' | 'approval' | 'child' | 'file';interface AgentsOwner
export interface AgentsOwner { type: string; id: string; revision?: number }interface AgentsAgentRef
The agent that runs it, with its face: a glyph from the registry, a hue, a picture, and the loop (harness) that runs it.
export interface AgentsAgentRef { id: string; name?: string; product?: string; glyph?: string; hue?: number; avatar_url?: string; harness?: string }type AgentsRunKind
export type AgentsRunKind = 'chat' | 'ask' | 'task' | 'code' | 'machine' | 'goal' | (string & {});interface AgentsModel
export interface AgentsModel { id: string; source?: 'openvibe' | 'keys' | 'machines' | 'plans'; machine?: string; name?: string; effort?: string }interface AgentsWhere
export interface AgentsWhere { kind: 'openvibe' | 'machine' | 'runner' | 'this-computer'; id?: string; name?: string }type AgentsTarget
export type AgentsTarget = 'new' | 'openvibe' | { repo: string; branch?: string };interface AgentsContext
export interface AgentsContext { site?: string; url?: string; title?: string; kind?: string; id?: string }interface AgentsAttachment
export interface AgentsAttachment { kind: 'image' | 'file' | 'audio' | 'video'; media_id?: string; url?: string; name?: string; mime?: string; bytes?: number; width?: number; height?: number; alt?: string }interface AgentsOutput
export interface AgentsOutput { kind: 'link' | 'file' | 'image' | 'video' | 'audio' | 'pr' | 'repo' | 'page' | 'post' | 'run'; title: string; url?: string; thumb?: string; media_id?: string; state?: string }interface AgentsBudget
export interface AgentsBudget { usd?: number; tokens?: number; seconds?: number; steps?: number }interface AgentsCost
export interface AgentsCost { usd?: number; tokens?: number; seconds?: number; steps?: number }interface AgentsRun
export interface AgentsRun {
id: string;
owner: AgentsOwner;
agent: AgentsAgentRef;
parent_run?: string | null;
budget?: AgentsBudget;
status: AgentRunStatus;
created_at: string;
updated_at: string;
result_summary?: string | null;
cost?: AgentsCost | null;
// 1.1.0 (Contracts 0.414.0), all optional:
title?: string;
kind?: AgentsRunKind;
/** Its address on the Frame: `<product>:<id>`. */
ref?: string;
url?: string;
model?: AgentsModel;
where?: AgentsWhere;
target?: AgentsTarget;
doing?: { text: string; glyph?: string } | null;
/** Why a waiting run waits; `message` is a conversation between turns. */
waiting?: { for: 'message' | 'approval' | 'takeover' | 'payment'; what?: string; approval?: string; since?: string } | null;
preview?: { text: string; from?: 'person' | 'agent' | 'system' | 'tool'; at?: string } | null;
context?: AgentsContext;
outputs?: AgentsOutput[];
counts?: { steps?: number; children?: number; files?: number; approvals?: number; unread?: number };
visibility?: 'private' | 'shared' | 'public';
ended_at?: string | null;
}interface AgentsRunList
export interface AgentsRunList { runs: AgentsRun[]; next?: string | null }interface AgentsToolCall
export interface AgentsToolCall { name: string; input?: unknown }interface AgentsStep
export interface AgentsStep {
run_id: string;
seq: number;
kind: AgentsStepKind;
text?: string | null;
tool_call?: AgentsToolCall | null;
result?: unknown;
cost?: { usd?: number; tokens?: number; seconds?: number } | null;
started_at: string;
ended_at?: string | null;
child_run?: string | null;
// 1.1.0 (Contracts 0.414.0), all optional:
from?: 'person' | 'agent' | 'system' | 'tool';
author?: { id?: string; name: string; avatar_url?: string };
status?: 'running' | 'done' | 'failed';
title?: string;
glyph?: string;
attachments?: AgentsAttachment[];
sources?: Array<{ n: number; title?: string; url: string; site?: string }>;
/** A rich card; a reader that does not know the type shows `text`. */
ui?: { type: string; data?: Record<string, unknown> };
desk?: { id: string; still_url?: string; action?: { type: string; x?: number; y?: number; text?: string } };
}interface AgentsStepPage
export interface AgentsStepPage { steps: AgentsStep[]; next?: number | null }interface AgentsApprovalOption
export interface AgentsApprovalOption { id: string; label: string }interface AgentsApproval
export interface AgentsApproval {
id?: string;
run_id: string;
step_seq: number;
what: string;
options: AgentsApprovalOption[];
decided_by?: AgentsOwner | null;
decided_at?: string | null;
answer?: string | null;
}interface AgentSource
export interface AgentSource { url: string; title: string; site: string }interface AgentUiEvent
export interface AgentUiEvent {
type: string;
timestamp: string;
threadId?: string;
runId?: string;
metadata?: { ov?: { title?: string; kind?: string; sources?: AgentSource[]; attachments?: unknown[]; cost_usd?: number | null; needs_you?: object | null; product?: string; ref?: string | null } };
[field: string]: unknown;
}interface AgentRun
Network's AG-UI ask run (agent.run@1, the composer's Ask). Different from AgentsRun.
export interface AgentRun {
id: string;
product: string;
title: string;
status: 'queued' | 'running' | 'waiting' | 'needs_you' | 'succeeded' | 'failed' | 'stopped' | 'cancelled';
plan: Array<{ title: string; status: string }>;
steps: Array<Record<string, unknown>>;
sources: AgentSource[];
result: Record<string, unknown> | null;
started_at: string;
ended_at: string | null;
cost_usd: number | null;
}interface AgentApproval
export interface AgentApproval { id?: string; action?: string; [field: string]: unknown }interface AgentEvent
export interface AgentEvent { id: string | null; event: string | null; data: AgentUiEvent | null }interface AgentsRunStart
agents.run-start@1: only `text` is required.
export interface AgentsRunStart {
text: string;
title?: string;
kind?: AgentsRunKind;
agent?: string;
model?: AgentsModel;
where?: AgentsWhere;
target?: AgentsTarget;
context?: AgentsContext;
attachments?: AgentsAttachment[];
sources?: Array<'web' | 'openvibe' | 'mine' | 'page'>;
depth?: 'quick' | 'balanced' | 'deep';
parent_run?: string;
budget?: AgentsBudget;
}interface AgentsStreamEvent
agents.event@1: one event of a run's stream.
export interface AgentsStreamEvent {
type: 'run' | 'step' | 'delta' | 'approval' | 'end';
run?: AgentsRun; step?: AgentsStep; approval?: AgentsApproval;
run_id?: string; seq?: number; text?: string; status?: 'done' | 'failed' | 'stopped';
}type AgentsRunLike
export type AgentsRunLike = string | Pick<AgentsRun, 'id'> & { ref?: string };interface AgentsListOptions
export interface AgentsListOptions { kind?: AgentsRunKind; status?: AgentRunStatus; q?: string; limit?: number; cursor?: string; before?: string; agent?: string; parentRun?: string; signal?: AbortSignal }interface AgentsStepsOptions
export interface AgentsStepsOptions { after?: number; limit?: number; signal?: AbortSignal }interface AgentsEventsOptions
export interface AgentsEventsOptions { after?: number; lastEventId?: string | number; signal?: AbortSignal; maxReconnects?: number; reconnectDelayMs?: number }interface AgentsFollowHandlers
export interface AgentsFollowHandlers extends AgentsEventsOptions {
onRun?(run: AgentsRun): unknown;
onStep?(step: AgentsStep): unknown;
onDelta?(delta: { run_id?: string; seq?: number; text?: string }): unknown;
onApproval?(approval: AgentsApproval): unknown;
onEvent?(event: AgentEvent): unknown;
}interface AgentsRuns
export interface AgentsRuns {
list(options?: AgentsListOptions): Promise<AgentsRunList>;
/** One run; null on 404. */
get(run: AgentsRunLike, options?: { signal?: AbortSignal }): Promise<AgentsRun | null>;
steps(run: AgentsRunLike, options?: AgentsStepsOptions): Promise<AgentsStepPage>;
/** Start a run: the words, or the whole agents.run-start@1 object. */
start(request: string | AgentsRunStart, options?: { signal?: AbortSignal; idempotencyKey?: string }): Promise<AgentsRun>;
/** Say something to a run: continue a conversation or steer work under way. */
say(run: AgentsRunLike, message: string | { text?: string; attachments?: AgentsAttachment[] }, options?: { signal?: AbortSignal; idempotencyKey?: string }): Promise<AgentsStep>;
stop(run: AgentsRunLike, options?: { reason?: string; signal?: AbortSignal }): Promise<AgentsRun>;
events(run: AgentsRunLike, options?: AgentsEventsOptions): AsyncIterable<AgentEvent>;
/** Follow a run until it ends; resolves with its end status (null when the stream closed without one). */
follow(run: AgentsRunLike, handlers?: AgentsFollowHandlers): Promise<{ status: 'done' | 'failed' | 'stopped' | null }>;
}interface AgentsApprovals
export interface AgentsApprovals {
/** Answer an approval by its id, its object, or the seq of the step that asked. */
answer(run: AgentsRunLike, approval: string | number | Pick<AgentsApproval, 'id' | 'step_seq'>, answer: string | Record<string, unknown>, options?: { signal?: AbortSignal }): Promise<AgentsApproval>;
}interface AgentsDeskView
export interface AgentsDeskView { desk: { id: string; [field: string]: unknown }; view: unknown; still: string | null }interface AgentsClient
export interface AgentsClient {
runs: AgentsRuns;
approvals: AgentsApprovals;
/** See it work: the desks a run may show, the person's control of one, the finished run's replay. */
desks(run: AgentsRunLike, options?: { signal?: AbortSignal }): Promise<{ desks: AgentsDeskView[] }>;
takeOver(run: AgentsRunLike, desk: string, options?: { signal?: AbortSignal }): Promise<unknown>;
handBack(run: AgentsRunLike, desk: string, note?: string, options?: { signal?: AbortSignal }): Promise<unknown>;
replay(run: AgentsRunLike, options?: { signal?: AbortSignal }): Promise<{ steps: object[] }>;
/** The first shapes, as released: an Ask run's snapshot, its approval post and its stream. */
run(id: string, options?: { signal?: AbortSignal }): Promise<AgentsRun | null>;
post(id: string, approval: AgentApproval, options?: { signal?: AbortSignal }): Promise<unknown>;
events(run: AgentsRunLike, options?: AgentsEventsOptions): AsyncIterable<AgentEvent>;
}interface AgentsClientOptions
export interface AgentsClientOptions { baseUrl?: string; service?: string; audience?: string; /** `/api/v1` on a product (default), `/api/frame` on the Frame. */ prefix?: string }export export function createAgentsClient(client: unknown, options?
export function createAgentsClient(client: unknown, options?: AgentsClientOptions): AgentsClient;export export function createFrameAgentsClient(client: unknown, opt
Every product's runs through the Frame (`/api/frame/runs…`): a run is named by its ref.
export function createFrameAgentsClient(client: unknown, options?: Omit<AgentsClientOptions, 'prefix' | 'service' | 'audience'>): AgentsClient;export export const KINDS: readonly ['chat', 'ask', 'task', 'code',
export const KINDS: readonly ['chat', 'ask', 'task', 'code', 'machine', 'goal'];export export const STATUSES: readonly AgentRunStatus[];
export const STATUSES: readonly AgentRunStatus[];export export const END_STATUSES: readonly ['done', 'failed', 'stop
export const END_STATUSES: readonly ['done', 'failed', 'stopped'];export export function isEnd(runOrStatus: AgentsRun | AgentRunStatu
export function isEnd(runOrStatus: AgentsRun | AgentRunStatus | null | undefined): boolean;export export function refOf(product: string, id: string): string;
export function refOf(product: string, id: string): string;export export function parseRef(ref: string): { product: string; id
export function parseRef(ref: string): { product: string; id: string } | null;export export function needsPerson(run: AgentsRun | null | undefine
Does this run need its person now (an approval, a takeover, a payment)? A conversation between turns does not.
export function needsPerson(run: AgentsRun | null | undefined): boolean;interface AgentsModelRequest
export interface AgentsModelRequest { messages: object[]; tools?: AgentTool[]; model?: string; budget?: AgentsBudget; signal?: AbortSignal }interface AgentsModelTurn
export interface AgentsModelTurn { text?: string; tool_calls?: object[]; usage?: { tokens?: number }; cost?: { usd?: number }; raw?: object }interface AgentModelAdapter
The only way the loop reaches a model: AI routes, a person's key, a Link machine's local model or a plan.
export interface AgentModelAdapter {
id: string;
family?: string;
complete(request: AgentsModelRequest): Promise<AgentsModelTurn>;
}interface AgentToolContext
export interface AgentToolContext { run: AgentsRun; toolCall: AgentsToolCall; signal?: AbortSignal }interface AgentToolResult
export interface AgentToolResult { result: unknown; cost?: { usd?: number }; artifacts?: object[] }interface AgentTool
A tool the loop may call: an OpenVibe product, an MCP server or one of a machine's own tools.
export interface AgentTool {
name: string;
description: string;
inputSchema?: object;
run(input: object, context: AgentToolContext): Promise<AgentToolResult>;
}interface AgentSandboxOptions
export interface AgentSandboxOptions { cwd?: string; env?: object; timeoutMs?: number; signal?: AbortSignal }interface AgentSandbox
Where code runs: a Codes worker, a Link machine or an OpenVibe computer.
export interface AgentSandbox {
id: string;
where?: 'codes-worker' | 'link-machine' | 'run-computer' | 'this-computer';
exec(command: string | string[], options?: AgentSandboxOptions): Promise<{ ok: boolean; output: string; exitCode?: number; artifacts?: object[] }>;
readFile?(path: string, options?: { encoding?: string }): Promise<string | Uint8Array>;
writeFile?(path: string, data: string | Uint8Array): Promise<{ path: string; bytes?: number }>;
}interface AgentMemoryQuery
export interface AgentMemoryQuery { text?: string; kinds?: string[]; limit?: number }interface AgentMemoryEntry
export interface AgentMemoryEntry { text: string; kind?: string; ref?: string; data?: object }interface AgentMemory
What a run may remember, scoped to its owner (Actor's memories, Codes' knowledge, a person's notes).
export interface AgentMemory {
read(query: AgentMemoryQuery): Promise<object[]>;
write(entry: AgentMemoryEntry): Promise<object>;
forget?(id: string): Promise<boolean>;
}interface AgentsPlanStep
export interface AgentsPlanStep { title: string; kind?: string; tool?: string }interface AgentPlanner
Turns the input into steps before the loop runs; replaceable, including with a no-plan adapter.
export interface AgentPlanner {
plan(input: { run: AgentsRun; text: string; context?: object; signal?: AbortSignal }): Promise<{ steps: AgentsPlanStep[]; text?: string }>;
}interface AgentsReview
export interface AgentsReview { ok: boolean; reason?: string; by?: string; cross?: boolean }interface AgentReviewer
The second look: a model of another family, a test suite or a rubric.
export interface AgentReviewer {
review(input: { run: AgentsRun; result: unknown; steps?: AgentsStep[]; signal?: AbortSignal }): Promise<AgentsReview>;
}