@agent-webkit/core API

npm install @agent-webkit/core

Runs in browsers, Node ≥ 18, Deno, Bun, and Cloudflare Workers.

`createAgentClient(opts)`

Factory for an AgentClient.

import { createAgentClient } from "@agent-webkit/core";

const client = createAgentClient({
  baseUrl: "https://api.example.com",
  token: "...",            // optional Bearer token
  fetchImpl: globalThis.fetch, // optional, for testing or non-standard runtimes
});

`CreateAgentClientOptions`

Field	Type	Required	Notes
`baseUrl`	`string`	yes	Server origin, no trailing slash.
`token`	`string`	no	Bearer token. Sent on every request.
`fetchImpl`	`typeof fetch`	no	Override fetch (testing, polyfilled runtimes).

`AgentClient`

interface AgentClient {
  createSession(opts?: CreateSessionOptions): Promise<Session>;
  attachSession(sessionId: string, opts?: { resumeFromEventId?: string }): Session;
}

`CreateSessionOptions`

Field	Type	Notes
`model`	`string`	e.g. `"claude-opus-4-7"`. Defaults to SDK default.
`permission_mode`	`string`	`"default"`, `"acceptEdits"`, `"bypassPermissions"`, ...
`cwd`	`string`	Working directory for the agent subprocess.

`Session`

What you get back from createSession or attachSession.

interface SessionHandle {
  readonly id: string;
  readonly protocolVersion: string;
  readonly lastEventId: string | undefined;

  events(): AsyncIterable<DeliveredEvent>;

  send(input: UserInput): Promise<void>;
  interrupt(): Promise<void>;

  approve(correlationId: string, options?: ApproveOptions): Promise<void>;
  deny(correlationId: string, options?: DenyOptions): Promise<void>;
  answer(correlationId: string, answers: unknown): Promise<void>;

  setPermissionMode(mode: string): Promise<void>;
  setModel(model: string | null): Promise<void>;
  stopTask(taskId: string): Promise<void>;

  detach(): void;        // Stop streaming, leave session alive on server
  close(): Promise<void>; // DELETE /sessions/{id}
}

`events()`

Async iterable over server-sent events. Auto-reconnects on transport errors using Last-Event-ID.

for await (const event of session.events()) {
  switch (event.event) {
    case "message_delta": /* ... */ break;
    case "message_complete": /* ... */ break;
    case "permission_request":
      await session.approve(event.data.correlation_id);
      break;
  }
}

DeliveredEvent is ServerEvent & { id: number }. See Wire protocol for the full event catalog.

`UserInput`

type UserInput = string | ContentBlock[];

type ContentBlock =
  | { type: "text"; text: string }
  | { type: "image"; source: { type: "base64"; media_type: string; data: string } }
  | ToolUseBlock
  | ToolResultBlock;

`ApproveOptions` / `DenyOptions`

interface ApproveOptions {
  updatedInput?: Record<string, unknown>;     // Modify the tool input before allowing
  updatedPermissions?: unknown[];              // Optional permission updates
}

interface DenyOptions {
  message?: string;     // Reason shown to the model
  interrupt?: boolean;  // If true, abort the current turn entirely
}

Low-level SSE helpers

For advanced use (e.g. building a custom transport on top), @agent-webkit/core exports:

import { feedSSE, newSSEParserState, type ParsedSSEEvent } from "@agent-webkit/core";

Export	Signature
`newSSEParserState`	`() => SSEParserState`
`feedSSE`	`(state: SSEParserState, chunk: string) => ParsedSSEEvent[]`
`ParsedSSEEvent`	`{ id?: string; event?: string; data: string }`

Also: Transport, TransportOptions, TransportError — for plumbing custom HTTP behavior.

Errors

Network and HTTP errors are thrown as TransportError. On the SSE iterator, transient errors trigger reconnect; only terminal failures (auth, 412 buffer eviction) propagate as thrown values.

@agent-webkit/core API

On this page