Create, configure, and test your agents
An agent is the smallest unit of automation on alChatBot. You pick a model, write a prompt, toggle skills, and connect it to a channel. This page covers everything you need to build one that actually works.
#The basics
Every agent has:
- A name — used to identify it in dropdowns and analytics.
- An AI provider + model — pick from your workspace's configured providers.
- A system prompt — the instructions that shape its voice, scope, and rules.
- A set of skills — checkboxes that add tools to what the agent can do (see the Skills chapter).
- Optional settings — memory depth, timezone, Whisper language, voice/vision toggles.
Everything is edited from /dashboard/ai/agents/<id>. Changes save when you click the yellow Save button (bottom-right) or hit Ctrl+S.
#Picking a model
Model choice is the biggest cost/quality lever. alChatBot supports:
- OpenAI — GPT-5, GPT-4o, o-series reasoning models.
- Anthropic Claude — Opus 4.7, Sonnet 4.6, Haiku 4.5.
- Google Gemini — 2.5 Pro, 2.5 Flash.
- Z.ai (GLM) — GLM 4.6, 4-Air-Vision.
For most support/sales use cases, Claude Opus 4.7 or GPT-5 give the best balance of tone and reasoning. Try Sonnet 4.6 or GPT-4oif you need to keep costs down at scale — they're noticeably cheaper and still handle most conversations well.
#Writing a system prompt
The system prompt is the single most important control you have. It should describe:
- Who the agent is (the business it represents).
- How it should speak (tone, languages, length).
- What it's allowed to do (topics in scope; things to refuse).
- Handoff rules — when to escalate to a human or another agent.
You are the support assistant for Acme Coffee, a small speciality-coffee shop in Baku.
Voice:
- Speak in the customer's language (Azerbaijani, Russian, or English) — mirror whichever they used first.
- Keep replies under two short sentences unless the customer asks for a detailed explanation.
- Friendly but professional. No slang.
Today is {{day}}, {{date}} at {{time}} ({{timezone}}). The customer is chatting via {{channel}}.
Scope:
- Answer questions about the menu, prices, opening hours, and location.
- Take orders for delivery inside Baku. Confirm address and phone before sending to the team.
- If asked about franchising or partnerships, say "Let me connect you with the founder" and call pauseAgent with a short summary.
Never invent details. If you don't know something (stock, weekend hours, a new promo), reply "Let me check with the team and get back to you", then call pauseAgent.Once your prompt is 300+ lines it becomes hard to maintain and models start to ignore parts of it. Move stable knowledge — menus, prices, FAQs — into a Data Table the agent can query on demand.
#Prompt variables
The System Prompt supports placeholders that get replaced with fresh values on every model call. That way the agent always knows what day it is, what channel the customer is on, and what timezone applies — without you re-editing the prompt.
| Placeholder | Example value | Notes |
|---|---|---|
| {{channel}} | WhatsApp / Instagram | |
| {{date}} | 08 July 2026 | day + month name + year |
| {{day}} | Wednesday | weekday name |
| {{day_number}} | 08 | day of month, zero-padded |
| {{month}} | July | month name |
| {{month_number}} | 07 | month as number |
| {{year}} | 2026 | |
| {{time}} | 14:30 | 24-hour local time |
| {{datetime}} | 08 July 2026 14:30 | combined date + time |
| {{iso_date}} | 2026-07-08 | yyyy-mm-dd (best-effort) |
| {{timezone}} | Asia/Baku | IANA zone selected on the agent |
In the editor, click any chip above the System Prompt textarea to insert the placeholder at the caret. Unknown placeholders pass through untouched, so downstream skill prompts aren't corrupted if a variable name has a typo.
#Timezone
The Timezone dropdown next to the System Prompt sets the IANA zone used to render {{date}},{{day}}, {{time}}. Pick the zone your customers are actually in — for a Baku-based business that'sAsia/Baku, for an Istanbul team it's Europe/Istanbul, and so on.
This is especially important when combined with the Google Calendar skill: the agent proposes and books slots in this timezone, so a mismatch leads to bookings in the wrong hour.
#History depth
Each turn, the agent sees the last N messages automatically. History depth controls N. Smaller values (3–5) force the model to lean on the Memory skill for older context — cheaper on tokens, slower to look things up. Larger values (10–20) hand the model more context for free but cost more per turn.
Default is 10. Increase if the model keeps forgetting recent details; decrease if you're burning tokens on old chatter.
#Voice and vision
- Audio enabled(default on): incoming WhatsApp/Instagram voice notes are transcribed via Whisper before the agent sees them. Without this, the agent gets a “🎤 Audio” placeholder and can't react to what was said. Pick the customer's language in the Whisper language dropdown for the best accuracy.
- Vision enabled (default on): incoming images are forwarded to the model as native image parts — perfect for product photos or screenshots. Requires a vision-capable model (GPT-4o+, Claude 4.x, Gemini 2.x, GLM-4-Air-Vision).
#Testing an agent
Every agent editor has three test tabs at the top:
- Sandbox — a scratch chat that doesn't write to real CRM records. Type as if you were a customer; watch tool calls and replies live.
- Conversations — search past real conversations across every channel this agent has handled.
- Usage — token counts, tool-call frequency, and cost estimates.
Sandbox uses a dry-run wrapper on write-tools like upsertClient and setUserField, so exploratory testing doesn't dirty real contacts. HTTP tools do fire — that's the whole point of testing them.
#Active vs Inactive
An agent has an Active toggle in the top-right of the editor. When set to Inactive, the agent is skipped everywhere — channel default fallback, automation action_ai_reply, everything. Useful for temporarily silencing an agent without deleting it.