Conversations

Conversations group a customer’s agent runs and save their user and assistant messages. Enable them on the deployed agent:

{
  "perHour": 20,
  "context": { "maxMessages": 20, "maxTokens": 4000 }
}

This object is config.endUserRuns.conversations. Its fields are required. perHour bounds new conversations per customer. context bounds recent transcript messages injected into model steps. The token bound uses an approximate character-based count for context selection; it is not the provider’s billed token count.

Create or reuse

import type { SteadClient } from '@getstead/client';

export async function sendSupportMessage(client: SteadClient, input: string) {
  const { conversation } = await client.createConversation('support-agent', {
    key: 'support-main',
  });
  return client.startRun({
    agent: 'support-agent',
    conversationId: conversation.id,
    input,
    async: true,
  });
}

Use a customer client. A key reuses the conversation within that customer’s project scope; omit it to create a new conversation. Reusing a key does not grant another customer access. A conversation is tied to its agent, and a run must use the matching agent.

Only one unfinished turn may occupy a conversation. A second concurrent start returns 409; wait for the existing turn, resolve its approval, or cancel it before retrying. Starting another request is not a way to bypass an approval.

Read history

client.listConversationMessages(id, { limit: 50 }) returns messages in transcript order within the page. The first page covers the newest window. Pass nextCursor back as cursor to retrieve older windows, prepending those pages in your UI. Limits are 1–1000, default 100; response size is also bounded.

The conversation must belong to the token’s project and customer. A foreign conversation returns 404. The transcript remains readable after an agent is retired, subject to history retention.

For React, useAgent(client, { agent: 'support-agent', conversation: { key: 'support-main' } }) creates or reuses the conversation and hydrates recent history on mount. Use conversationId to target an existing conversation; it takes precedence over conversation.

Persistence limits

Messages survive sign-out and reload because they are stored server-side. Your application must sign the customer back into the same identity. Context is bounded recent history, not every past message, and the hook’s initial history read is best-effort. Use the explicit history API if your UI needs pagination or a visible retry.

At the project’s history limits, older terminal runs can be reclaimed along with their conversation messages. See retention. Export records into your own application storage if you need a long-term archive.