n8n Agent Builder
Turns a plain-language request ("make a WhatsApp bot for my clinic that books appointments, using Claude") into working n8n workflows, deploys them through the n8n public API, and hands the user the links.
Everything runs through one script (Python 3.10+, standard library only):
python3 <skill-dir>/scripts/n8n_agent.py <command> ...
Run it from the user's project folder so it finds their .env. Spec files and the
<spec>.deployed.json state files live there too.
| file | read when |
|---|---|
references/spec.md | writing a spec - every field, tool and channel option |
references/channels.md | setting up WhatsApp, Telegram, Slack, webhook or website chat |
references/providers.md | choosing an LLM / embeddings provider, OpenAI-compatible URLs |
references/troubleshooting.md | any error |
templates/*.json | ready-made agents - start from one whenever it fits |
Workflow
1. Connection
python3 scripts/n8n_agent.py check
If it fails, the user needs a .env (copy of .env.example) with N8N_BASE_URL
(root URL, e.g. https://me.app.n8n.cloud) and N8N_API_KEY (n8n → Settings →
n8n API). Ask them to create it themselves. Never ask for secrets in chat and never
print them. If n8n is unreachable from here, still build the spec and use
build to hand over importable JSON files.
2. Pick a starting point
Run templates and pick the closest one; copy it with
new <template> -o <file>.json --name "..." [--provider ...]. Templates exist for:
restaurant orders, clinic appointments, real estate leads, e-commerce support, tutor,
HR FAQ, website lead capture, chat-with-documents, research, multi-agent front desk.
If nothing fits, write a spec from scratch (see references/spec.md).
3. Ask only what's missing
Keep it to one short round of questions. Typical gaps:
- business details for the
{PLACEHOLDERS}in the template (name, hours, prices...) - which LLM provider [default openai / gpt-4o-mini]
- where it should live: website chat (default), WhatsApp, Telegram, Slack, API
- IDs the tools need (Google Sheet ID, calendar ID) - or leave the placeholder and tell them to set it in the editor
- existing n8n credential IDs (shown in the credential's URL in n8n). Put them in
credential_idor, for tools/channels, in the top-levelcredentialsmap ({"googleSheetsOAuth2Api": "12"}) so one ID covers every node of that type.
Write a strong system_prompt: role, business facts, what to collect, when to use
each tool (by node name), what never to do, reply language, tone, escalation path.
4. Validate, then deploy
python3 scripts/n8n_agent.py validate agent.json # offline check + warnings
python3 scripts/n8n_agent.py deploy agent.json --activate
validate/deploy list unfilled placeholders and every node still missing a
credential. Fix placeholders before deploying. Missing credentials are fine: the
workflow is created inactive and the user selects credentials in the editor, then
activates (or re-runs update --activate).
deploy saves IDs and links to agent.deployed.json. Deploy order is handled
(sub-agents first). A spec with knowledge on a persistent store also creates a
separate "knowledge upload" workflow.
5. Test
python3 scripts/n8n_agent.py test agent.json # runs spec "tests"
python3 scripts/n8n_agent.py test agent.json -m "Hi" -m "Menu?"
Works for chat and webhook channels once active. For WhatsApp/Telegram/Slack ask the user to message the bot.
6. Hand over
Tell the user, briefly: what the agent does, its model, channels, tools; the links
from the deploy output (editor, chat, upload form, API); what they still must do
(credentials, Meta/Telegram/Slack setup from references/channels.md, upload
documents); and that the chat is public unless chat_auth is set.
For their own website: set "chat_mode": "embedded", update, then
ui agent.json -o chat-site [--mode bubble] [--color ...] [--files] makes a branded
chat site/widget (right-to-left support, voice input, file upload). It can be dragged onto
Netlify Drop or embedded with two script tags.
Studio (visual alternative)
If the user prefers a visual tool, or wants to let non-technical teammates build agents,
point them to the Studio: python3 <skill-dir>/studio/server.py (or python studio.py in
the repo) opens a local web app with chat-to-agent, a form builder, a live workflow diagram,
deploy/update/delete and a test chat. It reads the same .env. Online version (design and
download only): https://jrnoorbaloch.github.io/n8n-agent-builder/studio/
Changing and managing agents
| task | command |
|---|---|
| change prompt/model/tools/channels | edit spec, then update agent.json [--activate] (keeps chat URLs) |
| list agents | list (--all for every workflow) |
| backup a workflow | export <id> -o file.json |
| pause / resume | deactivate <id> / activate <id> |
| token use and cost | usage <id> --price-in 0.15 --price-out 0.6 ($ per 1M tokens) |
| remove | delete agent.json (everything deployed from it) or delete <id> - always confirm with the user first; pass -y only after they agree |
| add a credential via API | user sets LLM_API_KEY env var, then create-credential --provider anthropic --name "Claude" (also telegram) |
Rules
- Secrets only in
.envor n8n credentials - never in specs, chat, or git..deployed.jsonholds webhook URLs: keep it out of git (already in.gitignore). - Public chats spend the user's LLM credits: suggest
chat_authfor internal bots. postgres_querytool: insist on a read-only database user.- Prefer a persistent knowledge store (supabase/pinecone/qdrant/pgvector) for anything
beyond a demo;
memorystore is wiped on n8n restart. - Don't claim something works until
testpasses or the user confirms.