For AI agents: the complete documentation index is available at https://docs.clickmax.io/en/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/en/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/en/features/messaging/ai-agents.md.
  • English

      • Create an AI agent with your own key

      In Settings → Accounts Hub → My agents — or, from the CRM side, in Contacts & Commercial → CRM settings → My agents, which opens the same list — click New agent, register your provider API key (OpenAI or Anthropic), choose the model, write the persona and test the conversation. The agent starts as a draft; Publish changes creates the first version and sets it Active.

      Want an SDR answering on WhatsApp without building each part? Use Set up AI SDR: see How do I set up the AI SDR from scratch?.

      Role: any workspace member with access to Settings can create agents and register keys.

      Before you start

      • An OpenAI or Anthropic account with an active API key and available credit. The agent's calls are billed by the provider to your account.
      • Clickmax validates the key with the provider before saving it. The key is stored encrypted and never shown again: the screen only displays its last 4 digits.

      Steps

      1. Open Settings and, in the Accounts Hub group of the sidebar, click My agents. Click New agent.
      2. In the Provider step, choose OpenAI or Anthropic, paste the key into API key and click Validate and save key. If the workspace already has a key, use Use a registered key and select it. Click Continue.
      3. In the Model step, open the list and pick a model among those available on your account: Recommended models come first, followed by Other models on your account (models your account cannot access show disabled). The chosen model's description and profile show below the field. Adjust the Temperature.
      4. In the Identity step, choose the Agent photo: it starts with a random face; click another face in the gallery or Upload photo to use your own image (PNG, JPG or WebP, up to 5 MB — it is center-cropped into a circle). Then set the Name and Goal. The goal is only a label shown on the agent card so the team knows what it is for; what the agent does in the conversation goes in the persona. Persona and instructions starts with a generic example; rewrite it as you like or use Back to example.
      5. In Review, check the summary and click Create agent. You land on the agent page. It starts with no escalation rules: create yours in the Escalation tab (see below).
      6. In the Test tab, send messages as if you were the customer. The test uses the same instructions as the AI SDR conversations — persona, escalation rules that are on, and knowledge base — and when the agent decides to check the calendar, create a task or hand off to the team, the action shows up in the chat as Simulated action (with the reason, when there is one) without being executed. The test uses the published version. Each message uses your key with the provider.
      7. When you are happy, click Publish changes. The agent becomes Active and shows its published version. Use the Active switch to pause and resume without losing the configuration.

      Later edits (persona, model, escalation) show as Unpublished changes until you click Publish changes again.

      In the Escalation tab, click Add rule and fill in the Trigger (when to hand off, e.g. "Asks for a discount above 10%") and the Action (what to do, e.g. "Hand off to the sales team with the requested amount"). Both fields are required and take up to 255 characters; an agent takes up to 20 rules. Use each rule's switch to turn it on or off and the trash icon to delete it. While a rule is incomplete, Publish changes stays blocked and the header says why.

      The rules in the Escalation tab (each one shaped as "when X → do Y") apply wherever the agent talks to the contact: when handling conversations as the AI SDR, the rules that are on become part of the instructions it follows to decide when to hand the conversation to a person — and when it does, it records the reason and a summary. They also apply in Ask AI and in the Test tab. With no rules, the agent still hands off when the contact asks for a person or when it does not know the answer. Rules that are off are ignored, and rule changes only take effect after Publish changes. See what the agent does while talking.

      Persona and instructions accepts up to 20,000 characters. On the Configuration tab, the counter below the field shows how much of that limit you have used. Above it, Publish changes is blocked and the warning The instructions are over the 20,000-character limit. Shorten the text to publish. appears. Write the instructions as plain text: the field does not replace variables such as {nome} or {canal}.

      The agent photo — one of Clickmax's default faces or an uploaded photo — shows on the list card, the agent page, API keys and the AI SDR step in automations. To change it, open the agent and click the photo next to its name: pick another face, upload a photo (Upload photo/Replace photo) or use Remove photo to go back to the default face, then click Save photo. The photo saves right away, without Publish changes. The gallery has 32 illustrated people — the same ready-made photos offered when inviting a member and when changing your profile photo. An agent with no uploaded photo and no chosen face automatically gets one of these faces; an agent whose saved face left the gallery now shows that automatic face.

      To remove an agent, open its detail and click Delete. It leaves the list and stops replying; the provider key stays registered and the conversations remain on record.

      Registered keys show under API keys, below the agent list. Remove takes the key out of the workspace; if an active agent still uses it, switch that agent's key first.

      Knowledge sources

      In the Knowledge tab, click Add source and pick the Source type:

      • Document: PDF, TXT, MD, CSV, JSON or HTML up to 20 MB. DOCX and PPTX only on OpenAI.
      • Web page: paste the Address and we read the page text right away.
      • FAQ: Question and Answer pairs you write on screen (Add question to add more; 1 to 200 items).

      The content lives in your provider account (OpenAI or Anthropic), not in Clickmax. The agent checks the sources before answering; if the answer is not in them, it says it will confirm with the team instead of making something up. Limit of 20 sources per agent.

      Each source shows in the list with the status Synced, Syncing or Error (on Error, the reason shows under the name). Sync again appears on web pages (we re-read the address right away, useful when the page changed), on sources marked Syncing, and on FAQs marked Error. A document marked Error must be removed and uploaded again.

      With Anthropic, every message sends all sources to the model (and the provider bills them as input); keep the base lean — up to 10 MB combined. With OpenAI, the files become vectors in a Vector Store in your account and the model retrieves only the relevant passages (up to 8 per message).

      The Where the files live panel, at the top of the tab, shows the provider account (the agent's key), the Vector Store ID (OpenAI only, with a shortcut to the OpenAI dashboard), how many of the 20 sources are in use and the total size (on Anthropic, against the 10 MB cap). Click a source to see the File ID at the provider, the uploaded format and size, the address (web pages) and the questions (FAQs). With several source types, filter the list by type.

      The agent uses its sources everywhere it talks: in the Test tab, when answering as an AI SDR, and when another part of Clickmax asks it for an answer (meeting copilot, automations). In all of them it is told to check the files before talking about product, price, deadline or terms.

      Changing the model doesn't touch the sources. Switching the credential to another provider, or to a key from another account of the same provider, is blocked while there are sources: the files live in the current account. A new key from the same account (key rotation) is accepted.

      Sources do not go through Publish changes: they apply as soon as they show as Synced, even while the agent is a draft.

      Where to follow up

      • My agents: the list shows agents in batches; with many agents, click Load more at the bottom to see the next ones.
      • Logs: every agent conversation, filterable by result, channel and period. View transcript opens the messages; with many conversations, Load more at the bottom of the table brings the next ones. A question with no reply in the transcript means the provider failed on that send (for example, an invalid key or a usage limit).
      • Metrics: conversations, rate resolved by the agent, escalated rate and average duration over the last 30 days.

      If it did not work

      • "The provider rejected the key": the key is wrong, expired or lacks permission. Generate a new one in the provider dashboard and register it again. OpenAI keys start with sk-; Anthropic keys with sk-ant-.
      • "The provider rate-limited this account": your provider account hit its usage limit. Wait a few minutes or raise the limit with the provider.
      • The model I wanted is not listed: the list only shows models your provider account can access. Enable it with the provider and reload the page.
      • "Publish the agent before activating or pausing it": the Active switch only works after the first publish.
      • Cannot remove a key: agents are using that key. Switch their credential before removing it.
      • "This provider does not accept that file type": convert it to PDF or TXT. Anthropic does not read DOCX/PPTX.
      • "We could not read that page. Check the address.": the address must be public (http or https), weigh up to 5 MB and respond within 10 seconds. If you see "The page did not respond. Try again.", the site was slow or is down.
      • "Remove the knowledge sources before switching provider": the files live in the current provider account. Use Remove on each source in the Knowledge tab, switch the credential, then add the sources again.
      • "The new key belongs to another account and can't see the knowledge files": the chosen key is from another provider account. Use a key from the same account, or remove the sources, switch the credential, then add the sources again.