Agents

An agent in Nod is the entity that represents your external agentic system

What is an agent?

An agent in Nod is not an AI model — it's the bridge between your external system and Nod's human interface. When you create an agent, you're creating a named entity that:

Has its own credentials (agent_id + secret) for API authentication
Has its own conversation thread in the Nod app
Can create requests, send messages, and log activity
Can run scheduled and event-triggered tasks
Has an online/offline status visible to users

The external system behind the agent can be anything: a Claude Code session, a CrewAI crew, an n8n workflow, a Python script, a serverless function — anything that can make HTTP calls.

Interactive vs. approval-only

	Interactive	Approval-only
Chat	Full bidirectional chat	No chat interface
Requests	All 4 types (approval, choice, question, permission)	All 4 types
User can message agent	Yes, at any time	No — users only respond to requests
Tasks	Scheduled, one-time, and event-triggered	Not available
Activity feed	Yes	Yes
Best for	Assistants, coding agents, conversational AI	Approval gates, workflow automation, human-in-the-loop

Interactive agents

Interactive agents have a full chat interface. Users can send messages to the agent at any time, and the agent can reply. They can run scheduled tasks and deliver results as chat bubbles. This is what you use for coding assistants (like Claude Code), research agents, or anything where back-and-forth conversation is natural.

Approval-only agents

Approval-only agents communicate exclusively through structured requests. They don't have a chat interface — they only appear in the Requests and Activity sections of the app. They cannot run tasks or send messages. This makes them ideal for automation workflows where you need a human to approve, reject, or decide something — nothing more.

For example, an n8n workflow that processes refund requests might create an approval-only agent that sends approval cards for refunds over $500. The user taps approve or reject — no conversation needed. Or a CI/CD pipeline that needs a human gate before deploying to production.

What approval-only agents can do

Create requests (decisions), send activity alerts, and signal processing state (processing_start / processing_stop). Everything else — messages, tasks, task proposals — returns a 403 error.

Creating an agent

You can create agents through the Nod app or the API:

POST /api/agents (JWT auth)

{
  "name": "Deploy Bot",
  "role": "DevOps",
  "kind": "interactive",       // or "approval-only"
  "avatar": "rocket",
  "webhook_url": "https://my-server.com/nod-events"  // optional
}

The response includes the agent and a plaintext secret (shown only once):

Response (201)

{
  "agent": {
    "id": "agt_a1b2c3d4e5f6g7h8",
    "name": "Deploy Bot",
    "status": "not_connected",
    ...
  },
  "secret": "nod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Store the secret immediately. It's only returned at creation time and cannot be retrieved later.

Agent status

Nod tracks your agent's connection status:

Status	Meaning
online	Agent has an active WebSocket connection
configured	Agent has been set up but never connected
not_connected	Agent has connected before but is currently offline
error	Agent has connection issues (e.g. repeated webhook delivery failures)

Status is tracked automatically via WebSocket sessions. Users see the status in the Nod app alongside the agent's name.

Team members

By default, only the agent's creator can interact with it. You can add team members to share access:

POST /api/agents/:agent_id/members
{ "username": "bob" }

Members can view conversations, respond to requests, and see activity — but only the owner can change the agent's settings or delete it.