Skip to content

Prompt

Send input to a session and read the reply as a stream or an accepted receipt.

3 min read36 pages in SDK Reference

OpenAI Open in ChatGPTClaude Open in ClaudeGitHub Invertocat
On this page3
  1. Send a prompt
  2. Read the reply
  3. Forward the stream from a server route
import { Compozy } from "@compozy/client";

Send a prompt

The daemon either streams the reply or accepts the input without streaming it, for example when it is queued or steered. An accepted result carries status, delivery, and queue_position instead of chunks. A prompt stream does not reconnect. Stopping your reader does not cancel the agent's turn: call cancelSessionPrompt to cancel it.

Signature
compozy.prompt(input: PromptInput): Promise<PromptReply>

Options

workspaceIdstringrequired
sessionIdstringrequired
messagestringrequired
mode"queue" | "interrupt" | "steer"

Use queue when a session may be busy. interrupt cancels the active turn and starts this one. steer adds the input to the active turn when the provider supports live steering; otherwise the session's admission rules decide how it is delivered.

idempotencyKeystring

Generated when omitted. Supply the same key when retrying the same input to preserve its message identity and replay the daemon's receipt.

expectedTurnIdstring

Sent to the daemon as expected_turn_id.

signalAbortSignal

Stops reading without canceling the daemon's turn.

Example
import { Compozy } from "@compozy/client";

const compozy = await Compozy.connect();
const reply = await compozy.prompt({
  workspaceId: "workspace-id",
  sessionId: "session-id",
  message: "Hello",
});
if (reply.kind === "stream") {
  for await (const chunk of reply.chunks) console.log(chunk);
}

Read the reply

Inspect whether the input was accepted before reading chunks.

Signature
type PromptReply =
  | { kind: "accepted"; result: PromptResult }
  | {
      kind: "stream";
      chunks: AsyncIterable<UIMessageChunk>;
      toReadableStream(): ReadableStream<UIMessageChunk>;
    };

chunks ends after a finish or abort chunk. A stream that ends earlier, or whose signal is aborted, throws CompozyStreamError.

Example
if (reply.kind === "stream") {
  for await (const chunk of reply.chunks) {
    if (chunk.type === "text-delta") process.stdout.write(chunk.delta);
  }
} else {
  console.log(reply.result.status, reply.result.queue_position);
}

Forward the stream from a server route

Use promptResponse() in a server route to forward the AI SDK UI message stream unchanged. Accepted input is returned with status 202 and its JSON body.

Signature
compozy.promptResponse(input: PromptInput): Promise<Response>