TypeScript SDK

The official SDK is @aweb/sdk. It wraps public Aweb V2 routes, lifecycle receipts, discovery, and Maestro orchestration over the same catalog that currently reports 247 provider surfaces and 519 MCP tools.

Install

npm install @aweb/sdk

Initialize

import Aweb from '@aweb/sdk';

const aweb = new Aweb({
  apiKey: process.env.AWEB_API_KEY,
  // Optional. Defaults to the public Aweb V2 API in the SDK package.
  baseUrl: process.env.AWEB_API_URL ?? 'https://aweblabs.ai/api/v2',
  timeout: 60_000,
  maxRetries: 3,
});

First calls

const response = await aweb.responses.create({
  input: 'Summarize what Aweb does in one paragraph.',
});

const chat = await aweb.chat.completions.create({
  messages: [{ role: 'user', content: 'Explain provider routing.' }],
});

const capabilities = await aweb.capabilities.list({ family: 'research' });
const tools = await aweb.tools.recommend({
  objective: 'build a trading agent with GitHub pull requests and monitoring',
  installedProviders: ['github'],
});

console.log(response.data.id);
console.log(chat.data.choices[0]?.message.content);
console.log(capabilities.count);
console.log(tools.nextAction);

Agent-native tool planning

Tool Cards expose MCP Warehouse tools as typed, inspectable planning objects. The Agent facade keeps the simple path small while preserving approval and credential boundaries.

import Aweb, { Agent } from '@aweb/sdk';

const aweb = new Aweb({ apiKey: process.env.AWEB_API_KEY });
const agent = new Agent({ tools: aweb.tools });

agent.add('github').activate('github');

const plan = await agent.plan('build a trading agent with GitHub PRs and monitoring');
const runPlan = await agent.run('build a trading agent with GitHub PRs and monitoring');

console.log(plan.recommendedAdditions.map(item => item.tool.id));
console.log(runPlan.message);

Resources exposed today

responsesaweb.responses.create()Responses-style model output and streaming

chataweb.chat.completions.create()OpenAI-compatible chat completion surface

imagesaweb.images.generate(), upscale(), edit()Image generation and editing routes

videosaweb.videos.generate(), fromImage()Video generation routes

audioaweb.audio.speech(), transcriptions(), music()Speech, transcription, and music

capabilitiesaweb.capabilities.list(), get(), families()Public capability discovery

toolsaweb.tools.list(), inspect(), recommend()Agent-native MCP Tool Cards

orchestrateaweb.orchestrate.run(), get()Maestro jobs, runs, checkpoints, and receipts

batchaweb.batch.create(), list(), get(), cancel()Batch lifecycle commands

keysaweb.keys.rotate()Key rotation for authenticated workspaces

Maestro orchestration and receipts

Orchestration responses include durable job/run identity and audit receipts when the route produces lifecycle metadata.

const run = await aweb.orchestrate.run({
  query: 'Research competitors and draft launch positioning',
  capabilities: ['search.web', 'llm.chat'],
  policy: 'balanced',
});

console.log(run.data.job?.id);
console.log(run.data.run?.status);
console.log(run.data.audit_receipt?.request_id);

MCP boundary

The SDK is the public TypeScript client for REST/V2 routes. MCP access is exposed through the MCP manifest and server, and is documented separately because tool invocation is governed by auth, policy, and OS9/Mission Contract boundaries.

Error handling

import Aweb, { AwebError, AwebTimeoutError } from '@aweb/sdk';

try {
  await aweb.responses.create({ input: 'hello' });
} catch (error) {
  if (error instanceof AwebTimeoutError) {
    console.error('Timed out:', error.message);
  }

  if (error instanceof AwebError) {
    console.error(error.status);
    console.error(error.type);
    console.error(error.requestId);
    console.error(error.detail);
  }
}

Truth boundaries

The SDK package source is packages/aweb-sdk.
Public discovery routes can be called without a key; execution routes require auth.
Private beta systems such as MCP tool execution require approved access.
Provider and MCP counts should come from the integration catalog, not page literals.