Agent

The Agent node calls an external AI agent over HTTP. CraftBot sends the conversation context (variables, last inbound message, language hint) to the agent’s webhook; the agent decides what to reply and CraftBot ships the response back to the customer.

This node does not run an LLM inside CraftBot. AI reasoning, tool use, and model selection all live at the agent platform (n8n, LangGraph, or any HTTP-callable service). CraftBot only logs the call.

If you instead want CraftBot to run the agent itself — calling a language-model provider directly and answering from a knowledge base — use the AI Agent node. The Agent node here is for webhook agents; the AI Agent node is for in-platform agents. Both kinds are registered at Settings → AI Agents.

Configuring the node

1. Drop the Agent node from the AI & Intelligence category onto the canvas.
2. Open the configuration drawer:
   • Agent — pick a pre-registered agent from the dropdown. Admins maintain the catalogue at Settings → AI Agents. Disabled agents are hidden from the list. When you pick one, the drawer shows the agent’s endpoint URL, timeout, and auth type below the picker.
   • Payload template (JSON) — optional. The default payload includes tenant ID, conversation ID, session ID, language, the last inbound text, and a snapshot of the recipe variables. Override only when the agent needs a non-standard shape; supports {{variable}} interpolation.
   • Language hint — optional English / Arabic / auto. Forwarded to the agent and used by the safety pre-filter when set.
   • Response mapping — optional. Map fields from the agent’s JSON response onto recipe variables. Per row: dot-path on the response (e.g. answer.text), target scope (conversation / user), variable name, and type (string / number / boolean / object / array). The mapping runs after a successful call before the success port fires.

Sync vs async

Each registered agent declares its mode at registration time:

• Sync — CraftBot waits for the agent to respond within the configured timeout, then continues down the success port (or fail on error / timeout).
• Async — CraftBot fires the webhook and pauses the recipe. The agent calls back to CraftBot’s callback URL when it has a result. Useful when reasoning takes longer than a sync timeout allows.

You don’t configure the mode on the node itself — it’s read from the registered agent and shown in the dropdown label as (sync) or (async).

Output ports

• success — the agent returned a 2xx response with a usable body.
• fail — the agent timed out, returned an error, or the agent registration was invalid (deleted, disabled). Use this port to send a fallback reply or escalate.
• transferred — the safety pre-filter blocked the call. The canned safety message is sent to the customer automatically; this port lets the recipe also take a custom path (e.g. add a tag, set a priority). If the port is unwired, the session ends.

Safety pre-filter

Before every Agent node call, CraftBot runs a keyword pre-filter against the last inbound message and the interpolated payload. When the tenant has the safety filter enforced (the default), matched conversations are blocked from firing the webhook — the canned safety message is sent to the customer and the recipe routes down the transferred port (or ends the session if that port is unwired).

Keywords and canned messages are managed at Settings → Safety. The drawer surfaces a permanent reminder under the response-mapping editor.

Audit and PHI

Every fire is logged with the request, response, latency, and outcome. Real PHI values (names, IDs, etc.) are replaced with stable tokens before storage — the mapping is held briefly in Redis to support callback correlation, then permanently anonymised.

When to use it

• Customer asks an open-ended question your bot recipe doesn’t cover deterministically — let the agent attempt a reply.
• A specific recipe branch needs LLM-flavoured reasoning (intent classification, summarisation, light tool use).
• You want to keep PHI traffic out of LLMs and only let CraftBot send tokenised context.

When not to use it

• The customer’s question is deterministic and a Condition, FAQ, or Intent Route node can handle it. Save the agent call budget for genuinely ambiguous traffic.
• You need write access to a backend system — that lives on Smart Plugs, not on the Agent node.
• You need a deterministic HTTP lookup — use API instead. Agent calls always run through the safety pre-filter and write an audit row; that overhead is wrong for a simple member lookup.