Skip to main content

Configure

The Configure page (/configure/:agentId) is the administrative workspace for a single agent. It is accessible only to users with the admin role. The page loads the agent record by ID, shows an identity bar at the top, and renders a tab strip below it. Which tabs appear depends on the agent's execution_mode and whether it has declared template variables.

Agent Identity Bar​

The bar at the top of the page displays:

  • Avatar — a single-character icon derived from the agent name's first letter
  • Agent name — fetched from the agent record (name or the configurable type==agent/name field)
  • Type badge — the agent_type value
  • ID badge — the raw agentId from the URL
  • Imported badge — shown for agents whose execution_mode is not local (e.g. passthrough, proxy). This badge notes that orchestration is controlled by the source system and cannot be modified in Runtime. The tooltip reads: "Orchestration (skills, knowledge, MCP) is controlled by the source system and cannot be modified here."

Tab Availability​

The visible tabs are determined at load time from two factors:

Agent typeTabs shown
Local agent, no template variablesSkills, Knowledge, MCP Servers, Channels, Notifications
Local agent, with template variablesVariables, Skills, Knowledge, MCP Servers, Channels, Notifications
Imported / passthrough agent, no variablesChannels, Notifications
Imported / passthrough agent, with variablesVariables, Channels, Notifications

Variables Tab​

The Variables tab is available when the agent has at least one declared template variable (prompt_variables). Each variable is displayed as an editable text field. The field label comes from pv.label if set, otherwise from pv.name. The Jinja2 template reference (e.g. {{customer_name}}) is shown next to the label. A reset button restores the field to its declared default. A Default: hint shows the current default beneath each field.

Changes are batched — none are saved until the Save variables button is clicked. The button is disabled when there are no unsaved changes. On success the agent record is re-fetched so the tab reflects the saved state immediately.

Skills Tab​

The Skills tab lists every skill assigned to this agent. Each skill row shows:

  • Display name (falls back to name if no display_name is set)
  • Type badge — Custom, Inbuilt, or System, colour-coded
  • Description — shown beneath the name when present
  • Tool reference — the underlying tool identifier, shown in small muted text
  • Connection selector — appears inline when the skill has authentication_required: true; lets the administrator bind a stored credential to this skill for this agent

Skills are read-only in this view — adding or removing skills is done in the agent builder. The tab is not available for imported agents.

Knowledge Tab​

The Knowledge tab shows all datasources in the tenant, split into two groups:

  • Linked to Agent — datasources already attached to this agent (matched by datasourceid)
  • Other Available Sources — tenant datasources not currently linked to this agent

Each datasource card shows the name, datasource_type badge (database, file, common, or system), an Active badge when is_active is true, and a description when present. For datasources that require authentication, a ConnectionSelector is shown inline.

file-type datasources are expandable. Expanding a file datasource reveals its uploaded files with name and size. From the expanded view an administrator can:

  • Upload a file — triggers a file picker; the file is uploaded to the datasource immediately
  • Delete a file — removes the selected file; the list refreshes automatically

The tab is not available for imported agents.

MCP Servers Tab​

The MCP Servers tab lists all Model Context Protocol servers attached to this agent. Each server card shows:

  • Server name and a transport badge (e.g. stdio, sse)
  • Active / Inactive status badge
  • Description when provided
  • Connection selector — shown when authentication_required is true
  • Tools disclosure — clicking the tools count expands a list of all tool names exposed by this server; hovering a tool name shows its description

The tab is not available for imported agents.

Channels Tab​

The Channels tab exposes three delivery channel cards for routing agent interactions through external systems. Each card has a toggle switch (On / Off) and a Save button. Settings in this tab do not alter agent orchestration — they only control how the agent is exposed externally.

Microsoft Teams — connects the agent to a Teams bot via an Azure Bot app registration. Fields:

  • Client ID (App ID) — the Azure application (client) ID
  • Tenant ID — the Azure Active Directory tenant ID
  • Client Secret — the client secret value; displayed as masked bullets when a secret is already saved; leave blank on subsequent saves to keep the existing secret

Note: The Teams card used to carry its own Greeting response and Welcome message, and the Embed card its own Welcome message. Those fields have moved to the Conversation tab, where they are set once for the agent and apply on every channel. Text configured before the change was migrated automatically — there is nothing to re-enter.

Webhook — exposes the agent as an HTTP endpoint that external systems can POST to. The webhook worker processes runs asynchronously. Fields:

  • Authentication — None (public endpoint), API key (header-based), or HMAC (sha256-signed body)
  • API key header name — the header name used when api_key authentication is selected (defaults to X-Beak-Webhook-Key)
  • API key / HMAC shared secret — the secret value; masked when already saved
  • Trigger message — an optional prompt prefix prepended to every incoming payload

Once the webhook is enabled and saved, a Trigger URL panel appears below the save button. It shows the live endpoint URL with a copy button and tabbed integration samples for cURL, Python, and Node.js.

Mail — connects one or more Microsoft 365 mailboxes to the agent. Each new email in a connected mailbox triggers an agent run. Add a mailbox with an Azure App Registration that has Mail.Read (Application) permission and admin consent; see Settings for mail channel prerequisites. Per mailbox, the fields are:

  • Label — a name for the mailbox, shown in the mailbox list
  • Mailbox email — the address to watch, e.g. support@acme.com
  • Microsoft Tenant ID / Application (Client) ID / Client Secret — the Azure App Registration credentials; the secret is masked once saved, and left blank on later saves to keep the existing value
  • Test Connection — validates the credentials and mailbox access without saving

Under What the agent receives, two switches control how much of each email reaches the agent. Both are off by default, including for mailboxes connected before these settings existed, so enabling them is always a deliberate choice:

  • Send the whole conversation — by default the agent sees only the newest message, because every email starts a new conversation thread. Turn this on to include the earlier messages of the email thread as well. Long threads are trimmed to the most recent messages that fit a character budget, and the agent is told how many older messages were left out. Use this for mailboxes where replies depend on what was already agreed — a support or dispute inbox — rather than for one-shot request mailboxes.
  • Analyse attachments — extracts the text of the message's attachments and passes it to the agent, so it can answer questions about the file contents rather than only seeing filenames. Supports PDF, Word, PowerPoint, Excel, CSV, plain text, and images (via OCR). Inline images such as signature logos are skipped, and very large files are listed but not extracted.

Note: Attachment analysis is billed per page. It uses Azure Document Intelligence for documents and Azure AI Vision for images, and runs on every inbound email to that mailbox that carries an attachment. Enable it on mailboxes where the attachments matter, not across the board.

Note: Attachment analysis depends on the platform's document-extraction credentials, which are provisioned per environment by the Beak operations team — they are not a self-service Settings field. If they are not present, the agent still receives the email and the attachment list, with a note that extraction is unavailable, rather than failing the run. Contact Beak support to have them enabled for your environment.

Both settings can be changed at any time from Edit on the mailbox row; changing them does not interrupt mail delivery or require re-consenting the Azure app.

Conversation Tab​

The Conversation tab sets what the agent says before it is asked anything, and what it answers without asking the model. Both are properties of the agent, so they apply identically wherever it is reached — web chat, Microsoft Teams, the embedded widget, the desktop app and mail. The tab is available for imported agents too.

Opening messages​

Two fields, with deliberately different lifetimes:

  • Welcome message — shown at the start of every new conversation.
  • First-time message — shown once per person, ever. It is tracked per user per agent rather than per channel, so someone who sees it in Teams will not see it again in web chat.

Both accept {first_name} and {agent_name}, and the editor shows a live preview with a sample name. Leave a field empty to show nothing — an agent with neither set behaves exactly as before.

Standard answers​

A list of fixed replies for questions whose answer you already know. Each entry pairs a set of match rules with the exact text to send. There is no practical limit on how many you add.

When an entry matches, the agent returns your text verbatim and does not call the model — so the answer is exactly what you wrote, costs nothing, and comes back immediately.

Each entry has:

  • Name — for your reference only; it is never shown to the person chatting.
  • When the message… — how the message is compared:
    • Any of these keywords — matches whole words, so a hi keyword will not fire on "this".
    • Message contains — the phrase appears anywhere in the message.
    • Message is exactly — the whole message, ignoring punctuation and casing.
    • Regular expression — for patterns the other modes cannot express.
  • Only match short messages — a word cap for the whole message. Set it to 3 on a greeting so "hi there" matches but "hi can you create a ticket" still reaches the agent.
  • Also match similar wording — optional example phrasings. When none of the patterns match, the agent compares the message against these by meaning, so "I forgot my login" can reach an entry written for "reset my password". Leave it empty and the entry stays purely literal.
  • Answer — the reply. Supports the same placeholders as the opening messages.
  • Let the agent phrase this answer — off by default. Turn it on when the reply needs adapting to the conversation; the agent then uses your text as the required content instead of sending it verbatim, which is slower and uses tokens.

Order matters. The list is checked from the top and the first match wins, so put narrow rules above broad ones — a contains: ticket entry above an is exactly: ticket status entry will answer both. Use the arrows on each row to reorder.

Note: Use the Try a question box before relying on a new rule. Type a sample message and it reports which entry would answer it, or that none would. This is the only way to see one rule shadowing another before a real user finds it.

Where to edit​

The same settings appear in Beak AI Studio's agent editor, under Conversation, next to the agent's prompt. Both consoles read and write the same values, so it does not matter which you use.

Note: Standard answers replace putting stock replies in the system prompt. A prompt instruction is a suggestion the model may reword; an entry here is returned exactly as written, every time.

Notifications Tab​

The Notifications tab provides per-agent overrides for the three transactional email templates used by the approvals system. Templates use Jinja2 syntax and support the following placeholders: {{ agent_name }}, {{ requester_name }}, {{ approver_email }}, {{ prompt_summary }}, {{ magic_link }}, {{ expires_relative }}, and {{ tenant_name }}.

Three sub-tabs select the template being edited:

  • Request — sent to the approver when a new approval request arrives; must include {{ magic_link }} so the approver can act
  • Resolved elsewhere — sent when the approval was decided through another channel (chat or Teams) so the email recipient knows the link is no longer active
  • Expired — sent when the approval window closed with no decision

Each sub-tab exposes three fields: Subject, HTML body, and Plain-text body. Leaving a field blank causes the agent to use the platform default for that field. Changes are saved with the Save button; the Discard button reverts to the last saved state.

Best Practices​

  • Always save the Client Secret the first time you configure Teams — once the page is navigated away, the secret cannot be retrieved from the UI and must be rotated in Azure AD if lost.
  • For webhook integrations, prefer HMAC authentication over API key in production environments; it verifies payload integrity as well as caller identity.
  • Turn on mail Analyse attachments per mailbox rather than everywhere — it calls a per-page Azure service on every inbound email with an attachment, so a high-volume mailbox whose attachments the agent never reasons about is pure cost.
  • If an agent answers a mail thread as though earlier messages never happened, check Send the whole conversation on that mailbox: without it the agent only ever sees the newest message.
  • When uploading files to a file-type datasource, keep individual files under a few megabytes; large files slow the retrieval pipeline and may be truncated by the agent's context window.
  • Put frequently-asked, fixed answers in Conversation → standard answers rather than in the prompt: the reply is then guaranteed word-for-word, returns instantly, and costs no tokens.
  • Use the Variables tab to customise white-label text (company name, greeting) per deployment rather than creating separate agents for each customer.
  • The Notifications tab only needs to be touched when the platform default email templates do not match the tenant's brand; leaving all fields blank is a valid and low-maintenance configuration.
  • Overview — runtime dashboard
  • Agents — agent grid and chat view
  • Suites — install bundles that provision agents and their resources automatically
  • Approvals — review approval requests generated by agents
  • Connections — manage stored credentials referenced by skills and datasources
  • Providers — configure LLM provider credentials
  • Settings — tenant-level settings including mail channel prerequisites