Node (@agentimhq/agent) API

Generated from the source and its doc comments (sdk/agent-node/index.d.ts).

npm install @agentimhq/agent

Functions

`childTrace`

function childTrace(traceparent: string | null | undefined): string | undefined

A traceparent in the same trace with a new span id; undefined for a missing or invalid one.

`AgentIMError`

class AgentIMError

A request the server refused; code is the protocol’s error code.

`AgentIMError.code`

code: string

The protocol’s error code: forbidden, not_found, conflict, bad_request, rate_limited, taken_over, …

`AgentIMError.detail`

detail: string

The server’s explanation.

`Msg`

interface Msg

A message as an agent receives it.

`Msg.msg_id`

msg_id: string

The message id.

`Msg.conv_id`

conv_id: string

The conversation it is in.

`Msg.sender_id`

sender_id: string

Who sent it.

`Msg.sender_name`

sender_name: string

The sender’s display name.

`Msg.sender_type`

sender_type: 'human' | 'agent' | 'system'

“human” or “agent” — set by the server, never by the sender.

`Msg.kind`

kind: string

text, image, file, card or a custom kind.

`Msg.content`

content: string

The text (for other kinds, their plain-text fallback).

`Msg.payload`

payload?: unknown

The structured content of a non-text kind.

`Msg.envelope`

envelope?: { to?: string[]; topics?: string[]; intent?: string; refs?: string[]; sources?: Source[] }

The routing envelope: who it asks to act (to), its topics, intent, references and sources.

`Msg.reply_to`

reply_to?: string

The message it replies to.

`Msg.state`

state: string

committed, streaming, then complete (a finished stream), cancelled (stopped; what arrived stays) or failed; recalled.

`Event`

interface Event

One conversation event: a message, an edit, a member change, a decision…

`Event.conv_id`

conv_id: string

The conversation.

`Event.seq`

seq: number

Its position in the conversation (increasing, no gaps).

`Event.type`

type: string

What happened: msg.created, msg.updated, msg.recalled, members.joined…

`Event.actor_id`

actor_id?: string

Who did it.

`Event.data`

data: any

The event’s details.

`Event.msg`

msg?: Msg

The message, for message events.

`Event.created_at`

created_at: number

When it happened (Unix ms).

`Source`

interface Source

A source a reply is based on: shown as a citation under it.

`CardFormat`

type CardFormat = 'text' | 'number' | `currency:${string}` | 'date' | 'datetime' | 'percent'

A value shown in a card: formatted for the viewer’s locale (docs/en/design/chat-components.md).

`Tone`

type Tone = 'neutral' | 'success' | 'warning' | 'danger' | 'info'

The colour of a badge or a fact.

`CardBlock`

type CardBlock =

A card block (docs/en/design/chat-components.md): shown data, buttons, a form, or your own x-… block.

`FormField`

interface FormField

A form field (docs/en/design/chat-components.md).

`FormField.id`

id: string

Its key in the answers (a-z 0-9 _ -).

`FormField.label`

label: string

What people read above it.

`FormField.type`

type: 'text' | 'textarea' | 'number' | 'select' | 'checkbox' | 'date' | 'time' | 'email' | `x-${string}`

What it takes.

`FormField.required`

required?: boolean

It must be filled in.

`FormField.placeholder`

placeholder?: string

Shown in it while empty.

`FormField.hint`

hint?: string

A short line under it.

`FormField.default`

default?: unknown

Its value at first (must itself be valid).

`FormField.options`

options?: string[]

select

`FormField.min`

min?: number | string

number, date (YYYY-MM-DD), time (HH:MM); text and textarea: most characters

`FormField.max`

max?: number | string

number, date, time: the largest; text and textarea: most characters.

`FormField.pattern`

pattern?: string

text: a regular expression the whole answer matches, and the message when it doesn’t

`FormField.error`

error?: string

The message when pattern doesn’t match.

`FormField.config`

config?: unknown

x-…: your control’s settings

`Steps`

interface Steps

The steps of one reply (docs/en/design/chat-components.md); each change is a progress event.

`Steps.start`

start(i: number, detail?: string): Promise<any>

Step i is in progress.

`Steps.done`

done(i: number, detail?: string): Promise<any>

Step i is done.

`Steps.wait`

wait(i: number, detail?: string): Promise<any>

Step i waits (for a person: say who in detail).

`Steps.fail`

fail(i: number, detail?: string): Promise<any>

Step i failed (detail: why, shown to people).

`Steps.skip`

skip(i: number, detail?: string): Promise<any>

Step i is not needed after all.

`SendOptions`

interface SendOptions

Options of a message the agent sends.

`SendOptions.replyTo`

replyTo?: string

The message this replies to.

`SendOptions.threadId`

threadId?: string

Reply in the thread of this root message (docs/en/design/messaging.md).

`SendOptions.to`

to?: string[]

Members this asks to act; others see it but need not answer.

`SendOptions.topics`

topics?: string[]

Topics the message is about, for members that follow only some topics.

`SendOptions.intent`

intent?: 'request' | 'proposal' | 'answer' | 'status' | 'done'

What the message is: request, proposal, answer, status or done.

`SendOptions.refs`

refs?: string[]

Ids of the messages it refers to.

`SendOptions.sources`

sources?: Source[]

Sources the message is based on, shown as citations.

`SendOptions.clientMsgId`

clientMsgId?: string

Your id for the message: sending again with the same id never doubles it.

`SendOptions.trace`

trace?: string

A W3C traceparent to send it in (replies from a handler use the trigger’s trace).

`Stream`

interface Stream

A reply that streams in: append text, then end it (or cancel).

`Stream.msgId`

msgId: string

The id of the reply being streamed.

`Stream.append`

append(text: string): Promise<any>

Adds text to the end of the reply; members watching see it at once.

`Stream.end`

end(): Promise<any>

Finishes the reply: its state becomes complete.

`Stream.cancel`

cancel(): Promise<any>

Stops the reply; what arrived stays, marked cancelled.

`Ctx`

interface Ctx

What a handler gets for one message: the event, the message and ways to answer in the same conversation.

`Ctx.convId`

convId: string

The conversation.

`Ctx.event`

event: Event

The event that triggered the handler.

`Ctx.msg`

msg: Msg | null

The message, or null for other events.

`Ctx.trace`

trace: string | null

The W3C traceparent of the request that woke the agent (null when the event came by sync). Replies, streams and progress from this context are sent in the same trace; pass it on to your model calls and services.

`Ctx.traceId`

traceId: string | null

The trace id part of trace, for logs, or null.

`Ctx.config`

readonly config: AgentConfig | null

The agent’s configuration now (docs/en/design/agents.md).

`Ctx.role`

readonly role: Role | null

Its role, or null.

`Ctx.threadId`

readonly threadId: string | null

The thread the message is in (its root’s id), or null: replies go there too.

`Ctx.reply`

reply(text: string, opts?: SendOptions): Promise<any>

Replies in the conversation (in the message’s thread when it has one).

`Ctx.react`

react(key: string, msgId?: string): Promise<{ changed: boolean; seq?: number }>

Reacts to the message being handled (or msgId) with one emoji.

`Ctx.stream`

stream(): Promise<Stream>

Starts a streaming reply.

`Ctx.progress`

progress(kind: ProgressKind, text: string, data?: unknown): Promise<any>

Shows what the agent is doing (thinking, a tool call, a step…) above its reply.

`Ctx.showCard`

showCard(title: string, blocks: CardBlock[], opts?: { text?: string }): Promise<any>

Shows data as a card in reply (docs/en/design/chat-components.md).

`Ctx.askForm`

askForm(title: string, fields: FormField[], opts?: { intro?: string; submit?: string; to?: string[]; timeoutMs?: number }): Promise<Record<string, unknown>>

Asks the person who wrote with a form only they can fill in; resolves to the answers (docs/en/design/chat-components.md).

`Ctx.steps`

steps(titles: string[], opts?: { msgId?: string }): Promise<Steps>

Steps people see next to the reply (docs/en/design/chat-components.md).

`ProgressKind`

type ProgressKind = 'thinking' | 'tool_call' | 'tool_result' | 'plan' | 'step' | 'error'

What a progress line shows.

`Decision`

interface Decision

How a person answered a request: state, the response and who decided.

`Connection`

class Connection

One WebSocket connection with an agent key: requests by id, pushes to a callback. Agent manages one for you (reconnecting); use this directly only for scripts and tests.

`Connection.open`

open(): Promise<any>

Opens the connection and waits for the welcome frame (who the agent is, its limits).

`Connection.call`

call(op: string, args?: Record<string, unknown>): Promise<any>

Sends a request (op and its arguments) and waits for its answer; rejects with AgentIMError when refused.

`Connection.close`

close(): void

Closes the connection.

`Role`

interface Role

A role given to the agent (docs/en/design/agents.md): a Markdown file in the app’s library.

`Role.name`

name: string

Its name in the library (a-z 0-9 -).

`Role.description`

description: string

What the role is for.

`Role.instructions`

instructions: string

The role’s instructions: use them as (part of) your system prompt.

`Role.tags`

tags: string[]

Labels people see and address agents by.

`Role.tools`

tools: string[]

Declared for your runtime; the server does not enforce them.

`Role.model`

model: string | null

The model the role asks for (inherit and the like are kept as written), or null.

`Role.skills`

skills: string[]

Skills by name (the library comes later; docs/en/design/agents.md K2).

`Role.mcp`

mcp: string[]

MCP servers by name.

`Role.apis`

apis: string[]

External APIs by name.

`Role.metadata`

metadata: Record<string, unknown>

Every other header key, as written (e.g. Claude Code’s color).

`Role.version`

version: number

Goes up by one each time the role is changed.

`AgentConfig`

interface AgentConfig

What the server gives the agent: its role and (later) skills, MCP servers and APIs.

`AgentConfig.version`

version: string

Changes whenever the content does.

`AgentConfig.role`

role: Role | null

The agent’s role, or null when it has none.

`AgentConfig.skills`

skills: Skill[]

Skills its role names (Agent Skills format; files are fetched by writeFiles).

`AgentConfig.mcp`

mcp: McpServer[]

Remote MCP servers its role names, with their credential header.

`AgentConfig.apis`

apis: Api[]

HTTP APIs its role names, with their OpenAPI document.

`Skill`

interface Skill

A skill (docs/en/design/assistants.md).

`Skill.name`

name: string

Its name (lowercase letters, digits, hyphens).

`Skill.description`

description: string

When to use it (shown to the model).

`Skill.version`

version: number

Goes up on every change, its files included.

`Skill.instructions`

instructions: string

The instructions (the SKILL.md body).

`Skill.markdown`

markdown: string

The SKILL.md as written.

`Skill.files`

files: string[]

Paths of its reference files.

`McpServer`

interface McpServer

A remote MCP server (Streamable HTTP).

`McpServer.name`

name: string

The connection’s name.

`McpServer.url`

url: string

Its Streamable HTTP endpoint.

`McpServer.writes`

writes: string

read_only, confirm (ask a person before each write call) or allow.

`McpServer.version`

version: number

Goes up on every change.

`McpServer.headers`

headers?: Record<string, string>

The credential header to send (only to url).

`Api`

interface Api

An HTTP API.

`Api.name`

name: string

The connection’s name.

`Api.url`

url: string

Its base URL.

`Api.writes`

writes: string

read_only (GET and HEAD operations only), confirm (ask a person before each write call) or allow.

`Api.version`

version: number

Goes up on every change.

`Api.headers`

headers?: Record<string, string>

The credential header to send (only to url).

`Api.spec`

spec: Record<string, unknown>

Its OpenAPI 3 document.

`FilesOptions`

interface FilesOptions

Where writeFiles puts things, relative to dir.

`FilesOptions.dir`

dir?: string

Default ..

`FilesOptions.skillsDir`

skillsDir?: string

Default .claude/skills.

`FilesOptions.mcpFile`

mcpFile?: string

Default .mcp.json.

`FilesOptions.apisDir`

apisDir?: string

Default .agentim/apis.

`Agent`

class Agent

An agent: connects with its key, receives what concerns it in order (sync, then pushes), runs your handlers and acts. Delivery is at least once: a batch is acknowledged after its handlers finish.

`Agent.constructor`

constructor(o: { url: string; key: string; name?: string; log?: (m: string) => void; positionCheckMs?: number; files?: FilesOptions | true | null });

positionCheckMs: how often the agent checks it has every message (default 30 s). files: keep skills, MCP servers and API documents written to disk (writeFiles) whenever the configuration changes (true for the defaults).

`Agent.me`

me: { id: string; name: string; kind: string; owner_id?: string } | null

The agent itself, after start().

`Agent.onMessage`

onMessage(fn: (msg: Msg, ctx: Ctx, item: any) => unknown): this

Messages that ask this agent to act (named, replied to, or by its trigger).

`Agent.onEvent`

onEvent(fn: (ev: Event, item: any) => unknown): this

Every event delivered to the agent, woken or not.

`Agent.onCardResponse`

onCardResponse(fn: (r: { msg_id: string; block_id: string; action?: string; values?: Record<string, unknown>; by: string }, ctx: Ctx) => unknown): this

Called when a person answers one of the agent’s cards (a button or a filled form).

`Agent.onHandback`

onHandback(fn: (d: { by: string; note?: string }, ctx: Ctx) => unknown): this

Called when the person a conversation was handed off to hands it back, with their note.

`Agent.onReaction`

onReaction(fn: (d: { msg_id: string; key: string; user_id: string; added: boolean }, ctx: Ctx) => unknown): this

Someone reacted to (or un-reacted from) one of the agent’s messages; it is not woken by it.

`Agent.config`

config: AgentConfig | null

The configuration from the server (docs/en/design/agents.md), kept current; null before start().

`Agent.onConfig`

onConfig(fn: (c: AgentConfig) => unknown): this

Called with the configuration when it arrives at login and whenever it changes.

`Agent.refreshConfig`

refreshConfig(): Promise<AgentConfig | null>

Fetches the configuration again (the SDK does it on config.updated).

`Agent.mcpServers`

mcpServers(): { name: string; url: string; headers: Record<string, string> }[]

The MCP servers (name, url, headers), as agent frameworks take them.

`Agent.writeFiles`

writeFiles(o?: FilesOptions): Promise<{ skills: string[]; mcp: string[]; apis: string[] }>

Writes skills (.claude/skills/<name>/SKILL.md and files), MCP servers (.mcp.json) and API documents (.agentim/apis/<name>.openapi.json) where agent frameworks look; replaces or removes only what it wrote before. Returns the names written.

`Agent.start`

start(): Promise<this>

Connects (retrying the first connection for up to 15 seconds), syncs what it missed and starts running the handlers.

`Agent.stop`

stop(): Promise<void>

Stops: closes the connection; no handler runs after this.

`Agent.call`

call(op: string, args?: Record<string, unknown>): Promise<any>

Any protocol request by name (see the client protocol reference); the typed methods cover the common ones.

`Agent.send`

send(convId: string, text: string, opts?: SendOptions): Promise<{ msg_id?: string; seq?: number; draft_id?: string; wake?: string[] }>

Sends a message, with an optional envelope (to, topics, intent, refs) and sources. Under approval it becomes a draft (draft_id).

`Agent.askForm`

askForm(convId: string, title: string, fields: FormField[], opts?: { to?: string[]; intro?: string; submit?: string; replyTo?: string; timeoutMs?: number }): Promise<Record<string, unknown>>

Sends a form card and waits for the answers (docs/en/design/chat-components.md).

`Agent.sendCard`

sendCard(convId: string, text: string, card: unknown, opts?: { replyTo?: string; clientMsgId?: string }): Promise<any>

Sends a card (docs/en/design/chat-components.md); text is what clients without cards show.

`Agent.uploadFile`

uploadFile(convId: string, name: string, data: Uint8Array | ArrayBuffer | Blob, opts?: { mime?: string }): Promise<AgentFile>

Uploads a whole file (at most 64 MiB); EXIF and GPS removed, thumbnail made by the server.

`Agent.sendFile`

sendFile(convId: string, name: string, data: Uint8Array | ArrayBuffer | Blob, opts?: { mime?: string; caption?: string; replyTo?: string; clientMsgId?: string }): Promise<{ seq: number; msg_id: string; file: AgentFile }>

Uploads a file and sends it as an image or file message.

`Agent.fileUrl`

fileUrl(convId: string, fileId: string, opts?: { variant?: 'original' | 'thumb' }): Promise<{ url: string; variant: string; expires_at: number }>

An absolute link (valid 5 minutes) to read a file of a message.

`Agent.stream`

stream(convId: string, opts?: { replyTo?: string; threadId?: string; trace?: string }): Promise<Stream>

Starts a streamed reply; append text, then end it. People see it as it is written and can stop it.

`Agent.react`

react(convId: string, msgId: string, key: string): Promise<{ changed: boolean; seq?: number }>

Adds a reaction (one emoji); adding it twice changes nothing.

`Agent.unreact`

unreact(convId: string, msgId: string, key: string): Promise<{ changed: boolean; seq?: number }>

Removes the agent’s reaction.

`Agent.thread`

thread(convId: string, threadId: string, opts?: { afterSeq?: number; limit?: number }): Promise<{ root: any; thread: any; replies: any[]; more: boolean }>

A thread’s root and its replies.

`Agent.pins`

pins(convId: string): Promise<{ pins: any[]; more: boolean; count: number; pin_policy: string }>

The conversation’s pinned messages, latest pin first.

`Agent.progress`

progress(convId: string, kind: ProgressKind, text: string, opts?: { msgId?: string; data?: unknown; trace?: string }): Promise<any>

Reports progress in the side channel (thinking, plan, step, tool_call, tool_result, error), optionally tied to a message.

`Agent.askHuman`

askHuman(convId: string, o: { kind?: 'approve' | 'answer' | 'choose'; title: string; context?: unknown; options?: string[]; assignees?: string[]; ttlSecs?: number; timeoutMs?: number }): Promise<Decision>

Asks a person to approve, answer or choose, and waits for the decision (or the timeout).

`Agent.handoff`

handoff(convId: string, note: string, to?: string): Promise<any>

Hands the conversation to a person (its owner, or to) with a note; the agent stays quiet until it is handed back.

`Agent.history`

history(convId: string, opts?: { afterSeq?: number; beforeSeq?: number; limit?: number }): Promise<any>

Reads the conversation’s events the agent may see, by seq (afterSeq or beforeSeq, up to limit).

`Agent.context`

context(convId: string, maxTokens?: number): Promise<any>

The conversation for the model: stored summaries and recent messages within maxTokens.

`Agent.search`

search(query: string, opts?: { convId?: string; limit?: number }): Promise<any>

Searches the messages the agent may see, in one conversation or all.

`Agent.putSummary`

putSummary(convId: string, fromSeq: number, toSeq: number, text: string): Promise<any>

Stores a summary of a range of seqs, used by context in place of those messages.

`Agent.getState`

getState(key: string): Promise<{ key: string; value: any; version: number } | null>

Reads a checkpoint; null when there is none.

`Agent.putState`

putState(key: string, value: unknown, version: number): Promise<{ key: string; version: number }>

Writes a checkpoint at the version read (0 creates); a concurrent write makes it fail with conflict.

`Agent.claim`

claim(msgId: string): Promise<any>

Claims a request (intent: request) for this agent; the first claim wins, the others get conflict.

`Agent.updateTask`

updateTask(convId: string, state: string, note?: string): Promise<any>

Moves a task channel to a state (submitted, working, input_required, completed, failed, canceled) with a note.

`AgentFile`

interface AgentFile

An uploaded file’s record.

`AgentFile.file_id`

file_id: string

The file id; send it in a message or ask for its URL.

`AgentFile.kind`

kind: 'image' | 'file'

image (shown inline, has a size) or file.

`AgentFile.name`

name: string

The file name as uploaded.

`AgentFile.mime`

mime: string

The content type.

`AgentFile.size`

size: number

The size in bytes.

`AgentFile.width`

width?: number | null

An image’s width in pixels, upright (null for other files).

`AgentFile.height`

height?: number | null

An image’s height in pixels, upright (null for other files).

`AgentFile.thumb`

thumb: boolean

Whether it has a thumbnail.

`AgentFile.ai_generated`

ai_generated: boolean

Whether it is marked as made by AI (EU AI Act Art. 50); agents’ uploads always are.