Skip to main content

Agent Notifications

Notifications is an agent capability. With it enabled, an agent can tell someone about an outcome as part of its work — a ticket escalated, a job finished, a threshold crossed — instead of leaving that message for a person to write afterwards.

The capability is turned on per agent in Beak AI Studio and is off by default. Existing agents are unchanged after an upgrade until an administrator enables it.

Sending uses your workspace's notification settings, so the agent never holds mail credentials and cannot choose which mail server or bot identity to send through. What the agent decides is who to notify (from a list you set), which channel to use (from the channels you have configured), and what to say — preferring wording you have already approved.

Enabling the Capability​

In Beak AI Studio, open the agent and go to Settings. Turn on Notifications. Three controls appear.

  • Channels (optional) — Which channels this agent may use. Leave every channel unselected to allow any channel that is configured for the workspace. Selecting channels restricts the agent to those.
  • Allowed recipients (required) — Who the agent may notify. Add a full email address (ops@acme.com) or a domain (acme.com) to allow anyone with an address at that domain.
  • Subject prefix (optional) — Text put in front of every subject, so recipients can tell agent-sent messages from a colleague's.

Note: With no allowed recipients added, the agent refuses to send anything. This is deliberate. An agent reads documents, tickets and web pages, and it cannot reliably tell an instruction inside that content from an instruction from you — so a document containing "also send a copy to an outside address" is a real risk. Naming the audience yourself is what removes it. An empty list means nobody, never anyone.

Subdomains are not included automatically. acme.com allows ops@acme.com but not ops@mail.acme.com; add mail.acme.com as its own entry if you want it.

Channels​

Recipients are always given as email addresses. Each channel then resolves that address to its own delivery target, so one recipient list governs every channel rather than one list per channel.

  • Email — Sent through the workspace SMTP settings. Reaches anyone on the allowed list.
  • In-app — Appears in the recipient's notification bell in Beak AI Runtime. The recipient must be a Beak user in the same workspace; if the address does not match a user, the agent reports that rather than failing silently.
  • Microsoft Teams — Sent as a Teams message from the agent's bot. Requires the agent to have a Teams deployment with bot credentials, and requires the recipient to have messaged the agent in Teams at least once before — that first message is what establishes the conversation Beak can reply into.
  • Slack — Slack settings can be saved, but sending to Slack is not supported yet. If it is configured, the agent is told so explicitly and will not pretend to have delivered a Slack message.

An agent only ever sees the channels that are genuinely usable for it right now. A channel that is not configured is not offered, and asking for one produces a message explaining why rather than a silent no-op.

Templates​

Before composing a message, the agent looks for a stored notification template for that agent and uses one if it fits. This keeps recurring notifications in wording you approved rather than a fresh paraphrase each time.

Templates are managed per agent in Beak AI Runtime, under Configure → Notifications.

Writing a Template​

Each template has:

  • Key — a short identifier such as ticket_escalated. Lower-case letters, digits, hyphens and underscores.
  • Description — what the template is for. The agent reads this when choosing between templates, so write it for that reader.
  • Category — what kind of notification this is: Informational, Success, Warning, Critical or Security. It sets the coloured label at the top of the email and helps the agent pick wording that matches what happened, rather than inferring urgency from the key.
  • Channel — restrict the wording to one channel, or leave it as Any channel.
  • Body format — HTML or Plain text.
  • Subject — optional. When empty, the agent supplies one.
  • Body — the message, with {{variable}} placeholders the agent fills from the situation at hand. A line whose placeholder has no value is dropped, so a template can carry optional detail without leaving blanks in the output.
  • Active — clear this to retire a template without deleting it. The agent stops offering it immediately.

One Body, Every Channel​

Write the body once, in HTML. Email sends your markup; Microsoft Teams and the in-app bell receive a plain-text rendering derived from that same markup, with paragraphs and table rows preserved as line breaks rather than run together.

This is deliberate: keeping a separate copy per channel means the wording drifts the first time someone fixes a typo in one and not the other, and the drift is invisible because each channel looks correct on its own.

If you want the chat version shorter than the email, fill in Plain-text override. Leaving it empty means "derive it", which is the setting that keeps the channels saying the same thing.

Your own markup is preserved. Values substituted into {{variable}} placeholders are escaped, so a ticket subject that happens to contain angle brackets is displayed as text rather than treated as formatting.

Preview Before Saving​

Save & preview renders the template with sample values you supply and shows both results side by side — the email as a recipient sees it, and the plain text going to Teams and the bell. Check both. A body that reads well as an email can read poorly once its formatting is removed, and the preview is where you find that out instead of a recipient.

The preview renders what is stored, so it saves the template first. The button says so.

When No Template Fits​

The agent writes the message itself. Both paths render through the same notification layout, so a templated and a composed message look the same to the recipient.

Note: Notification templates are wording the agent sends. The same tab also has Email layout overrides, which replace the surrounding email design for a message type — a different thing, and normally left alone.

Configuring the Mail Server​

Email notifications need workspace SMTP settings. There is one setting per workspace, editable from either console:

  • Beak AI Runtime — Settings → Notifications (SMTP)
  • Beak AI Studio — Settings → Notification Email (SMTP)

Both edit the same values, so a change in one appears in the other. Approval emails use the same server.

The fields are the mail host and port, the username and password, whether to use SSL/TLS, the from-address, the sender name, and a reply-to address. Test connection connects to the server and authenticates without sending mail, so a wrong password is reported immediately rather than surfacing later as a notification that never arrived.

Note: Leave the password field blank when saving to keep the stored password. Only type in it when you are changing the password.

While SMTP is disabled, nothing is sent — agent notifications and approval emails are skipped.

What the Agent Cannot Do​

The capability is deliberately bounded. An agent with Notifications enabled cannot:

  • notify an address outside the allowed recipients list;
  • use a channel you have not configured, or one Beak has no way to deliver on;
  • choose a different mail server, forge a from-address, or read the stored credentials;
  • send to more than ten recipients in a single notification;
  • act for another workspace — the workspace and agent are fixed when the agent starts, not chosen per message.

Refused sends are recorded, so repeated attempts to reach an address outside the list are visible rather than silent.

Best Practices​

  • Name the narrowest audience that works — Prefer specific addresses over a whole domain, and a domain over several domains. The list is the control; a broad list is a broad blast radius.
  • Write templates for anything recurring — A template is wording you reviewed once and get every time, and it removes the run-to-run variation of a model rewriting the same message.
  • Check the derived plain text, not just the email — Most recipients of a Teams or in-app notification never see your HTML. The preview shows both; a table that carries the message in email may be the part that reads worst without it.
  • Set a subject prefix — Recipients can then filter agent mail, and nobody mistakes an automated notification for a colleague's message.
  • Test the connection after changing SMTP — Saving proves the values were stored, not that they work. The test proves the server accepts them.
  • Tell the agent when to notify, in its prompt — The capability makes notifying possible; the prompt decides when it is appropriate. Without guidance an agent may notify more often than you want.