# How it fits together > The whole model in one page — workspaces, agents, knowledge, deployments, channels, versions, and the two ways in. Source: https://docs.amomic.in/concepts/architecture --- Everything in this documentation is an elaboration of a few nouns: a **workspace** holds **agents**; a **deployment** puts an agent on a **channel**; **versions** record what an agent was set to. Read this page once and the rest of the docs stop being a list of features and start being obvious. ## The whole model in one sentence You build one agent, you deploy it onto each channel where customers can reach you, and every one of those channels feeds back into the same inbox, the same customer directory, and the same analytics. ```mock {"component": "PlatformDiagram", "props": {"caption": "One agent, deployed onto channels. Customers arrive on the left; your systems talk to the API on the right."}} ``` ## A workspace A workspace is your organisation. It owns the agents, the knowledge, the channel connections, the conversations, the contacts, the API keys, and the bill. It is also the isolation boundary. Every query the platform runs is filtered by workspace before anything else happens, and there is no mechanism — no sharing setting, no cross-workspace agent, no shared knowledge base — for data to cross it. A WhatsApp number connected to one workspace cannot be connected to another. Two workspaces are two products as far as the data is concerned. Everything else on this page happens *inside* one workspace. [Workspaces and roles](/concepts/workspace) covers who can do what within it. ## An agent is a persona, knowledge, and tools An agent is not a chatbot script and not a flow chart. It is three things bundled together: | Part | What it is | Where you set it | |---|---|---| | **Persona** | Its name, its purpose, its instructions, the language it works in, and how strictly it must stick to your content. | The agent's **Persona** tab | | **Knowledge** | The knowledge bases you have explicitly attached. An agent can only answer from knowledge you attached to it. | The agent's **Knowledge** tab | | **Tools** | The things it can *do* rather than know — open a ticket, send a WhatsApp message, call your API, end a call. | The agent's **Tools** tab | Those three things are channel-neutral. You do not write a WhatsApp agent and a phone agent; you write one agent, and each channel renders it appropriately — the same answer arrives as light markdown in the web widget, as WhatsApp's own bold and italic syntax on WhatsApp, and as plain spoken prose on a call. That is why the model is shaped this way: **you describe the job once**. When your refund window changes from 7 days to 14, you update one knowledge source and every channel is correct. See [Agents](/build/agents), [Knowledge bases](/build/knowledge), and [Tools and actions](/build/tools). ## Saved changes are live; versions are the record Customers are always served the agent's **saved** settings. When you save the persona, flip a tool switch or attach a knowledge base, the next message or call on every channel uses the change. A call already in progress keeps the settings it started with. You never redeploy for an agent change. A **version** is a numbered record of the agent's whole setup at one moment: persona, per-channel personas, attached knowledge and tool settings. You create one with **Publish**. A version never changes once written, which is what makes it useful: - **It is the point you roll back to.** Rolling back to Version 3 restores exactly what Version 3 recorded, on every channel at once. - **It is the history.** You can compare any two versions and see who published each and when. - **It is required once.** An agent must be published before its first deployment. When you have saved changes since the last version, the agent's badge reads `Changes to publish`. Those changes are **already live**; they are just not recorded yet. This shapes how you work: test a change in the agent's **Test** tab right after you save it, publish when you are happy, and roll back if something goes wrong. [Versions](/build/versions) and [When your changes reach customers](/build/agents#when-your-changes-reach-customers) have the details. ## Deploying puts an agent on a channel A **channel** is a kind of touchpoint: web chat, WhatsApp, or voice. A **channel connection** is a specific one you own and have verified — this website's domain, that WhatsApp Business number, this phone number. A **deployment** is the join between them: *this agent, on that connection, with this channel-specific configuration.* ``` agent + channel connection + channel config = deployment (what it says) (where customers (greeting, call reach you) language, domains) ``` The channel config is the part that genuinely differs per channel and has nowhere else to live: the opening line a caller hears, which language the call opens in, whether calls are recorded, which domains the widget may load on, which WhatsApp sender number it answers from. One agent can have many deployments: a website widget, a WhatsApp number, and two phone numbers, all serving the same agent. Each touchpoint is answered by one agent at a time, and each deployment is independent. Disabling the phone deployment does not touch the widget. Behind the scenes a deployment is created, checked, and only then switched on. When a new deployment takes over a connection, for example when you deploy a different agent to the same number, the old one is superseded in the same step, so a number never has two agents. Changing a live deployment's channel settings works the same way: a replacement is checked before it takes over, and if the check fails the old deployment carries on. [Deployments](/build/deployments) covers deploying, editing, disabling and removing. ## Everything converges Whatever channel a customer arrives on, the same three things happen. **One inbox.** Every conversation — a widget chat at 2 a.m., a WhatsApp thread, a phone call transcript — lands in the same inbox with its full transcript, tagged with the channel it came from. You do not check three places. **One customer directory.** When an agent needs to identify someone — to open a ticket, say — it resolves them against your contacts by email, phone, and WhatsApp ID before creating anything new. A returning customer enriches the record that already exists rather than spawning a duplicate. **One set of analytics.** Conversation volume, messages per visitor, channel mix, and voice performance are computed across every deployment of every agent, and can be filtered down to a single touchpoint. [Conversations and contacts](/concepts/conversations) explains the transcript and identity model in detail, including where the identity story is still incomplete. When the agent should stop, a person takes over in [Live support](/console/human-handoff), or the agent opens a [ticket](/console/tickets). ## The two ways in There are exactly two interfaces, and they are split along a deliberate line. ### The console, for humans `console.amomic.in` is where people work: creating agents, writing personas, adding knowledge, configuring tools, publishing versions, connecting channels, deploying, reading the inbox, taking live handoffs, working tickets, running campaigns, managing the team and the bill. [Using the console](/console/overview) is the map. These are decisions that want review, permissions, and a visible history — which is exactly what a UI provides and an API does not. ### The API, for your systems `https://services.amomic.in/api/v1` is where the things you call ten thousand times a day live: sending a message, placing a call, reading a conversation, opening a ticket, upserting a contact. It is a small, flat REST surface, server-side only, authenticated with a workspace-scoped key. Besides messages and calls it creates and runs campaigns and reads call outcomes. Start at [Your first API call](/start/first-api-call) or the [API overview](/api/overview). ### Which one does what | Task | Console | API | |---|---|---| | Create or edit an agent | Yes | — | | Add or refresh knowledge | Yes | — | | Configure tools and the tool policy | Yes | — | | Publish a version | Yes | — | | Deploy, pause, or replace a deployment | Yes | — | | Connect a WhatsApp number, request a phone number | Yes | — | | Create or revoke an API key | Yes (admins) | — | | Send a WhatsApp message | The agent does it in conversation | [`POST /messages`](/api/messages) | | Place an outbound AI call | From a ticket, or as a campaign call batch | [`POST /calls`](/api/calls) | | Read a conversation transcript | Inbox | [`GET /conversations`](/api/conversations) | | Open a support ticket | Tickets | [`POST /tickets`](/api/tickets) | | Create or match a contact | Contacts | [`POST /contacts`](/api/contacts) | | Run a campaign | Campaigns | [`POST /campaigns`](/api/campaigns) | | Be told when something happens | The notification bell | [Webhooks](/webhooks/overview) | The API has no agent-building routes. Configuration that changes behaviour for every future customer belongs where a person can review it; traffic belongs on the API. ::: warning The API is not callable from a browser `/api/v1` sends no CORS headers at all. API keys are workspace-scoped, so a key in front-end JavaScript is a leaked workspace. For anything in the page, use the [hosted widget](/channels/web-chat) or [custom-UI client](/channels/web-chat-custom-ui); both use least-privilege visitor sessions and no API key. ::: ## Following one customer through Priya opens your site at 11 p.m. and asks about a delayed order. 1. The **widget** loads on an allowed domain and finds the **deployment** attached to it. That deployment names the **agent**. 2. The agent's attached **knowledge bases** decide what it may search. Her question is searched by meaning and by keyword, and the best passages are put in front of the model. 3. The agent answers from those passages. Because it cannot resolve the delay itself, it reaches for a **tool** — `create_support_ticket` — which first resolves Priya against your **contacts** by email, then opens a ticket and returns its public reference, `AM-4F91C2E0`. 4. The whole exchange is a **conversation** in your **inbox**, with the ticket linked to it. 5. Your backend hears about it on the `ticket.created` **webhook**, and your ops tool calls [`POST /messages`](/api/messages) the next morning to send her the resolution on WhatsApp — the same person, matched on the same phone number. A handful of nouns, one customer, no duplicated configuration anywhere. ## What is deliberately not in the model Naming the gaps is faster than discovering them. - **There is one agent, with optional channel persona overrides.** Phone, WhatsApp, and web chat may replace the default purpose or instructions for that medium, while knowledge, tools, versions, and deployment controls remain part of the same agent. Build two agents when the job or authority genuinely differs. - **There is no per-deployment knowledge override.** Knowledge is attached to the agent; every deployment of that agent sees the same knowledge. - **There is no cross-workspace sharing.** Agents and knowledge bases do not travel between workspaces. - **Versions are never edited.** Not by you, not by support. Publish a new one, or roll back to an old one. - **Channel connections are not created by the API.** Numbers and domains are provisioned and verified in the console. ## Where to go next ::: cards ::: card Workspaces and roles [Who can do what](/concepts/workspace), how invitations work, and why API keys are workspace-wide. ::: ::: card Build an agent [Agents](/build/agents) — the fields that matter, and how to write a purpose that produces a good agent. ::: ::: card Teach it something [Knowledge bases](/build/knowledge) — the five source types, how retrieval works, and how to get good answers out of it. ::: ::: card Put it somewhere [Deployments](/build/deployments) — deploying to each channel, editing, disabling and removing. ::: ::: card Look up a word [Glossary](/concepts/glossary) — every term in these docs, defined in two sentences with a link. ::: ::: card Drive it from code [Your first API call](/start/first-api-call) — a working request in about a minute. ::: :::