Types

Exhaustive reference of all exported types and functions from the experimental-agent package.

Grouped by category: core, storage, usage, sandbox, tool, error, and skill.

Core Types

AgentOptions

import type { AgentOptions, SkillInput } from "experimental-agent";

type AgentOptions<Tools, TSandboxBindings, TContext, TState, TMessageMetadata> = {
  model?: GatewayModelId;
  system?: string;
  storage?: unknown;
  tools?: Tools;
  hooks?: AgentHooks;
  contextSchema?: z.ZodType<TContext>;
  stateSchema?: z.ZodType<TState>;
  messageMetadataSchema?: z.ZodType<TMessageMetadata>;
  needsApproval?: NeedsApprovalMap<Tools>;
  sandbox?: SandboxBinding | SandboxBinding[];
  skills?: SkillInput[];
  activeTools?: (keyof Tools | BuiltInToolName)[];
  generation?: GenerationOptions;
  logging?: unknown;
};

Agent configuration. See agent().

SessionOptions

import type { SessionOptions, SkillInput } from "experimental-agent";

type SessionOptions<Tools> = {
  model?: GatewayModelId;
  system?: string;
  skills?: SkillInput[];
  activeTools?: (keyof Tools | BuiltInToolName)[];
  generation?: GenerationOptions;
};

Session-level overrides. See Session API.

SessionUpdateOptions

type SessionUpdateOptions<Tools> = Pick<
  SessionOptions<Tools>,
  "model" | "system" | "skills" | "activeTools" | "generation"
>;

Options for session.update(). Subset of SessionOptions. Inferred from the session type.

SendInput

import type { SendInput } from "experimental-agent";

type SendInput =
  | string
  | { role?: UIMessage["role"]; parts: UIMessage["parts"]; metadata?: Record<string, unknown>; id?: string };

Input for session.send(). String or full message object.

AgentStatus

import { AgentStatus } from "experimental-agent";

type AgentStatus =
  | { type: "sandbox-setup" }
  | { type: "sandbox-setup-cold" }
  | { type: "loading-skills" }
  | { type: "processing-approvals" }
  | { type: "needs-approval" }
  | { type: "thinking" }
  | { type: "custom"; status: string };

Transient status indicator. Emitted as data-status chunks with transient: true.

AgentDataTypes

import type { AgentDataTypes } from "experimental-agent";

type AgentDataTypes = { status: AgentStatus };

Data part types for UIMessage. Used as DATA_PARTS generic.

InferUIMessage

import type { InferUIMessage } from "experimental-agent";

type InferUIMessage<A> = A extends { tools: infer T; $UIMessage: UIMessage<infer M> }
  ? UIMessage<M, AgentDataTypes, InferUITools<T>>
  : UIMessage<unknown, AgentDataTypes>;

Infer typed UIMessage from agent, including message metadata. Use typeof myAgent.$UIMessage.

RpcPayload

import type { RpcPayload } from "experimental-agent";

type RpcPayload = {
  name?: string;
  method: string;
  params: unknown;
};

RPC request payload for agent handler.

RpcResult

import type { RpcResult } from "experimental-agent";

type RpcResult<T = unknown> =
  | { result: T }
  | { error: { code: string; message: string }; status?: number };

RPC response. Success has result; error has error.

GenerationOptions

import type { GenerationOptions } from "experimental-agent";

type GenerationOptions = {
  maxSteps?: number;
  temperature?: number;
  topK?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
  maxOutputTokens?: number;
  headers?: Record<string, string>;
};

Model generation parameters. See GenerationOptions.

Storage Types

StorageHandlers

import type { StorageHandlers } from "experimental-agent/storage";

Map of storage RPC method names to handler functions. See StorageConfig.

Storage

import type { Storage } from "experimental-agent/storage";

Storage interface with session, message, part, sandbox, command, setup namespaces.

Session

import type { Session } from "experimental-agent/storage";

type Session = {
  id: string;
  createdAt: number;
  updatedAt: number;
  lastMessageId: string | null;
  sandboxId: string | null;
  state?: Record<string, unknown>;
};

Session record from storage. The state field holds mutable per-session state defined by stateSchema.

Message

import type { Message } from "experimental-agent/storage";

type Message = {
  id: string;
  sessionId: string;
  role: "user" | "assistant" | "system";
  createdAt: number;
  startedAt: number | null;
  completedAt: number | null;
  interruptedAt: number | null;
  usage: MessageUsage | null;
  metadata?: Record<string, unknown> | null;
  /* ... */
};

Message record. The optional metadata field stores application-defined data that round-trips through storage unchanged. See Message Metadata.

Part

import type { Part } from "experimental-agent/storage";

type Part = {
  id: string;
  messageId: string;
  sessionId: string;
  index: number;
  part: UIMessage["parts"][number];
};

Message part record. part matches AI SDK UIMessage part shape.

Sandbox (storage record)

import type { Sandbox } from "experimental-agent";

type Sandbox = {
  id: string;
  setup: {
    binding: string;
    version: string | null;
    completedAt: number | null;
    metadata: Record<string, unknown> | null;
    networkPolicy: NetworkPolicy | null;
  };
  createdAt: number | null;
  lastActiveAt: number | null;
};

Sandbox record from storage. Tracks binding type, setup version, and completion state.

ListResult

import type { ListResult } from "experimental-agent";

type ListResult<T> = {
  items: T[];
  nextCursor: string | null;
};

Paginated list result.

ResolvedStorage

import type { ResolvedStorage } from "experimental-agent";

type ResolvedStorage = {
  url: string;
  headers?: Record<string, string>;
};

Resolved storage URL and headers.

RpcRequest

import type { RpcRequest } from "experimental-agent";

type RpcRequest = {
  method: string;
  params: unknown;
};

Storage RPC request body.

RpcResponse

import type { RpcResponse } from "experimental-agent";

type RpcResponse<T = unknown> =
  | { result: T }
  | { error: { code: string; message: string } };

Storage RPC response.

Usage Types

MessageUsage

import type { MessageUsage } from "experimental-agent";

type MessageUsage = {
  steps: StepUsage[];
  summary: UsageSummary;
};

Usage per message.

StepUsage

import type { StepUsage } from "experimental-agent";

type StepUsage = {
  stepIndex: number;
  model: string;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  cacheReadTokens: number;
  cacheWriteTokens: number;
  reasoningTokens: number;
};

Usage per step.

UsageSummary

import type { UsageSummary } from "experimental-agent";

type UsageSummary = {
  model: string;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  cacheReadTokens: number;
  cacheWriteTokens: number;
  reasoningTokens: number;
  stepCount: number;
};

Aggregated usage with step count.

SessionUsage

Returned by session.history() and session.usage(). Not exported; infer from return type.

type SessionUsage = {
  total: UsageSummary & { messageCount: number };
  byMessageId: Record<string, UsageSummary | null>;
};

Sandbox Types

SandboxBinding

import type { SandboxBinding } from "experimental-agent";

Sandbox binding interface. Use the built-in factories (vercelSandbox(), localSandbox(), dockerSandbox()) from experimental-agent/sandbox. See Sandbox Bindings.

SandboxInstance

import type { SandboxInstance } from "experimental-agent";

Sandbox instance interface with exec, readFile, writeFiles, getDomain, kill, updateNetworkPolicy, start, stop, snapshot, getStatus. See Sandbox Bindings.

ExecResult

import type { ExecResult } from "experimental-agent";

type ExecResult = {
  commandId: string;
  logs: () => AsyncIterable<{ stream: "stdout" | "stderr"; data: string }>;
  result: Promise<{ stdout: string; stderr: string; exitCode: number }>;
};

Command execution result from sandbox.exec().

Tool Types

ToolContext

import type { ToolContext } from "experimental-agent";

type ToolContext<TContext = Record<string, unknown>, TState = Record<string, unknown>> = {
  context: TContext;
  state: TState;
  sessionId: string;
  sandbox: SandboxInstance;
  messages: UIMessage[];
};

Context passed to custom tool execute. State is mutable in tools. See ToolContext.

BuiltInToolName

import type { BuiltInToolName } from "experimental-agent";

type BuiltInToolName = "Read" | "Write" | "Edit" | "Grep" | "List" | "Bash" | "Skill" | "JavaScript";

Union of built-in tool names.

builtinToolNames

import { builtinToolNames } from "experimental-agent";

const builtinToolNames = {
  Read: "Read",
  Write: "Write",
  Edit: "Edit",
  Grep: "Grep",
  List: "List",
  Bash: "Bash",
  Skill: "Skill",
  JavaScript: "JavaScript",
};

Object mapping tool names to themselves. Use for type-safe tool references.

Error Types

SessionNotFoundError

import { SessionNotFoundError } from "experimental-agent";

Thrown when session does not exist.

MessageNotFoundError

import { MessageNotFoundError } from "experimental-agent";

Thrown when message does not exist.

SandboxNotFoundError

import { SandboxNotFoundError } from "experimental-agent";

Thrown when sandbox does not exist.

SandboxError

import { SandboxError } from "experimental-agent";

Sandbox operation error (exec, readFile, etc.).

StorageError

import { StorageError } from "experimental-agent";

Generic storage error.

StorageConflictError

import { StorageConflictError } from "experimental-agent";

Storage conflict (e.g. optimistic concurrency). Throw from custom handlers for CONFLICT RPC response.

Skill Types

SkillSummary

import type { SkillSummary } from "experimental-agent";

type SkillSummary = {
  name: string;
  description: string;
  skillMdPath: string;
};

Summary of a discovered skill.

UploadableFile

import type { UploadableFile } from "experimental-agent";

type UploadableFile = {
  path: string;
  content: string | Buffer;
};

File for sandbox.writeFiles().

Functions

agent

import { agent } from "experimental-agent";

const myAgent = agent("my-agent", options?);

Create an agent. See agent().

Types

On this page