ClearMakes Agents documentation

An agent is an AI assistant you build for one job — answering your customers, helping your team, handling a specific workflow. It answers from three things you give it: sources (your documents and website), actions (Gmail, Slack, HubSpot and any MCP server), and instructions (how you tell it to act). It is told not to make up an answer it has no grounds for, though AI answers can still be wrong.

You build and run agents from the bar across the top of the app:

Open an agent and its own tabs appear under its name: Summary, Instructions, Sources, Actions, Style, Go live, Chats and Settings, plus a Try it button. The rest of this page follows those.

From nothing to an agent on your site:

1. Create an agent. On Agents, choose New agent. Start blank, from a personal-assistant or business template, or from the template catalog. Give it a name and a main goal — one sentence on what it is for.
2. Give it sources. On Sources, upload documents or add your website. It reads, indexes and starts answering from them.
3. Add actions (optional). On Actions, link Gmail, Slack or any tool so the agent can act, not just answer.
4. Test it. Try it is the real thing — same answers, knowledge and tools a visitor would get.
5. Go live. On Go live, copy the one-line website snippet, a share link, or an embed — or talk to it from your own code with the API below.

Creating an agent is one decision per screen. You pick a starting point — Blank, Personal assistant, Business agent (choose an industry and a use case), or Browse starters — and the app suggests a name and a main goal you can edit before it is created. Nothing is final; every choice here is editable afterwards under Behavior.

An agent's Summary is its home: its avatar, name and main goal, an Active / Paused switch, recent activity, and short prompts for whatever it still needs — add knowledge, connect apps, customize, test.

Behavior is how the agent speaks and what it is for. Three pieces combine into how it acts (a set of safety and grounding rules is always added on top and is not shown, because they are not yours to change):

A saved voice lets you reuse a persona you have written across several agents rather than retyping it.

Knowledge is what the agent answers from. On the Sources tab you add it two ways:

How hard the agent looks, and how well it reads long or interlinked documents, is tuned under Settings.

Beyond an agent's own files there is a shared company layer — the Company Brain — that indexes a Google Drive folder for the whole workspace and keeps it in step automatically, checking often through the day and doing a full pass nightly. You connect Drive once, signing in through a dedicated sync account; from then on it is hands-off.

Each agent gets two controls over the shared knowledge, on its Knowledge tab:

On Actions you give an agent the ability to do things — read a calendar, look up a customer, post to a channel — not just answer from documents. Connections belong to one agent; connecting an app for one does not connect it for another.

In a conversation the agent decides for itself when a tool is needed, runs it alongside searching your knowledge, and answers from whichever has the information. You see a small “Using…” note while it does.

Style is how the agent looks to a visitor, with a live preview beside the controls:

• A display name (which can differ from the agent's internal name), an avatar, a welcome message, and up to three suggested questions. Leave the questions blank and the agent proposes its own from what it knows.
• An accent colour from a palette, a custom colour, or pulled from your own website; an advanced panel sets the rest of the colours.
• Whether to show the “Powered by ClearMakes” badge (removable on paid plans).

An agent's Settings hold the switches most people set once:

Advanced also shows the agent's ID (for the widget and API) and Delete agent, which removes the agent, its knowledge and its conversations for good.

Go live gives four ways to put an agent in front of people. All of them read the agent's live settings, so you copy once and later edits to appearance or behavior carry through on their own:

When a message comes in, the agent works through it rather than guessing:

1. It works out what is being asked — a quick question, something that needs digging through your knowledge, something a connected app can do, or a question about data in a spreadsheet.
2. It searches your knowledge and runs any needed tools at the same time, and answers from whichever holds the information. The chat does not show which document an answer came from.
3. When the question calls for it and you have allowed it, the answer can include a chart, a generated image, or an analysis of an uploaded spreadsheet.

Try it runs this exact path, so what you see there is what a visitor gets.

An agent can be read by another AI assistant — so someone in Claude or ChatGPT can ask it about your knowledge. On the Knowledge tab, under Use this agent from Claude or ChatGPT, create an API key scoped to exactly what that one agent can read.

• You get a personal link to paste into Claude or ChatGPT as a connector — no install. It exposes reading tools only: search the knowledge, fetch a document, list the areas it covers.
• The key can also be used as a bearer token against the REST knowledge endpoints.
• The secret is shown once. You can rename a key, give it an expiry, rotate its secret, or delete it. A key reads only what its agent reads — never more.

POST /api/v1/chats/with-message

Creates the conversation and answers the first message in one call. The response is an SSE stream, not JSON — the first event carries the chat_id you need in order to continue.

curl -N -X POST https://agents.clearmakes.com/api/v1/chats/with-message \
  -H "Content-Type: application/json" \
  -d '{"chatbot_id": "YOUR_AGENT_ID", "content": "What are your opening hours?"}'

-N matters: without it curl buffers the response and the stream looks like it arrives all at once at the end.

POST /api/v1/chats/{chat_id}/messages/stream

Sends the next message in an existing conversation. Use the chat_id from the chat_created event. Earlier turns are already in the agent's context — send only the new message.

curl -N -X POST https://agents.clearmakes.com/api/v1/chats/CHAT_ID/messages/stream \
  -H "Content-Type: application/json" \
  -d '{"content": "And on weekends?"}'

Every line is data: followed by one JSON object with a type. Read token and done; the rest are there if you want to show progress, and can be ignored safely. Treat an unknown type as something to skip — more may be added.

data: {"type": "chat_created", "chat_id": "4cff03c1-..."}
data: {"type": "status", "step": "classifying_intent"}
data: {"type": "sources", "sources": [{"title": "handbook.md"}]}
data: {"type": "token", "content": "We are open "}
data: {"type": "token", "content": "9 to 5, Monday to Friday."}
data: {"type": "done", "message_id": "8f1c...", "chat_title": "Opening hours"}

Reading the stream in JavaScript:

const res = await fetch("https://agents.clearmakes.com/api/v1/chats/with-message", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ chatbot_id: AGENT_ID, content: "Hello" }),
})

const reader = res.body.getReader()
const decoder = new TextDecoder()
let buffer = ""
let answer = ""

while (true) {
  const { value, done } = await reader.read()
  if (done) break
  buffer += decoder.decode(value, { stream: true })

  // Events are newline-delimited; the last piece may be incomplete.
  const lines = buffer.split("\n")
  buffer = lines.pop() ?? ""

  for (const line of lines) {
    if (!line.startsWith("data: ")) continue
    const event = JSON.parse(line.slice(6))
    if (event.type === "token") answer += event.content
    if (event.type === "done") return answer
    if (event.type === "error") throw new Error(event.message)
  }
}

GET /api/v1/chatbots/{agent_id}/widget-config

The agent's public presentation — display name, greeting, avatar, colours and which features are switched on. Use it to make your own interface match what you set under Appearance. It returns only what a visitor is meant to see; instructions, knowledge and credentials are never included.

curl https://agents.clearmakes.com/api/v1/chatbots/YOUR_AGENT_ID/widget-config

Failures before the stream starts are ordinary JSON with a detail. Once the stream has started, a failure arrives as an error event instead, and no done follows it.

If you want the ready-made chat bubble rather than your own interface, you do not need this API at all. Paste the snippet from your agent's Publish page:

<script
  src="https://agents.clearmakes.com/agents.js"
  data-chatbot-id="YOUR_AGENT_ID"
  defer
></script>

The widget handles the streaming, the appearance settings and the conversation history for you.

Creating agents, uploading knowledge, reading conversations and managing connected apps all need a signed-in session and are done in the dashboard, not through this public API. A conversation started here is an anonymous visitor and never reaches anyone's personal connected accounts.

There is a free plan and three paid ones, one price worldwide, with two months free on yearly billing. What each includes:

Connect your apps covers connected apps, custom REST and MCP tools, Google Drive sync, and the developer API keys. Precise answers unlocks the higher-quality models, your own AI key, and self-hosted models.

A conversation is counted once when it starts. A precise conversation counts as five. One conversation can have up to 20 AI replies on Free and 50 on paid plans. You are warned at 80% of your monthly allowance; agents keep answering a little past the limit, then new conversations wait until the next month or an upgrade. Visitors only ever see “this assistant is currently unavailable”, never anything about billing.

Your Workspace settings hold your team and your plan. Invite people by generating a single-use link that lasts seven days and sending it yourself — there is no email step — choosing whether they join as an Admin or a Member. You can change a member's role, remove someone (their agents and conversations stay), or revoke an invite that has not been used. The number of seats follows your plan.

Roles also set how much of the shared company knowledge someone's agents can reach, so a member cannot build an agent that reads documents above their own level.

• Documents and websites you add are read to answer questions and are never shared between workspaces.
• Connected apps are used only by the agent you connected them to, on behalf of the person who connected them. A visitor talking to your public agent never touches anyone's personal account.
• Keys and tokens you enter for a custom tool or your own AI provider are encrypted and never shown again.
• Deleting an agent, a document or a key is immediate and cannot be undone. Copies left in our backups are removed as the backups roll over, within 30 days.