Assistant Runner

What this is

The Runner is for one-shot tasks — you send input, the assistant processes it, you get output back. No memory, no state between calls.

Good for things like:

Generating a summary, email, or report
Extracting structured data from a document
Answering a question based on provided context
Any automation that takes input and produces output

Run and get a response

import client from "./lib/amarsia"

const result = await client.run({
  content: [{ type: "text", text: "Write a 3-sentence product description for a noise-cancelling headphone." }],
  variables: {
    PRODUCT_CATEGORY: "headphones",
    AUDIENCE: "commuters",
  }, // optional
})

console.log(result.content)
// → "Experience crystal-clear audio with our noise-cancelling..."

You can pass variables in the same call when your assistant prompt expects dynamic values. They are optional, but commonly used.

content is an array of typed parts (text, image, video, audio, url). Read the full body schema in Runner API and multimodal examples in Multimodal.

Response shape

Every run returns the same structure:

{
  "content": "Experience crystal-clear audio...",
  "model": "model-name",
  "input_tokens": 42,
  "output_tokens": 61
}

Field	Type	What it is
`content`	string	The assistant's response
`model`	string	Which model processed the request
`input_tokens`	number	Tokens consumed for your input
`output_tokens`	number	Tokens consumed for the response

Streaming response

Instead of waiting for the full response, stream it token by token. Great for showing output live in the UI.

const unsubscribe = client.stream.subscribe((state) => {
  if (state.status === "streaming") {
    process.stdout.write(state.live ?? "")
  }
  if (state.status === "success") {
    console.log("\n✓ Done:", state.data?.content)
    unsubscribe()
  }
})

await client.stream({
  content: [{ type: "text", text: "Write a detailed product spec." }],
  variables: {
    PRODUCT_CATEGORY: "headphones",
    AUDIENCE: "commuters",
  },
})

// cancel active stream if needed
client.stream.abort()

state.live — partial text as it streams in
state.data — the complete response once done
state.live is cleared to "" after stream completion

With variables

Pass dynamic data into your assistant's instructions:

const result = await client.run({
  content: [{ type: "text", text: "Draft a support reply." }],
  variables: {
    CLIENT_NAME: "Sarah",
    ISSUE_TYPE: "billing",
  },
})

const streamed = await client.stream({
  content: [{ type: "text", text: "Now rewrite as 3 bullets." }],
  variables: {
    CLIENT_NAME: "Sarah",
    ISSUE_TYPE: "billing",
  },
})

See Quickstart — Variables for how variables work.

Next steps

Conversations — need the assistant to remember previous messages? Use the Conversation API
Multimodal — pass images, PDFs, or audio as input
Runner API reference — full method details