SDK Quickstart

The Simple AI SDK (@simple-ai-lab/sdk) is a typed TypeScript client for the Simple AI API. It works in two places:

Inside code actions — bundled when you save and authenticated automatically; just import it.
In your own applications — install it from npm and authenticate with an API key.
In an Agent repository — define action-first agents and publish them with the simple CLI.

Inside a Code Action

No installation or keys are needed. Simple bundles the SDK when you save the Action, and the handler’s client is ready to use:

import { defineAction } from '@simple-ai-lab/sdk';

export default defineAction(async ({ inputs, client }) => {
  const { records, total } = await client.data.query({
    tableName: 'orders',
    text: inputs.orderNumber,
    size: 5,
  });
  return { total, orders: records };
});

In Your Own Application

npm install @simple-ai-lab/sdk

Create an API key in the dashboard under Settings → API Keys, then:

import { SimpleAI } from '@simple-ai-lab/sdk';

// Reads SIMPLE_API_KEY from the environment by default
const client = new SimpleAI();

// Or pass it explicitly
const explicit = new SimpleAI({ apiKey: process.env.MY_SIMPLE_KEY });

Error Handling

Every non-2xx API response throws a SimpleAIError with the HTTP status, a machine-readable code when available, and the parsed response body:

import { SimpleAI, SimpleAIError } from '@simple-ai-lab/sdk';

const client = new SimpleAI();
try {
  await client.data.get('customers', 42);
} catch (e) {
  if (e instanceof SimpleAIError && e.status === 404) {
    // record does not exist
  } else {
    throw e;
  }
}

What’s Included Today

client.data — full custom data access: query, records, bulk upserts, and tables
defineAction — typed code-action handlers, including steering the conversation to another node
defineAgent — typed Agent v2 graphs, settings, prompts, extraction schemas, and resource references
action.* — HTTP, code, custom-data, and knowledge-base Actions
simple CLI — pull, typecheck, diff, and publish an Agent branch

Get Started

Core Concepts

Channels

Campaigns

Journeys

Post-Call Intelligence

Agent Capabilities

Integrations

CCaaS Integrations

SDK

Help Center

Inside a Code Action

In Your Own Application

Error Handling

What’s Included Today

​Inside a Code Action

​In Your Own Application

​Error Handling

​What’s Included Today

Inside a Code Action

In Your Own Application

Error Handling

What’s Included Today