Runtime Contract

Message Envelope

Advanced integrations can send a JSON-RPC 2.0 style payload directly to an agent:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "agent.request",
  "params": {
    "sessionId": "session-1",
    "userId": "user-1",
    "content": {
      "text": "Hello"
    }
  }
}

For normal Node-RED flows, use agent-in to build this shape for you.

sessionId is required for every supported inbound method. userId is optional in the message contract, but a stable value is operationally required for user-scoped facts and non-session budgets.

Inbound Methods

Method	Purpose	Required content
agent.request	Start or continue an agent turn.	{ text, images? }
agent.status	Read current session status.	No content required.
tool.response	Return a skill result to the agent.	Tool result data and correlation fields.

images may contain URL images or base64 image data when the selected model supports vision input.

Accepted And Runtime Messages

An agent.request first returns an accepted response with the original request ID:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "result": {
    "phase": "thinking",
    "status": "accepted",
    "sessionId": "session-1"
  }
}

Runtime events are then emitted as JSON-RPC-style notifications:

{
  "jsonrpc": "2.0",
  "method": "agent.response",
  "params": {
    "sessionId": "session-1",
    "content": {
      "text": "Hello"
    }
  }
}

Notifications do not carry the original request ID. Use sessionId, and tool correlation fields where applicable, to associate them with runtime work.

Stored Event Types

The event store and Agent Studio may contain these runtime event types:

• agent.request
• agent.clarify
• agent.response
• agent.status
• agent.warning
• agent.error
• agent.usage
• agent.plan
• agent.summary
• agent.debug
• tool.request
• tool.response
• memory.read
• memory.write

Not every event appears in every run. Planning, summary, and debug events depend on the selected configuration and runtime path.

These stored events are not all emitted from the Agent node’s output. Normal output messages include the immediate accepted response and user-facing notifications such as agent.response, agent.clarify, agent.warning, and agent.error. Use the event store or Agent Studio to inspect internal usage, planning, summary, memory, tool, and debug activity.

Debug events can contain complete request and response details. Enable debug mode only in trusted environments.

Tool Response

A tool result must preserve the correlation values emitted with the tool call:

{
  "jsonrpc": "2.0",
  "method": "tool.response",
  "params": {
    "sessionId": "session-1",
    "content": {
      "callId": "call-1",
      "tool": "skill-node-id::action-name",
      "data": {
        "result": "value"
      }
    }
  }
}

The runtime can group parallel tool calls and continue only after all results in the group have returned.

Context Modes

Mode	Behavior
full	Includes the full stored conversation history.
summary	Includes a stored summary plus the latest window of messages.
lastn	Limits context to a recent subset. The configured number is an upper bound in the current runtime.
none	Sends no stored conversation history.

The history window counts stored history entries rather than conversational turns. Requests, responses, clarifications, tool calls, and recorded tool results can each consume an entry.

None still includes the current request, system instructions, available tools, runtime context, current date and time, and normal scoped facts.

Memory And Events

Smartunit stores two kinds of operational data:

Data	Purpose
Facts	Saved memory such as preferences, profile details, summaries, and usage totals.
Events	Activity history used to inspect sessions, responses, tool calls, warnings, and errors.

Normal fact keys that do not start with __ are automatically supplied to the model on each reasoning call. Facts can be scoped to a session or user. Treat a stable userId as required for User scope. Event history remains session-based. Images are not retained in stored conversation events.

memory.read and memory.write continue processing through another reasoning step. Writing an existing scoped key replaces its value and kind. Writing null leaves an empty fact record rather than deleting it; fact deletion is not currently exposed as a model action.

Changing the configured fact scope does not migrate existing records.

Event history can contain user input, model output, and tool results, so handle exports and screenshots carefully.

Normal facts are sent to the configured model provider. Do not store API keys, passwords, authentication tokens, or other secrets as agent facts.

Budgets And Usage

Budgets can limit tokens or provider-reported spend. Supported periods are:

• session
• daily
• weekly
• monthly
• lifetime

Warnings emit agent.warning; hard limits emit agent.error and stop the turn.

Daily periods reset at midnight UTC, weekly periods start Monday UTC, and monthly periods start on the first day of the UTC month. Session budgets use the session; other periods aggregate by user.