Simple AI SDK

Typed TypeScript client for the Simple AI API. Use it inside Simple AI code actions (preinstalled and authenticated automatically) or in your own applications with an API key.

npm install @simple-ai-lab/sdk

Inside a code action

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

export default defineAction(async ({ inputs, config, client }) => {
  const { records } = await client.data.query({
    tableName: 'customers',
    filters: [{ column: 'email', values: [inputs.email] }],
  });
  return { found: records.length > 0 };
});

No API key handling needed — the sandbox injects short-lived, organization-scoped credentials automatically.

In your own application

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

// Reads SIMPLE_API_KEY from the environment (dashboard: Settings → API Keys)
const client = new SimpleAI();

const { records, total } = await client.data.query({
  tableName: 'orders',
  text: 'ORD-1042',
});

client.data covers custom data end to end: query, facets, list, get, create, update, delete, deleteAll, batchUpsert, and getBatch. Errors throw SimpleAIError with the HTTP status, machine-readable code, and parsed body.

Define an agent

Agent authoring is action-first: integrations are immutable Actions, and Agent commits pin exact Action versions. New source does not create legacy tools or HTTP graph nodes.

import { action, defineAgent, node, prompt } from '@simple-ai-lab/sdk';
import { z } from 'zod';

const lookup = action.http({
  key: 'lookup-account',
  name: 'Lookup account',
  description: 'Fetch an account',
  input: z.object({
    account_id: z.string().describe('The account identifier from the caller'),
  }),
  output: z.object({ account_name: z.string() }),
  outputMappings: { account_name: '{{ httpResponse.body.name }}' },
  request: {
    method: 'GET',
    url: 'https://example.com/accounts/{{ inputs.account_id }}',
  },
});

export default defineAgent({
  key: 'support',
  name: 'Support',
  branch: 'main',
  nodes: [
    node.prompt({
      key: 'root',
      name: 'Root',
      root: true,
      prompt: prompt.inline('Help the caller.'),
      actions: [
        action.callable({
          key: 'lookup-action',
          action: lookup,
          name: 'lookup_account',
          description: 'Look up an account',
          inputs: {
            account_id: action.fromAgent('The account identifier'),
          },
          // Action output name -> Agent parameter name
          outputParameters: { account_name: 'customer_account_name' },
        }),
      ],
    }),
  ],
});

Install @simple-ai-lab/cli for simple init, pull, typecheck, diff, and publish.

Documentation

Full docs: https://docs.usesimple.ai — see the SDK Quickstart and Code Actions guides.

License

Elastic License 2.0 — free to use; the SDK may not be provided to third parties as a hosted or managed service.