AI Studio operations and safety

This page documents the AI Studio screens that operate agents once they exist: the inbox for conversations handed to people, the trace explorer, the guardrail screens, the model and publishing rules, and the three ways of exposing an agent to the outside (a website chat widget, messaging channels, and MCP). Building agents is in Build an agent; bots and voice are in Build a bot.

All screens open from Workspace > AI Studio in the Explorer or from the AI Studio home page. Each screen loads on demand.

Hand-overs from agents

Where: Workspace > AI Studio > Hand-overs from agents. Page key ai-handoffs.

The team's inbox of conversations an agent passed to a person. A hand-over is created when an agent decides it cannot continue, when the person asks for a human, or when a bot flow reaches a "hand to a person" step.

Control	Description
Status switch	Waiting (status OPEN), Taken (TAKEN), Closed (CLOSED).
Row	The person's id, the agent code, the team (when set), the time, and who has taken it. Also the reason the agent gave (Why), a summary of the conversation and any reply already sent.
Reply to the person	Free text. Send reply sends it into the person's conversation and marks the hand-over TAKEN.
Take	Marks an OPEN hand-over TAKEN by you without replying.
Close	Marks it CLOSED. A closed hand-over shows no controls.

API: GET /api/v1/agents/handoffs?status=OPEN&agentCode=, PUT /api/v1/agents/handoffs/{id} with status and reply, and GET /api/v1/agents/{agentCode}/conversations/{sessionId}/handoffs. CLI operation: agent-handoffs.

Trace explorer

Where: Workspace > AI Studio > Trace explorer. Page key ai-traces.

Every agent run across all agents, with its steps as a time bar chart (waterfall).

Filter	Values
Agent	an agent code
Status	Any, COMPLETED, FAILED, AWAITING_APPROVAL, CANCELLED
Person	the user who asked
Period	Today, 7, 30 or 90 days (default 7)
Question contains	text matched against the question

The list shows status, the question, agent, person, number of steps (and how many failed), duration and time, 20 runs per page. Opening a run shows its id, agent and version, any error, and one bar per step: the tool code or step type, a bar positioned and sized by start time and duration as a share of the run, and the milliseconds. Failed or rejected steps are red.

Replay as a dry run sends the same question to the agent's current draft with dryRun set, so no action is performed, and shows the answer.

API: GET /api/v1/agents/traces with agent, status, user, days, q, page, size; GET /api/v1/agents/executions/{id}/steps; GET /api/v1/agents/executions/{id}/explain. CLI operations: agent-executions, agent-steps, agent-explain.

Organisation guardrails

Where: Workspace > AI Studio > Organisation guardrails. Page key ai-guardrails.

Safety checks applied to every agent, RAG pipeline, prompt run and OpenAI-compatible API call in the workspace, before the item's own checks. Where two levels both check, the stricter setting wins. Changing them needs the publish permission. A change reaches other servers within 30 seconds.

There are two independent blocks, Check every request and Check every answer. Each has an on/off switch and, when on, these settings:

Setting	Values	Description
Checks	Personal data (pii), Prompt injection (injection), Blocked terms (blockedTerms), Harmful content, model based (moderation), and a strict variant that refuses the call when no moderation model is available (moderationStrict)	Which checks run. Defaults when switched on: pii and injection.
Blocked terms	comma separated text	Shown when Blocked terms is on.
When something is found	flag (flag and continue), mask (mask personal data), block (block the run)	The action taken. Default flag.

Last change by and when is shown under the Save button.

API: GET, PUT /api/v1/ai/guardrails/default.

What the guardrails caught

Where: Workspace > AI Studio > What the guardrails caught. Page key ai-guardrail-report.

A report of findings for 7, 30 (default) or 90 days: the total and how many were blocked, counts by check (Personal data, Prompt injection, Blocked terms, Too long, Harmful content), counts by source (agent, pipeline, prompt, API), and the latest 15 events with time, source, side (request or answer), action and checks. The text that triggered a finding is never stored or shown.

API: GET /api/v1/ai/guardrails/events?days=30.

Application guardrails

Where: Workspace > AI Studio > Application guardrails. Page key ai-app-guardrails.

Guardrails for one application, checked after the organisation's for every AI call made for that application: its agents, prompts, pipelines and API keys. The order is organisation, application, agent, skill, tool. Each level can only add checks.

Field	Description
Application code	Letters, digits, _, . and -, starting with a letter, up to 64 characters, for example hcm. Otherwise: Enter the application's code, for example hcm.
Check requests, Check answers	Same checks and actions as the organisation guardrails.

Applications that have their own guardrails appear as chips; select one to edit it, or use its delete control to remove it.

API: GET /api/v1/ai/guardrails/applications, PUT and DELETE /api/v1/ai/guardrails/applications/{applicationCode}.

Model and publishing rules

Where: Workspace > AI Studio > Model and publishing rules. Page key ai-rules.

Three workspace rules for AI use.

Routing

Send a request to another model profile when it matches. The first matching rule wins.

Field	Description
From profile	The profile the request was made for. Empty means any.
When the request	contains personal data (sensitive), is short (short), is long (long), mentions a keyword (keywords).
At most (characters)	For is short. Must be greater than 0.
At least (characters)	For is long. Must be greater than 0.
Keywords	For mentions a keyword. At least one.
Send to profile	The target profile. Required.

The save button is disabled while a rule is invalid. Messages: Rule 1: choose the profile to send to., set how short (characters)., set how long (characters)., add at least one keyword., a rule cannot send a profile to itself.

Where data may go

Field	Description
Allowed provider regions	Comma separated, for example eu, in. Empty means any. Each provider states its region in its own settings as dataRegion.
Only providers that keep no data	Allows only providers that declare zero retention.

Try a request takes a profile and sample text and answers where it would go (Goes to <profile> (routed)) and whether the provider is allowed or why it is refused.

Publishing

Publishing an agent needs approval requires someone other than the person who sent the agent for review to approve it before it goes live.

API: GET, PUT /api/v1/ai/model-policy; POST /api/v1/ai/model-policy/try with profile and text; GET, PUT /api/v1/agents/publish-policy.

Website chat

Where: Workspace > AI Studio > Website chat. Page key ai-chat-widgets.

Puts an agent on a public website as a chat window through one script tag. Visitors are not signed in. The agent runs as the user you choose, so give that user only what a visitor may do (the right to run agents and read access). The agent's "Remember people" setting must be off.

Field	Description
Agent code	Required: Choose the agent.
Runs as user	Required: Choose the user the agent runs as for visitors.
Title	Header text of the window.
Colour	A six digit hex value such as #1565c0; otherwise The colour is a hex value such as #1565c0. Default #1565c0.
Greeting	First message shown.
Websites that may show it	One per line. Each must be https://host (optionally with a port) or http://localhost. At least one is required: Add at least one website address (https://...). The widget works only on these sites.
Messages per minute (all visitors)	Default 20.
On	Switches the widget on or off.

Each widget has a public key. The screen shows the snippet to add before the closing body tag of the website:

<script src="https://sites.example.com/bot.js" data-erp-bot="PUBLIC_KEY" async></script>

The address in src is the website runtime that serves bot.js; enter it in the field above the list. New key rotates the public key, which stops the old snippet from working. Each visitor chats in a conversation of their own. If the bot belongs to a portal, signed-in portal members also get tools for their own records (see Portals).

API: GET, POST /api/v1/agents/widgets, PUT and DELETE /api/v1/agents/widgets/{id}, POST /api/v1/agents/widgets/{id}/rotate-key.

Teams, Slack, WhatsApp

Where: Workspace > AI Studio > Teams, Slack, WhatsApp. Page key ai-channels.

A message that arrives on a channel is answered by an agent, and the answer goes back the same way and is shown in the Communications inbox. Channel accounts are set up in Communications first. When a person replies in the inbox, the agent stays quiet in that conversation for the pause time.

Field	Description
Channel	Microsoft Teams (MS_TEAMS), Slack (SLACK), WhatsApp (WHATSAPP), Google Chat (GOOGLE_CHAT), E-mail (EMAIL), SMS (SMS).
Account (optional)	The number of the channel account. Empty means every account of the channel. A non-number is refused: The account is its number, or empty for every account.
Agent code	Required: Choose the agent.
Replies as (user)	Required: Choose the user the agent runs and replies as. Everyone writing in is served as this user, so "Remember people" must be off.
Pause (hours)	0 to 720, default 24. Otherwise: The pause after a person replies is 0 to 720 hours.

Each route has an on/off switch and a remove control.

API: GET, POST /api/v1/agents/channel-routes, and update and delete by id on the same path.

Agents over MCP

Where: Workspace > AI Studio > Agents over MCP. Page key ai-mcp-agents.

Offers agents to outside AI tools through the workspace's MCP server. Clients see them through the tool ask_agent. A signed-in person runs an agent as themselves. An app key runs it as the user chosen here, and the key also needs agent:<code> in its allowed models.

Field	Description
Agent code	Required: Choose the agent.
Runs as (user)	Required for app keys: Choose the user it runs as for app keys.
What it does (shown to clients)	Optional description.

Remove an offer with its delete control. The agent's "Remember people" setting must be off.

API: GET /api/v1/ai/mcp/agents, PUT /api/v1/ai/mcp/agents/{agentCode}, DELETE /api/v1/ai/mcp/agents/{agentCode}.

Related

Build an agent, Test AI changes with evaluations and guardrails, Usage, keys and gateway, Build a bot.