Runtime API

Wire methods to user actions

Keep one runtime instance and route every returned value through the five-state handler. An HTTP handler around invoke() is not a complete conversational integration by itself.

A useful host boundary has distinct handlers: message → chat, known operation → invoke, option click → select, approval click → confirm, cancellation → cancel. Authenticate each handler and derive its session from the caller. IDs returned by a previous result are continuation handles, not credentials.

Configuration inputs and per-call inputs differ

configPath, provider adapters, stores, and the default presentation mode belong to runtime creation. The message, tool arguments, user token, context, and abort signal belong to each call. Supplying both config and configPath is an error; neither overrides the other.

The method examples below are host fragments: identifiers such as sessionId, token, message, choice, and signal must come from your authorized application handlers. For a standalone program with concrete values and assertions, use the booking fixture.

Before shipping, test repeated confirmation, expired selection, cancellation, and a changed config. A method returning without throwing does not imply completion; inspect result.status.

Public exports are defined in src/v2/index.ts.

Create a runtime

const runtime = await AgentRuntime.create({
  configPath: "./config.yml",
  presentation: "raw",
});

RuntimeOptions supports:

interface RuntimeOptions {
  config?: unknown;
  configYml?: string;
  configPath?: string;
  model?: ModelAdapter;
  presentationModel?: ModelAdapter;
  sessionStore?: SessionStore;
  rateLimiter?: RateLimiter;
  retriever?: ToolRetriever;
  authentication?: AuthenticationOptions;
  fetch?: typeof fetch;
  env?: NodeJS.ProcessEnv;
  onEvent?: RuntimeHook;
  presentation?: "raw" | "ai" | "both";
  debug?: boolean;
  now?: () => Date;
}

Exactly one configuration source is allowed.

chat()

const result = await runtime.chat({
  sessionId,
  message: "Show available appointments tomorrow",
  auth: { token },
  context: { tenant: { id: "t_1" } },
  presentation: "both",
  signal,
});

Requirements:

• non-empty string message;
• maximum 20,000 characters in current runtime code;
• configured/provided model adapter;
• session ID using allowed characters.

invoke()

const result = await runtime.invoke({
  sessionId,
  tool: "search-services",
  arguments: { q: "hair" },
  auth: { token },
});

Use when the host already knows the tool. It does not need a model for raw execution.

select()

const result = await runtime.select({
  sessionId,
  selectionId,
  choice,
  auth: { token },
});

The selection must still exist, be unexpired, match the current session/context hash, and use a current option ID.

confirm()

const result = await runtime.confirm({
  sessionId,
  confirmationId,
  auth: { token },
});

The confirmation must match the current prepared operation and unexpired dependency data.

cancel()

await runtime.cancel({ sessionId });

Resets pending execution and clears published references.

listTools()

Returns the immutable model-facing tool definitions.

const tools = runtime.listTools();

getConfig()

Returns a cloned/redacted resolved configuration view.

const config = runtime.getConfig();

diagnostics()

Currently exposes HTTP circuit state:

console.log(runtime.diagnostics());

clearSession()

await runtime.clearSession(sessionId);

Clears session state and stored session credential for that ID.

dispose()

runtime.dispose();

Marks the runtime disposed and releases owned credential-store resources. It does not magically cancel arbitrary in-flight network calls; use request abort signals for request cancellation.

Session ID format

Current runtime validation accepts server-owned session IDs matching roughly:

[A-Za-z0-9_-]{1,200}

Treat this as the current Runtime contract and avoid putting secrets or PII directly in the session ID.