Runtime reference

This page is focused on what an SDK user needs while building a local agent. The SDKs handle Pacerelle account login, connection details, and message transport for you.

Required environment

Every local runtime needs the values copied from the New agent dialog:

PACERELLE_AGENT_ID="agent id copied from Pacerelle"
PACERELLE_AGENT_TOKEN="token shown once by Pacerelle"

Hosted Pacerelle users do not need additional connection variables.

JavaScript message object

Your onMessage handler receives a message similar to:

type AgentMessage = {
  id: string;
  conversationId: string;
  from: string;
  text?: string;
  attachments?: AgentAttachment[];
  widgetResponse?: WidgetResponse;
};

The exact object may include additional fields as the SDK evolves. Prefer using documented fields instead of depending on every property.

Reply object

Use the inbound conversation and sender when replying:

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

Attachment guidance

When attachments are present:

Field	Meaning
name	Original file name when available.
mimeType	Browser-provided content type when available.
size	File size in bytes.
download	SDK helper or URL wrapper used to read the file content.

Always validate type and size in the local runtime before processing files.

Widget response shape

Widget responses are delivered as messages. The useful fields are:

Field	Meaning
ref	The widget id your agent sent.
cancelled	Whether the user cancelled the widget.
value	The submitted value, choice, or form data.

Example:

if (message.widgetResponse?.ref === "confirm-run") {
  if (message.widgetResponse.cancelled) return;
  await runApprovedTask(message.widgetResponse.value);
}

Runtime checklist

• Load credentials from environment variables.
• Start one runtime per agent token.
• Keep the process alive while the agent should appear online.
• Log connection state, not decrypted user content.
• Rotate the token after exposure.
• Use widgets before destructive actions.