Conversations

Conversations are for multi-turn flows where each message remembers earlier context in the same thread.

Every thread has a conversation_id. Save it if you want to continue that thread later (for example, after a page refresh or from another device).

content is an array of typed parts (text, image, video, audio, url). For full body structure and multimodal input examples, see Runner API and Multimodal.

Step 1 — Start a new conversation

First message creates a new conversation_id.

import client from "./lib/amarsia"

const conversation = client.conversation
conversation.start()

const data = await conversation.run({
  content: [{ type: "text", text: "Hi! I need help with my order." }],
  variables: { CUSTOMER_TIER: "pro" }, // optional, first message only
  meta: { userId: "user_123", channel: "web-chat" }, // optional, first message only
})

console.log(data.conversation_id) // "conv_abc123"
console.log(conversation.id) // "conv_abc123"
console.log(data.content)

Step 2 — Resume an existing conversation

If you already have a saved conversation_id, bind to it before sending the next message.

const conversation = client.conversation
const storedConversationId = "conv_abc123" // from DB/session

conversation.start(storedConversationId)

await conversation.run({
  content: [{ type: "text", text: "My order number is #4821." }],
})

Step 3 — Continue the current thread

After a conversation is active, keep calling run(...) or stream(...).

await conversation.run({
  content: [{ type: "text", text: "It still has not arrived after 10 days." }],
  historyLimit: 10, // optional
})

Step 4 — Stream conversation responses

Use streaming for token-by-token UX.

await conversation.stream({
  content: [{ type: "text", text: "Give me two options." }],
  historyLimit: 10,
})

console.log(conversation.live) // partial during stream
console.log(conversation.data?.content) // final output after stream

Step 5 — Fetch message history

// explicit conversation id (no need to call start first)
const messages = await conversation.loadMessages({
  conversationId: "conv_abc123",
  page: 1,
  pageSize: 20,
})

console.log(messages)

Step 6 — List conversations and filter by `meta`

const threads = await conversation.list({
  page: 1,
  pageSize: 20,
  meta: { userId: "user_123", channel: "web-chat" },
})

Rules for `variables` and `meta`

variables: allowed on first message of a conversation only.
meta: allowed on first message only; used for filtering with GET /{deployment_id}/conversations.
Passing variables or meta on continuation throws a validation error in the SDK.

Conversation response shape

{
  "conversation_id": "conv_abc123",
  "content": "Assistant output...",
  "model": "MODEL_NAME",
  "input_tokens": 42,
  "output_tokens": 61,
  "created_at": "2026-04-20T10:00:00Z",
  "updated_at": "2026-04-20T10:00:00Z"
}

Common pitfalls

Forgetting to store conversation_id after the first message.
Passing variables or meta to continuation messages.
Calling conversation.loadMessages() without an active conversation id and without conversationId in options.