Run TypeScript Actions During AI Phone Calls

​

Writing 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] }],
  });

  if (records.length === 0) {
    return { found: false };
  }
  return { found: true, plan: records[0].plan };
});

• inputs — the Action’s declared inputs, already validated against its input schema
• config — your organization’s configuration variables (for API keys and settings)
• client — the Simple AI SDK, authenticated for your organization automatically; you never handle an API key

​

Authentication

​

Steering the conversation

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

export default defineAction(async ({ inputs, client, workflow }) => {
  const account = await lookupAccount(client, inputs.email);

  if (account.delinquent) {
    workflow.transitionTo({
      nodeName: 'Collections',
      message: 'Let me get you to the right team.',
      reason: 'account is delinquent',
    });
  }

  return { plan: account.plan };
});

• nodeName — the node to run next, exactly as it is named in the Agent. Any node in the workflow is reachable; you do not need an edge from the node that invoked the action.
• message — optional. A short sentence the agent speaks as it moves.
• reason — optional. Recorded with the transition on the call.

​

Capabilities

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

export default defineAction(async ({ inputs, metadata, workflow }) => {
  const account = await lookupAccount(inputs.email);

  if (account.delinquent && metadata.capabilities.includes(ActionCapability.WORKFLOW_TRANSITION)) {
    workflow.transitionTo({ nodeName: 'Collections' });
  }
  return { delinquent: account.delinquent };
});

​

Calling an LLM

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

export default defineAction(async ({ inputs, llm }) => {
  const response = await llm.infer({
    model: '<router ladder slug>',
    instructions: 'Summarize the caller notes in one sentence.',
    input: inputs.notes,
  });
  const summary = response.output
    .flatMap((item) => item.content ?? [])
    .filter((part) => part.type === 'output_text')
    .map((part) => part.text)
    .join('');

  return { summary };
});

• model — a router ladder slug, not a vendor model ID. Ask Simple AI support which slugs to use.
• Everything else is an ordinary Responses API body, such as input, instructions, text, or temperature. Requests are never streamed.
• The response comes back with its output typed, as above; other Responses API fields are there untyped.
• If the router refuses the request, infer throws SimpleAIError with its HTTP status, code, and message.

​

Rules and Limits

• TypeScript or JavaScript in the Cloudflare Workers runtime. Use standard web APIs such as fetch, Request, and Response; Node.js APIs are not available.
• The importable packages are @simple-ai-lab/sdk, openai, zod, and libphonenumber-js. They are bundled when you save.
• libphonenumber-js parses, validates, and formats phone numbers (for example to E.164 before dialing). The default entry point carries minimal metadata; import libphonenumber-js/max when you need getType() or other extended-metadata lookups.
• The Simple AI SDK is authenticated automatically. To call an LLM, use llm.infer, or store your own OpenAI API key in an organization configuration variable and pass it to the OpenAI client from config.
• Timeout: configurable per action, 1–60 seconds (default 30). Voice conversations feel best well under 10 seconds — configure filler speech on the agent for longer actions.
• Network requests: up to 100 subrequests per execution.
• Result size: the returned value must serialize to JSON of at most 1 MB.
• Logs: console.log / console.error output is captured and shown in test runs and call transcripts — it never pollutes the result.
• Each execution runs in a fresh Worker isolate; nothing persists between runs. Persist state in custom data instead.

​

Testing