Conversations

Conversations are persisted multi-turn threads for agents. They give an agent memory across calls without your app having to resend the whole history.

#How it works

Call an agent with a thread query parameter:

POST /v1/agents/{id}/chat/completions?thread=my-thread-123

On each call Relay:

1. Loads the thread's prior messages and prepends them to the conversation.
2. Runs the agent normally (prompt, skills, tools, RAG all apply).
3. Persists this turn (your user message + the assistant reply) back to the thread — only when the call succeeds.

The response carries X-Relay-Thread-Id. Pass any id of your choice; the thread is created on first use. The thread id also becomes the trace's session id (unless you sent X-Relay-Session-Id yourself), so a conversation appears as one session on the Sessions page.

What's persisted is only the user-authored turns plus assistant replies, as role and text content — the agent's prompt seed turns (from a chat prompt) are re-applied each call and never stored, so they don't accumulate; tool calls and images are not stored either, so an image sent on one turn is not remembered on the next.

A threaded call always runs non-streamed: the gateway has to persist the finished reply, so stream: true is ignored and the reply arrives as a single JSON response.

#Managing threads

The panel's Conversations page lists persisted threads and lets you open one (assistant turns render as Markdown) or delete it. The control-plane api/Conversations supports search, GET {id}, save/upsert, and delete.

#Playground

The Playground can also save an ad-hoc chat to Conversations (a toggle in its settings drawer), so exploratory sessions can be kept for reference.

#When to use threads

Use a thread when the interaction is genuinely conversational (support chat, an assistant that refers back to earlier turns). For stateless one-shot calls, skip thread= and just send the messages you need — it's cheaper, simpler, and it can stream.