# Agents > Create an agent, find your way around the agent studio, write a purpose and instructions that work, attach knowledge, and archive or restore an agent. Source: https://docs.amomic.in/build/agents --- An agent is the thing your customers talk to. You write it once: a name, a purpose, instructions, the knowledge it may use and the tools it may call. Every channel you deploy it to (web chat, WhatsApp, a phone number) then runs that same agent in the way that suits the channel. This page covers creating an agent, the agent studio, the persona fields and what each one does, attaching knowledge, and archiving. Publishing and rollback have their own page, [Versions](/build/versions). Putting an agent on a channel is covered in [Deployments](/build/deployments). **Who can do this:** workspace **owners** and **admins**. A **member** who opens **Agents** sees *Administrator access is required.* with a **Retry** button. Members still see the conversations agents have, in the [Inbox](/concepts/conversations). ![The Agents page with five agent cards showing their publication badges, channel chips and knowledge counts, and the Archived agents section expanded](https://docs.amomic.in/screens/agents/list.light.webp) *Each card shows whether the agent is published, where it is live, and how much of its knowledge is ready.* ## The Agents page **Agents** in the sidebar lists every agent in the workspace, three to a row on a wide screen. Each card shows: | Part of the card | What it tells you | |---|---| | Name and badge | `Not published`, `Published`, or `Changes to publish`. See [Publication badges](#publication-badges). | | Purpose | The first two lines of the agent's purpose, or *Purpose not configured*. | | Channel chips | One chip per channel the agent is deployed on, such as `Web · Live`, `WhatsApp · Live` or `Phone · Paused`. Deployments on the same channel in the same state share one chip with a count, like `Web · Live (2)`. Hover a chip to see which site or number it stands for. | | No chips | *Published, not deployed yet* or *Not deployed yet*. | | `{ready}/{total} KB ready` | How many of the attached knowledge bases are ready to answer. | | **Deploy** | Opens the deploy menu. It appears only once the agent is published. | | **…** menu | **Open studio**, **Test**, and **Archive**. | A chip turns red (`Error`) when the channel reports a problem, amber (`Paused`) when you have disabled that deployment, and green (`Live`) otherwise. When the workspace has no agents yet, the page shows *Create your first AI agent* with a **New agent** button. ## Create an agent ::: steps ::: step Open the form Go to **Agents** and choose **New agent**. ::: ::: step Fill in the four fields Only **Agent name** and **Purpose** are required. The table below explains each field. ::: ::: step Create it Choose **Create agent**. The agent is created as an unpublished draft, and the console opens it in the studio. No website, number or channel is touched until you deploy it. ::: ::: ![The Create an agent form with the Agent name, Purpose, Additional instructions and Business knowledge fields filled in](https://docs.amomic.in/screens/agents/new.light.webp) | Field | Required | Limit | What it does | |---|---|---|---| | **Agent name** | Yes | 60 characters | What your team calls it. Customers see it on the web widget and hear it in the default phone greeting. | | **Purpose** | Yes | 500 characters | The outcome this agent owns. The console's hint says it plainly: describe the outcome, not the channel where it will run. | | **Additional instructions** | No | 40,000 characters | Tone, style and specific rules. You can refine them later. | | **Business knowledge** | Yes (defaults to the first option) | — | **Require a ready knowledge base before publishing**, or **No business knowledge — safe general behavior only**. | A workspace can hold at most 20 agents. At that point the console refuses with *Agent limit reached for this organization.* Most workspaces need far fewer. One agent serving web chat, WhatsApp and a phone number is the normal shape. Build a second agent when the *job* is different, not because you have a second channel. Plan limits are listed in [Limits and plans](/operate/limits). ::: note The name is said out loud A new phone deployment greets callers with *Hello! You're speaking with {agent name}. How can I help you today?* until you write your own opening line. `Support Agent v2 (test)` is a name your callers will hear. Use something you would say on the phone. ::: ### Business knowledge: require it or not This setting decides whether the agent may be published with nothing to look up. | Option on the create form | On the Persona tab | Effect | |---|---|---| | **Require a ready knowledge base before publishing** | **Require ready business knowledge** | Publishing is blocked until at least one attached knowledge base is ready. | | **No business knowledge — safe general behavior only** | **Explicitly no business knowledge** | You state that this agent answers with no company content. The readiness check stops asking for knowledge. | Keep the first option unless the agent really has nothing to look up, for example an agent whose only job is to open a ticket. The moment an agent should answer questions about *your* business, requiring knowledge stops it from being published with nothing behind it. ## The agent studio Opening an agent takes you to its studio at `/agents/{agentId}`. The header shows the agent's name, its badge (`Published`, `Unpublished changes` or `Not published`), its purpose and its channel chips. On the right are **Test**, **Deploy** (once published) and a **…** menu with **Archive agent**. Below the header are seven tabs: | Tab | What you do there | |---|---| | **Overview** | See the readiness checks and publish. See [Testing & publishing](/build/testing#readiness-checks). | | **Persona** | Edit the name, language, purpose, instructions, grounding and knowledge requirement, and give a channel its own persona. | | **Knowledge** | Attach and detach knowledge bases. | | **Tools** | Turn built-in tools on or off and decide whether the agent may take actions. See [Tools & actions](/build/tools). | | **Test** | Have a test conversation and record verdicts. See [Testing & publishing](/build/testing). | | **Deployments** | Put the agent on web chat, WhatsApp or a phone number, and manage those deployments. See [Deployments](/build/deployments). | | **Versions** | See the version history, compare, publish and roll back. See [Versions](/build/versions). | ## When your changes reach customers Read this before you edit an agent that is already live. **Saved changes are live straight away.** Chat, WhatsApp and phone calls all run on the agent's saved settings. So when you choose **Save draft** on the Persona tab, flip a switch on the Tools tab, or attach or detach a knowledge base, the next message or call uses the change. You do not need to publish or redeploy first. A call already in progress keeps the settings it started with. Publishing does something different: it **records** the current setup as a numbered version. That version is the point you can compare against and roll back to. It is also required once, before an agent's first deployment. The console says the same thing on the **Versions** tab: *Saved edits since Version 4. They're already live, but not yet recorded as a version.* What this means in practice: - **Test risky changes before you save them.** The **Test** tab runs the agent's current saved settings, so the safe order is: make a small change, save it, test it straight away, and roll back if it is wrong. For a larger rewrite, consider building it in a second agent that is not deployed, testing it there, and then copying the text across. - **Publish after a change you are happy with.** It gives you a named point to come back to. - **If a saved change goes wrong, roll back.** [Roll back](/build/versions#roll-back-to-an-earlier-version) restores an earlier version on every channel at once. To take the agent off one channel straight away instead, **Disable** that deployment. See [Deployments](/build/deployments#disable-enable-and-remove). ## Publication badges The badge answers one question: has everything you saved been recorded as a version? | On the Agents page | In the studio header | Meaning | |---|---|---| | `Not published` | `Not published` | The agent has never been published. It cannot be deployed yet. | | `Published` | `Published` | The saved settings match the current version. | | `Changes to publish` | `Unpublished changes` | You have saved changes since the current version. **Those changes are already live**; they are not yet recorded as a version. | `Changes to publish` is normal for an agent someone is improving. It does not mean customers are still getting the old behaviour. Publish when you want the change recorded. ## Persona and behaviour The **Persona** tab holds everything that decides how the agent talks. Change the fields, then choose **Save draft**. The console confirms with *Agent draft saved.* and the change is live from the next message. | Field | Options or limit | What it does | |---|---|---| | **Agent name** | 60 characters | Same as on the create form. | | **Language** | **English**, **Hindi**, **Multilingual** | The language the agent writes and speaks in. **Multilingual** lets it follow the customer. | | **Purpose** | 500 characters | The outcome the agent owns. | | **Instructions** | 40,000 characters | How it goes about the job. The counter stops accepting text at the limit. | | **Grounding policy** | **Strictly grounded**, **Balanced** | How tightly it must stay inside your knowledge. | | **Knowledge requirement** | **Require ready business knowledge**, **Explicitly no business knowledge** | Same setting as **Business knowledge** on the create form. | **Agent name** and **Purpose** cannot be empty. **Save draft** stays disabled until both have text. ### Grounding policy **Strictly grounded** is the default and the right default. - **Strictly grounded**: the agent answers from passages it retrieved and says it does not know when your content does not cover the question. It stays conversational, but it will not fill a gap with something plausible. - **Balanced**: the agent leans on your content but may reason more generally around it. Switch to **Balanced** only when you have watched a strictly grounded agent on the **Test** tab refuse questions you were happy for it to answer. If answers feel stiff, the usual fix is more knowledge, not a looser policy. ### Language versus call language The persona **Language** is not the same as a phone deployment's call language. | Setting | Where it lives | What it controls | |---|---|---| | Persona **Language** | The agent | The language the agent thinks and writes in on every channel | | **Call language** and **Greet callers in** | The phone deployment, per number | What a caller may speak, and which language the call opens in | A number can open in Hindi while the agent's language is **Multilingual**. See [Languages](/channels/voice-languages). ## Per-channel persona Under **Per-channel persona**, **Phone**, **WhatsApp** and **Web chat** can each have their own purpose, their own instructions, or both. Each panel shows a badge: `Uses the default` or `Own persona`. ![The Per-channel persona card: Phone uses the default, WhatsApp has its own instructions](https://docs.amomic.in/screens/agents/persona-channels.light.webp) *WhatsApp has its own instructions; Phone and Web chat carry on with the default.* - Leave both fields empty and the channel uses the default. - Fill in only **Purpose on this channel** to change the job on that channel but keep the default instructions. - Fill in only **Instructions on this channel** to keep the job but change how it is done. - **Use default** clears both fields so the channel goes back to the default. Save to apply it. Nothing is copied. Changing the default later still changes every channel that uses it. Channel personas are for the medium, not for a different job. A phone answer should be spoken one short thought at a time with no formatting. A WhatsApp reply should be short because the customer may answer hours later. A web chat answer can carry links and lists. If the *job* or the knowledge the agent may use is different, build a second agent. A channel persona is not a security boundary. The **Test** tab runs the agent as web chat, so it uses the **Web chat** persona. To try a phone or WhatsApp persona, use the real channel. ## Write a purpose that works The purpose is 500 characters and does more work than anything else you type. It is not a description for your colleagues. It is the sentence the agent uses, on every turn, to decide whether a question is its job. A vague purpose does not make a vague agent. It makes a *confident* agent with no boundaries: one that answers billing questions it knows nothing about, because nothing told it billing was not its job. ### The shape that works A good purpose answers three questions, in order: 1. **What does it resolve?** Name the outcomes. 2. **From what?** Name the source it may draw on. 3. **What does it hand off?** Name the line it does not cross. Three clauses, usually under 300 characters. ### Before and after **Support agent, before:** > Help customers. None of the three questions is answered. This agent will attempt anything, including pricing it has never seen and complaints it cannot resolve. Nothing tells it to hand off, so it will not. **Support agent, after:** > Answer warranty, AMC, installation and troubleshooting questions about our appliances from our manuals and service policy. Book technician visits on request. Hand off refunds, damaged-on-delivery cases and anything about a pending payment. Now the agent knows what is in scope, what its authority is, and what belongs to someone else. When a customer asks about a failed payment, it opens a ticket instead of inventing a refund rule. --- **Receptionist, before:** > Answer the phone for our clinic. This describes the channel, not the job. "Answer the phone" is what the deployment does. The agent still does not know what a good call looks like. **Receptionist, after:** > Tell callers our timings, location, and which doctors are available on which days, from the clinic information sheet. Take a callback request for anything about test results or fees. The outcomes are named, the source is named, and the escape route is a concrete action rather than an apology. --- **Order desk, before:** > Handle customer queries about orders and be helpful and friendly. Our company was founded in 2019 and we sell home appliances across India with a focus on customer satisfaction. This is the most common failure, and it looks like effort. Half the field is company background, which belongs in a knowledge base where it can be searched and updated. The useful half still says only "handle queries". **Order desk, after:** > Resolve order-status, delivery-date and return-eligibility questions using the order lookup tool and our returns policy. Confirm the order number before quoting anything. Escalate damaged-on-arrival cases to a ticket. ### Rules of thumb - **Name the outcomes, not the audience.** "Support our B2B customers" is not an instruction. "Answer contract, invoice and onboarding questions" is. - **Describe the job, not the channel.** The same agent runs on the widget, WhatsApp and the phone. "Reply to WhatsApp messages" is wrong on two of the three. - **Always include the hand-off clause.** Without a stated boundary, every question is in scope. One sentence ("hand off anything about X") is what makes the agent open a [ticket](/build/tools#create-support-tickets) instead of guessing. - **Keep facts out of the purpose.** Prices, timings and policies belong in a [knowledge base](/build/knowledge), where a refresh updates them without anyone editing the agent. - **Read it back as an instruction to a new hire on day one.** If a capable person could not act on it, neither can the agent. ## Instructions Instructions cover *how*, once the purpose has settled *what*. The field holds 40,000 characters, but length is not the goal. Most agents work best with well under a page. Every line is weighed on every turn, and ten rules that contradict each other are worse than four that do not. Good instructions look like this: ```text Be warm and brief — two or three sentences unless the customer asks for detail. Ask for the model number before troubleshooting. Ask one clarifying question at a time, never a list. Quote warranty periods exactly as the service policy states them; never round them. Never invent a price, a date or a policy detail. ``` Bad instructions read like a second purpose, or a knowledge base in disguise ("Our office hours are 9 to 6…"). If a line contains a fact that could change, it is in the wrong place. ::: danger Never put credentials in instructions The console says so under the field: no provider credentials, access tokens or customer secrets. Instructions are recorded in every published version and anyone who can open the agent can read them. Credentials for your own tools go in the source's headers, where they are encrypted and never shown again. See [Tools & actions](/build/tools#a-live-read-tool). ::: ## Attach knowledge The **Knowledge** tab shows which knowledge bases this agent answers from. ![The Knowledge tab of an agent with two attached knowledge bases marked ready, and the Attach existing knowledge picker below](https://docs.amomic.in/screens/agents/knowledge-tab.light.webp) ::: steps ::: step Choose a knowledge base Under **Attach existing knowledge**, open **Choose a knowledge base**. Each option shows the knowledge base's name and its chunk count. Knowledge bases already attached are not listed. ::: ::: step Attach it Choose **Attach**. The knowledge base appears under **Attached knowledge**, and the agent can use it from the next message. ::: ::: To build a new knowledge base, choose **Manage knowledge**, which opens the **Knowledge** page. The same knowledge base can teach several agents. Each attached row shows the knowledge base's name (a link to it), the content revision the agent is reading (`Revision …`, or `pending` before the first one), a state badge and **Detach**. | Badge | Meaning | |---|---| | `ready` | The knowledge base has at least one source or some indexed content. Counts toward the readiness check. | | `empty` | Attached, but the knowledge base has no sources yet. | | `degraded` or `unavailable` | The knowledge base is marked as failing. It does not count toward the readiness check. | `ready` is about the knowledge base having sources, not about each source succeeding. A website source whose crawl failed still makes the knowledge base `ready`. Open the knowledge base and check each source's state before you rely on it. See [Source status](/build/knowledge#source-status). When a knowledge base refreshes its content, the agent moves to the new revision on its own. You do not need to re-attach it. ::: warning Attaching and detaching are live Attach and detach take effect immediately on every channel the agent is deployed to. The console's toast says *Publish a new version when ready*. That publish only records the change; it does not hold it back. Detaching the only ready knowledge base from an agent that requires knowledge also blocks its next publish. ::: How knowledge bases are built and kept fresh is covered in [Knowledge bases](/build/knowledge). ## Archive and restore an agent Archiving takes an agent out of daily work without deleting anything. Its conversations, calls and published version history are kept, and an archived agent cannot be deployed. ::: steps ::: step Disable its deployments first Archiving is refused while the agent is live anywhere. Open the **Deployments** tab and **Disable** each live deployment. See [Deployments](/build/deployments#disable-enable-and-remove). ::: ::: step Archive it Choose **Archive** from the card's **…** menu, or **Archive agent** from the studio's **…** menu. Confirm with **Archive agent**. ::: ::: ![The Archive Service Desk dialog warning that the agent is still live on 1 deployment](https://docs.amomic.in/screens/agents/archive-dialog.light.webp) If the agent is still live, the dialog says so: *This agent is still live on 1 deployment. Pause them from the Deployments tab first — archiving is blocked while anything is live.* Confirming anyway fails with *Pause or replace active deployments before archiving this agent.* The Deployments tab calls this action **Disable**. To bring an agent back, open **Archived agents** at the bottom of the Agents page and choose **Restore** on its row. A restored agent returns as `Published` if it had been published, or `Not published` if not. Its deployments stay disabled until you enable them. ## Troubleshooting | What you see | Why | What to do | |---|---|---| | *Administrator access is required.* on the Agents page | You are a member. Agents are managed by owners and admins. | Ask an owner or admin to change your role in **Settings**. | | **Save draft** is greyed out | **Agent name** or **Purpose** is empty. | Fill in both. | | *Agent changed since it was loaded.* | Someone else saved this agent after you opened it. | Reload the page, then make your change again. | | *Agent limit reached for this organization.* | The workspace already has 20 agents. | Archive agents you no longer use. | | No **Deploy** button | The agent has never been published. | Publish it from **Overview** or **Versions**. See [Versions](/build/versions). | | A change you saved is not showing on a channel | The change is live, but the channel has its own override. | Check **Per-channel persona** for that channel, and the deployment's own settings (for example a phone number's opening line). | | The agent answers from the wrong knowledge | A knowledge base is attached that should not be, or the right one is not `ready`. | Check the **Knowledge** tab. | ## Where to go next ::: cards ::: card Record and roll back [Versions](/build/versions): publishing, comparing two versions, and rolling back. ::: ::: card Give it something to know [Knowledge bases](/build/knowledge): building the content an agent answers from. ::: ::: card Let it do things [Tools & actions](/build/tools): tickets, WhatsApp messages, bookings and your own API. ::: ::: card Find the bad answers first [Testing & publishing](/build/testing): what to test and the readiness checks. ::: :::