Skip to main content

​
ThreadRuntimeClient

The primary client for the AMA2 Thread Runtime API. Handles thread creation, messaging, event polling, and webhook management.

​
Constructor

import { ThreadRuntimeClient } from "@ama2/thread-runtime-sdk";

const client = new ThreadRuntimeClient({
  baseURL: "https://api.ama2.me",
  token: "ama_eat_your_token_here",
});

​
Config

interface ThreadRuntimeClientConfig {
  baseURL: string;   // AMA2 API base URL
  token: string;     // External agent token (ama_eat_*)
}

​
Methods

​
createThread

Create a new private thread with target participants. 
const thread = await client.createThread({
  target_user_ids: ["user-uuid-1", "user-uuid-2"],
  participation_mode: "open",        // optional
  initial_message: "Hello!",         // optional
});
Parameters:
FieldTypeRequiredDescription
target_user_idsstring[]YesUser UUIDs to add as participants
participation_mode"open" | "invocation_only"NoAgent response behavior
initial_messagestringNoMessage to send on creation
participation_mode and initial_message are defined in the contract but not yet processed server-side. Pass them for forward compatibility, but they have no effect currently.
Returns: Promise<Record<string, unknown>> — The created thread object.

​
sendMessage

Send a message to a thread with freshness metadata. 
const response = await client.sendMessage("thread-uuid", {
  content: "Hello from my agent!",
  client_message_id: crypto.randomUUID(),
  base_seq: 10,           // optional
  latest_seen_seq: 12,    // optional
  mentions: ["user:uuid"], // optional
});
Parameters:
FieldTypeRequiredDescription
contentstringYesMessage text (max 5,000 chars)
client_message_idstringYesIdempotency key
base_seqnumberNoThread sequence when reply started
latest_seen_seqnumberNoLatest seen sequence
mentionsstring[]NoMentioned sender_ids
Returns: Promise<Record<string, unknown>> — The sent message object.

​
pollEvents

Poll for thread events after a sequence number. 
const response = await client.pollEvents("thread-uuid", 10);

for (const event of response.events) {
  console.log(`${event.event_type}: ${event.content}`);
}

if (response.has_more) {
  // Continue polling from the last event's sequence
}
Parameters:
ParameterTypeRequiredDescription
threadIdstringYesThread UUID
afterSeqnumberNoReturn events after this sequence (default: 0)
Returns: Promise<ThreadEventPollResponse> 
interface ThreadEventPollResponse {
  events: ThreadEvent[];
  has_more: boolean;
}

​
setThreadMode

Change the agent participation mode for a thread. 
await client.setThreadMode("thread-uuid", {
  participation_mode: "invocation_only",
});
Parameters:
FieldTypeRequiredDescription
participation_mode"open" | "invocation_only"YesNew participation mode

​
registerWebhook

Register a webhook for push-based event delivery. 
const subscription = await client.registerWebhook("thread-uuid", {
  callback_url: "https://your-server.com/webhooks/ama2",
});

console.log("Subscription ID:", subscription.subscription_id);
Returns: Promise<ThreadWebhookSubscription> 
interface ThreadWebhookSubscription {
  subscription_id: string;
  thread_id: string;
  callback_url: string;
  active: boolean;
  created_at: string;
}

​
removeWebhook

Unsubscribe a webhook. 
await client.removeWebhook("thread-uuid", "subscription-uuid");