> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt > Use this file to discover all available pages before exploring further. # Create Your First AI Agent > A friendly, step-by-step guide to building an AI agent that answers your customers — explained in plain language, with a full example. ## What is this? Imagine you open a shop and hire a new helper. On day one you'd tell them: * **who they are** ("You work at the bakery"), * **how to talk** ("Be friendly and short"), * **what they know** ("Here's our menu and opening hours"), * **what they're allowed to do** ("You can pass a customer to me if they're upset"), * **what they must never do** ("Never promise a discount"). An **AI agent** is exactly that helper — but it lives inside the platform, reads your customers' messages on WhatsApp, Instagram, Facebook, or Web Chat, and writes the replies for you. Everything in the agent builder is one of those five instructions. This guide walks you through building one from nothing, and ends with a complete example you can copy. \[SCREENSHOT: ai-agent-guide-overview — The AI Agents page showing an agent with the Active status and the Agentic Mode switch turned on] ## What can I do here? By the end you will have: * an AI setting that gives your agent a "brain" * an agent with a name, a personality, and clear instructions * reference material (your knowledge) the agent can look things up in * safety rules turned on * a tested agent that's live on your channel ## How to use it ### Before you start — a 3-item checklist Your agent needs somewhere to talk to customers. Connect WhatsApp, Instagram, Facebook, or Web Chat in [Channels](/workspace/channels). The agent needs an AI provider to think with. Go to **Settings → AI Setting** and click **Add AI Setting**. Choose a **Provider**, paste your **API Key**, and pick a **Model**. Then use the power icon to make it **Active**. \[SCREENSHOT: ai-agent-guide-ai-setting — The AI Setting tab with a saved, Active AI setting] Think of the API key as the "battery" for the brain. Without an active AI setting the agent has nothing to think with, and the builder tells you to go add one. Have your prices, opening hours, return policy, or a help-page link ready. You'll hand these to the agent in Step 5. ### Step 1 — Create the agent and give it a name (General tab) 1. Go to **AI Agents** in the sidebar and click **Create**. 2. **Agent Name** — pick something clear, like `Bakery Helper`. 3. **Agent Type** — pick the closest match: **Support** (answers questions), **Sales** (helps people buy), **FAQ** (answers common questions), **Booking** (takes appointments), or **Custom** (anything else). This is just a label to keep things tidy. 4. **Description** — write one or two sentences saying what this agent is for, for example: *"Answers customer questions about our cakes, prices, and opening hours, and helps with orders."* The description matters more than it looks. If you later build a second agent, the platform reads each agent's description to decide **who should answer which message** — a bit like a receptionist deciding which specialist to hand a customer to. Say what makes this agent different. The **AI Rewrite** button will polish your sentence for you. 5. **Save** the agent. Some tabs — Capabilities, External Capabilities, Skills, and Workflows — only unlock after the agent exists, so save before you continue. \[SCREENSHOT: ai-agent-guide-general — The General tab with Agent Name, Agent Type, and Description filled in] ### Step 2 — Choose its personality (Behavior tab) * **Tone** — how it sounds: **Neutral**, **Friendly**, **Professional**, **Casual**, or **Formal**. A bakery might pick **Friendly**; a law firm might pick **Formal**. * **Priority** (1–1000) — if you have several agents, the higher number goes first. Leave it at the default `100` for now. * **Status** — set this to **Testing** while you're building. That's like a "trainee" badge: it's not doing the real job yet. ### Step 3 — Tell it how to behave (Instructions tab) This is the most important step. Write the **System Instructions** the way you'd brief a new employee: short sentences, plain words, and clear rules. A good set of instructions answers five questions: | Question | Example | | -------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Who are you?** | You are the friendly helper for Sweet Crumbs Bakery. | | **What is your job?** | Answer questions about our cakes, prices, and opening hours, and help customers place an order. | | **How should you talk?** | Reply in short, warm messages. Use simple words. One question at a time. | | **What must you never do?** | Never invent prices or ingredients. Never promise a discount. If you're not sure, say so. | | **When should a human step in?** | If the customer is upset, asks for a refund, or asks something you can't answer, hand over to the team. | If you're not happy with how it reads, click **AI Rewrite** — it turns your rough notes into a clear instruction. Review the result before you save. \[SCREENSHOT: ai-agent-guide-instructions — The Instructions tab with example system instructions and the AI Rewrite button] The agent can only follow what you write. If you don't say "never promise a discount," it might. Be specific about the things that matter. ### Step 4 — Give it something to read (Knowledge tab) An agent that has only instructions can chat nicely but doesn't know **your** facts. The Knowledge tab is its library. 1. Click **Add Source**. 2. Choose a **Source Type**: | Source Type | Use it when | | ------------------------------------------------------------------ | ----------------------------------------------------------------- | | **Manual Text** | You want to type or paste facts, such as prices and opening hours | | **Website URL** | Your answers are on a web page | | **Sitemap Crawl** | You want the agent to read many pages from your site | | **llms.txt Crawl** | Your site has an `llms.txt` guide for AI | | **PDF**, **Word**, **Markdown**, **Text**, **CSV**, **Excel** file | Your facts are in a document or spreadsheet | 3. Give it a **Title** (optional) and add the content, link, or file. Save it. 4. Watch the status. The agent reads the source and it moves from **Pending** → **Processing** → **Processed**. Wait for **Processed** before you test. If it says **Failed**, check the link or file and add it again. \[SCREENSHOT: ai-agent-guide-knowledge — The Knowledge tab showing added sources with Processed status badges] Start small. Add one or two good sources — a price list and a short FAQ — rather than everything you own. Short, accurate, up-to-date facts give better answers than a huge pile of old ones. ### Step 5 — Decide what it's allowed to do (Capabilities tab) Capabilities are "buttons the agent may press." Without them it can only talk. With them it can also *act*. They're grouped by area — **Contacts**, **Conversation**, **Knowledge**, **Catalog**, **Events**, and **Automation** — for example: * update a contact's details * **hand off to a human** * search your product catalog Turn on only what the agent really needs. Two helpful settings: * **Require customer confirmation** — the agent asks the customer "Shall I go ahead?" before it does something that matters. * **Handoff Assignment** — when the agent passes a chat to a person, who gets it? **Unassigned** (anyone can pick it up), **Fixed team member**, **Round robin** (take turns), or **Least busy**. \[SCREENSHOT: ai-agent-guide-capabilities — The Capabilities tab with the hand-off capability enabled and Handoff Assignment options showing] **External Capabilities** and **Skills** are for later. External capabilities let the agent call your own systems (a web request or MCP tool), and skills are reusable extras. You don't need either for your first agent. ### Step 6 — Choose where it works and how it talks (Channels tab) 1. Under **Communication Channels**, pick **All Channels**, or just **WhatsApp**, **Facebook**, **Instagram**, or **Web Chat**. 2. **AI Setting Source** — choose the AI setting from the checklist. 3. **Allowed Response Modes** — **Text** is always on. Turn on **Buttons** and **List** if you want the agent to reply with tappable options. 4. **Response Language** — **Auto** answers in whatever language the customer writes in; **Fixed** always answers in the language you type in. 5. **Media Capabilities** — turn on **Image Understanding**, **Voice Input**, **Voice Output**, or **Video Understanding** if you want the agent to handle pictures, voice notes, or videos. ### Step 7 — Turn on the safety rules (Guardrails tab) Switch on **Enable Guardrails**. Guardrails are safety checks that stop the agent from writing harmful, unfair, or inappropriate replies — like a seatbelt. Keep them on. ### Step 8 — Try it before real customers do (Test tab) 1. Open the **Test** tab. This is the **Agent Playground** — a safe practice room. 2. Type a message a customer would send, like *"Do you have chocolate cake?"* and press **Send**. 3. Read the reply. You can also see which tools the agent used to answer. 4. Try tricky questions too: something it shouldn't know, something rude, something outside its job. 5. If an answer is wrong, fix the **Instructions** or add the missing fact to **Knowledge**, then test again. Click **New Conversation** to start a fresh test. \[SCREENSHOT: ai-agent-guide-test — The Test tab playground with a sample customer conversation] ### Step 9 — Go live 1. Set the agent's **Status** to **Active** (Behavior tab), or click **Activate** on its row in the AI Agents list. 2. On the AI Agents list, make sure the **Agentic Mode** switch is **on**. This is the channel's master switch — if it's off, no agent answers, even an Active one. 3. Send a real message to your channel from your own phone to check it works. Keep an eye on the first few real conversations in your [Inbox](/workspace/inbox/overview). You can always **Pause** the agent from the list, and a teammate can take over any chat. ## A complete example you can copy Here's a finished agent for a made-up bakery. | Setting | Value | | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Agent Name** | Sweet Crumbs Helper | | **Agent Type** | Support | | **Description** | Answers questions about Sweet Crumbs Bakery's cakes, prices, delivery, and opening hours, and helps customers place an order. | | **Tone** | Friendly | | **Status** | Testing, then Active | | **Channels** | WhatsApp | **System Instructions** ```text theme={null} You are the friendly helper for Sweet Crumbs Bakery. Your job: - Answer questions about our cakes, prices, delivery, and opening hours. - Help customers decide what to order. How to talk: - Reply in short, warm messages. Use simple words. - Ask only one question at a time. Rules: - Only use the facts in your knowledge. Never invent prices, flavours, or ingredients. - Never promise a discount or a special delivery time. - If you are not sure, say "Let me check with the team" and hand over to a person. - If the customer is upset or asks for a refund, hand over to a person right away. ``` **Knowledge (Manual Text)** ```text theme={null} Opening hours: Monday to Saturday, 8am to 7pm. Closed on Sunday. Delivery: Free within 5 km for orders over 30 dollars. Otherwise 4 dollars. Cakes: Chocolate 25 dollars, Vanilla 22 dollars, Red velvet 28 dollars. Custom cakes need 48 hours notice. ``` **Capabilities:** hand off to human (Handoff Assignment: **Round robin**). **Guardrails:** on. **Try these in the Test tab** * *"What time do you open on Saturday?"* → should say 8am. * *"Can I get a cake tomorrow with my name on it?"* → should mention 48 hours' notice. * *"Give me 50% off!"* → should politely say it can't promise discounts. * *"This is terrible, I want my money back!"* → should hand over to a person. ## Working with more than one agent You can create several agents — for example one for **Sales** and one for **Support**. When a channel has two or more active agents, the platform automatically adds a hidden "router" that reads each customer message and hands it to the agent whose **Description** fits best. That's why clear, different descriptions help so much. **Priority** decides who goes first when more than one could answer. You can also move an agent between channels with **Export** (downloads the agent as a JSON file) and **Import** (loads it into any channel you choose). Importing creates brand-new copies, so nothing gets overwritten. ## Troubleshooting / Technical Notes * **The agent doesn't reply at all.** Check the three master switches: the agent's **Status** is **Active**, **Agentic Mode** is **on** for the channel, and the agent's **Channels** tab includes the channel the message came from. * **The builder says there are no AI settings.** Add and activate one in **Settings → AI Setting** first (see the checklist). * **It gives wrong or made-up answers.** Add the missing fact to **Knowledge**, make sure the source shows **Processed**, and tighten the **Instructions** ("Only use the facts in your knowledge"). * **A knowledge source shows Failed.** Check that the link opens in a normal browser or that the file isn't empty, then add it again. * **The Capabilities tab is empty or locked.** Save the agent first, then reopen it. * **I can't create another agent.** Your plan limits how many agents you can create — the limit shows on the **Create** button. * **A customer is stuck with the agent.** Any teammate can take over the conversation in the [Inbox](/workspace/inbox/overview), and you can pause the agent from the list at any time. ## Related docs * [AI Agents overview](/workspace/ai-agents/overview) * [Settings](/workspace/settings) — AI Setting * [Inbox](/workspace/inbox/overview) * [Analytics](/workspace/analytics) — AI Usage tab * [AI Response steps in Automation](/workspace/automation/steps/ai-steps)