First Agent Flow

This guide describes the baseline flow to build before adding custom skills or a production UI.

Required Pieces

Create these config nodes first:

• agent-connection: model provider URL and API key.
• agent-model: a reusable model configuration with its sampling settings.
• agent-behaviour: system instructions, max iterations, and debug mode.
• agent-memory: facts store, events store, and memory scope.
• agent-budget: optional token or spend limit.

Then create these flow nodes:

• agent-in: converts a normal Node-RED message into the format the agent expects.
• agent: runs the agent.

Baseline Wiring

incoming message -> agent-in -> agent -> downstream response handler

Use agent-in in Message mode:

• Session ID: usually msg.topic for chat/channel style integrations.
• Message: usually msg.payload.
• User ID: optional for session-only operation. Provide a stable value when memory or budgets should follow a user across sessions.

Configure the agent node with the connection, behaviour, model, memory, and optional budget config nodes. Choose one context mode:

• Full Conversation: sends all stored history.
• Summarized: keeps a summary plus a recent window.
• Last N Messages: limits history to a recent subset.
• None: sends no stored event history, but still supplies scoped facts and other runtime context.

Choose a reasoning mode:

• Direct: one model reasons and returns structured agent actions. This is the recommended starting point.
• Thinker: a Think Model reasons in plain text, then a Schema Model converts the reasoning into structured actions.

See Reasoning Modes for model-selection guidance, cost and latency differences, and troubleshooting.

Direct Message Test

You can test the agent with a simple message through agent-in, or send an advanced request directly to the agent node. For a direct request, place this object in msg.payload:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "agent.request",
  "params": {
    "sessionId": "demo-session",
    "content": {
      "text": "Say hello in one sentence."
    }
  }
}

Use placeholder values when testing or writing examples.

Adding A Skill

Use agent-skill when the agent needs to call flow logic.

1. Add an agent-skill node on the same flow tab.
2. Define one or more actions with a name, description, and parameters.
3. Select the skill in the agent node’s skill set.
4. Wire each skill output to the action logic.
5. Return the result through agent-in in Tool Response mode.

The agent adds correlation fields to skill calls. The tool response must preserve those fields so the result is returned to the correct session.

Return handled failures through Tool Response mode as well. Reserve action, sessionId, callId, and tool for runtime fields, and do not include :: in an action name.

See Agent Skill for action parameters and output mapping, and Agent In for the tool-response fields.

Keep Examples Safe

Do not save real API keys, customer records, internal URLs, private credentials, or private user messages in flow names, skill descriptions, screenshots, or docs.