Activity

Log what your agent is doing and show processing state

Overview

Activity events appear in the user's activity feed in the Nod app. Use them to show what your agent is doing — files edited, commands run, searches made.

POST/api/agent/events

Log an activity entry via REST.

typerequired

string

Must be "alert"

titlerequired

string

Activity headline

text

string

Additional detail

task_run_id

string

Associate with a task run

Request

POST /api/agent/events
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

{
  "type": "alert",
  "title": "Deployment completed",
  "text": "v2.4.1 deployed to staging"
}

With task run

{
  "type": "alert",
  "title": "Running tests",
  "text": "npm test -- --coverage",
  "task_run_id": "run_abc123"
}

POSTWebSocket frame

Log activity via WebSocket.

WebSocket frame

{
  "type": "alert",
  "title": "Editing src/index.ts",
  "text": "/Users/alice/project/src/index.ts",
  "task_run_id": "run_abc123"
}

Processing indicators

Show users when your agent is actively working. The Nod app displays a "Thinking..." bubble in the chat. While the indicator is active, any alert events your agent logs will update the bubble text in real time. Available via both REST and WebSocket.

See the Activity Guide for detailed examples of both WebSocket and webhook patterns.

POST/api/agent/events

Control the processing indicator via REST. Use processing_start when your agent begins working, and processing_stop when it finishes. The indicator auto-clears after 30 seconds if processing_stop is never received.

typerequired

string

"processing_start" or "processing_stop"

conversation_id

string

Which conversation shows the indicator

status_text

string

Custom label (e.g. "Searching the web..."). Defaults to "Thinking". Only used with processing_start.

Call processing_start when your agent begins a task, and processing_stop when it finishes. If your agent crashes and processing_stop is never sent, the indicator auto-clears after 30 seconds.

Start processing

POST /api/agent/events
X-Nod-Agent-Id: agt_abc123
X-Nod-Secret: nod_abc123...

{
  "type": "processing_start",
  "conversation_id": "conv_abc123"
}

With custom label

{
  "type": "processing_start",
  "conversation_id": "conv_abc123",
  "status_text": "Searching the web..."
}

Stop processing

{
  "type": "processing_stop",
  "conversation_id": "conv_abc123"
}

POSTWebSocket frame

For WebSocket-connected agents, send heartbeat and idle frames instead. The heartbeat-based approach gives real-time status updates since agents send it every ~1 second.

conversation_id

string

Which conversation shows the indicator

status_text

string

Custom label (e.g. "Reading files..."). Defaults to "Thinking".

Send agent_heartbeat every ~1 second while working. Change status_text as the activity changes — the app updates instantly. Send agent_idle when done.

Default (shows 'Thinking')

{
  "type": "agent_heartbeat",
  "conversation_id": "conv_abc123"
}

Custom status text

{
  "type": "agent_heartbeat",
  "conversation_id": "conv_abc123",
  "status_text": "Searching the web..."
}

Clear indicator

{
  "type": "agent_idle",
  "conversation_id": "conv_abc123"
}

Event types

Type	Description
decision_created	A new request was created
decision_resolved	A request was approved/rejected/responded to
agent_message	Agent sent a message
agent_action	Agent performed an action (alert)
system	System event (agent connected, etc.)