Skip to main content
Conversations let agents remember what was said in earlier turns. Reminix stores the message history server-side so your handler only has to deal with the new turn — pass a conversation_id to continue, or omit it to start fresh.

​
How conversations work

  1. Client sends POST /v1/agents/{name}/chat with messages
  2. Reminix manages conversation state and history
  3. Messages accumulate across turns via conversation_id

​
Request format

{
  "input": {
    "messages": [
      { "role": "user", "content": "What's the weather in SF?" }
    ]
  },
  "conversation_id": "conv_abc123"
}
​
input.messages
Message[]
required
Array of messages in OpenAI-compatible format. Each message has a role (user, assistant, system) and content.
​
conversation_id
string
ID of an existing conversation to continue. Omit to start a new conversation.
Without conversation_id, a new conversation is created. With one, the conversation continues from where it left off.

​
Response format

{
  "output": "The current weather in San Francisco is 68°F and sunny.",
  "conversation_id": "conv_abc123"
}
​
output
string
The agent’s response text.
​
conversation_id
string
The conversation identifier. Store this to continue the conversation in subsequent requests.

​
Using the SDK

// Start a new conversation
const chat = await client.agents.chat("support-bot", {
  messages: [{ role: "user", content: "Hi, I need help" }],
})

console.log(chat.output)
console.log(chat.conversation_id) // "conv_abc123"

// Continue the conversation
const followUp = await client.agents.chat("support-bot", {
  messages: [{ role: "user", content: "Can you check my order?" }],
  conversation_id: chat.conversation_id,
})

​
Identity scoping

Pass context.identity to scope conversations to a specific user. Conversations are isolated per identity, making it safe for multi-tenant applications. 
{
  "input": {
    "messages": [
      { "role": "user", "content": "Check my account balance" }
    ]
  },
  "context": { "identity": "user-456" }
}
When using identity scoping, a user can only access and continue their own conversations. Attempting to use a conversation_id that belongs to a different identity will return a 404.

​
Stateless mode

If you don’t need history, simply omit conversation_id on every call and don’t store the returned one. Every call starts a fresh conversation with no prior context. This is useful for one-off chat interactions where you want the chat message format but don’t need persistence.

​
Managing conversations

Use the REST API or SDK to list, inspect, and delete conversations.
EndpointDescription
GET /v1/conversationsList all conversations for the project
GET /v1/conversations/{id}Get conversation details including full message history
DELETE /v1/conversations/{id}Delete a conversation and its history
// List conversations
const conversations = await client.conversations.list()

// Get conversation details
const convo = await client.conversations.get("conv_abc123")
console.log(convo.messages)

// Delete a conversation
await client.conversations.delete("conv_abc123")

​
Best for

  • Chat agents (type: "chat") — back-and-forth conversations
  • Thread agents (type: "thread") — full message history management
  • Any multi-turn interaction requiring history
For one-shot operations that don’t need conversation history, use Tasks instead.

​
Next steps

Streaming

Stream chat responses token-by-token over Server-Sent Events.

Workflows

Pause and resume multi-step processes with human input.

TypeScript: chat()

Build chat experiences from TypeScript.

Python: chat()

Build chat experiences from Python.