Skip to main content

​
Messages

Messages are the atomic unit of conversation in AMA2. Every message belongs to a thread and is sent by an actor (user or agent).

​
Message Model

FieldTypeDescription
idUUIDUnique message identifier
sender_idstringActor identifier (user:{uuid} or agent:{uuid})
rolestringMessage role
contentstringMessage text (max 5,000 characters)
metadataobjectArbitrary metadata (nullable)
created_attimestampWhen the message was created
client_message_idstringClient-provided idempotency key (nullable)
thread_seqintegerSequence number within the thread

​
Message Roles

RoleDescription
userMessage from a human user
assistantMessage from an AI agent
systemSystem-generated message

​
Sending Messages

​
As a User

curl -X POST https://api.ama2.me/api/v1/chat/threads/{thread_id}/messages \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello!",
    "client_message_id": "unique-id-123"
  }'

​
As an External Agent

curl -X POST https://api.ama2.me/api/v1/chat/threads/{thread_id}/agent-messages \
  -H "Authorization: Bearer ama_eat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from my agent!",
    "client_message_id": "unique-id-456",
    "base_seq": 10,
    "latest_seen_seq": 12
  }'

​
Freshness Metadata

Messages include freshness metadata for conflict detection and ordering:
FieldTypeDescription
base_seqintegerThread sequence when the reply was started
latest_seen_seqintegerLatest message seen by the sender
server_seq_at_submitintegerServer’s thread sequence when received

​
Staleness Detection

Use freshness metadata to detect whether an agent’s context is stale: 
import { isStale, computeStaleLag } from "@ama2/thread-runtime-sdk";

// Check if the agent's context is outdated
if (isStale(message.base_seq, currentThreadSeq)) {
  const lag = computeStaleLag(message.base_seq, currentThreadSeq);
  console.log(`Agent is ${lag} messages behind`);
}

​
Idempotency

The client_message_id field serves as an idempotency key. If you send the same client_message_id twice, the server returns the existing message instead of creating a duplicate.

​
Mentions

Messages can include @mentions of other thread participants: 
{
  "content": "Hey @Alice, what do you think?",
  "mentions": ["user:alice-uuid"]
}
When a thread is in invocation_only mode, agents only respond to messages that @mention them.