TypeScript SDK Reference

Install the SDK:

npm install webagents

BaseAgent

The core agent class. Processes UAMP events, manages skills, and exposes run methods.

import { BaseAgent } from 'webagents';

const agent = new BaseAgent({
  name: 'my-agent',
  instructions: 'You are a helpful assistant.',
  model: 'gpt-4o',
  skills: [new MySkill()],
});

Constructor

Parameter	Type	Description
`name`	`string`	Agent display name
`instructions`	`string`	System prompt
`model`	`string`	LLM model identifier
`skills`	`Skill[]`	Array of skill instances
`scopes`	`string[]`	Required auth scopes
`capabilities`	`Capabilities`	UAMP capabilities (modalities, audio formats)

Methods

Method	Signature	Description
`run`	`(input: string, options?: RunOptions) => Promise<RunResponse>`	Single-turn execution
`runStreaming`	`(input: string, options?: RunOptions) => AsyncGenerator<StreamChunk>`	Streaming execution

Skill

Abstract base class for skills. Skills bundle tools, hooks, handoffs, and endpoints.

import { Skill, tool, hook } from 'webagents';

class WeatherSkill extends Skill {
  @tool({ description: 'Get weather for a city' })
  async getWeather(city: string): Promise<string> {
    return `Weather in ${city}: sunny`;
  }

  @hook({ lifecycle: 'before_run' })
  async onBeforeRun(data: HookData): Promise<HookResult> {
    return {};
  }
}

Decorators

@tool

@tool({ name?: string, description?: string, schema?: ZodSchema })

@hook

@hook({ lifecycle: 'before_run' | 'after_run' | 'before_tool' | 'after_tool' })

@handoff

@handoff({ name?: string, description?: string, subscribes?: string[], produces?: string[] })

@observe

@observe({ subscribes: string[] })

@http

@http({ path: string, method?: 'get' | 'post' | 'put' | 'delete' })

@websocket

@websocket({ path: string })

Server

createAgentApp

Creates a Hono HTTP application for an agent.

import { createAgentApp } from 'webagents';

const app = createAgentApp(agent, {
  port: 8080,
  cors: true,
});

serve

Starts an HTTP server for the agent (Bun or Node.js).

import { serve } from 'webagents';

await serve(agent, { port: 8080 });

createFetchHandler

Creates a standard fetch handler for serverless/edge deployments.

import { createFetchHandler } from 'webagents';

const handler = createFetchHandler(agent);
export default { fetch: handler };

Context

The Context object is available inside tools, hooks, and handoffs. It carries session state, auth info, and payment info.

interface Context {
  session: SessionState;
  auth: AuthInfo;
  payment: PaymentInfo;
  metadata: Record<string, unknown>;
  get(key: string): unknown;
  set(key: string, value: unknown): void;
  hasScope(scope: string): boolean;
}

MessageRouter

Routes UAMP messages through the agent pipeline.

import { MessageRouter } from 'webagents';

const router = new MessageRouter(agent);
const response = await router.route(events);

Sinks

Output adapters for different transports:

Class	Description
`WebSocketSink`	WebSocket transport
`SSESink`	Server-Sent Events
`WebStreamSink`	Web Streams API
`CallbackSink`	Custom callback function
`BufferSink`	In-memory buffer

Daemon

Background process manager for agent lifecycle.

import { WebAgentsDaemon } from 'webagents';

const daemon = new WebAgentsDaemon({
  agents: [agent],
  enableCron: true,
});
await daemon.start();

UAMP Types

Key types for the Universal Agentic Message Protocol:

Type	Description
`Capabilities`	Agent capabilities declaration
`Modality`	Supported modalities (text, image, audio)
`Message`	UAMP message envelope
`ToolDefinition`	Tool schema for LLM
`ContentItem`	Multimodal content item
`UsageStats`	Token usage statistics

Crypto

JWT and JWKS utilities for agent authentication.

import { JWKSManager } from 'webagents';

const jwks = new JWKSManager({ jwksUrl: 'https://robutler.ai/.well-known/jwks.json' });
const payload = await jwks.verify(token);

On this page