Simple AI SDK

Typed TypeScript client for the Simple AI API. Use it inside Simple AI code actions (bundled 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. Simple routes SDK requests through a protected outbound binding that injects a short-lived, organization-scoped credential without exposing it to action code.

Steering the conversation

An action invoked from a workflow can send the caller somewhere else. workflow.transitionTo records the node to run next, so the agent goes there instead of following the node's own edges. It returns normally: the rest of your handler still runs, and the value you return is still mapped to the action's outputs.

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

export default defineAction(async ({ inputs, client, workflow }) => {
  const { records } = await client.data.query({
    tableName: 'accounts',
    filters: [{ column: 'email', values: [inputs.email] }],
  });

  if (records[0]?.status === 'delinquent') {
    workflow.transitionTo({
      nodeName: 'Collections',
      message: 'Let me get you to the right team.',
      reason: 'account is delinquent',
    });
  }

  return { status: records[0]?.status ?? 'unknown' };
});

A transition accompanies the result rather than replacing it, so the example above both writes status to its outputs and moves the conversation. Asking twice keeps the last request, and an action that throws transitions nowhere.

The same action can run where there is no conversation to steer — as a per-turn action, an automatic before/after-call action, or in data sync. Those invocations do not grant WORKFLOW_TRANSITION, and transitionTo throws MissingCapabilityError instead. If your action runs in both places, check first:

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

export default defineAction(async ({ metadata, workflow }) => {
  if (metadata.capabilities.includes(ActionCapability.WORKFLOW_TRANSITION)) {
    workflow.transitionTo({ nodeName: 'Collections' });
  }
  return { escalated: false };
});

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

Agents use immutable Actions for integrations, 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' },
        }),
      ],
    }),
  ],
});

action.fromAgent(...) sets an explicit input description override for that callable. Inputs omitted from inputs inherit their Action schema descriptions at runtime; the SDK leaves those overrides absent in the compiled Agent.

Built-in Actions use Agent v2 schemas by default. To preserve a pulled Action version's stored schemas, provide input, output, and outputMappings together.

call.backgroundNoise takes the Agent v2 block, { trackName, gainMultiplier }. Leave gainMultiplier out to keep it out of the commit, and pass backgroundNoise: null for an Agent with no background noise configured at all. Left unset, the block follows voice.backgroundNoise at gain 1.

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.