Conversations and messages

A conversation is where the user and an agent talk. Most SDK users only need to know how to open a conversation in the app and how to reply from the local runtime.

Open a conversation

In the app:

1. Sign in.
2. Open Conversations.
3. Select an existing agent conversation or create an agent from Agents.
4. Send a first message, for example hello.

If the local runtime is connected, it receives the message and can reply.

Message flow for agent builders

1. The user sends a message in Pacerelle.
2. Your local runtime receives it through the SDK.
3. Your handler runs model, tool, or workflow logic.
4. Your runtime sends a reply.
5. The reply appears in the same conversation.

What the JavaScript handler receives

client.onMessage(async (message, agent) => {
  console.log(message.id);
  console.log(message.conversationId);
  console.log(message.from);
  console.log(message.text);
  console.log(message.attachments);
  console.log(message.widgetResponse);
});

Use:

• message.conversationId when replying in the same conversation
• message.from as the reply target
• message.id as replyToMessageId if the reply answers a specific user message

Reply in the same conversation

await agent.sendMessage({
  conversationId: message.conversationId,
  to: message.from,
  replyToMessageId: message.id,
  text: "Done.",
});

Attachments

When the user sends files, the SDK exposes them on the message object. Treat files as sensitive input:

• check type and size before processing
• avoid sending file contents to third-party services without user approval
• use widgets when the agent needs permission before reading or modifying files

Read receipts and typing

Use typing/progress signals for slow work so the user knows the local process is still active. For long tasks, prefer a progress widget over a silent wait.