# AI Agents **Lodgestory CRM › Settings › AI Agents** > **Write the instructions, attach the tools, and let AI handle the top half of your conversations in your own voice.** > **TL;DR** > > * **What it is —** the configuration page for every AI touchpoint in Lodgestory CRM. Each AI Agent carries a persona (a name, a description, a system prompt) and an optional set of tools it can use to look up bookings, check availability, create tickets, or call anything else your business exposes. > * **Who it's for —** Account Owners and Admins author AI Agents and tools. Users benefit from them through the inbox and bot journeys. > * **Top outcome —** one well-designed AI Agent per channel that handles around 60% of routine messages and hands over cleanly for the rest. ## At a glance | | | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Plan tiers** | All paid tiers. AI usage is part of your plan allowance. | | **Who can use it** | Account Owners and Admins author agents. Users and the bot role consume them through the inbox and bot journeys. | | **Channels** | Each AI Agent is scoped to one channel, so WhatsApp, Email, Instagram, and Web Chat can each have their own voice. | | **Integrations** | Runs inside [Bot Journeys](bot-journeys.md), powers the AI Assistant drafts in [Home / Unified Inbox](../workspace/home-unified-inbox.md), and validates free-text answers inside bot prompts. | | **Top limits** | Persona name 2–255 characters. System prompt up to 10,000 characters. Tool timeout defaults to 5 minutes. No cap on agents per channel or tools per agent. | | **API** | Yes — partner API for creating and updating AI Agents, tools, and tool attachments. | ## How to find it **Sidebar: Settings → AI Agents.** **Direct URL:** `https://lodgestory.com/crm/settings/ai-agents` \[SCREENSHOT: ai-agents-landing.png — list of AI Agents grouped by channel] ## What is AI Agents? ### The problem it solves AI shows up in three distinct places in your inbox, and each one needs the same underlying decisions — who's the agent, what tone do they use, what can they look up on your behalf. 1. **Inside a bot journey.** A customer types; the AI Agent answers; it may decide to check your availability system, then reply with a quote. 2. **Drafting for a human agent.** Your team member opens a complex chat and asks the AI Assistant for a starting draft they can edit and send. 3. **Validating free-text answers.** A bot asks *"What date are you arriving?"* and needs to decide whether *"Maybe next Tuesday"* counts. Without a shared configuration surface you'd end up copying prompts across three places, watching them drift, and forking tone per channel. AI Agents keeps all three in sync: one persona per channel, one shared library of tools, one place to update the prompt and have every consumer pick it up the next time it runs. ### What you get * **Per-channel personas.** Give WhatsApp a warm concierge voice, Email a measured operations tone, and Web Chat a fast, friendly greeter. Same underlying AI, different personas. * **System prompts with up to 10,000 characters.** Write the rules your AI should follow — scope, escalation triggers, tone, what never to do — with room to be specific. * **A shared tools library.** Define a tool once (check availability, look up a booking, fetch the weekend rate, open a support ticket), and attach it to any AI Agents that need it. * **Function-calling that actually works.** Your tools are described with a standard schema the model understands. When a guest asks about a booking, the AI decides to call the tool, Lodgestory fetches the result, and the AI weaves the answer into its reply. * **Channel summary.** At a glance, see which channels have an AI Agent configured and which don't. * **Bulk edit.** Delete many agents or tools at once when you're tidying up. ### How it's different * **Three runtimes, one configuration.** Bot journeys, the AI Assistant in the inbox, and AI-based answer validation all read the same AI Agents you configure here. Edit once; every consumer picks the change up on the next run. * **Agents are per-channel; tools are organisation-wide.** You can keep WhatsApp and Email on distinct personas without duplicating your tool library — the same `getBookingStatus` tool works for every channel that needs it. * **Standards-based tool schema.** Tool definitions follow the same function-calling format the major AI platforms use, so migrating tools in and out is straightforward. ### Customer scenarios * **Villa concierge on WhatsApp.** An Admin writes a system prompt: *"You are the concierge for a luxury villa group. Answer questions about check-in, pool hours, and Wi-Fi. For availability or rates, call *`checkAvailability`*. For booking details, call *`getBookingStatus`*. If the guest asks for a human, say so and stop."* Attaches both tools. Drops the AI Agent into a bot journey. Inbound WhatsApp now flows through. * **Drafting a refund reply.** A team member opens a complex refund chat. The AI Assistant panel shows a draft using the channel's configured agent — brand voice, booking context fetched via a tool — and the team member edits and sends. * **Validating dates.** A bot prompt asks for an arrival date with AI-based validation. The AI looks at *"next Tuesday"* and decides it counts; the bot moves on. On *"soon"*, the AI decides it doesn't and the bot re-asks. ### How it fits with the rest of Lodgestory CRM AI Agents is the configuration layer. Downstream: * **[Bot Journeys](bot-journeys.md)** — the **AI Agent** step references an agent by name; the **Prompt** step can use AI-based validation from the same agent. * **[Home / Unified Inbox](../workspace/home-unified-inbox.md)** — the AI Assistant draft pulls the channel's configured agent. * **[Connections](connections.md)** — each AI Agent is scoped to a channel you've set up here. ## Core concepts | Term | What it means | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **AI Agent (persona)** | A named voice with a system prompt, scoped to one channel. You can have multiple per channel if you want different personas for different flows. | | **System prompt** | The behavioural instructions you write for the AI — scope, tone, rules, escalation triggers. | | **Tool** | A named action the AI can invoke — look up a booking, check availability, create a ticket. Tools are organisation-wide and can be attached to any agent. | | **Tool parameters** | A structured description of the arguments a tool accepts, so the AI knows what to send when it calls the tool. | | **Attachment** | The link between an AI Agent and a tool. The same tool can be attached to many agents. | ## Quick Start — your first AI Agent in 10 minutes ### Step 1 — Open AI Agents Sidebar: **Settings → AI Agents.** \[SCREENSHOT: ai-agents-qs-1-landing.png] ### Step 2 — Create a tool Open the Tools tab and click **+ New Tool**. A tool needs: * A **name** the AI will use — for example, `getBookingStatus`. * A **description** that tells the AI when to call it — *"Fetches the booking status given a booking reference."* * **Parameters** — a short description of the inputs the tool needs. For the example above, one required `bookingRef` string. * A **URL** where the tool call should be sent — for example, `https://ops.example.com/api/bookings/{bookingRef}/status`. * The **HTTP method** and any **headers** your endpoint needs (including authentication). ### Step 3 — Create the AI Agent Go to the Agents tab and click **+ New Agent**. Pick the channel (e.g. WhatsApp), then fill: * **Persona name** — e.g. *Support Bot*. * **Description** — a short internal note. * **System prompt** — a paragraph or two describing personality, scope, escalation rules, and when to call which tool. Save. \[SCREENSHOT: ai-agents-qs-3-create.png] ### Step 4 — Attach the tool On the agent's detail panel, click **Attach tool** and pick `getBookingStatus`. Save. ### Step 5 — Use it in a bot journey Open [Bot Journeys](bot-journeys.md). Drop an **AI Agent** step into a journey, pick the agent you just created, save, and deploy. ### Step 6 — Test Open the bot journey's test panel and send a message that mentions a booking reference. The AI should recognise the reference, call `getBookingStatus`, and reply using the result. ### What's next * Add more tools (weather, availability, ticket create). * Iterate on the system prompt based on real chats. * Configure a different persona for the Email channel if the tone should change. ## How it works When an AI Agent is invoked — inside a bot journey, as a draft in the inbox, or as a validator — Lodgestory loads the persona and the tools you've attached, builds the conversation context, and sends it to the AI. If the AI decides to call a tool, Lodgestory runs the call on your behalf, returns the result to the AI, and waits for the next response. This loop continues until the AI produces a final answer or reaches its safety limits. All of this happens inside a single turn: the guest sees "typing…" and then a reply that already contains the tool's result. Tool calls time out at 5 minutes by default so a slow or broken endpoint can't hang the conversation, and there's a safety cap on how many loops a single turn can go through so an AI can't get stuck in a tool-call cycle. The behavioural rules live in your system prompt. The tools live in your shared library. Swap the prompt, change every conversation's tone the next time they run. Update a tool's URL, and every agent that uses it picks up the new endpoint on its next call. ## Features in depth ### Agent list Columns: persona name, description, channel, attached tool count, created date, actions. Filter by channel; search by name; filter to agents that have at least one tool attached. ### Create and edit an agent Fields: persona name (2–255 characters), description (up to 7,000), system prompt (10–10,000), and the channel the agent is scoped to. Markdown is supported in the system prompt, with a preview alongside the editor. ### Tools library Each tool has: * A name and description (the AI reads these to decide when to call). * Parameter definitions. * A URL, HTTP method, and headers for the actual call. * Flags for how arguments are passed at call time. * A type — typically a URL-backed HTTP call. ### Attach and detach On the agent detail page, pick from the shared tool library and attach. The same tool can be attached to many agents. ### Channel summary A quick view of which channels have agents and how many. Useful for spotting gaps — *"Instagram has zero agents"* — before they surface as a service problem. ### Bulk actions Select many agents or many tools and delete them in one go. ## Roles and permissions | Action | Account Owner | Admin | User | Bot | | -------------------------------- | :-----------: | :---: | :--------------------: | :--------------------: | | View agent and tool list | Yes | Yes | Yes | Yes | | Create, edit, or delete an agent | Yes | Yes | No | No | | Create, edit, or delete a tool | Yes | Yes | No | No | | Attach or detach a tool | Yes | Yes | No | No | | Use an agent at runtime | Yes | Yes | Yes (via inbox drafts) | Yes (via bot journeys) | ## Cross-module workflows ### A. AI triage, then human hand-off A guest asks a complex question on WhatsApp. The bot journey hands to an AI Agent step. The AI attempts to answer using its tools. If the guest asks for a human, the AI says so and stops, and the journey hands off to the Sales team. Full trail stays in the conversation. ### B. In-inbox drafts A team member opens a slow-moving email conversation. The AI Assistant panel pulls the Email channel's agent, reads the thread, drafts a reply in your tone. The team member edits and sends. ### C. Smart validation A bot prompt asks *"What dates are you looking at?"* with AI-based validation. The AI accepts *"the long weekend in May"* as a valid answer and proceeds; on *"soon"*, it asks again with a gentler re-prompt. ## Limits a user will run into | Limit | Value | | ------------------ | ----------------------------------------------------------- | | Persona name | 2–255 characters | | Description | Up to 7,000 characters | | System prompt | 10–10,000 characters | | Tools per agent | No hard cap. Practical limit: 5–10. | | Agents per channel | No hard cap. | | Tool timeout | 5 minutes | | AI turn loop cap | 50 tool calls before the AI is asked to give a final answer | ## Errors and FAQ ### Errors you might see | Message | What it means | What to do | | ---------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------- | | *Agent persona name already exists for this channel* | Two agents on the same channel can't share a name. | Rename one. | | *System prompt must be 10–10,000 characters* | The prompt is too short or too long. | Adjust. | | *Invalid tool parameter schema* | The parameters block isn't well-formed. | Fix the schema. | | *Agent not found* | The agent you're editing no longer exists. | Refresh the list. | | *Tool timed out* | Your tool's endpoint took longer than 5 minutes. | Speed up the endpoint or shorten what the tool does. | | *AI kept calling tools without resolving* | The AI hit the safety loop cap. | Tighten the exit conditions in your system prompt. | ### FAQ **Can an AI Agent use a tool attached to a different agent?** Only if you explicitly attach the same tool to the other agent. There's no global attachment. **Can I have multiple agents on one channel?** Yes. Give them distinct persona names. Different bot journeys on the same channel can each pick a different agent. **Where are tool secrets (like API keys) stored?** Inside the tool's headers. Treat tool configuration as sensitive — only admins should edit it. **How does the AI Assistant draft work?** It loads the channel's agent, feeds it the recent conversation, and runs an inference pass. Any tool calls the agent makes run on your behalf. The final reply is the draft; the team member edits and sends. **Does the AI remember past conversations?** Out of the box, no. Each inference sees only the recent messages of the current conversation. If you want the AI to recall past history (like *"this guest stayed with us last summer"*), expose a tool that fetches it. **How do I stop the AI from looping?** Tighten your system prompt with explicit exit conditions — for example, *"End your reply with 'FINISHED' once the guest's question is answered."* You can also lower the loop cap on the individual bot journey step. **Can I roll back an agent change?** Not through the UI today. Keep a copy of the prior system prompt in your notes if you want to revert quickly. ## API A partner API is available for creating AI Agents, managing tools, and handling attachments. Contact your account team for access. ## Changelog * **Apr 2026** — Initial public documentation. ## Related modules and next steps * [Bot Journeys](bot-journeys.md) — the **AI Agent** step and AI-based prompt validation both read from here. * [Home / Unified Inbox](../workspace/home-unified-inbox.md) — AI Assistant drafts use the channel's configured agent. * [Connections](connections.md) — the channels your agents are scoped to.