Automations and agents
An AI agent in killBottleneck is anything that answers a webhook — an n8n workflow, a cron job, your own script — and can perform a map step. This page is about marking such a step, who keeps the agents and when they start.
What other pages cover
“When X → do Y” right in the map is automation rules (including deputies). Projects that create themselves from a template are in Templates. Connecting an AI assistant (Claude, Cursor) from outside is in Account and settings and in MCP.
Where to find it
- In the goal window, the Automation category: Who performs this, Which automation does it, I would like this automated, Wait for children, the node's rules.
- The user menu → AI agent registry (AI manager and administrator).
- In rules, the run an agent action.
Who performs the step
Every goal records Who performs this: Person or Automation. The assignee stays human — even for an automation it is the assignee who gets notified and who sees the goal in their My day. For an automation you fill in Which automation does it (A record of what already runs here. If the name matches an agent in the registry, killBottleneck can start it itself.).
Any goal can have I would like this automated switched on (Lets the AI agent managers know. They decide whether to build it.) with an optional note why it slows you down today. The AI manager gets an AI agent request notification; once they build the automation and record it on the goal, the request clears itself and you get Automation is ready. Such a goal carries the automation wanted badge on its card.
The AI agent registry
An AI manager (or administrator) keeps the directory: Name (Nodes reference the agent by this name. It must be unique.), Description, Webhook address, Signing secret (killBottleneck signs the request body with it in the X-Signature header (HMAC-SHA256). It is never shown again.), Enabled and Who may run it (Separate e-mails with commas. Empty means anyone who can edit a map may run this automation.). Without a secret the dialog warns that the request is signed with an empty key.
At the bottom is the Where the agent reports back block with the callback address: When finished, POST run_id, run_token and status (done/failed), optionally result. That completes the node and hands over to the next step. When the address points to localhost, the dialog says a remote automation cannot reach it — set KB_PUBLIC_URL.
When an automation starts
An automated goal does not start by itself when created — it waits for one of these:
- You switch the goal to In progress. The manual “it's being done now” — starts the automation right away. The same path retries a failed run (Restart it by switching the goal to “In progress”.).
- The goal “comes up” — all its subgoals get done. This dependency behaviour must be switched on with Wait for children; without it the goal does not wait for its subgoals.
- You upload an attachment to the goal — the window says so in advance: Uploading a file starts the automation “…” right away.
- A rule with the “run an agent” action — The run is queued and dispatched within a minute.
What you see: the run state right in the goal window — Starting the automation… / Automation running… / finished / failed (with the reason on failure). When the agent reports done, the goal completes and the next step unblocks — automated steps chain by themselves. A run that never reports back is marked failed by the watchdog after the limit (KB_AGENT_TIMEOUT_MIN, default 90 minutes; checked once an hour) — Automation failed — and the assignee and the AI managers are told.
The name must match an agent in the registry
If you name an automation on a goal that matches no registered and enabled agent, the window says so right away: This agent is not in the registry yet — the step won't run on its own until you create it there. To just note it down, switch on “I'd like this automated”.
Limits and variables
KB_PUBLIC_URLtells the agent where to report back — without it a remote agent calls localhost.- Agents on a private network (typically self-hosted n8n) need
KB_ALLOW_PRIVATE_WEBHOOKS=1on your own server, or the narrowerKB_PRIVATE_WEBHOOK_HOSTS(ahost:portlist). On a hosted instance a private address is not possible at all. See Environment variables → Automation. - Only the AI manager and administrator see the registry; members pick an agent by name.
- A watchdog failure shows up at the hourly check — 90 to 150 minutes after the run started.
killBottleneck driven from outside
The other direction — your code or an AI assistant working with the maps — goes through API keys (the user menu → API keys; a Read only or Read and write key, optional expiry, the token shown once, Rotate key) or through Connect AI agent (OAuth, no key). It opens two doors: the REST API for scripts and integrations and the built-in MCP server for assistants like Claude. A key acts as its owner: it reaches the maps the owner can see and writes according to the share level; it never reads roles and cannot reach administration. Details in Account and settings.
Related
- Automation rules — the “run an agent” action and everything else the map does by itself
- Connecting through n8n — n8n as an agent and as an API client
- MCP server — connecting an AI assistant step by step
- Environment variables — the configuration around automations

