Agents

What are agents?

An agent is a persistent digital colleague: its own identity (name, avatar, description), its own knowledge file (AGENTS.md), its own reference files and its own spend cap. You can address an agent via chat (interactive runs) or let it run autonomously (on a schedule or in reaction to a webhook).

Unlike the earlier assistants, an agent stays “awake” between sessions:

• It learns by editing its own AGENTS.md
• It can run multiple parallel threads
• It has its own run history (what did it do when, what did it cost)
• It can get work done without your presence, within clear guardrails

Note: Agents are included in the Business and Max license. Existing assistants were automatically migrated to agents; configuration, sharing settings and files are preserved.

Agent home base

You reach your agents via the sidebar → Agents. For each selected agent, you see a three-column view:

• Center: The currently selected thread or run, with the chat input below
• Right (context panel): Status, spend cap usage, trigger block (schedule or webhook URL), enabled integrations, full run history, followed by this agent’s chats that someone shared with you (“Shared with me”) or that you shared yourself (“Shared by me”)
• Left: Navigation between Chat, Projects, Agents, Search and Settings

Via the “Configure agent” button in the context panel, you open the full-page configuration with all tabs (see below).

Creating an agent

Click “New agent” in the Agents tab. A chat with the Agent Builder opens and clarifies the open points with you:

1. Role: what should the agent do, how does it recognize good work?
2. Name: what should it be called?
3. Trigger: chat-only, schedule, webhook endpoint, or a combination?
4. Integrations: which of your tools should the agent be allowed to access?
5. Sharing: who should be allowed to use the agent, and in which role (use, edit, administer)?

You can also start right away: “Create an agent that checks my emails every hour”, the AI only asks for the gaps. All details end up in the agent’s AGENTS.md and can be freely edited there later. If the agent needs scripts, such as a guard script for its schedule, the AI writes and tests them right in this chat. The same applies when you change an existing agent from a regular chat.

Configuration in detail

Via “Configure agent” you reach six tabs: General, Instructions, File attachments, Tools & accounts, Trigger and AI model. Sharing, duplicating and the danger zone live inside the General tab.

Which tabs you see depends on your role: if you are only allowed to use the agent, you see General, Instructions and AI model. File attachments and Tools & accounts come with the right to edit, and Trigger only with the right to administer.

Tab: General

Name, description, avatar and the “Agent active” switch for manual pausing or resuming. For the avatar you upload an image or have the AI generate one; without an image the agent shows its initials in a color you can pick. For agents that were paused automatically (spend cap reached, three consecutive failures), the reason is shown here.

The switch is operated by the owner, everyone with the “Administer agent” role and workspace administrators. If you are only allowed to edit the agent, you see the status including the reason but cannot flip it: taking an agent out of service or arming it again affects everyone who uses it.

Further down in the same tab you find the sharing settings (see Sharing: who may do what?), the duplicate button and the danger zone for deleting the agent for good. The danger zone only appears if you may administer the agent. The owner is always shown here, even if you are only allowed to use the agent.

Tab: Instructions

This is where the agent’s AGENTS.md lives, its natural-language knowledge and behavior file. You can edit it directly (inline markdown editor) or ask the agent in chat to add something: “Discuss a change” opens a new chat with the agent, where it asks you what should change about it. Both paths write to the same file. Saving happens automatically when you leave the editor.

Via “Show version history” you see all previous versions with timestamp, a diff comparison between two versions of your choice and a restore button. Version history is kept automatically for 90 days.

Below the editor you choose the always-loaded skills. Their full content goes to the AI together with the AGENTS.md on every run, including runs started by a schedule or a webhook. Without this setting the agent only reads a skill when it decides on its own that the skill fits. Load the procedure here that the agent should carry out the same way every time, at most five skills. Every always-loaded skill makes every run a little more expensive, so only pick what the agent really needs every time. You can choose from your workspace skills that you can see yourself, that is your own and those shared with you. Built-in skills such as PDF or Excel are read by the agent anyway when it needs them. Integrations such as Microsoft 365 or Lexware Office are not loaded permanently; you enable them in the Tools & accounts tab. If an always-loaded skill is later deleted or cannot be reached by the agent, it stays in the list with a notice, and the agent reports it during its run.

Tip: The AGENTS.md is natural language, not programming, not pseudocode. Describe logic in prose: “When a new email arrives from a known customer, summarize it and suggest a reply.”

Tab: File attachments

Reference files that the agent “has in mind” on every run (max. 25 files). Useful for tone-of-voice documents, style guides, templates, price lists. More details in the section Files & knowledge per agent.

Tab: Tools & accounts

This tab holds the accounts the agent works with, each with the provider, the address of the account and the person it belongs to. You pick the account and its tools come along; there is nothing to tick twice. The list is grouped by owner, with your own accounts at the top. Accounts shared with you to use only are listed below without a switch, naming the person who can share them with you with “Use and pass on”. Every account appears exactly once, even when it was connected by more than one route. This holds for every integration alike, Notion or Asana included: the list shows the account you signed in with, with its address. If you hold several at one integration, switch on the one the agent should work with; with several switched on, it takes your default account.

A sentence above the list tells you where the agent stands: if no account is switched on, it works with the accounts of whoever is using it. If at least one is switched on, it works only with those. In full under Accounts: which accounts an agent works with.

Further down, under Web search, you decide when the agent may search the internet: Never, Only in chat or In chat and autonomously. With “Only in chat” it searches while someone is writing to it, but not in runs by schedule, webhook or “Start a run now”. In chat it also only searches for people who may search the internet themselves. If an administrator has switched web search off for the agent’s owner, the choice is fixed at “Never”.

Under Projects you assign the agent to projects. It is the same assignment as in the project’s access list. You can add it and change role or mode if you may edit the agent and administer the project; removing it takes one of the two. Per project you choose the role Read only or Can edit and, as with web search, Only in chat or In chat and autonomously. With “Only in chat” the agent works in the project with the project rights of the person currently writing to it, at most with its own role, and not at all in automatic runs. With “In chat and autonomously” it has its fixed role, for everyone who may use it, including people without access to the project themselves, and also by schedule, webhook or “Start a run now”. Before you switch, a dialog shows you who reaches the project’s contents that way. New assignments start with “Read only” and “Only in chat”.

In the project the agent can do what the AI can do in a project chat: read the context and files and search the project files, with “Can edit” also keep the context up to date and add or remove files. If it is assigned to exactly one project, it works there on its own. With several, it takes the project you name in the chat or in the schedule’s task, for example “Check the BeetleSee project against the project plan”. That way an agent with “Can edit” and “In chat and autonomously” compares the project context with an app every morning by schedule. Its chats stay with the agent and do not appear in the project. More under Agents in a project.

This tab is operated by anyone who may edit the agent, recipients with the “Edit agent” role included. You can only switch on accounts you hold yourself and accounts, company accounts included, shared with you with “Use and pass on”: an account shared with you to use only cannot be put into an agent. Whoever contributes an account is then named next to it in the list.

Tab: Trigger

Configure schedule and/or webhook. The last run shows how it ended, and for a failure the reason along with its error ID. Details in the Triggers section further below.

At the top of the tab you can read who pays for the runs a trigger starts: they come out of the workspace credit, not out of your personal quota. Once that credit is empty the hint turns into a warning, and administrators find the way to top it up right there. More on this under What counts as the agent’s usage?.

This tab is visible only to the owner, to everyone with the “Administer agent” role and to workspace administrators. The reason: a trigger lets the agent work unattended with the accounts on its account list, which is a decision about other people’s accounts and not merely a change to content.

Tab: AI model

• Base model: the AI model the agent uses by default
• Allowed models: optional whitelist (for example only economical models for frequently running schedules)
• Monthly spend cap: safety net that prevents an agent from consuming more quota than intended. The default is €10/month; you can raise or lower the value per agent at any time
• Early warning at high usage: email to owner/admin at, for example, 80 % usage

Details: Spend cap per agent.

Sharing: who may do what?

In the General tab you decide who sees the agent and what they may do with it. Sharing is a list with one row per person or group, and a role dropdown on the right of each row. If nobody is in the list, only you have access.

Use “Add a group or person …” to open the picker. It shows all existing groups and people right away, grouped by kind, so you pick instead of guessing a name. Typing filters the list when you are after someone specific. Entries that already have access stay visible, greyed out and marked “Already granted”. With a lot of entries the list shows only the first ones per section and tells you to narrow down the search.

If everyone in the workspace should have access, pick the entry for all members from the list (it appears as “Alle Mitglieder”). This is the system group that covers every member of your workspace, so you do not have to add each person individually.

You can also say it in the chat while the assistant builds or changes the agent, for example “share it with everyone” or “Max (max@company.com) may administer it”. Name people by their e-mail address and groups by their name; if the assistant cannot find someone in your workspace, it asks instead of guessing. Whoever is added that way may use the agent unless you name another role. Everyone else on the list stays as they are; only those you explicitly name are removed. Sharing from the chat works only for people who may also share the agent in this tab.

Each row gets exactly one of three roles:

Role	What it allows
Use agent	Can call and run the agent in chat, but cannot change anything about it.
Edit agent	Can additionally change the agent’s instructions, file attachments, tools and accounts.
Administer agent	Can additionally change the sharing, transfer ownership, set up triggers, pause or resume the agent and delete it.

Existing shares keep working exactly as before, there is nothing to redo. Two things do change:

• Deleting is no longer part of editing. People an agent was shared with can still edit it, but they can no longer delete it. Deleting is now part of Administer agent.
• Workspace administrators no longer edit along automatically. On someone else’s agent they get no editing rights by default. If they need to change something, they add themselves to the list as an editor, and that entry is visible to everyone in the list.

Administration, on the other hand, stays fully with workspace administrators, including on agents they do not own: change the sharing, transfer ownership, set up automatic triggers, pause or resume the agent and delete it.

That does not widen what they get to see: the agent list and the chat show only what belongs to them or has been shared with them. A colleague’s personal agent does not appear there, not even when the AI is asked in conversation which agents you have.

The first time you share a previously personal agent, a dialog asks whether it should take your accounts along. The preset is without, and then everyone works with their own accounts in chat. See Accounts: which accounts an agent works with.

If the agent is assigned to a project with “In chat and autonomously”, everyone you share it with reaches that project’s contents through it, see Agents in a project.

Above the access list you see the agent’s owner, with name and email address. It is always visible, even if you are only allowed to use the agent, so you immediately know whom to ask. An agent keeps its owner permanently, including after you share it with the entire workspace.

Changing the owner: the owner, everyone with the “Administer agent” role and workspace administrators can hand the agent over to someone else via the “Change owner” button. The dialog lists the people in your workspace right away: pick the person and you are done, they now hold all owner rights. You only need to type if you want to narrow the list down.

Whoever hands the agent over only has access afterwards if they are on the access list, with the role entered there. That also applies if you created the agent yourself. If the previous owner should keep working on it, the new owner adds them, for example with “Edit agent”. Typical cases: you change roles and hand your agent over, or an administrator assigns a heavily used agent to a new responsible person.

Deleting an agent

At the very bottom of the General tab sits the danger zone, where you delete an agent permanently. The section appears only for the owner, for people with the “Administer agent” role and for workspace administrators. Anyone who may edit the agent does not see it.

Hiding an agent someone shared with you

If someone shares an agent you do not need, you can hide it for yourself. The command lives in the agent list in the left sidebar, in the “Shared with me” section: hover over the agent and an eye icon appears on the right with the “Hide for me” command. Your own agents (the “My agents” section) do not offer it; you can only hide what somebody else shared with you.

What happens then:

• The agent disappears from your lists and is no longer offered to the assistant in the chat
• Nothing changes for the owner or for anyone else, and the owner is not notified
• The agent stays hidden even if it is shared with you again later
• A “Hidden” section appears at the bottom of that same sidebar, and you can bring the agent back from there at any time

So hiding only tidies up your own view, it is not a change to the sharing. If you want the access gone entirely, talk to the owner.

Threads: multiple conversations per agent

With an agent you run any number of parallel threads, like in Teams or Slack with a colleague. Each thread has an automatically generated title and its own history. The agent knows the context per thread, but its knowledge file (AGENTS.md) and identity apply across threads.

• Shared agents: Threads are private per user, if you and a colleague use the same agent, you each only see your own threads.
• Autonomous runs (schedule, webhook) are excluded; they are visible to all users with access, because they have no human counterpart. Anyone with access to the agent can share the transcript of such a run like any other chat (via a link or directly with specific people), see Sharing a chat.

Triggers: when does the agent run?

An agent runs on four possible triggers:

Chat trigger

You write to the agent, the classic case. The agent additionally receives your personal context (name, language, time zone, Du-/Sie-Form).

Which accounts it uses depends on its account list: if nothing is switched on there, it works with your accounts, for example in your mailbox. If at least one account is switched on, it works only with those, even when you are the one asking. Details under Accounts: which accounts an agent works with.

Schedule

The agent runs regularly, for example hourly, every Monday at 09:00 or on the 1st of each month. One schedule per agent is possible, in IANA time zones (for example Europe/Berlin); daylight saving transitions are handled correctly.

Optionally, a guard script can be placed in front of it, a small pre-filter that checks, without an AI call, whether there is any work at all. Examples: “Have new emails come in since the last run?”, “Has the website changed?”, “Are there open tickets in the CRM?”

If the guard finds nothing, no AI run starts, no costs, no empty email summary. The run then shows up in the run history as “Nothing to do”. If it finds something, it hands the result directly to the agent and the agent starts with the right context.

If a task runs by fixed rules every time, such as filing receipts according to a fixed pattern, the guard script can also do it entirely on its own. Then no AI run starts either, and the run history shows “Done” with the script’s short message, for example “12 receipts booked, 2 filed for review”. Such runs have no conversation, because the agent was never woken.

If the agent works with data from another system, such as a weekly report, the guard script fetches that data as well. For this the agent builds a fixed fetch script with you in the chat and tries it on real data before the schedule starts. That way the data is fetched the same way every time, and you have seen the result once before the first report goes out. The same goes for everything after that which runs the same way on every run, such as removing duplicate entries, filtering by period, counting or putting together a list from a fixed pattern: a script the agent calls does that too. The AI itself only takes on what needs judgment, such as writing an accompanying text. Older agents that still do such steps themselves on every run suggest the switch as soon as you change them or report a wrong result. They tell you which steps are affected and why the agent will run more reliably afterwards, and try the new script with you on real data.

The guard script works with the same accounts as the agent itself. Every switched-on account is available to it as an environment variable, and the file /home/user/.credentials lists which account is behind which variable. If your agent has several accounts with the same provider, for example two Microsoft 365 mailboxes, your script has to name the one it means via that variable: without it the platform cannot guess and stops.

Some of the built-in 9brains tools are available to the guard script as well, with the same permissions as the agent: searching data sources, listing the files of a data source, walking through folders on a connected file server, searching the 9brains help and fetching web pages. A guard can for example check whether new files have arrived in the receipts inbox on the file server. If the AI may change files in a data source, the script can also create folders, move files and delete files there, without first asking the way the AI does in the chat. It cannot open or store files this way; the agent does that in the run.

In a knowledge base, on the other hand, the script can store files itself, replace them with a new version and delete them, without any AI rephrasing or sorting anything. That is how an agent mirrors a OneDrive folder into a knowledge base at regular intervals, for example, see Example 4. The agent needs the same permission you need to edit files directly in the “Files” tab: Approve access on a knowledge base of your company. The scripts the agent runs in a run or in the chat can do the same.

This way you save measurable quota on hourly or more frequent triggers and prevent the agent from reporting on unchanged data.

Webhook trigger

On request, each agent gets a unique HTTPS URL that external systems (CRM, monitoring, your own applications) can call to trigger a run. The valid URL is shown in the Triggers tab, ready to copy. It has the form https://chat.9brains.de/api/v1/agents/{agent-id}/webhook, but never assemble it by hand; copy it from the interface.

Configurable:

• Authentication: Bearer token (default), HMAC signature with timestamp protection, or open (only for test setups)
• Response mode: Fire-and-forget (HTTP 202 immediately, run executes in the background) or Synchronous with timeout (the calling system waits for the result, 30 seconds by default, 120 at most; if the run fails, it gets an error code in the errorCode field instead of a result, see Error codes in synchronous mode)
• Rate limit: default 60 requests/minute, adjustable
• Guard script: like the schedule, optional

Tokens and secrets are shown once in plain text and can be rotated at any time.

Error codes in synchronous mode

If a run does not go through, the response has status set to failed (or skipped) and errorCode set to one of these values:

errorCode	Meaning
credit_exhausted	The workspace’s credit is used up.
trial_daily_limit	The daily limit of the trial is reached.
agent_budget_exhausted	The agent’s monthly spend cap has been reached.
model_not_allowed	The agent’s AI model is not allowed for it.
model_unavailable	The AI model could not be reached.
context_too_long	The task and its data were too large for the AI model.
timeout	The run took too long.
sandbox_unavailable	The working environment was unavailable due to a problem at 9brains.
script_failed	The guard script reported an error.
agent_reported_failure	The agent stopped the run itself.
owner_missing	The agent no longer has an owner.
run_already_active	Another run of this agent was still in progress (status is then skipped).
not_started	The run could not start due to a problem at 9brains.
unknown	An unexpected error.

What exactly happened is shown on the run in the run history, along with its error ID.

What the agent receives from the request

Call the URL via POST and send everything the agent needs to know in the body. This is usually JSON, but plain text, XML or CSV work just as well. The content goes into the agent’s context unchanged: up to 1 MB in full, larger content truncated and additionally stored as a file in its inbox. Images, PDFs and other binary files never enter the context; they are always stored as a file.

The body is therefore how you pass parameters to the agent. Describe in AGENTS.md which fields you send and what the agent should do with them, so it can process them reliably.

The agent also sees the HTTP method used and a few request headers (Content-Type, User-Agent, X-Source). A guard script additionally receives the complete request including all headers.

What does not arrive: Parameters appended to the URL such as ?customer=Smith are discarded; the agent never sees them. A GET call therefore delivers no content at all. Use POST with a body.

The agent always treats webhook content as information, not as an instruction, see the Security & data sovereignty section below.

Manual trigger

In the agent home base there is a button “Start a run now”, which starts the agent as if it had been triggered by schedule or webhook. Including guard script. Useful for tests.

Caution: Manual test runs have the same side effects as real runs; if the agent normally sends emails, it will also do so during the test.

What an agent only does in chat

When an agent runs autonomously, by schedule, webhook or “Start a run now”, it builds nothing new: no skill and no other agent. That is your decision and only happens when you ask for it in chat. An agent may adjust itself in an autonomous run, for example move its own schedule or note what it learned in its AGENTS.md. It does not change other agents, and on itself it leaves sharing, spend cap, accounts and webhook untouched.

Accounts: which accounts an agent works with

An agent only has an account list of its own once somebody has given it accounts. The list lives in the Tools & accounts tab. Per account there are exactly two possibilities: it is switched on because a person deliberately handed it over, or it is not on the list at all. Half states, such as an entry still waiting for a confirmation, no longer arise.

A separate “autonomous approval” is gone as well. A switched-on account is the approval, for chat and for automatic runs alike.

While the agent is yours alone

There is nothing to set up. An agent you have never shared follows your accounts. If you store a new account, it is available to the agent without you doing anything. In runs started by a schedule or a webhook it only takes your own accounts and accounts, company accounts included, shared with you with “Use and pass on”. An account shared with you to use only is used only while you operate the agent in chat.

On sharing you are asked: with your accounts or without

The first time you share a previously personal agent, a dialog asks whether it should take your accounts along. It shows you which accounts that would be:

• Without my accounts (the preset): no account is entered, the agent starts with no account list. In chat everyone then works with their own accounts, and in automatic runs the agent has none.
• With my accounts: your own accounts and those shared with you with “Use and pass on” go onto the list. Everyone who uses the agent afterwards works under your name and with your data, for example in your mailbox.

Whichever you choose, the list never grows on its own afterwards: if you store a new account later, the shared agent does not pick it up automatically. You can change the list at any time in the Tools & accounts tab.

With no account switched on, the agent follows the person in front of it

An empty list acts like no list at all in chat: the agent works with the accounts of whoever is operating it. Ask it about your email and it looks into your mailbox; when your colleague asks, it looks into hers. That is the right state for agents everyone is meant to use for their own work, a writing assistant for your own mailbox for instance.

For automatic runs on a schedule or via webhook this never applies. There is nobody sitting in front of it whose accounts could count, so the agent gets none. An agent that is meant to work without you therefore needs at least one account switched on.

One switched-on account is enough, and only the list counts

As soon as a single account is switched on, the agent works exclusively with it, for everyone who uses it, in chat just as in automatic runs. It is then like a colleague with a keyring of their own: ask it about your email and it looks into the mailbox on its list, not into yours.

That is also why you are asked when switching one on. Whoever hands over an account of their own hands it to everyone who may use the agent.

Contributing an account

You can only contribute accounts you hold yourself and accounts, company accounts included, shared with you with “Use and pass on”. An account shared with you to use only, or somebody else’s, cannot be put into an agent, not even by an administrator. If the owner takes the role back to “Use” or stops sharing, the agent loses the account at once. There are exactly two ways, and both ask you first:

• Agent → Tools & accounts: you switch an account on.
• Settings → Integrations: you pick an agent with “Add agent” under “Agents using this account” on an account.

Both show the same dialog. It names who is allowed to use this agent (people and groups by name, not merely a count) and states that the agent also works without you: in other people’s chats and in automatic runs. If a schedule is already running for the agent, it says so explicitly. The agent only gets the account once you agree.

Your agreement is stored: who agreed, when, for which agent, for which account, and who was allowed to use the agent at that moment. In an audit it is the answer to why an agent was allowed into your mailbox.

Switching an account back off needs no agreement, since nothing changes hands. Anyone who may administer the agent can also take somebody else’s account off the list, but never switch one on. Only the person who holds the account, or someone it is shared with with “Use and pass on”, can bring it back, which is why a warning appears before you do it.

If you hand over an account that is on an agent’s list, it stays there and then belongs to the person you handed it to. If it is their own agent, it keeps working with it. On every other agent the account rests until they confirm it there; they do that at their account under Settings → Integrations, where they see who uses the agent.

This cannot be done from chat. If you ask the assistant to give a shared agent an account, it refuses and points you to the Tools & accounts tab. An agreement has to come from a person who has seen the audience.

Several accounts of the same provider

This is expressly allowed. Every account appears as its own row with its address, so you can tell two Google accounts apart. If more than one account fits a task, the agent never silently picks one; it names the one it used.

The same account appears exactly once. Previously one sign-in could sit in the list twice, once as an integration and once as a connection, with two switches of which turning off one did nothing.

Note for older agents: accounts an agent did not receive through a deliberate decision, but automatically, are no longer used. In chat you will not notice, because it follows the person operating it. An agent with a schedule, however, needs at least one account switched on: check the Tools & accounts tab and switch on the account it should work with. Old entries nobody ever confirmed are marked there as not in use.

What the agent finds in SharePoint and on the file server

For data sources with a permission check the same rule applies as for accounts: an agent only ever finds the files one particular human is allowed to see. In chat that is the person operating it. If a Microsoft account is on its list, it is that account’s permissions, in chat as well as in automatic runs. When it runs on a schedule or through a webhook with no Microsoft account switched on, it is its owner’s permissions.

This way an agent finds at night what it finds during the day, without anybody having to switch off the permission check on the data source.

Notifications without a mailbox of its own

If an agent only needs to let people know, for example send a report to you or to colleagues, it needs no mailbox for that. It sends the mail from a 9brains address, a line at the end names it, and replies go to the person it runs for: to you in the chat, to its owner in automatic runs. The same recipients apply as in the chat: yourself, members of your workspace, addresses on your company domain and 9brains support, see Send emails from the chat. A single run sends at most 50 mails. For mails to customers or partners, switch on a mailbox as one of its accounts. Once one is switched on, it sends every mail from there, to any recipient.

Files & knowledge per agent

Each agent brings three kinds of content with it that persist across all runs:

• Knowledge file AGENTS.md: Role, instructions and everything the agent has learned about its task. You and the agent can edit it; every change is versioned (90 days history).
• Reference files: Documents that the agent “has in mind” on every run (tone-of-voice, style guides, templates, price lists). Max. 25 files per agent, up to 100 MB each. Managed in the File attachments tab.
• Run results: Artifacts that the agent produces during a run (reports, exports, email drafts). Stored separately per run and linked in the run history.

Encryption: All content is stored client-side encrypted (client-side encryption with per-tenant keys); even platform operators cannot read the plain text. The same encryption also applies to chat attachments.

Run history

In the right context panel you see all runs of the agent, chat runs, scheduled runs, webhook runs and manual test runs, in chronological order with grouping by Today / Yesterday / Last 7 days / Older.

Each entry shows a label indicating what triggered the run: “You · 09:30”, “Schedule · 08:00”, “Webhook · 11:17”. Clicking into a run shows the complete trace including all tool calls, the result and the costs. If a run failed, you see the reason in plain words there, with the message of the system involved below it; use “Copy details” to paste both, including the error ID, into a support request. Runs that could not even start, for example because the credit was used up, are listed in the run history too.

Administrators can jump from each individual tool call back to the triggering run; the answer to “Why did the agent send this email to the customer yesterday at 03:00?” is therefore always one click away.

You can also just ask. The agent itself and any normal chat look up the run history when needed, for example for “Why did this morning’s run fail?” or “What did the agent send yesterday?”. The same rules apply as in the panel: other people’s chats with the agent stay hidden.

Stopping a running run

While a run is still going, its page carries a “Stop run” button. It really does stop the agent, including one that was started in the background by a schedule or a webhook. The run is recorded as cancelled, and the costs incurred up to that point appear in the history as usual. The button is visible to anyone who may edit the agent.

Whatever the agent had already done before the stop stays done: an email that went out does not come back. A stopped run does not count as a failure, so it does not move the agent closer to the automatic pause after repeated errors.

When the agent stops a run itself

Nobody watches runs that start from a schedule, a webhook or “Run now”. If something does not look right to the agent, for example because data is missing, a script reports an error or a check from its instructions does not hold, it stops the run instead of carrying on with a doubtful result: it then sends, saves or changes nothing, whether its job is an email, an entry in another system or a file. The run shows up as failed in the run history with the agent’s reason, and you as the owner get an email with that reason. If a guard script crashes or takes longer than 15 minutes, the agent starts instead and sees the error. It fixes technical faults on its own, for example when a connected system has renamed a field. It does not change what gets filtered, booked or sent, and whatever it changed in the script is stated in its answer in the run. If it cannot fix the fault that way, it stops the run and you get the email. If the guard script explicitly stops the run itself, the agent does not start and the email arrives right away. After three failed runs in a row the agent pauses automatically, whether they were started by a schedule, a webhook or “Run now”, and you get the pause email instead. If a run fails because of a disruption on the 9brains side, for example because the environment for running code does not start right then or the AI model cannot be reached, you get no email and the run does not count towards the pause. The next scheduled run simply tries again.

Spend cap per agent

So that an agent, especially one running autonomously, never quietly runs away, every agent has its own monthly spend cap as a safety net. When it is reached, the agent automatically pauses and you are notified by email. That way you always know the maximum you spend per month before anyone intervenes.

The default is €10/month, which is comfortable for most use cases (inbox check, SEO watch, occasional chat). You can adjust the value per agent at any time, upwards if your agent should do more, downwards if you want to lock things down even tighter. Administrators can override the value for every agent in the workspace.

In addition, there are:

• Early warning at high usage: email to owner and admin at, for example, 80 % of autonomous usage
• Allowed models: whitelist per agent (for example only economical models), to exclude premium models for frequently running schedules
• Auto-pause after three consecutive failures: prevents a configuration-related error from quietly consuming quota

What counts as the agent’s usage?

The agent sidebar and the admin overview show the autonomous usage: schedule, webhook and runs started via “Run now”, including the sub-agents they spawn. Chat is not part of that figure.

The split goes down to the individual message. If you open a thread a scheduled run created and keep writing in it yourself, the autonomous part stays with the agent and what you wrote counts as your own usage. Whoever types pays for what they typed, no matter how the thread came about.

The spend cap works on the same figure, that is, on autonomous usage only. It is the emergency brake against an agent spinning up on its own at night with nobody watching. What you type in the chat therefore does not stall your agent: that usage runs against your own quota, and the workspace pool brakes independently on top.

For an agent used only in chat, the sidebar hides the status and usage card. The figure would sit at €0.00 permanently, and pausing such an agent does nothing, because a pause only blocks schedule and webhook runs. The card appears as soon as you set up a schedule or webhook, and stays visible for the rest of the month once autonomous usage has occurred.

Where usage is billed depends on what happened, not on who owns the agent:

• Autonomous runs are paid out of the workspace’s credit
• What you type in the chat counts towards your own quota, in whichever agent you typed it

Once the credit is empty, no autonomous run starts any more; you can still chat. You do not have to wait for a run to fail to notice: as soon as the credit is used up, the agent reads “No credit” instead of “Active” in the agent list, on its landing page and in the sidebar, and “Run now” is disabled. A manually started run is an autonomous run too and would be refused the same way.

The agent deliberately stays switched on. As soon as somebody tops up the credit, it resumes on its schedule by itself; nobody has to switch it back on.

During the trial there is no credit yet. Autonomous runs count against the agent owner’s daily limit there, just like their chats. Once the daily limit is reached, the agent reads “Daily limit reached”, no autonomous run starts any more, and it carries on by itself the next day. A run that has already started is finished.

More on the quota system: Budget & quota.

Admin view of all agents

Administrators see under Settings → Usage analytics → Agents an overview of all agents in the workspace, personal or shared, with owner, autonomous usage, spend cap, utilization, top model, number of autonomous runs and status. For each agent, three actions are available there:

• Edit spend cap & models as an admin override (independent of the owner)
• Pause / Resume for immediate stop or reactivation
• Delete including stopping all triggers, invalidating the webhook URL and cleaning up agent content

Detailed description of the columns and actions: Usage analytics, agent overview (admin).

Security & data sovereignty

The existing data protection guarantees also apply to agents, see Data protection & data sovereignty. In addition:

• Client-side encryption: Knowledge file, reference files and run results are stored encrypted; even platform operators cannot read the plain text.
• Marking of untrusted content: Content from incoming webhooks, email bodies or web scrapes is explicitly marked in the AI context as information (not as instruction). This lowers the risk that hidden commands in such content are executed by the agent; complete protection against prompt injection is not possible according to the current state of the art, so the rule applies: treat all integrations with care and regularly review which accounts your shared agents carry in their list.
• Isolated code execution: Guard scripts and other code tools run in a sandboxed environment that can only reach approved targets on the internet.
• Complete audit trail: every tool call by an agent is linked to the triggering run. Administrators can jump back from every action to the trigger and payload.

Four concrete examples

To make the concept more tangible, here are four realistic agents as they are set up in practice. You can adopt them as a template and say in chat “Create an agent like this example, but with …”.

Example 1: Daily briefing

An agent that prepares your daily briefing every morning, the way a personal assistant at the desk would prepare it.

Configuration:

• Trigger: schedule, weekdays 06:30 Europe/Berlin
• Guard script: “Is today a weekday and not in the stored vacation calendar?”, if no, no AI run
• Integrations: Microsoft 365 (mail + calendar), data warehouse connection (Databricks or PostgreSQL via On-Premises Connector), web research

Workflow of each run:

1. Review inbox: Reads unread emails since the last briefing, classifies them as “answer today”, “can wait”, “for information only” and drafts reply suggestions for the top 3 urgent emails in the owner’s tone (from AGENTS.md).
2. Prepare meetings: Lists all of today’s calendar appointments with participants and location. Per meeting, a preparation note from your knowledge base (previous customer notes, recent email exchange, open tickets).
3. Company KPIs: Pulls the current status from your data warehouse, for example revenue yesterday vs. previous day and the same weekday of the previous week, new leads, closed deals, critical open tickets. Notable deviations are briefly contextualized. The connection can run directly via the Databricks integration or, for on-premises data warehouses (PostgreSQL, MS SQL and others), via the On-Premises Connector.
4. Market radar: Researches via the platform’s web tools current news on the topics stored in AGENTS.md (industry, competitors, trend topics). Delivers the top 3 as a two-sentence summary with source and a brief assessment “What does this mean for us?”.
5. Delivery in two ways at once:
   • Email to the owner: Compact overview for quick scanning on the way to the office
   • Report in 9brains: Detailed version with all details and source links, stored in a personal knowledge base “Daily briefings” for later reading

What the agent learns over time: It keeps its AGENTS.md up to date itself. Which email senders you mark as important, which KPIs you regularly comment on, which news you dismiss as “not relevant”, all that goes into its instructions and makes the next briefing more precise.

Example 2: Ticket triage via webhook

An agent that decides on incoming system alerts whether a ticket needs to be created and informs the right person.

Configuration:

• Trigger: webhook (Bearer token auth, Fire-and-forget response mode)
• Integrations: Atlassian (Jira), Microsoft 365 (mail)

Workflow of a run:

1. An external monitoring system (e.g. Grafana, status page tool) calls the agent webhook URL with the alert payload.
2. The agent checks in Jira whether an open ticket already exists for this alert (search by component, error text, service).
3. If a ticket exists: Comments the existing ticket with the new incident and a correlation note “Similar symptom, possible link with ticket X”.
4. If no ticket exists: Creates a new Jira ticket, with a structured description, severity suggestion, suspected component and the latest relevant log excerpts from the alert.
5. Sends the responsible team lead a short note via M365 mail with the ticket link and its own assessment “Looks like X, can wait” or “Please look at this today, critical path”.

Why this helps in practice: First-level triage otherwise takes 15 to 30 minutes daily and is often done inconsistently. The agent does it immediately, always in the same scheme, and the team lead only gets the curated cases on their desk.

Example 3: Competitor watch

An agent that monitors the most important web pages of your top competitors weekly and only writes the real changes to the knowledge base.

Configuration:

• Trigger: schedule, every Monday 09:00 Europe/Berlin
• Guard script: “Have the stored web pages changed substantively since the last run?”, if no, no AI run and no email
• Integrations: web tools of the platform (page crawl), knowledge management, Microsoft 365 (mail)

Workflow of each run:

1. Fetch pages: Retrieves the five competitor web pages stored in AGENTS.md (product page, pricing, newsroom, careers page, About page) as structured text.
2. Diff to previous week: Compares with the state of the last indexing, stored in a shared knowledge base “Competitors”.
3. Assessment: Ignores cosmetic changes (date stamps, cookie banners) and only writes out the substantively relevant changes, grouped by competitor. Per change, a two-sentence assessment: “What is new, why might this be relevant for us?”.
4. Knowledge base update: Creates a new entry “Competitor watch CW XX”, with diff summary and links to the respective pages.
5. Email to management: Compact weekly overview with the top changes and a single recommendation “What we should react to this week”.

Why this helps in practice: Nobody clicks reliably through 25 competitor pages every week. The agent does it consistently, sorts out the noise and delivers an actionable recommendation. The guard script ensures there are no empty “Nothing new” emails.

Example 4: Mirroring a OneDrive folder into a knowledge base automatically

An agent that copies the documents you share with partners in a OneDrive folder into a knowledge base every hour. That knowledge base is published as a public chat, where your partners ask about prices, delivery terms or data sheets.

Configuration:

• Trigger: schedule, hourly
• Guard script: does the whole comparison itself, no AI run starts
• Integrations: Microsoft 365 (OneDrive), plus a knowledge base of your company on which the agent has Approve access

Flow of each run:

1. Read the folder: The script fetches the files from the OneDrive folder “Shared externally”.
2. Compare: It compares them with the files in its folder of the knowledge base. It skips unchanged files, stores new ones, replaces changed ones with the new version, and deletes from the knowledge base whatever is no longer in the OneDrive folder. It leaves subfolders in there alone, including files someone put there by hand. If no file at all comes back from OneDrive, for example because fetching failed, it deletes nothing and reports the error.
3. Report: The run history shows “Done” with a line such as “2 new, 1 replaced, 1 deleted, 14 unchanged”. Whatever it could not take over is listed with the reason, for example a file over 3.9 MB or two files that would get the same name in the knowledge base (“Preisliste Händler.pdf” and “Preisliste-Haendler.pdf”).

About a minute later the public chat answers from the new state. The files land in the knowledge base’s attachments folder, ideally in a subfolder of their own, so the comparison only touches its own files. 9brains writes their names in a form that works in every link: “Preisliste Händler.pdf” becomes “Preisliste-Haendler.pdf”. Names in other writing systems, such as Chinese or Cyrillic, also get a short code appended so they do not overwrite each other. The same file types as in the “Files” tab are possible, from a script up to just under 4 MB per file. Every change appears in the knowledge base’s history with the agent as author. For text files such as Markdown or CSV, you can also restore an older version under “Versions” in the “Files” tab.

Why this helps in practice: Your team maintains the partner documents where it works anyway, and the chat is still always up to date. Nobody has to upload files by hand, and since no AI is involved, a run costs next to nothing.

Troubleshooting

What to do when an agent does not run as expected.

Agent aborts a run with an error message

Three common causes, check in this order:

• Agent spend cap reached: In the AI model tab you see usage and cap. If usage is close to or over the limit, raise the cap or wait until the 1st of the following month. Background under Which brake kicks in when?.
• Workspace credit used up: Autonomous runs are paid out of the credit. Once it is empty, no autonomous run starts any more, even if the license quotas still have headroom. An administrator can top up credit under Billing.
• Auto-pause after three consecutive failures: If three autonomous runs in a row ended with an error, the platform automatically pauses the agent to protect quota. Look at the last three runs in the run history, fix the cause (often a changed API response from an external tool) and reactivate the agent in the General tab.

Schedule does not start at the expected time

1. Check time zone: Schedules run in the configured IANA time zone (default Europe/Berlin), not in UTC. Summer and winter time are handled correctly.
2. Activity status: In the General tab, “Agent active” must be set. For paused agents (manually or via auto-pause), no trigger fires.
3. Credit: If the agent reads “No credit” instead of “Active”, the workspace credit is used up. The schedule stays in place, but no run starts until an administrator tops the credit up.
4. Guard script: If a guard script is configured and found nothing on the last run, no AI run executes; this is intentionally not an error state. In the run history, the case appears with the hint “Guard with no hits”.

Webhook trigger responds with 401 or 403

• Bearer token: The token is shown once in plain text and can be rotated at any time in the Triggers tab. Format: Authorization: Bearer <token> without quotation marks.
• HMAC signature: If enabled, the signature must be computed over the exact body payload and the timestamp header must be within the five-minute window.
• Rate limit: Default value is 60 requests per minute. On 429 responses, adjust the value in the Triggers tab.

Frequently asked questions

What is the difference between an agent, a knowledge base or a skill?

In short: An agent is someone who takes on tasks. A knowledge base is knowledge that the AI accesses. A skill is a capability that the agent uses. A detailed distinction including decision guidance can be found under Knowledge & context, what do I use for what?.

What goes into the AGENTS.md and what into a skill?

The AGENTS.md holds what only applies to this agent: its role, when it runs, whom it reports to and the decisions that belong to exactly this job, such as a supplier that must never appear in the report. A skill holds how a kind of task is done: the procedure, fixed scripts, known pitfalls and the check at the end. The rule of thumb: if a second agent or a normal chat would need the same thing, it is a skill. Load such a skill permanently in the Instructions tab and it is part of every run.

Can multiple users edit the same agent?

Yes, if you give them the “Edit agent” role. With it they change the instructions (AGENTS.md), tools, spend cap and file attachments. You can give that role to individual people, to whole groups, or to all your colleagues at once through the “Alle Mitglieder” entry for all members. Whoever only has “Use agent” can use the agent but change nothing about it.

Whoever created the agent and later handed it over to someone else only edits it with this role from then on.

Five things are reserved for the owner, everyone with the “Administer agent” role and the workspace administrators:

• Changing the sharing (who is in the list, and with which role)
• Setting up triggers (schedule and webhook), because that makes the agent run unattended with the accounts on its list
• Pausing or resuming the agent, because that affects everyone who uses it
• Changing the owner
• Deleting the agent

So workspace administrators have those five options on agents they do not own as well. That does not make them editors automatically, though; for editing they put themselves into the sharing list, visibly to everyone.

The agent’s account list, by contrast, belongs to editing: anyone who may edit the agent maintains it in the Tools & accounts tab. What each person can switch on there is limited to the accounts they hold themselves and accounts, company accounts included, shared with them with “Use and pass on”; an account shared to use only cannot be put into an agent. Anyone who may administer the agent can take somebody else’s account out, but never switch one on.

Can I duplicate an agent?

Yes. When duplicating, configuration, AGENTS.md and reference files are taken over. Not taken over are trigger configurations, the account list, the project assignments and the run history. The clone starts as a manual, unshared agent and therefore follows your own accounts again at first.

How many agents can I create?

There is no hard upper limit. What the agent consumes autonomously is paid out of the workspace’s credit and is additionally capped by its monthly spend cap. What you type in the chat runs against your own quota.

Multiple schedules on one agent?

In this version: no. One schedule per agent is possible. For multiple independent schedules, you create multiple agents; AGENTS.md can easily be shared via duplication.

Can agents call other agents?

Currently: no. Each agent runs independently. Multi-agent orchestration is on the roadmap.

Which email providers can agents use?

Currently Microsoft 365 as a ready integration. With it, an agent can read, reply to and send emails. Which mailbox depends on its account list: if a mailbox is on the list, it uses that one, in chat just as in automatic runs. If none is, it works in the mailbox of whoever is asking it in chat, and not at all in automatic runs.

A native Gmail or IMAP integration is not currently available. If you want to connect another provider, you can build your own MCP skill that talks to the provider’s API. For a native connection of additional email providers, please contact your 9brains representative; we will take demand into roadmap prioritization.

Can agents access internal or on-premises systems?

Yes, via the On-Premises Connector. It establishes an encrypted WireGuard tunnel into your company network. In combination with a suitable integration or skill, an agent can then, for example, query an internal PostgreSQL database, talk to a locally operated Odoo, SAP or Microsoft Dynamics or work against internal HTTP APIs. The connection is outbound only; your network remains unreachable from the outside.

Internal file servers, NAS systems and SMB shares can additionally be connected as a searchable data source, including automatic indexing. An agent then finds those files just like documents from OneDrive or SharePoint. Optionally the Windows file permissions are carried over, so each person only sees the files they are entitled to on the drive.

Can I have meetings or tasks created?

9brains has no built-in meeting or task management. With the connected Microsoft 365 integration, an agent can however work directly in your Outlook calendar or your Outlook task list, create new meetings, send invitations or create tasks with a due date. For example, tell the agent: “Schedule a meeting for Thursday at 2 p.m. with customer Müller” or “Create a task for me for tomorrow: review offer”.

Can I migrate my ChatGPT Custom GPTs?

There is currently no automatic migration import, but there is a simple workflow in chat: tell the AI “I want to transfer a Custom GPT to 9brains” and then paste name, description and the system prompt of your Custom GPT into the chat. The AI creates an agent from it with a matching configuration and adopts the instructions into the AGENTS.md. Any reference files of your Custom GPT you then upload in the File attachments tab of the agent.