Skip to main content
Complete API documentation for the Agentic Browser Protocol.
This document contains the complete API documentation and TypeScript definitions for ABP.

​
window.abp Interface

Every ABP-compliant app MUST expose this interface: 
interface ABP {
  // Required methods
  initialize(params: InitializeParams): Promise<InitializeResult>;
  shutdown(params?: ShutdownParams): Promise<void>;
  call(capability: string, params?: object, options?: CallOptions): Promise<ABPResponse>;

  // Optional methods
  listCapabilities(): Promise<Capability[]>;
  describeCapability(name: string): Promise<Capability | null>;
  supports(name: string): Promise<SupportInfo>;
  notify(event: string, data?: unknown): void;
  notifyProgress(info: ProgressInfo): void;
  elicit(request: ElicitationRequest): Promise<ElicitationResponse>;
  cancel(callId: string, reason?: string): Promise<CancelResponse>;

  // Metadata
  protocolVersion: string;
  app: { id: string; name: string; version: string };
}

​
Core Methods

​
initialize()

Start an ABP session. 
initialize(params: InitializeParams): Promise<InitializeResult>
Parameters: 
interface InitializeParams {
  agent: { name: string; version: string };
  protocolVersion: string;
  requestedCapabilities?: string[];
  features: {
    notifications: boolean;
    progress: boolean;
    elicitation: boolean;
  };
  agentCapabilities?: {
    allowedRequests: string[];
  };
}
Returns: 
interface InitializeResult {
  sessionId: string;
  protocolVersion: string;
  app: { id: string; name: string; version: string };
  capabilities: CapabilitySummary[];
  features: {
    notifications: boolean;
    progress: boolean;
    elicitation: boolean;
    dynamicCapabilities: boolean;
  };
}
Example: 
const session = await abp.initialize({
  agent: { name: 'my-agent', version: '1.0.0' },
  protocolVersion: '0.1',
  features: { notifications: true, progress: true, elicitation: true }
});

​
shutdown()

End an ABP session. 
shutdown(params?: ShutdownParams): Promise<void>
Parameters: 
interface ShutdownParams {
  reason?: string;
}
Example: 
await abp.shutdown({ reason: 'User requested disconnect' });

​
call()

Execute a capability. 
call(capability: string, params?: object, options?: CallOptions): Promise<ABPResponse>
Parameters:
  • capability — Capability name (e.g., "convert.markdownToHtml")
  • params — Capability-specific parameters
  • options — Call options
interface CallOptions {
  timeout?: number;
  progressToken?: string;
  callId?: string;
}
Returns: 
interface ABPResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: ABPError;
  metadata?: {
    duration: number;
    cached?: boolean;
  };
  cancelled?: boolean;
}

interface ABPError {
  code: string;
  message: string;
  details?: unknown;
  retryable: boolean;
  retryAfter?: number;
  alternatives?: string[];
}
Example: 
const result = await abp.call('convert.markdownToHtml', {
  markdown: '# Hello World',
  options: { sanitize: true }
});

if (result.success) {
  console.log('HTML:', result.data.html);
} else {
  console.error('Error:', result.error.message);
}

​
Discovery Methods

​
listCapabilities()

List all available capabilities. 
listCapabilities(): Promise<Capability[]>
Returns: Array of Capability objects (see Types).

​
describeCapability()

Get detailed information about a specific capability. 
describeCapability(name: string): Promise<Capability | null>
Returns: Capability object or null if not found.

​
supports()

Quick check if a capability is supported and available. 
supports(name: string): Promise<SupportInfo>
Returns: 
interface SupportInfo {
  supported: boolean;
  available: boolean;
  reason?: string;
  requirements?: Requirement[];
  features?: Record<string, boolean>;
  alternatives?: string[];
}
Example: 
const support = await abp.supports('convert.markdownToHtml');
if (support.available) {
  // Can use right now
} else {
  console.log('Not available:', support.reason);
}

​
Communication Methods

​
notify()

Send a notification to the agent (app → agent). 
notify(event: string, data?: unknown): void
Example: 
abp.notify('notifications/state/changed', {
  field: 'documentReady',
  oldValue: false,
  newValue: true
});

​
notifyProgress()

Report progress for a long-running operation. 
notifyProgress(info: ProgressInfo): void
Parameters: 
interface ProgressInfo {
  operationId: string;
  progress: number;
  total?: number;
  percentage?: number;
  status?: string;
  stage?: string;
  estimatedRemaining?: number;
}
Example: 
abp.notifyProgress({
  operationId: 'pdf-123',
  progress: 5,
  total: 10,
  percentage: 50,
  status: 'Rendering page 5 of 10'
});

​
elicit()

Request input from the agent/user. 
elicit(request: ElicitationRequest): Promise<ElicitationResponse>
Parameters: 
interface ElicitationRequest {
  method: string;
  params?: Record<string, unknown>;
  timeout?: number;
}
Returns: 
interface ElicitationResponse {
  success: boolean;
  data?: unknown;
  error?: ABPError;
  cancelled?: boolean;
}
Example: 
const response = await abp.elicit({
  method: 'elicitation/input',
  params: {
    prompt: 'What page size?',
    schema: { type: 'string', enum: ['letter', 'a4'] }
  }
});

if (response.success) {
  const pageSize = response.data.value;
}

​
cancel()

Cancel a long-running operation. 
cancel(callId: string, reason?: string): Promise<CancelResponse>
Returns: 
interface CancelResponse {
  callId: string;
  cancelled: boolean;
  reason?: string;
}

​
Transport Message Format

The ABPMessage envelope type is used by postMessage and WebSocket transports: 
interface ABPMessage {
  type: ABPMessageType;
  id?: string;           // For request-response correlation
  timestamp: number;     // Unix milliseconds
  payload: unknown;
}

type ABPMessageType =
  // Agent → App
  | 'initialize'
  | 'capabilities/call'
  | 'capabilities/cancel'
  | 'shutdown'
  | 'elicitation/response'
  // App → Agent
  | 'initialize-result'
  | 'capabilities/call-result'
  | 'capabilities/cancel-result'
  | 'notification'
  | 'progress'
  | 'elicitation/request';

​
Message Types

DirectionTypePurpose
Agent → AppinitializeEstablish session
App → Agentinitialize-resultSession established
Agent → Appcapabilities/callCall capability
App → Agentcapabilities/call-resultCapability response
Agent → Appcapabilities/cancelCancel in-progress call
App → Agentcapabilities/cancel-resultCancellation result
App → AgentnotificationPush event
App → AgentprogressOperation progress
App → Agentelicitation/requestElicitation from app
Agent → Appelicitation/responseResponse to elicitation
Agent → AppshutdownEnd session
This envelope is used by postMessage and WebSocket transports. Puppeteer transport uses page.evaluate() directly.

​
Puppeteer Callback Function Names

Client implementations using Puppeteer/Playwright MUST use these function names for interoperability:
FunctionDirectionPurpose
__abp_notificationApp → AgentNotifications
__abp_progressApp → AgentProgress updates
__abp_elicitationApp → AgentElicitation requests
__abp_capabilities_changedApp → AgentCapability changes

​
Types

​
Capability

interface Capability {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  available: boolean;
  requirements: Requirement[];
  features: Record<string, boolean>;
  experimental?: boolean;
  deprecated?: boolean;
  deprecationMessage?: string;
  alternatives?: string[];
  browserRequirement?: string;
}

​
Requirement

interface Requirement {
  type: 'permission' | 'context' | 'gesture' | 'browser' | 'hardware' | 'state';
  description: string;
  met: boolean;
  resolution?: string;
}

​
CapabilitySummary

interface CapabilitySummary {
  name: string;
  available: boolean;
  experimental?: boolean;
  deprecated?: boolean;
}

​
Standard Error Codes

CodeDescriptionRetryable
NOT_INITIALIZEDSession not initializedYes
UNKNOWN_CAPABILITYCapability doesn’t existNo
INVALID_PARAMSParameters don’t match schemaNo
PERMISSION_DENIEDUser denied permissionYes
REQUIREMENT_NOT_METCapability requirement not satisfiedDepends
OPERATION_FAILEDCapability execution failedDepends
NOT_SUPPORTEDFeature not supportedNo
TIMEOUTOperation timed outYes
See Error Handling Guide for complete details.

​
Standard Elicitation Methods

MethodDescription
elicitation/inputRequest required user input
elicitation/preferenceRequest optional preference
elicitation/confirmRequest yes/no confirmation
elicitation/selectRequest selection from options
elicitation/resourceRequest a file or resource
sampling/createRequest AI assistance
See Elicitation Guide for details.

​
Complete TypeScript Definitions

For reference implementations, here are the complete TypeScript definitions for all ABP types:

​
Core ABP Interface

interface ABP {
  // ─────────────────────────────────────────────────────────────────────────
  // IDENTITY
  // ─────────────────────────────────────────────────────────────────────────

  /** Protocol version implemented */
  readonly protocolVersion: string;

  /** App identification */
  readonly app: AppInfo;

  // ─────────────────────────────────────────────────────────────────────────
  // LIFECYCLE
  // ─────────────────────────────────────────────────────────────────────────

  /** Initialize a session with the app */
  initialize(params: InitializeParams): Promise<InitializeResult>;

  /** End the session */
  shutdown(params?: ShutdownParams): Promise<void>;

  /** Check if a session is initialized */
  readonly initialized: boolean;

  /** Current session ID (if initialized) */
  readonly sessionId: string | null;

  // ─────────────────────────────────────────────────────────────────────────
  // CAPABILITIES
  // ─────────────────────────────────────────────────────────────────────────

  /** List all available capabilities */
  listCapabilities(): Promise<Capability[]>;

  /** Get details for a specific capability */
  describeCapability(name: string): Promise<Capability | null>;

  /** Quick check if capability is supported and available */
  supports(name: string): Promise<SupportInfo>;

  // ─────────────────────────────────────────────────────────────────────────
  // CALLING CAPABILITIES
  // ─────────────────────────────────────────────────────────────────────────

  /** Call a capability */
  call<T = unknown>(
    capability: string,
    params?: Record<string, unknown>,
    options?: CallOptions
  ): Promise<ABPResponse<T>>;

  // ─────────────────────────────────────────────────────────────────────────
  // CANCELLATION
  // ─────────────────────────────────────────────────────────────────────────

  /** Cancel an in-progress capability call */
  cancel(params: CancelParams): Promise<CancelResponse>;

  // ─────────────────────────────────────────────────────────────────────────
  // NOTIFICATIONS (App → Agent)
  // ─────────────────────────────────────────────────────────────────────────

  /** Send a notification to the agent */
  notify(event: string, data?: unknown): void;

  /** Send progress update to the agent */
  notifyProgress(progress: ProgressInfo): void;

  // ─────────────────────────────────────────────────────────────────────────
  // ELICITATION (App → Agent)
  // ─────────────────────────────────────────────────────────────────────────

  /** Request something from the agent via elicitation */
  elicit<T = unknown>(request: ElicitationRequest): Promise<ElicitationResponse<T>>;

  // ─────────────────────────────────────────────────────────────────────────
  // EVENT HANDLERS (Agent sets these)
  // ─────────────────────────────────────────────────────────────────────────

  /** Handler for notifications from app */
  onNotification?: (notification: Notification) => void;

  /** Handler for progress updates from app */
  onProgress?: (progress: ProgressInfo) => void;

  /** Handler for elicitation requests from app */
  onElicitation?: (request: ElicitationRequest) => Promise<ElicitationResponse>;

  /** Handler for capability changes */
  onCapabilitiesChanged?: (changes: CapabilityChanges) => void;
}

​
Identity Types

interface AppInfo {
  id: string;           // Unique identifier: "vendor.app-name"
  name: string;         // Human-readable name
  version: string;      // Semantic version
  description?: string;
}

interface AgentInfo {
  name: string;         // Agent name: "my-agent"
  version: string;      // Agent version
}

​
Lifecycle Types

interface FeatureFlags {
  notifications: boolean;
  progress: boolean;
  elicitation: boolean;
  dynamicCapabilities?: boolean;
}

interface AgentCapabilities {
  allowedRequests: string[];
}

​
Discovery Types

interface ABPManifest {
  abp: string;                        // Protocol version, e.g., "1.0"
  app: ManifestAppInfo;               // App identification
  capabilities: ManifestCapability[]; // Available capabilities
}

interface ManifestAppInfo {
  id: string;           // Unique identifier: "vendor.app-name"
  name: string;         // Human-readable name
  version: string;      // Semantic version
  description?: string; // Brief description
  homepage?: string;    // App homepage URL
  icon?: string;        // URL to app icon
  support?: string;     // Support URL or email
}

interface ManifestCapability {
  name: string;              // Capability name, e.g., "convert.markdownToHtml"
  description?: string;      // Human-readable description
  inputSchema?: JSONSchema;  // Input parameters schema
  outputSchema?: JSONSchema; // Output data schema
  experimental?: boolean;    // Capability is experimental
  deprecated?: boolean;      // Capability is deprecated
}

interface DiscoveryResult {
  supported: boolean;        // Whether app supports ABP
  manifest?: ABPManifest;    // The manifest (if supported)
  reason?: string;           // Why discovery failed (if not supported)
}

​
Capability Changes

interface CapabilityChanges {
  added: string[];
  removed: string[];
  changed: string[];
}

​
Cancellation Types

interface CancelParams {
  callId: string;           // ID of the call to cancel
  reason?: string;          // Optional reason for logging/debugging
}

interface CancelResponse {
  callId: string;           // Echo back the call ID
  cancelled: boolean;       // Whether cancellation succeeded
  reason?: string;          // Why cancellation failed (if applicable)
}

​
Binary Data Types

interface BinaryData {
  // The binary content (format depends on transport)
  content: string | ArrayBuffer | Blob;

  // REQUIRED: MIME type of the content
  mimeType: string;

  // REQUIRED when content is a string: encoding used
  encoding?: 'base64' | 'utf-8';

  // RECOMMENDED: size in bytes
  size?: number;

  // OPTIONAL: suggested filename
  filename?: string;
}

interface BinaryDataReference {
  // URL to download the content
  downloadUrl: string;

  // REQUIRED: MIME type
  mimeType: string;

  // REQUIRED: size in bytes
  size: number;

  // OPTIONAL: suggested filename
  filename?: string;

  // OPTIONAL: when the URL expires (Unix timestamp ms)
  expiresAt?: number;

  // OPTIONAL: authentication for download
  auth?: BinaryDownloadAuth;
}

interface BinaryDownloadAuth {
  type: 'bearer' | 'query';
  token?: string;           // For query auth
  header?: string;          // For bearer auth
}

// Union type for binary responses
type BinaryOutput = BinaryData | BinaryDataReference;

​
Elicitation Method Types

// Standard elicitation method names
type StandardElicitationMethod =
  | 'elicitation/input'
  | 'elicitation/preference'
  | 'elicitation/confirm'
  | 'elicitation/select'
  | 'elicitation/resource'
  | 'sampling/create';

// elicitation/input
interface ElicitationInputParams {
  prompt: string;
  schema: JSONSchema;
}
interface ElicitationInputResponse {
  value: unknown;
}

// elicitation/preference
interface ElicitationPreferenceParams {
  prompt: string;
  schema: JSONSchema;
  default: unknown;
}
interface ElicitationPreferenceResponse {
  value: unknown;
}

// elicitation/confirm
interface ElicitationConfirmParams {
  message: string;
  destructive?: boolean;
}
interface ElicitationConfirmResponse {
  confirmed: boolean;
}

// elicitation/select
interface ElicitationSelectParams {
  prompt: string;
  options: Array<{ value: string; label: string }>;
  default?: string;
}
interface ElicitationSelectResponse {
  selected: string;
}

// elicitation/resource
interface ElicitationResourceParams {
  type: string;
  uri?: string;
}
interface ElicitationResourceResponse {
  content: string;
  mimeType: string;
}

// sampling/create
interface SamplingCreateParams {
  task: string;
  context?: string;
}
interface SamplingCreateResponse {
  result: string;
}

​
JSON Schema (Simplified)

interface JSONSchema {
  type?: string | string[];
  properties?: Record<string, JSONSchema>;
  items?: JSONSchema;
  required?: string[];
  enum?: unknown[];
  const?: unknown;
  default?: unknown;
  description?: string;
  minimum?: number;
  maximum?: number;
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  format?: string;
  [key: string]: unknown;
}

​
Window Declaration

For TypeScript projects, add this to your global declarations: 
declare global {
  interface Window {
    abp?: ABP;
  }
}

​
Next Steps

Protocol Overview

Full specification details

Building ABP Apps

Build your first ABP app

Examples & Tutorials

Working code examples