AI Agents

This page is where admins register every AI agent in the workspace. CraftBot draws a hard line between customer-facing agents (called by recipes during a real customer conversation) and the admin-facing Recipe Copilot (an in-product assistant that helps admins build and diagnose recipes on the canvas). They share a registry page but are different concepts — pick the right kind for the job.

Customer-facing agents — called from a recipe node during a real conversation:

• Webhook agent — an external HTTP endpoint. CraftBot does not run language-model orchestration itself; the AI flow lives on an external platform (n8n, LangGraph, anything that exposes an HTTP webhook). CraftBot just POSTs the conversation context and ships back whatever the endpoint returns. Called from the Agent node.
• In-platform agent — an agent CraftBot runs itself by calling a language-model provider (Anthropic or OpenAI) directly. You give it a system prompt, a knowledge base, and a model; CraftBot handles the call. Called from the AI Agent node.

Admin-facing assistant — not called from any recipe:

• Recipe Copilot (✦ Set up Recipe Copilot button) — the in-product assistant that powers the Craft Copilot panel on the recipe canvas. Generates nodes from natural-language descriptions, diagnoses validation issues, and explains nodes to authors. Only one Recipe Copilot exists per tenant. See Craft Copilot for the canvas-side experience.

The page header carries three buttons that map directly to those three kinds: + Webhook agent, + In-platform agent, and the primary ✦ Set up Recipe Copilot button. Once a Recipe Copilot is configured, the third button changes to ✦ Edit Recipe Copilot — you cannot create a second one.

Registering a webhook agent

1. Settings → AI Agents → + Webhook agent.
2. Name (e.g. Eligibility Triage) and an optional Description.
3. Endpoint URL — the absolute URL the recipe will POST to. HTTPS is required in production.
4. Mode — pick one:
   • sync — one HTTP round-trip. The recipe waits for the response, then continues.
   • async — CraftBot fires the request, the agent acknowledges, and replies later via a callback URL. Use this for long-running agents (LLM chains, document processing) that can’t return in one round-trip.
5. Timeout (ms) — between 1,000 and 120,000. Sync mode hard-fails after the timeout. Async mode treats this as the acknowledgement timeout.
6. Auth type — pick one:
   • none — no authentication header is added.
   • bearer — CraftBot adds Authorization: Bearer <secret>.
   • hmac_sha256 — CraftBot signs the request body and adds X-CraftBot-Signature: <hash>.
7. Secret — required for bearer and HMAC modes. At least 8 characters. Stored encrypted in the credential vault and never returned to the UI again.
8. Enabled — uncheck to disable an agent without deleting it. Disabled agents are visible in the recipe canvas but Agent nodes pointing at them fail closed.

Registering an in-platform agent

1. Settings → AI Agents → + In-platform agent.
2. Name and an optional Description.
3. LLM provider — Anthropic or OpenAI.
4. Model — pick a model from the dropdown. The list is provider-aware: with Anthropic selected it offers Claude Opus 4.7, Claude Sonnet 4.6, and Claude Haiku 4.5; with OpenAI selected it offers GPT-4o, GPT-4o mini, GPT-4.1, and GPT-4.1 mini. Switching the provider resets the model to a valid choice for the new provider, so you can’t end up with a mismatched pair.
5. Knowledge base — pick a knowledge base from the dropdown. Its entire contents are folded into the prompt as context, so the agent answers from your published material. Knowledge bases are maintained at Knowledge Bases.
6. System prompt — the standing instructions for the agent: its role, tone, what it should and shouldn’t answer.
7. Temperature — how much variation the model is allowed. Lower is more deterministic.
8. Max tokens — the ceiling on the length of a single reply.
9. Timeout (ms) — how long CraftBot waits for the model before treating the call as failed.
10. Escalation — turn this on to let the agent hand off to a human when it isn’t confident. With it on you can supply optional escalation messages in English and Arabic, shown to the customer at the moment of hand-off.
11. Enabled — uncheck to disable without deleting.

Data-residency warning

An in-platform agent sends conversation content to a US-hosted language-model provider (Anthropic or OpenAI). This is a known and accepted data-residency exception to the usual MENA-residency rule. The audit log for the call is PHI-tokenised as normal, but the request that goes to the model carries live conversation content. The form shows this warning whenever you create or edit an in-platform agent — read it and confirm the trade-off is acceptable for your tenant before enabling the agent.

Setting up the Recipe Copilot

The Recipe Copilot is the language-model behind the Craft Copilot panel on the recipe canvas. It is admin-facing — it never speaks to a customer and is never called from a recipe node. Until you set it up, the Craft Copilot panel shows an empty state pointing back here.

1. Settings → AI Agents → ✦ Set up Recipe Copilot.
2. Name and an optional Description (helpful when reviewing the registry; not shown to authors).
3. Enabled — uncheck to disable the Copilot without removing the configuration. With it off, the Craft Copilot panel on the canvas tells authors the assistant is currently disabled.
4. LLM provider — Anthropic or OpenAI.
5. LLM model — pick a model from the provider-aware dropdown.
6. System prompt — the standing instructions for the Copilot. Use this to nudge its style (concise vs. verbose), its bias (prefer subflows, prefer minimal nodes), or any tenant-specific conventions your recipes follow.
7. Temperature — how much variation the model is allowed. Lower is more deterministic; useful for Diagnose, where you want the same recipe to surface the same issues twice in a row.
8. Max tokens — the ceiling on the length of a single Copilot reply.
9. Requests per user per hour — soft cap on how often an individual admin can hit the Copilot. Protects the bill if someone leaves the panel open generating in a loop.
10. Behaviour toggles — three independent switches:
    • Offer matching templates when generating from a description — when on, the Copilot scans your recipe templates and offers a starting template if it finds a close match to the prompt.
    • Show the “Suggest next node” tooltip by default on the canvas — when on, the Copilot drops a small hint near the most recently placed node nudging the author toward a likely next step.
    • Run Diagnose automatically when the Copilot panel opens — when on, opening the panel kicks off a Diagnose pass straight away so issues are surfaced without the author asking.
11. Recipe context mode — how much of the current recipe the Copilot sees on every request. Full JSON is the only choice today; Summarised is shown for forward visibility but is not yet available.

Only one Recipe Copilot exists per tenant. Once configured, the page-header button switches from Set up to Edit Recipe Copilot and the customer-facing “New agent” flow does not offer Copilot as an option.

The agents table

Each row shows:

• Kind — a badge marking the agent as Webhook, In-platform (azure tint), or ✦ Recipe Copilot (gold tint).
• Endpoint / Model — the endpoint URL for webhook agents, provider · model for in-platform agents, or provider · model for the Recipe Copilot.
• Auth — the auth type for webhook agents; — for in-platform agents and the Recipe Copilot (CraftBot manages the provider credentials itself).
• Test — only shown for webhook agents (see below).

Testing a webhook agent

The Test button on a webhook-agent row sends a probe payload to the configured endpoint and reports:

• HTTP status code returned by the agent.
• Round-trip latency in milliseconds.
• The raw response body.

Use it after registering or rotating a secret to verify credentials, reachability, and the agent’s response shape — all without wiring it into a recipe.

In-platform agents have no Test button — they don’t expose an endpoint to probe.

Rotating a secret

The stored secret for a webhook agent is never displayed in clear, even to the admin who created it. To replace it:

1. Open the agent and tick Rotate stored secret.
2. Enter the new value in the New secret field.
3. Save. The old secret is overwritten in the vault.

Where agents are used

• Agent node in the recipe canvas — wires a recipe to a registered webhook agent.
• AI Agent node in the recipe canvas — wires a recipe to a registered in-platform agent.
• Craft Copilot panel on the recipe canvas — powered by the Recipe Copilot. See Craft Copilot.
• Safety pre-filter — every customer-facing agent call (webhook + in-platform) runs the keyword pre-filter from Safety before the call fires. Matches block the call, send the canned reply, and route the conversation to a human. The Recipe Copilot does not run the safety pre-filter — it never talks to a customer, only to an admin building a recipe.

Best practices

• For webhook agents, use HMAC when the agent platform supports it — it’s strictly stronger than bearer because the signature also covers the request body.
• Start webhook agents in async mode if you don’t know the typical response time. You can switch to sync later if every call returns under a second or two.
• For in-platform agents, keep the system prompt tightly scoped and pair it with a focused knowledge base — a smaller, on-topic KB produces sharper answers than a sprawling one.
• Turn on escalation for any in-platform agent that handles real customer questions, so a low-confidence answer hands off cleanly instead of guessing.
• Keep one agent per logical purpose. “Eligibility lookup” and “Authorization request” should be two registry rows, not branches inside a single agent.

Deleting an agent

Deleting an agent leaves any recipes that pointed at it in a broken state — the node will fail closed with an “agent not found” error. Disable the agent first (uncheck Enabled) and verify no recipes still depend on it before deleting permanently.