Quickstart

What you need

Two things before you write any code:

API Key — your secret credential for authenticating requests.

Get it from the Amarsia dashboard under API Keys. Store it as an environment variable — never hardcode it.

AMARSIA_API_KEY=your_key_here

Deployment ID — identifies which assistant to run. In Amarsia, you build and deploy assistants. Each deployed assistant has its own Deployment ID. Find it in the assistant's Deploy tab in the dashboard.

AMARSIA_DEPLOYMENT_ID=dep_abc123

Install

npm install @amarsia/sdk

Initialize the client

Create the client once and reuse it everywhere:

import { amarsia } from "@amarsia/sdk"

const client = amarsia.init({
  apiKey: process.env.AMARSIA_API_KEY!,
  deploymentId: process.env.AMARSIA_DEPLOYMENT_ID!,
})

export default client

Variables

Your assistant's system instructions can have dynamic slots called variables. They let you inject real data into the prompt at runtime — things like a user's name, account info, or any context the assistant needs.

Where to find them: Open your assistant in the dashboard and check the system instructions. Variables are always written in UPPER_CASE_WITH_UNDERSCORES like CLIENT_EMAIL or PRODUCT_NAME.

How to pass them:

const result = await client.run({
  content: [{ type: "text", text: "Help this customer." }],
  variables: {
    CLIENT_EMAIL: "jane@example.com",
    PLAN_NAME: "Pro",
  },
})

The variable names must match exactly what's in your assistant's instructions. If there's a mismatch, the slot will be left blank.

Your first request

import client from "./lib/amarsia"

const result = await client.run({
  content: [{ type: "text", text: "Say hello." }],
})

console.log(result.content)

Next steps

• Assistant Runner — run your assistant and handle the response
• Conversations — build a stateful chatbot
• Multimodal — send images, PDFs, audio alongside text