Agents

What are agents?

An agent is a persistent digital colleague: its own identity (name, emoji, 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 (scheduled via cron 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 (cron schedule or webhook URL), enabled integrations, full run history
• 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 regular chat opens with the initial message “I want to create a new agent”. The AI clarifies the open points with you:

1. Role: what should the agent do, how does it recognize good work?
2. Name & emoji: what is it called, how do you recognize it at a glance?
3. Trigger: chat-only, cron schedule, webhook endpoint, or a combination?
4. Integrations: which of your tools should the agent be allowed to access?
5. Visibility: only you, a group, or the entire workspace?

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.

---

Configuration in detail

Via “Configure agent” you reach eight tabs:

Tab: General

Name, description, emoji and the “Agent active” switch for manual pausing or resuming. For agents that were paused automatically (spend cap reached, three consecutive failures), the reason is shown here.

Tab: Models & costs

• Base model: the AI model the agent uses by default
• Allowed models: optional whitelist (for example only economical models for high-volume crons)
• 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.

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. 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.

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: Files

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

Tab: Integrations

A toggle per integration (on/off). In addition, a separate section “Autonomous approval (for cron/webhook)”: here you approve individually, per personal integration, whether an autonomous trigger may use it, see below.

Tab: Triggers

Configure cron schedule and/or webhook. Details in the Triggers section further below.

Tab: Sharing

Change visibility (personal / group / workspace). When switching from “Only me” to “Group” or “Entire workspace”, a re-consent dialog appears if you have approved personal integrations for autonomous use, otherwise other users would see results from your M365 account in the run history.

Tab: Danger zone

Delete agents permanently.

---

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 (cron, webhook) are excluded; they are visible to all users with access, because they have no human counterpart.

---

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) and uses your integrations for tool calls (for example your M365 account, not the owner’s).

Cron trigger (schedule)

The agent runs regularly, for example hourly, every Monday at 09:00 or on the 1st of each month. One cron 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. If it finds something, it hands the result directly to the agent and the agent starts with the right context.

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: https://api.9brains.de/agents/{agent-id}/webhook. External systems (CRM, monitoring, custom apps) can call this URL to trigger a run.

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 (caller waits up to 60 seconds for the result)
• Rate limit: default 60 requests/minute, adjustable
• Guard script: like the cron trigger, optional

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

Manual trigger

In the agent home base there is a button “Start execution now”, which starts the agent as if it had been triggered by cron 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.

---

Integrations & autonomous approval

For each agent you define which of your integrations the agent may use. New agents have all your integrations enabled by default. When you connect a new integration (for example Microsoft 365 added later), it is automatically activated in your existing agents; you receive a notification and can correct the default individually.

Personal vs. tenant integrations

• Personal integrations are tied to your OAuth account (M365, Google, Atlassian). When an autonomous run uses them, it acts from your personal account.
• Tenant integrations are configured workspace-wide (Firecrawl, internal APIs with shared keys) and need no individual approval.

Consent for autonomous runs

Autonomous runs (cron, webhook) have no human counterpart. That is why you must approve in advance and individually which of your personal integrations an automatic trigger may use. For this purpose, the Integrations tab has its own section “Autonomous approval” with checkboxes per integration and explicit warnings.

Important for shared agents: If you share an agent with active autonomous approval, results from your personal account will appear in the run history of all users with access. The platform actively asks you on visibility changes whether this is intentional.

Chat runs are excluded: there, the agent always uses the integrations of the current caller (so the integrations of the person currently writing), no consent needed, no leakage.

---

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. 5 files per agent. Managed in the Files 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, cron 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”, “Cron · 08:00”, “Webhook · 11:17”. Clicking into a run shows the complete trace including all tool calls, the result and the costs.

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.

---

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 % usage
• Allowed models: whitelist per agent (for example only economical models), to exclude premium models for high-volume crons
• Auto-pause after three consecutive failures: prevents a configuration-related error from quietly consuming quota

Which quota a run is charged to depends on the agent’s visibility:

• Personal agents (only you): usage goes to your personal quota
• Shared agents (group or workspace): usage goes to the workspace quota, even for chat runs, because a shared agent is by definition a team resource and the attribution would otherwise depend arbitrarily on the triggering trigger

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, usage, spend cap, utilization, top model, run count 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 autonomous approvals are active.
• 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.

---

Three concrete examples

To make the concept more tangible, here are three 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: cron, 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: cron, 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.

---

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 Models & costs 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?.
• 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.
• Workspace or personal quota in low-cost mode: If the agent is configured to use a premium model and the workspace pool is running in low-cost mode, the agent pauses. Configure an economical model as allowed in the Models & costs tab, or wait for the next quota reset.

Cron trigger does not fire at the expected time

1. Check time zone: Cron 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. 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?.

Can multiple users edit the same agent?

Only the creator (owner) and workspace administrators can edit an agent. Other users with access can chat with the agent and view its run history, but cannot change the configuration.

Can I duplicate an agent?

Yes. When duplicating, configuration, AGENTS.md and reference files are taken over. Not taken over are trigger configurations, autonomous approvals and the run history; the clone starts as a manual agent so that you do not accidentally have your personal integrations active in a copy.

How many agents can I create?

There is no hard upper limit. Usage per agent runs against your personal quota (for personal agents) or the workspace pool (for shared agents).

Multiple cron schedules on one agent?

In this version: no. One cron 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, in chat runs from your personal mailbox, in autonomous runs from the owner’s mailbox (after explicit approval).

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.

For internal file servers, NAS systems or SMB shares as a searchable data source (with automatic indexing), support is currently not yet released; it is part of the data sources roadmap.

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 Files tab of the agent.