51 pages, in navigation order. The API Reference is generated from the live specification and is not included — read the online API Reference.
Opens your browser's print dialog — choose Save as PDF as the destination.
Welcome to AskRAI
Documentation for the Responsible AI platform — architecture, admin console, integrations, and guardrails
AskRAI is a Responsible AI platform that brings intelligent automation to your organization — without stretching budgets or adding complexity. With configurable safety and compliance controls, an always-on audit trail, and transparent logic, AskRAI helps teams Resolve issues, Inform decisions, Engage users, and Support operations.
Your team curates the knowledge base from existing enterprise sources — documents, FAQs, and internal policies — through the admin console. Nothing is crawled or ingested on its own: every item is there because someone put it there.
When a user asks a question, AskRAI answers from your curated knowledge base rather than from the model's own training data. Every response is recorded with the question that produced it, the confidence it scored, and the result of every check that ran. Grounding an answer in content you approved is the main defence against an invented one.
Configurable safety and compliance controls, an always-on audit trail, and transparent logic keep every response accountable and traceable.
Data Curation and Knowledge Base
Admin
Admins curate enterprise knowledge from existing sources, ensuring the AI only uses approved, reviewed content.
Active AI Guardrail (AAIG)
Safety
Configurable guardrails screen the question, the generated answer, and the arguments an agent sends to a tool — blocking, warning, or redacting according to the rule you wrote.
Seamless Integration
Integration
Deploy AskRAI as a Microsoft Teams bot for instant, organization-wide access — plus a governed API and MCP server for applications and AI agents.
Concepts
Understand how AskRAI delivers responsible AI — from knowledge management and guardrails to confidence scoring and governance
AskRAI is a Responsible AI platform that delivers intelligent automation with built-in safety, compliance, and accountability. Every response is grounded in curated knowledge, evaluated by the guardrails you have attached, scored for confidence, and recorded in a full audit trail.
When a user asks a question, the platform runs a multi-step pipeline designed to keep the response grounded, governed, and traceable.
The user sends a question through Microsoft Teams — the one human channel available today — or a machine calls through a programmable interface (API, CLI, or MCP) authenticated with a credential.
Active AI Guardrails evaluate the question against your safety, compliance, and quality rules. A guardrail set to Block stops the request here and no answer is produced; one set to Warn or Redact records or rewrites and lets the turn continue. The same rules can instead be set to read the generated answer, or the arguments an agent sends to a tool.
AskRAI searches the curated knowledge base for relevant content and composes a grounded answer.
The platform assigns a confidence score reflecting how well the knowledge base supports the answer.
The response is delivered. Afterwards, your escalation rules are evaluated against the confidence band and can open a support ticket for human follow-up.
Every step is recorded in a complete audit trail for governance and continuous improvement.
A guardrail on the Input stage runs before retrieval, so it can stop an answer from being generated at all; one on the Output stage runs after generation and can still withhold or rewrite the answer before anyone reads it. Escalation runs after the answer has been delivered, so it can raise a ticket for a human — but it cannot withhold the response.
Knowledge management defines what the assistant knows. Guardrails define what it must not do. Confidence scoring defines how certain it must be. Access control defines who gets access to what. And governance gives you the tools to monitor, measure, and improve over time.
Each concept builds on the others — groups bundle knowledge packs with guardrails, and the audit trail captures how all of these interact during every conversation.
The RIESE Model
Five pillars that define what your AI assistant does — Resolve, Inform, Engage, Support, and Escalate
The RIESE model defines five distinct ways your AI assistant interacts with users. Each pillar represents a different intent — from answering a straightforward question to escalating a complex issue to a human agent. Understanding these pillars helps you organize your knowledge base and configure your assistant to handle each scenario appropriately.
The assistant directly solves the user's problem with a definitive answer. This is the ideal outcome — the user gets what they need without any human involvement.
Example: "How do I reset my password?" → The assistant provides step-by-step reset instructions from the knowledge base.
Inform
The assistant provides factual information or context that helps the user make a decision. The response educates rather than solves.
Example: "What are the office hours for the permits department?" → The assistant returns the hours, location, and contact details.
Engage
The assistant enters a multi-turn conversation to clarify the user's needs, gather required details, or guide them through a process.
Example: "I need to apply for a building permit" → The assistant asks about the project type, location, and scope to determine which forms and requirements apply.
Support
The assistant provides ongoing assistance for complex workflows that span multiple steps or require follow-up. This goes beyond a single answer to provide guided support.
Example: "Walk me through preparing my grant application" → The assistant helps the user gather documents, fill in sections, and check eligibility requirements across multiple messages.
Escalate
The assistant recognizes that it cannot confidently answer — its confidence falls into a band you have configured to escalate — and hands the request off to a human by opening a support ticket.
Example: "I want to file a formal complaint about my neighbor's construction" → The assistant creates a support ticket so a human agent can follow up.
Escalation is not a failure — it is a designed outcome. A well-configured assistant knows its limits and hands off gracefully when human judgment is needed.
How content enters AskRAI, gets organized into knowledge packs, and powers AI responses through Text Search and AI Search
The knowledge base is the single source of truth for your AI assistant. Every response is grounded in content your team put there, rather than in the model's own training data, and nothing outside it is retrieved. To see exactly which items a question retrieved, replay it in the Sandbox — the retrieval set is not kept in the audit record.
AskRAI supports two types of knowledge content, each suited to different use cases:
Type
What it is
Best for
Q&A pairs
A question and its answer — written by a curator, imported from a CSV or XLSX table, or generated from a document you upload
Direct answers to common questions (Resolve, Inform)
Document chunks
Segments extracted from uploaded PDFs
Reference material, policies, and detailed procedures (Inform, Support)
Both types live in the same knowledge base. The difference is in how they enter the system — and in how they are read: admin AI Search merges both, while at query time the assistant searches each separately and keeps whichever leg scored higher, summarizing that one alone.
When you upload a document to a knowledge pack, AskRAI processes it through an automated pipeline.
Upload — drag and drop files into a document-type knowledge pack. A document-type pack accepts PDF only; a Q&A-type pack also accepts CSV and XLSX tables of ready-made pairs. There is no OCR, so a PDF has to carry a real text layer — a scan or a photograph fails.
Extract — the system reads the file's text layer, keeping track of which page each passage came from.
Chunk — long documents are split into overlapping windows that each capture a coherent unit of information.
Embed and store — each chunk is turned into a vector and written to the knowledge base, which makes it searchable the moment it lands.
For Q&A pairs, you write the question and answer directly — no parsing pipeline needed.
A new Q&A is not live when you save it. It is created as a Draft, and only Approved items are retrievable — the assistant cannot see a draft. To publish a Q&A you must approve it, and that takes effect immediately: there is no indexing run to wait for. If a curator adds an answer and users still get "I don't know", an unapproved draft is the first thing to check.
Knowledge packs are containers that group related content together. Each pack has a content type (Q&A or Document) chosen at creation, and content within a pack shares the same lifecycle and access controls.
Packs serve two purposes:
Organization — group content by topic, department, or use case (e.g., "HR Policies", "Building Permits", "IT Self-Service")
Access control — groups reference knowledge packs to control which users can access which content
A user's AI assistant only searches knowledge packs that their group memberships grant access to. Content in packs outside their groups is invisible to their queries.
Every knowledge item follows a status workflow that controls whether the assistant answers from it:
Status
Visible to users?
Description
Draft
No
The starting status for a hand-written Q&A — awaiting review
Approved
Yes
Reviewed and live — used in answers
Needs Attention
No
Flagged for review — temporarily hidden
Discarded
No
Soft-deleted — never used in an answer
Only Approved content is retrievable, so an item in any other status answers nothing.
What you upload decides whether anyone reviews it. Chunks produced for a Document pack are created Approved and are live as soon as processing finishes — uploading a document to one publishes its content with no review step. Everything bound for a Q&A pack lands as Draft instead and answers nothing until approved: a pair you write by hand, a CSV or XLSX table you import, and the pairs generated from a PDF uploaded to a Q&A pack. So importing five hundred pairs and then asking about them returns nothing until you approve them — use Bulk Approve All QnAs on the pack once you have read them.
AskRAI offers two ways to search the knowledge base:
Text Search — substring matching against questions, answers, titles, section headings, document content and tags. Fast and predictable, and the only mode that reliably finds an exact identifier or phrase.
AI Search (semantic) — meaning-based search that finds relevant content even when the wording differs from the query. Uses vector embeddings to match by concept rather than keywords.
These two modes are a curator tool on the Knowledge Base page — they are how you look content up. They are not a runtime setting. At query time the assistant always searches by meaning, the way AI Search does; there is no per-tenant switch that selects a retrieval mode, and nothing to configure.
Knowledge Base — create and manage Q&A pairs and document chunks
Knowledge Packs — organize content into collections and upload files
Guardrails — understand how safety rules protect knowledge-based responses
Access Control — learn how groups control access to knowledge packs
Guardrails
A guardrail is three decisions — what it checks, which payload it reads, and what it does about a violation
A guardrail is one check AskRAI runs over one payload of a turn. Every guardrail is three decisions made independently of each other: a kind that decides how the check is performed, a stage that decides which payload it reads, and an action that decides what happens when it fires.
Those three are what the rest of this page is about. One more setting does change behaviour: priority is the order guardrails are evaluated in, and it decides which blocker is reported as the reason. The category is a label for the people reading the console.
A guardrail's kind, stage, action and status are set on the Admin → Guardrails page, which Platform Admins and the holders of View policies, guardrails and egress open, and only the holders of Manage policies, guardrails and egress change. The Console → Guardrails page, open to the same readers, is where you watch the same guardrails perform.
Six kinds ship today. Five of them are evaluated in code: they cost no model call, add no provider latency, and give the same answer every time.
Kind
What it looks for
Can redact
PII
Personal identifiers — email, phone, US SSN, payment card, IBAN. Each has a precise detector, including a Luhn check for cards and mod-97 for IBANs.
Yes
Regex deny
Anything matching patterns you write. Up to 25 patterns, each up to 200 characters.
Yes
Word deny
Specific terms. Up to 500 words, matched as whole words by default or anywhere inside a word if you choose.
Yes
Secret scan
API keys, tokens and private keys, using the shipped pattern set. Takes no configuration.
Yes
Link domain
Links pointing at a host your egress allowlist does not admit. Takes no configuration — it reads the allowlist in force.
No
LLM judge
A natural-language rule you write, put to a model. This is what every guardrail was before the other five existed.
No
The last column matters because Redact is an action a kind has to be able to perform. A judge returns a verdict rather than the position of what it objected to, and a link-domain check has nothing to substitute, so neither can redact. The console refuses that combination when you save it rather than at runtime.
A Link domain guardrail with no egress allowlist in force cannot be evaluated, and AskRAI stops the turn rather than passing it. With nothing to compare a host against, "allowed" would be a verdict the check never reached — so this is the one control whose unknown answer is deliberately not silence. If you attach one, attach an allowlist too.
The user's question, or an agent beat's inbox: the tasks and messages other people and agents left for it.
Before retrieval, so a blocked request costs no search and no summarisation tokens.
Output
The answer the assistant generated, or what an agent is about to say or record.
After the answer exists and before anyone reads it.
Tool call
The arguments an agent is about to send to a tool, serialised as JSON.
After every free check and before anything billable — a judge here costs the tenant a model call.
A rule phrased as a constraint on the response is enforceable: set its stage to Output. Set that same rule on Input and it fires on nothing and reports compliance on every turn.
Redact means something different at each stage. On Input it rewrites the question, and what continues into retrieval — and what the audit record stores as the question — is the rewritten text. The auto-route classifier is the exception: its tier picks the guardrail model, so it reads the question as asked, before any guardrail. On Output it rewrites what is delivered: the answer, and the title of each citation, which for a Q&A entry is its stored question. A title too long to be checked in full is left out, and when the check cannot finish in time, every citation's title is. On Tool call it refuses the call entirely: a redacted argument is a different call to the far side, and sending one the model never wrote would be worse than not sending it at all.
An output guardrail turns off token-by-token streaming. A check that can refuse or rewrite an answer cannot run after the caller has already read it, so for a tenant with an Output guardrail in force the answer is held until it has been governed, then delivered in one piece. Tenants with none stream exactly as before.
There is no majority rule and no scoring: one blocking guardrail is enough. A Warn does not stop the turn — its effect is the record it leaves, which is why it is worth reviewing the audit trail for warnings rather than waiting for something to break.
The deterministic kinds are evaluated first, one after another in priority order. The LLM judges run afterwards, concurrently — at most three at a time. If something has already blocked, only the judges that would Block are skipped; a Warn judge still runs. (A judge cannot be set to Redact — see the table above.)
Three consequences follow from that order:
A regex settles what a judge would be billed to decide. This one is free: the deterministic kinds always run before any judge, whatever priority you give them, so a cheap check that blocks keeps the turn off a model. Priority does not control it.
Priority orders the deterministic checks among themselves, lowest number first, and when several would block, the first is the one reported as the reason. Set the number you want evaluated first to the lowest value, not the highest: the console says so beside the priority box.
A redaction earlier in the order changes what every later guardrail reads. A PII guardrail that redacts at priority 1 means the judge at priority 9 sees the redacted text, not the original.
Once a deterministic check has blocked the turn, blocking judges are skipped — their verdict cannot change the outcome and the tenant should not be billed for it. Judges set to Warn still run, because they were attached to observe exactly these turns and a skipped one would report "never fired" on the population it exists to watch.
AskRAI stops the turn instead of allowing it. A control that quietly stops checking while still reporting compliance is the failure this whole plane exists to prevent, so it is the one outcome the evaluator will not produce. A turn fails closed when:
an LLM judge names a model that no longer resolves, or the tenant has no model configured for the guardrail stage;
an LLM judge on an agent names no judge model of its own: only a person's question is routed one to fall back on, so such a judge cannot be attached to an agent, and an agent that already carries one fails closed on every beat until it has one;
a pattern runs long enough to be abandoned;
a pattern does not compile, or would build more than a pattern may. Saving refuses both, so this is a guardrail saved before that check, and it stops every turn it governs, whatever its action, until the pattern is fixed;
a Block or Redact guardrail is handed a payload longer than 100,000 characters — neither "I refused all of this" nor "I handled every span in this" can be said honestly about a prefix. A Warn guardrail scans the first 100,000 characters and says so in its record;
a guardrail was written by a newer build than the one evaluating it. Only the subjects that attached it fail; everyone else in the tenant is unaffected.
A guardrail governs a subject, never the tenant at large.
For a person asking a question, the subject is their groups — the union of every guardrail listed by every group they resolve into.
For a team agent, the subject is the agent itself.
Either can also carry policies, and a policy brings its own guardrails. All of those sources compose into one effective set, under a single rule: every merge is a narrowing. Guardrails union together, and a host must be admitted by every allowlist in force. For an agent, a policy's ceilings also take the lower value. Attaching a second policy can tighten what a subject may do and can never loosen it — so there is no "bypass" group, and no way to exempt one population by adding something to it.
A person's question calls no tool and runs no beat, so a policy on a group governs it through its Input and Output guardrails, and through its allowlist only as the list a Link domain guardrail checks links against. Its ceilings, approval requirements and Tool call guardrails govern an agent's beats and do not apply to the group's members. See A policy on a group.
Only guardrails whose status is Active take part. A draft governs nothing, however carefully it is written.
Saving a guardrail applies to the next turn, not the current one, and is in force everywhere within five minutes at the outside.
Every evaluation — pass or fail — is written to the audit trail and counted in the analytics. There is no setting that reduces this. A redaction records how many spans it replaced and never the values, which would put the content back into the record the redaction exists to keep it out of.
Administrators can mark a guardrail trigger as a false positive in the conversation logs. Those marks drive the per-guardrail false-positive rate on the guardrail analytics, which is how you find a rule that fires too eagerly without weakening it blind.
Sandbox — test guardrail behaviour before it reaches production
Confidence & Escalation
How AskRAI scores response confidence and uses escalation rules to decide when conversations need human attention
Every AI response receives a confidence score — a percentage reflecting how well the knowledge base supports the answer. The score sorts the answer into a band, and your escalation rules decide what follows from that band. Scoring happens as the answer is produced; escalation happens after it has been delivered, which is what decides the difference between the two.
Confidence scores fall into three configurable bands. You set the thresholds in Admin — the defaults are shown here.
Band
Default range
Typical behavior
High
90% and above
The assistant is confident in its answer. Response is delivered normally.
Medium
60% – 89%
The assistant has a reasonable answer but some uncertainty. The response is delivered.
Low
Below 60%
The assistant cannot adequately answer. The conversation is typically escalated.
Threshold boundaries are fully configurable per tenant. When you adjust them, a reclassification preview shows how existing conversations would be recategorized — so you can see the impact before saving.
Escalation rules define what happens when a response falls into a particular confidence band. Each rule specifies a condition (confidence band) and an action to take.
Generates a support ticket in the Tickets queue for human follow-up. The ticket carries the original question and the answer, and — unless you clear Include AI context on the rule — the confidence score.
Auto Respond
Takes no follow-up action. The answer has already been delivered, and nothing else happens. Use it for a band where you trust the assistant's answers.
Escalation happens after delivery. AskRAI answers the user first, and your rules are then evaluated against the record of that turn. So escalation is a follow-up mechanism, not a gate — nothing it does can un-send an answer. To prevent a response, use a guardrail, which is evaluated during the turn itself.
One other thing can stop an answer before it is written, and it is neither a guardrail nor an escalation rule: if the best knowledge-base match scores below the tenant's minimum relevance threshold, the assistant returns its low-confidence reply without composing an answer at all. See Confidence Thresholds.
When multiple escalation rules match (for example, if two rules both apply to the Medium band), the rules are evaluated in priority order. The first matching enabled rule's action is executed, and no later rule in that band runs — so an Auto Respond rule ordered above a Create Ticket rule for the same band means no ticket opens for it.
Every confidence band should have at least one matching escalation rule. If no rule matches a given band, the platform defaults to delivering the response without escalation — which may not be the behavior you want for low-confidence answers.
The confidence score is not a simple keyword-match percentage. After the assistant drafts an answer, a lightweight assessment step scores two things:
Answer quality and groundedness — how well the drafted answer actually addresses the user's question using the retrieved knowledge base content, rather than guessing or padding.
Retrieval relevance — how close the top knowledge base results the answer was built from are to the question, measured as the similarity score retrieval returns for each of them.
Only the first of those bands the answer. Retrieval relevance is kept as a separate signal and does not move the confidence band. A high score means the assistant judged its own answer well-grounded in what it retrieved. A low score means it is uncertain — perhaps the question is outside the knowledge base's scope, or the best-matching content only partially fits.
A tenant can have a decision model such as TypeSafe's Jev score its answers instead. The score is then the probability that the answer addresses the question, times the probability that its sources state every factual claim in it. That moves which band answers fall in, and so which rules fire.
Users, roles, groups, and multi-tenant isolation control who can access which knowledge and guardrails
AskRAI's access control model determines who can access which knowledge and what safety rules apply to their interactions. The model is built on four layers — users, roles, groups, and tenants — that combine to provide fine-grained, scalable access management without per-user configuration.
Unlocks areas of Admin, or reaches every organization and project
Grants knowledge packs and guardrails
A Platform Admin can open Admin and reconfigure the tenant. A Member cannot, apart from Admin → Organizations once they are Admin on an organization: they see only the organizations and projects shared with them, work in each at the level it is shared at, and use every console page but Guardrails, which, like Admin, is reserved for the people whose roles grant it. A role you build grants the areas of Admin you choose, and a person holding several roles holds all they grant. An Auditor has what a Member has, and can also open Admin to read its Change Log, the record of who changed what there; no other Admin page, and no change, is open to them. Inside a project, Read opens it and changes nothing; Write sends its messages, writes its brief, works its tasks, starts and stops its team, decides its agents' proposals, and changes its team, its agents and its files; Admin also shares it, changes an agent's autonomy, edits, resets and deletes the project, and deletes its agents. These are levels a project's Admins grant from its Share dialog (see Sharing & Access), and someone holding none does not see the project at all. An organization is shared the same way: Write on it creates projects in it, and Admin on it is Admin on every project in it, while Read or Write on it reaches none of them. A tenant starts closed: someone with no grant and no role reaching every organization or project sees no organization and no project until one is shared with them. Three tenant permissions reach past the grants: Administer every organization and Administer every project give Admin on every project, and View every organization and project gives Read on every one; a Platform Admin holds all three. Tenant roles and access levels alike are separate questions from what content anyone can see — that is decided by groups and resource-access roles, described below, and applies to admins and members alike.
Users are real people in your organization. They are synced automatically from your identity provider — you do not create user accounts manually in AskRAI. Every synced user is a Member until an admin grants them a tenant role on the Access page — with one exception: the very first user to sign in to a brand-new tenant is automatically promoted to Platform Admin, so there is always someone who can open Admin and grant roles to everyone else. Administrators can:
View user details (name, department, job title, email address)
Block or unblock user accounts
Users gain access to knowledge and guardrails through their group memberships, never directly.
The roles in this section are resource-access roles — the ones that decide which knowledge and guardrails an interaction gets. They are unrelated to the tenant roles (Platform Admin, Auditor, Member and the ones you build on the Access page) that unlock Admin.
Roles represent usage patterns rather than individual people. Each role defines mapping rules — conditions that automatically classify incoming interactions based on properties like:
Rule type
Example
Channel
Teams, Web Chat, API
Authentication
Authenticated vs. Unauthenticated
Caller type
Human, Application, Agent
Credential type
Which class of credential made the call
Those four are the whole list. A role can still hold a rule of another kind — Device, Referrer, Location or Time — and none of them can be evaluated against a request: no caller reports a device or a referrer, and a location or time rule names nothing a request carries. AskRAI holds such a rule aside, and the role matches no request at all rather than matching on its other rules. The role's editor lists those rules read-only and lets you remove them, after which the role matches on its remaining rules — see Rules of a kind that is not offered.
When a user sends a message, the system evaluates mapping rules to determine which roles apply. Every rule on a role must match for that role to apply, and a user receives the combined access of every role that does — there is no ordering between roles. Roles are assigned to groups, so matching a role grants the user that group's knowledge packs and guardrails.
Roles enable dynamic access control without per-user configuration. For example, you can create a "Public Kiosk" role that matches unauthenticated web chat requests, and a separate "Employee" role that matches authenticated Teams messages — each with different knowledge packs and safety rules.
Groups are the central connection point in the access model. A group bundles together:
Members — users and roles that belong to the group
Knowledge packs — content collections the group can access
Guardrails — safety rules that apply to the group's interactions
A user's effective access is the union of all knowledge packs and guardrails from every group they belong to. If a user belongs to Group A (with packs 1 and 2) and Group B (with packs 2 and 3), they can search packs 1, 2, and 3. A group either grants a pack or it does not, and a grant from any one group is enough: no group takes away a pack another grants.
Administrators add and remove users and roles individually
Automatic
Declared on the API, but not reachable: the console creates every group as Manual, and automatic assignment is not evaluated for a person asking a question. Use roles to grant group access by rule instead.
AskRAI is a multi-tenant platform. Each tenant operates in complete isolation — data, configuration, users, knowledge, and guardrails are fully separated between tenants.
From a product perspective, this means:
Each organization gets its own independent AskRAI environment
Users in one tenant can never see or search content from another tenant
Configuration changes in one tenant have no effect on others
Administrative actions (creating groups, editing guardrails, managing users) are scoped entirely to the current tenant
Tenant isolation is enforced at every layer of the platform. No tenant administrator can see or reach another tenant's data or configuration, and no configuration option shares content between tenants — every record of your data, and every query against it, is scoped to a single tenant.
Knowledge Packs — create content collections to assign to groups
Guardrails — author the safety rules a group or policy carries
Governance & Audit — learn how access control ties into audit and compliance
Governance & Audit
Audit trails, analytics dashboards, sandbox testing, and the continuous improvement loop for responsible AI
AskRAI is designed for organizations that need accountability, transparency, and continuous improvement in their AI operations. Every interaction is recorded, every guardrail evaluation is logged, and every confidence score is tracked — giving your team the data needed to monitor, measure, and improve your AI assistant over time.
Two different things are called governance. This page is about the record — what AskRAI captures about an interaction, and the review loop that record supports. The controls that decide what an interaction is allowed to do — policies, guardrail definitions, egress allowlists — live under Admin → Governance. The two meet here: every control that runs writes to the trail below.
Governance in AskRAI is not a one-time setup — it is an ongoing cycle of interaction, review, tuning, and testing.
Interact — users ask questions through connected channels. Every interaction flows through the query pipeline.
Audit — the platform records the full context of every interaction: the query, the response, the confidence score, guardrail evaluation results, and processing metadata.
Review — administrators use the dashboard and conversation logs to identify patterns: frequent low-confidence answers, guardrail false positives, knowledge gaps, and usage trends.
Tune — based on review findings, administrators adjust configuration: add knowledge content, refine guardrail prompts, adjust confidence thresholds, or modify escalation rules.
Test — changes are validated in the sandbox environment before going live, ensuring they work as expected.
Deploy — verified changes are applied to production, and the cycle continues.
Every conversation generates an audit record containing:
Data point
Description
User query
The original question the user asked
AI response
The generated answer
Confidence score
The score the answer received. The band is not stored — it is derived from your thresholds as you read the record, so moving a threshold relabels past conversations
Guardrail evaluations
Pass/fail result for each guardrail, with the reason any that fired gives. A check that passed records no reason
Ticket decision
Whether a ticket should be opened, the reason, and the resulting ticket ID
Processing metadata
Response time, model and routing information, channel, caller, and session details
This data powers the dashboard analytics, conversation review, and compliance reporting.
One thing the audit record deliberately does not keep: the retrieved search results — every knowledge item that matched, and its score. It keeps only the best match: its score, and for a Q&A entry its question and stored answer, shown in the conversation's Nearest Knowledge Base Match. Retrieval detail is available live in the Sandbox, which is built for exactly this kind of inspection but never persists anything. The escalation rule is recorded: when a rule opens a ticket, the audit's ticket-decision reason names it ("Escalated by rule: …"), though not its id.
The Sandbox is a safe environment for validating configuration changes before they affect live users. You can:
Test with custom configurations — select specific guardrails and knowledge packs to evaluate
Test as a group — simulate a group's exact configuration to verify the end-user experience
Inspect the full pipeline — view guardrail evaluation results, search debug data, audit previews, and model information for every test message
Validate escalation rules — see which rules would trigger and what actions would be taken, without creating real tickets
Sandbox conversations are not recorded as production audit records. This keeps your analytics clean while giving you full visibility into how changes will behave.
AskRAI's governance model supports compliance requirements by providing:
Traceability — every response is recorded with the question that produced it, the confidence score it received, and the result of every check that ran. Which knowledge items were retrieved is not part of that record — replay the question in the Sandbox to see the retrieval set
Accountability — audit records capture who asked, what was answered, and what safety checks were applied
Transparency — a guardrail that fires records why. A check that passed records no reason, and the deterministic kinds never produce prose at all — a fired pattern check records how many spans matched
Control — the content lifecycle (Draft → Approved → Needs Attention → Discarded) decides what is retrievable, and gives you a place to park an item you no longer trust
Overview of the AskRAI admin console — run projects, monitor activity, manage content, and configure settings
The AskRAI admin console is the central hub for managing your AI assistant. From here you can run projects where people and AI agents collaborate, monitor platform activity, curate knowledge, configure guardrails, and manage users and settings. The bell in the header tells you when something is waiting on you.
The bell in the console header and its toasts — what its count means, how the list behaves, which events notify whom, where each notification opens, and how long notifications last
The bell near the right-hand end of the console header tells you what is waiting on you: an agent's proposal to approve, a message an agent sent you, a team its budget has stopped, a new escalation ticket, a directory sync that has started failing, or an agent suggested as a template. Without it, each of these shows only on the page it lives on — you would see it only if you happened to open that page.
Notifications are delivered in the console only. AskRAI sends no email, Teams message or push notification for them, and there are no per-person preferences: you receive every notification addressed to you.
The badge on the bell counts your unread notifications, capped at 99+. Screen readers announce the button as Notifications, 3 unread when three are waiting, and as Notifications when nothing is unread.
The count is not pushed to you the moment something happens. It refreshes every 30 seconds while the console is visible in your browser, whenever you return to the console window, and each time you open the list — so a new notification can take up to half a minute to appear.
A message an agent sends you, and a proposal you can decide, also pop up as a toast at the bottom of the screen, wherever you are in the console — on another project's page, in Admin, or on the Dashboard:
Toast
Says
Message from Release Writer
The start of the message, up to 140 characters
Approval requested
The agent's name and what it proposes, such as Release Writer: Publish the v2.4 release notes (+1 more)
Click Open on a toast to do what clicking its item in the list does: it marks the notification read and opens the project's Interactions tab. A toast leaves after a few seconds; the notification stays in the list either way. Press Alt+T to move to the toasts with the keyboard, which keeps them on screen while you are there.
A toast arrives with the count, so up to 30 seconds after the agent's beat. Each item toasts once in each browser tab open when it arrives: what the list already held when you opened the console, and anything you have read, raises none. Other notifications appear in the list alone.
These events raise a notification; a hosted tool server's notices are described with Tools. The title names who or what acted and what happened; the detail beneath it says what it was.
Notification
Raised when
Title and detail
Opens
Message
An agent sends you a message: one on Full autonomy sends it in a beat, and one on Manual approval once its proposal to send it is approved
Message from Release Writer, with the message beneath
The project's Interactions tab, where the message is
Proposal
A beat of an agent on Manual approval autonomy proposes one or more actions
Beacon needs approval, with the first proposal's summary beneath, followed by (+2 more) when the beat proposed three
The project's Interactions tab, whose Pending approvals card sits at the top
Budget stop
A project exhausts its budget and its whole team is stopped, or one agent is stopped by its own spend cap
Onboarding Automation: team stopped — budget exhausted, or Onboarding Automation: Atlas stopped — budget exhausted for one agent
The project's Budget tab
Escalation ticket
An escalation rule opens a ticket
Escalation ticket opened, with the ticket's title — or, failing that, its question — beneath
The Tickets page
Directory sync failed
A Google Workspace directory sync fails when the run before it did not
Contract Reviewer is suggested as a template, with who suggested it, from which project, and their note beneath
Admin → Agent templates → Suggestions
Suggestion decided
A template admin approves or rejects your suggestion
Your suggestion of Contract Reviewer was approved, with the template and version it was published as; or …was rejected, with the reason beneath
The template, if you may manage agent templates; otherwise the project's Team tab
Opening a message, proposal or budget-stop notification selects that project on the Projects plane and opens the tab. If the project belongs to an organization other than the active one, the console first switches the active organization to the project's own. If the project can no longer be opened, the Projects plane opens as it normally would.
A ticket notification opens the Tickets page, not the ticket. Pick the ticket out of the list by the title the notification showed.
A budget stop for one agent opens the project's Budget tab. The agent's own cap, and its Resume, are on the agent's Budget tab — open the agent from the Team tab.
A notification goes to the people expected to act on it, not to everyone who could open the page it points to. Everyone a project is shared with can open it, but you see only the notifications addressed to you.
Notification
Who receives it
Message
The person the agent addressed it to, if they can open the project. A message to the whole team, or to another agent, notifies nobody
Proposal, Budget stop
The people on the project's Team tab who hold Write access or above on it. When none does, the people its Admin grants name — each person granted Admin, and the members of each active group granted Admin. When those name nobody, the people its organization's Admin grants name, in the same way. When those name nobody too, the tenant's Platform Admins, so an agent-only team's proposals still reach someone. Everyone notified can decide a proposal, and so can anyone else with Write access to the project
The person who made the suggestion — unless they decided it themselves
A Platform Admin holds every permission that opens Admin, an Auditor only the one to read the Change Log, a Member none, and a role you build the ones you chose for it. So the ticket, directory-sync and template-suggestion notifications go to the tenant's Platform Admins and to whoever holds a role granting that permission — whether the role was assigned to them directly or through a group.
A Platform Admin does not receive a project's notifications when someone on its team holds Write access or above, or its or its organization's Admin grants name anyone, though they can still approve or reject its proposals. Holding Administer every organization or Administer every project gives Admin on every project but brings none of its notifications. To hear about such a project's proposals and budget stops, add yourself to its Team tab: a Platform Admin, like a holder of either permission, holds Admin on every project, so you qualify.
Recipients are decided when the event happens, not when you look:
Joining later brings nothing from before. A person added to a project, or made a Platform Admin, receives only the notifications raised from then on.
Leaving the team takes nothing away. A person removed from a project's team, or whose access to it is lowered but not removed, keeps what they already received until it expires, though they decide its proposals only while they hold Write access or above.
Losing access hides a project's notifications. A message, proposal or budget-stop notification shows, counts and toasts only while you can still open its project. If the project is no longer shared with you, they leave your list and count, and come back if it is shared with you again before they expire.
One event notifies at most 500 people. In a tenant with more recipients than that for a single event, some of them do not receive it.
Each event notifies you once, however many times AskRAI comes across it:
Messages — one per message.
Proposals — one per agent beat. A beat that proposes several actions raises a single notification, naming the first and counting the rest.
Budget stops — one per stop. A team or agent that stays stopped raises nothing further. One that is restarted and runs out again raises a new notification.
Escalation tickets — one per ticket.
Template suggestions — one when suggested, one when decided.
Directory sync failures — one per change in what failed. A sync that fails notifies you, and further failures of the same kind do not: one you can fix (Google refused the connection), or one on AskRAI's side. A failure of the other kind notifies you again, so a refusal that follows a failure on AskRAI's side always reaches you. Once a sync succeeds, the connection is disconnected, or one of its connection fields is saved with a new value, the next failure notifies you again. Changing only Real-time user sync does not count.
Notifications are kept for 30 days, read or unread, and then disappear from the list. Only the notification goes: the proposal, ticket, budget state or sync status it pointed to stays on its own page. Deleting a project deletes its notifications with it.
Nothing clears a notification when someone deals with its source. If a colleague approves or rejects a proposal before you open yours, your notification stays unread, and opening it lands on a Pending approvals card that no longer lists that proposal.
You receive nothing for a project's proposals or budget stops
You are not on the project's Team tab, or you hold less than Write access on it. Admin grantees, the organization's Admins and Platform Admins receive a project's notifications only when nobody on its team holds Write or above
Ask one of the project's Admins to share it with you at Write if you hold less, then someone with Write to add you to its Team tab. Notifications raised before you joined do not appear
An agent acts but never raises a proposal notification
The agent is not on Manual approval — Full autonomy agents apply their actions directly, so there is nothing to approve
Set its autonomy on its Heartbeat tab if you want to review its actions first
A proposal notification opens on a Pending approvals card without its proposals
Someone else with Write access to the project approved or rejected them first, the agent that raised them was deleted — which rejects them — or the run was cleared with Reset, which deletes proposals but leaves their notifications
Nothing to approve — the task board and the Activity tab show what a person decided, unless Reset cleared those too. A deleted agent's proposals leave no entry there: the agent is simply gone from the Team tab
A budget notification names one agent, but the project's Budget tab shows budget left
That agent was stopped by its own spend cap, not by the project budget
Raise or clear the cap on the agent's Budget tab, then press Resume there
A Member receives no ticket or directory-sync notifications
These go to the holders of Manage escalation rules and Manage directory sync
Expected. Assign that person a role holding the permission under Access if they should receive them
A directory sync keeps failing but only one notification arrived
A run of failures of one kind notifies once
Open Admin → Directory Sync and read the error on the card. If it names what Google refused, fix the connection, then click Sync now. If it says the sync failed on our side, there is nothing to fix on your side: the next scheduled sync runs again
No toast appeared for a notification in the list
Only messages and approvals toast, and only those that arrive while the console is open. What the list held when you opened the console raises none, nor does one already read
Expected — open it from the list
A new notification has not appeared yet
The count refreshes every 30 seconds, not instantly
Open the list, or switch back to the console window, to refresh it at once
Opening a notification changed the active organization
The project belongs to a different organization from the one that was active
Expected — switch back with the header org switcher when you are done
An older notification is gone
Notifications expire 30 days after they are raised
Its source — the proposal, ticket, budget or sync status — is still on its own page
Organize work into projects within an organization — create, browse, edit, and delete projects, and track each project's team and budget from a single workspace
Projects are the workspaces where your people and AI agents collaborate. Each project lives inside an organization and brings together a team, a budget, and an overview of how everyone connects. Open the Projects plane from the plane switcher in the top header.
The Projects plane pairs a searchable project list with a per-project workspace — here the Onboarding Automation project, scoped to the active Acme Automation Org organization.
A project always belongs to one organization, and the active organization scopes which projects you see. Switching organizations in the header switcher reloads the Projects plane for the newly selected organization.
Organization → projects — you need at least one organization before you can create a project. If your tenant has no organizations yet, the Projects plane prompts you to Create an organization in Admin first. If none is shared with you, it reads Nothing is shared with you yet and names your tenant's Platform Admins, who can share one with you.
One workspace per project — selecting a project opens its workspace, where the Overview, Team, Workspace, Interactions, Activity, Budget, Dashboard and Events tabs live.
Team and budget — every project tracks the people and agents working on it (the Team tab) and an optional spending budget.
A live team — the Interactions tab runs the project's agents and people as an autonomous workspace, with messages, a task board, and Start/Stop controls.
Access levels — a project's Admins share it at Read, Write or Admin, which decides who sees it, who works in it, and who makes its weightiest decisions: raising an agent's autonomy, editing, resetting and deleting it.
Projects are scoped to the active organization, and you see only the ones shared with you. If the project list looks wrong, confirm which organization is active in the header org switcher — see Organizations for how the active organization works — and ask one of a missing project's Admins to share it with you.
The Projects sidebar lists every project in the active organization that you can read. Use it to search, switch between projects, and start a new one.
Search — type in the Search projects box to filter the list by name or description. Press Alt+/ (Option+/ on a Mac) anywhere on the Projects plane, outside a text field, to jump to it. While you search, the list shows every match under a count of how many there are, and a search nothing matches says so, quoting it. The × in the box clears the search; Escape clears it and leaves the box.
Two groups — the six most recently updated projects appear under Recent; the rest are grouped under All projects.
Status at a glance — an entry shows On hold or Archived beside the project's name, and one showing neither is Active. Those under Recent also show how long ago each was updated: Today, Yesterday, or a number of days such as 3d.
Run state at a glance — the dot before each project's name says whether its team is running: a breathing green dot while it is Running, an amber one while it is Paused, and a hollow ring while it is Stopped. Hover the dot to read the state, and a screen reader hears it after the project's name. It follows a start, pause or stop of the project you have open at once, and of any other project within about 15 seconds, without a reload. While any team you can see in the organization is running, the logo at the top left gently drifts; it holds still if your system asks for reduced motion.
Archived projects — left out of the list. When the organization has any, switch on Show archived under the search box to list them too.
Select a project — click any project to open its workspace on the right.
Return to it — the browser's address bar names the project and tab you have open, so reloading the page, or opening a copied link to it, brings back the same project on the same tab.
When the active organization has no projects you can read yet, the workspace shows an empty state with a New project button to create your first one.
Creating a project needs Write access to the active organization. For anyone else, the + button, New project and the header's Create → Project stay in place, disabled, with a reason saying creating a project needs Write access to this organization.
Click the + button at the top of the project list in the sidebar (or the New project button in the empty state) to open the create dialog. You can also choose Create → Project at the right of the top header, from any tab.
On the Projects plane, Create starts a project or adds an agent or an assistant to the project you have open.
New projects are created in the current organization; you set the status and budget afterward by editing the project.
Open the create dialog. Click + in the Projects sidebar. The dialog notes that the project is created in the current organization.
Name the project. Enter a Name — this is required and identifies the project throughout the workspace. It must differ from the name of every other project in the organization by more than case, symbols or extra spaces, so launch plan! is refused where Launch Plan exists. The same name in another organization is fine.
Add a description (optional). Use the Description field for a short summary of what the project is for.
Create. Click Create. The new project is added, selected automatically, and opens to its Overview tab.
Whoever creates a project is its Admin, and joins its team unless they are a Platform Admin. New projects start as Active, with no budget and an Idle check-in of 60 minutes. To set a status, allocate a budget or change the idle check-in, edit the project after creating it.
The project's display name, shown in the sidebar and workspace header. Unique within the organization, whatever its case, symbols or extra spaces
Yes
Description
A short summary of the project's purpose
No
Status
Active, On hold, or Archived — set when editing (new projects default to Active). Only an Active project's team can run, and an Archived project is read-only; see Project status
Set on edit
Budget total (USD)
An optional ceiling on what the project may spend in total — set when editing
Set on edit
Idle check-in (minutes)
The longest an agent with nothing to do waits between beats — set when editing. Defaults to 60
Set on edit
Assistant suggestions
Whether the project's assistants offer help unasked when a run hits something they can help with — set when editing. On by default
Selecting a project opens its workspace. The header shows the project name and status, its description, Share, a More menu holding Edit and Delete, the Reset icon button and the run controls — Share opens who the project is shared with. Four tiles sit under them: Team counts its people and agents, shows the first eight as avatars, says how many agents are active, and reads how many are working, or Idle; Interactions counts its open tasks, how many of all its tasks are done, on a bar showing how many are done, in progress, blocked and to do, and beside them its messages, how many came from AI agents and a dot for each of the newest 18, an agent's in purple and a person's in grey, and says how many proposals wait for your approval, or failing that how many tasks are blocked; Budget gives what has been spent of the budget total and the share used, on a bar that turns amber at 75% and red at 90%, or with no budget total what has been spent, under No cap; and Activity shows how busy the team is: its events per minute over the last minute, a line of that pace across the last ten minutes, and the run peak, its busiest minute since the project was last reset. Below, eight tabs organize the work. The Team tab counts the project's people and agents, and the Interactions tab its messages and tasks, until approvals wait on it: it then counts those instead, in purple. A screen reader announces each count in words, such as Interactions, 3 waiting for approval.
The workspace stays live on every tab, whatever the team's run state: the header's run state, its badges and its Budget figure follow the team — a budget stop included — and so do the messages, tasks, activity and agent run state the tabs show, with no reload.
The project itself does too. When another admin edits its name, description, status, budget or idle check-in, the header, the run controls and the Budget tab show the change within a few seconds. If they set it to On hold or Archived, Start team or Resume is disabled here and says why.
So does its team. An agent another admin adds appears on the Team tab, the relationship graph and the header's counts within a few seconds, and what it writes on Interactions carries its name. One they delete leaves them, and the Team tile's working count with it. Another admin's edit of an agent — its name, model or heartbeat — is not brought to your page: reload it to see the change on the roster.
The Overview tab summarizes how the project is staffed and connected.
Pinned dashboards — the dashboards someone pinned to the Overview from the Dashboard Assistant, each a card showing its current figures, which follow the work with no reload. Click one to open the whole dashboard. The row appears only once a dashboard is pinned.
Project relationships — a live interaction graph of how people, agents, and models connect.
Recent activity — a feed of what the team's agents and people are doing, drawn from the Interactions workspace, and what the project's assistants did, as on the Activity tab.
Pinned dashboards, each showing its first figure and trend as the project stands now.
The Project relationships card on the Overview tab draws the project as a graph: who is on the team, who reports to whom, which model each agent runs on, which of the project's workspace folders each agent may read and write, which knowledge packs each agent searches, and the project's assistants beside the team. While the team is running, it also animates the work as it happens.
The graph places the team on the left, and on the right their models with the workspace beneath them, so each line runs straight from an agent to what it uses or reaches. Beacon reports to Atlas, and both run on the same model — so it collapses into a single shared node. Atlas reads the whole workspace and writes only to screens; Beacon reads and writes all of it.
Someone on the project team, labelled with their name and job title
Agent node
An AI agent, labelled with its name and the model that powers it
Model node
A model an agent runs on. Agents sharing a model share one node, so you can see at a glance which model the project leans on
Reports to edge
The reporting line between two members, mirroring the org chart. Each manager sits below the people who report to them, so these lines nest, and each arcs out to the left of the team
Uses edge
Connects an agent to its model. These edges animate while the team is running
Workspace node
The project's whole workspace, for an agent that may read or write all of it. Click it to open the Workspace tab
Folder node
A folder an agent was granted on its Access & Data tab, with its path when it is nested. Click it to open the Workspace tab at that folder
Knowledge pack node
A knowledge pack an agent searches, drawn while the project's organization is still granted it. Agents holding the same pack share its node. Click it to open the pack on the Knowledge Packs page
Accesses edge
Connects an agent to the workspace, a folder or a knowledge pack, labelled write where it may write and read where it may only read. An agent only ever reads a knowledge pack
Assistant node
One of the project's assistants, labelled with its name and kind. Assistants stand in a column of their own, outside the team, so their card is dashed, and the legend's Assistant reads key appears with them. Click one to open its chat on the Team tab
Start the team and the graph goes live — the status line reads Live — pulses show real agent heartbeats, messages, and task handoffs. Three kinds of pulse then light up the graph as the events actually happen:
Pulse
What just happened
Agent heartbeat
The agent glows green — it is taking a beat right now. With reduced motion on, it stays still and shows the word Working instead
Message (live)
A line flashes from the sender to the recipient. A broadcast to everyone glows the sender instead
Task handoff (live)
A line flashes from the task's creator to its new assignee, labelled with the task's title. It is drawn from the creator even when someone else did the reassigning
Each pulse is an event the team produced. Each agent beats on its own configured cadence — five minutes by default, and as often as every 30 seconds — so a healthy graph is calm rather than busy. If you see nothing at all, check that the team is Running and that your agents have Automatic heartbeat enabled.
Focus a member. Click a person or agent to focus it, or Tab to it and press Enter or Space. Everything it connects to stays sharp, everything else dims, and a hint reads Showing relationships for …. Click the canvas, or press the member again, to clear it.
Filter. Turn People, Agents, Models, Workspace, Knowledge or Assistants off to hide that kind of node, or use All to turn everything on or off at once. Models, Knowledge and Assistants show once the graph has a node of their kind: Knowledge appears with the first knowledge pack an agent holds, and Assistants with the project's first assistant. With every filter off, the card reads Nothing matches your filters. Your filters stay as you left them when you open another tab.
Pan and zoom. Drag to pan, scroll or pinch to zoom. Nodes cannot be dragged. The graph frames itself again when the window changes size.
If the project has no people, agents or assistants yet, the card reads No team yet — add people and agents on the Team tab to populate it. A project with assistants but no team draws its assistants alone.
The Workspace tab holds the project's files: the ones its people upload and the ones its agents produce, organized into folders by the people with Write access to it. An agent writes Markdown, CSV, JSON and plain-text files itself, into the folders it may write, and an agent at Manual approval proposes each one for approval first. When an agent calls a hosted tool that writes a file — a chart, a spreadsheet export, a Markdown summary — or saves an email's attachment, the file lands here: in the agent's default folder when it has one, and otherwise in a tool-outputs folder with one subfolder per tool server. An agent whose workspace access lets it write nowhere saves no file. Anyone who can open the project can open its files.
Browse — the tab shows one folder at a time, its folders first and then its files, each in name order. Click a folder to open it, and use the path above the list to go back up. Each file shows its name, size and when its current version was made, and its preview adds its version once it has more than one, the tool that wrote it, written by an agent for a file an agent wrote itself or uploaded for a file a person uploaded. A folder holding more than 200 items lists the first 200, and Load More at the end of the list adds the next 200.
Live — the tab follows the project as it changes: a folder someone else creates, a file they upload, move or delete, or a file a tool or an agent writes appears in the folder you have open without a reload. If someone deletes the folder you are in, the tab goes back to the top of the workspace and says so.
Preview — click a file to open it beside the list. PNG, JPEG and WebP images show inline, Markdown files render as formatted text, plain-text, CSV and JSON files show as text, laid out as they are stored, and Word documents (.docx, and macro-enabled .docm) of up to 25 MB are laid out as pages. Links in a Word document show as text and do not open. Excel workbooks (.xlsx, macro-enabled .xlsm and Excel 97-2003 .xls) of up to 10 MB show each visible sheet in a tab of its own, as a grid of what each cell displays in Excel, number, date and percentage formats applied: the first 1,000 rows and 100 columns of a sheet and the first 1,000 characters of a cell, a formula's last calculated value, and links as text. A formula the file holds no calculated value for, or only a placeholder, as in a workbook a script or library wrote, shows as written (=SUM(B2:B3)) in italics, with a line under the sheet saying Excel calculates it when it opens the file. Charts, images, colours, borders, column widths and merged cells are left out. PDFs of up to 50 MB show their pages, whose text you can select and copy; a PDF's links, form fields and scripts do nothing there. PowerPoint decks (.pptx, and macro-enabled .pptm) of up to 50 MB show as slides you scroll through, with their text, pictures, shapes, tables and charts; charts and effects are approximate, animations, speaker notes, video and sound are left out, and links show as text and do not open. A macro in a Word, Excel or PowerPoint file never runs in a preview. Every other kind of file, Word 97-2003 .doc, PowerPoint 97-2003 .ppt, binary .xlsb and SVG images included, is offered as a download rather than displayed. The Versions tab beside the preview lists the file's versions.
Download — every file can be downloaded, from its row's menu or from its preview. Links are made when you ask for one and expire shortly after, so ask again for a fresh one.
Files an agent cites — a file an agent names in a message, a task's result or an activity entry shows there as a link, usually reading as the file's path, that opens the same preview and Versions tab. A file deleted since reads deleted file.
The people with Write access to the project or above organize its workspace:
New folder — creates a folder in the folder you have open.
Rename — from a file's or folder's menu. A name must be unique in its folder, and cannot be . or .. or hold a slash.
Move… — from a file's or folder's menu, opens the workspace's folder tree to pick where it goes, the top of the workspace included. A folder cannot be moved into itself or into a folder inside it.
Delete — from a file's or folder's menu. Deleting a folder deletes everything inside it. A delete is final: there is no trash to restore from.
A folder that is, or holds, an agent's default folder cannot be deleted, or moved where that agent may not write: the refusal names the agents, and you change their default folder on their Access & Data tab first.
Folders nest at most 16 deep, and a project holds at most 5,000 folders. Each change is recorded on the project's Activity tab with who made it.
Anyone with Read access can browse, preview and download the project's files, but sees these controls disabled, with a reason naming the Write access they need.
Upload — picks one or more files, which go into the folder you have open. You can also drag files from your computer onto the list, into the folder you have open, or onto a folder's row, into that folder.
Upload new version — from a file's menu, uploads a file from your computer as that file's next version. It keeps its name and place.
A name already taken — when the folder already holds a file of the same name, AskRAI asks what to do with each such file: Replace uploads it as that file's next version, Keep both uploads it beside it with a number added, as report (2).md, and Skip leaves it out.
A file can be up to 100 MB. Each one shows its progress as it goes up, then Uploaded, or why it could not be. A file that is uploaded appears for everyone who has the folder open, and each upload is recorded on the project's Activity tab.
An Outlook mailbox archive, a .pst or .ost file, can be up to 20 GB. One larger than 100 MB goes up in parts:
Progress — the row shows how much of the archive has gone up.
A part that fails is sent again on its own, a few times. If it still fails, the row says so and offers Retry, which carries on from the parts not yet sent rather than starting over.
Cancel — stops the upload. Nothing of it is kept, and the room it set aside is freed at once.
Time — an archive must finish uploading within 23 hours of starting, about 2 Mbit/s for 20 GB. Past that, it is refused and has to be uploaded again.
A 20 GB archive is larger than the 10 GB file storage allowance your tenant starts with, so it needs AskRAI to raise the allowance first: the upload says so when there is not room for it.
Once uploaded, an archive is indexed, its folders and messages read one part at a time, and its row shows how far that has got:
Waiting to be indexed, then Indexing, with the messages indexed so far: Indexing: 4,210 messages so far. A 20 GB archive takes an hour or two.
Indexed — how many messages it holds: 19,038 messages indexed. A damaged archive can hold folders or messages that cannot be read. They are skipped and counted, never left out silently: 19,038 messages indexed; 2 folders and 193 messages could not be read.
Not indexed — why, in words: the archive is encrypted, its format cannot be read, it is too large, or indexing kept failing.
The index counts against your tenant's file storage allowance beside the archive itself.
Once an archive is indexed, the agents granted a mailbox connection can search its messages and read them.
A file's type comes from the extension in its name, and AskRAI keeps that type only when the file's contents bear it out: PNG, JPEG and WebP images, PDFs, Word, Excel and PowerPoint files (macro-enabled and Excel 97-2003 ones included), Outlook mailbox archives, Markdown, CSV, JSON and plain text. A file of any other type, or whose contents do not match its extension, is kept as a plain download, but for a mailbox archive larger than 100 MB, which is refused.
Every file keeps its versions. A file's Versions tab lists them newest first, each with its number, who made it — the tool and the agent that called it, the agent that wrote it, or the person who uploaded or restored it — what made it, when, and its size, with the current version marked Current. A version an agent proposed at Manual approval also names who approved it: Written by Atlas · approved by Nadia Rahman. A file keeps its last 50 versions; an older one leaves the list.
Open — shows that version in the Preview tab, where you can download it too. Anyone who can open the project can open any version.
Restore — the people with Write access to the project or above can restore an earlier version. AskRAI copies it and makes the copy the file's new current version, numbered after the newest, so the versions before it stay in the list, the one restored included, until the file passes the 50 it keeps. Each restore is recorded on the project's Activity tab.
Anyone with Read access can open every version, but sees Restore disabled, with a reason naming the Write access it needs. A restored copy takes up storage as any file does, so a restore is refused while your tenant's file storage allowance is full.
The agent that called the tool is told each file's name, type, size and link, so it can cite the file in its messages, where it shows as a link to the file. The tool's result never carries the file's contents.
AskRAI checks every file before it appears here. A file's type comes from the extension in its name, not from what the tool claimed, and is kept only when its contents bear it out, so a file named as an image whose contents are not shows as a plain download. A tool can only write files into the project whose agent called it.
All of your tenant's projects share one file storage allowance, 10 GB unless AskRAI has raised it. The bottom of the Workspace tab shows how much of it your tenant's files use. Once it is used up, uploads and restores are refused, an agent's own file is not saved and the agent is told why, and hosted tools still run but can no longer save new files: the agent is told, and the call's row in the tool's Calls tab reads Not saved: workspace storage is full or unavailable; overwritten and removed copies count until they expire.
An upload sets aside room for its file as it starts. A file you upload counts at once; one abandoned before it finishes uploading keeps its room for about two hours, and a mailbox archive going up in parts for up to 23 hours unless you cancel it.
A file an agent writes counts as it is written, a proposal waiting for approval included. Rejecting a proposal frees its room only once AskRAI removes what the agent wrote and its kept copy expires, up to about 39 days later.
Every hosted call sets aside room for its files. For about 17 minutes after it starts, a call holds room for the most it could save, 5 files of 25 MB, until AskRAI has counted what it actually saved. So an empty 10 GB allowance has room for about 80 calls in any 17 minutes, and fewer as it fills; a call past that runs without saving files.
Overwritten and removed copies count until they expire. AskRAI keeps each copy of a file that is overwritten or removed for 30 days. A tool that saves to the same file again and again uses room for every copy, and once that fills the allowance, hosted calls save no files until enough copies expire.
Deleting a project frees its share only once its files are removed and their kept copies expire, up to about 39 days later.
The Activity log lists what happened on the project, newest first: what its agents and people did, and what its assistants did. An assistant is not on the team, so each of its entries is marked Assistant: when it joined the project and when it left. Show assistants, beside the title once the project has had an assistant, takes their entries out of the list and puts them back. Load more reads older entries.
Each call an agent makes to one of its tools is an entry too, such as called crm_createCase on tool server 'CRM', with the tool's name at its right; one the platform refused before it ran reads could not call. Click it to see the tool and its server, the input the agent sent and the start of what came back, with the server's credentials removed. A call whose input a guardrail refused shows none. A call made to a server while it is marked as a simulated system is marked Simulated, and keeps the server's name and mark as they were then. Agents do not read these entries in their own activity, so a busy team's lookups never crowd out its tasks and messages.
A reset clears the team's entries and leaves the assistants'.
The Budget tab tracks spending against the project's budget total.
The Budget tab follows spend as the team's agents beat and its assistants reply, so the latest figure appears without a reload.
When a budget is allocated, the Budget overview shows the amount used against the total (for example $62.43 of $100 allocated), the percentage utilized over a bar, and rows for Allocated, Spent by the team, Spent by assistants while the project has assistants or a removed one has spent or replied, and Remaining, the last of which reads an amount, At budget limit, or Over budget by $20.00. The two spent rows add up to the amount used. If no budget is set, the tab reports that spend is uncapped, tells you how much has accrued so far, and prompts you to edit the project to allocate one.
Under Spent by the team, each agent on the team has a row with its spend and its share of what the team has spent, largest first; an agent that has not spent anything reads no spend yet. Deleting an agent removes its row but not its spend, so a last row, Deleted agents and earlier spend, holds whatever the agents listed do not account for, so the rows cover all of the team's spend. A project with no budget lists the same rows, since a share is of what was spent rather than of a budget.
Under Spent by assistants, each of the project's assistants has a row with its spend and how many replies it has given, counting everyone's chats with it, in the order they were added. Removing an assistant keeps its spend, so its row stays while it has spent anything or given a reply.
The Budget tab reads amounts of $100 or more in whole dollars. Below that, they read in dollars and cents, and small amounts are never rounded away: a project that has spent a fraction of its budget total reads <1% utilized rather than 0%, one that is nearly exhausted reads >99% utilized rather than 100%, and an amount under a cent keeps two significant digits, such as $0.0041, rather than reading $0.00. The project header's Budget tile carries the same percentage, as <1% used, beside what has been spent of the budget total.
The budget total is the only budget value you set directly. Usage accrues automatically as the project's agents beat and its assistants answer — each beat and each answer is priced from its model's token rates, which you can set per model on Model Providers. The cap is measured against the project's lifetime spend; it does not reset at the start of a month.
When a project exhausts its budget, AskRAI hard-stops the whole team: every agent stops, the run state becomes Stopped, and the project's status is set to On hold. The header's Budget tile reads Budget exhausted and Start team is disabled. Recovery therefore takes two steps — raise the Budget total (USD)and set the status back to Active — because raising the budget alone leaves the project on hold, and Start team stays disabled until its status is Active. Neither edit restarts the team: once both are saved, press Start team. Lowering the budget total below what the project has spent changes no status: on a project still Active, raising the budget is the only step before Start team.
The people on the project's team who hold Write access or above — or, when none does, the next in line — also receive a notification of the stop, which opens this tab. So does an agent stopped by its own spend cap.
Beneath the budget, the Budget tab reports the project's Idle check-in — the longest an agent with nothing to do waits between beats.
The readout states the ceiling in plain units, and says outright that a wake overrides it.
This is the other half of what a team costs. The budget total bounds the total a project may spend; Idle check-in bounds the rate a team that has finished its work keeps spending, because a beat is a model call whether or not there is anything to do. An agent whose beats change nothing doubles its own interval toward this ceiling; anything sent to it — a message, a task, a person acting — wakes it immediately regardless. See Agent Heartbeat for the full rule.
The Dashboard tab is one grid of cards and charts that the people on the project arrange for everyone who reads it: dashboards pinned from the Dashboard Assistant, charts of the project's events, and figures your own systems write through the API. See Dashboard.
The Events tab declares the event types the project records, such as a case closed and whether the customer stayed, and lists the events its agents and people have recorded. See Project Events.
Open More in the project header and choose Edit to open the edit dialog. Editing is where you set the project's status, budget and brief. Edit opens with Write access to the project, which writes the brief; every other field needs Admin, and with Write alone they are disabled, under a reason naming the Admin access they need. With Read, Edit is disabled, with a reason naming the Write access it needs.
The edit dialog adds Status, Budget total (USD), Idle check-in (minutes), Assistant suggestions and the brief on top of the name and description.
The edit dialog exposes these fields:
Field
Description
Name
The project's display name (required), unique within the organization as on create. The project's own name always saves, in another case too, as does a name two projects already shared
Description
A short summary of the project's purpose
Status
Active, On hold, or Archived. Saving On hold or Archived stands a running team down as soon as you save — see Project status
Budget total (USD)
The ceiling on total project spend, in US dollars. Must be greater than zero; cents are accepted. Leave it blank for no budget
Idle check-in (minutes)
The ceiling an idle agent's interval backs off to. A whole number of minutes from 1 to 525,600 (one year)
Assistant suggestions
Whether the project's assistants speak up unasked when a run hits something they can help with. On for a new project. Each suggestion is charged to the project's budget
Brief
The team's first message, up to 400 characters, which waits in the message composer while the project has no messages. Nothing is sent until someone sends it. Clear it to remove the brief
Brief goes to
Whom the brief starts addressed to: Everyone on project, or one person or agent on its team
Click Save changes to apply. A value a field cannot take is named under that field as you type, and Save changes stays disabled until you correct it. Zero, a negative number, or text the field cannot read as a number in Budget total reads Enter an amount above $0, or leave it blank for no cap. To remove a cap entirely, clear the field rather than setting it to zero.
The dialog keeps the values it opened with, even if another admin changes the project while it is open. If they change a field the dialog shows, it says so above the fields. Saving writes only the fields you changed, so their change to any other field stands. To see their change, close the dialog and open it again. If you both changed the same field, the later save wins. Saving without changing anything closes the dialog and writes nothing.
Idle check-in is checked the same way: a value outside 1 to 525,600, or one that is not a whole number, reads Enter a whole number from 1 to 525600. under the field.
A project's status decides whether its team may run at all; the run controls in the header decide whether it runs now. Only an Active project's team can run.
Status
Meaning
Active
The project is in normal use, and its team can be started
On hold
Work is on hold. Saving On hold while the team runs pauses it as soon as you save: the run state becomes Paused, and every running agent stops beating and spending. A beat already under way finishes
Archived
The project is retired but retained for reference, and is read-only. Saving Archived while the team runs stands it down the same way, except that the run state becomes Stopped
While the status is not Active, Start team — or Resume, on a paused team — is disabled, and the reason is shown under the run controls: Project is on hold — set its status to Active to run the team, or Project is archived — set its status to Active to run the team. An agent's Run heartbeat on its Heartbeat tab and the Resume on its Budget tab are disabled too, with the same reason. Pause and Stop stay available whatever the status, so you can always wind a team down.
The save only moves what is still running. A team you had already paused or stopped keeps its run state, and so does an agent stopped on its own — from its own run control, or by its own spend cap.
Setting the status back to Active restarts nothing. Once it is saved, press Resume in the header for a paused team, or Start team for a stopped one — the same last step as recovering from a budget stop.
While a project is Archived, nothing on it can change: no message can be sent, no task created, edited or deleted, no proposal approved or rejected, nobody added to or removed from its team, no agent created or edited, no workspace file or folder uploaded, renamed, moved, deleted or restored, no event type declared or event recorded, and no Dashboard arranged. A reset is refused too. Everything stays readable: its messages, tasks, team, agents' settings, workspace, activity and budget.
The header says Read-only: Project is archived — set its status to Active to change it. The message and task composers are not shown, and every other control that would change something is disabled with that reason. AskRAI refuses these changes however they are made, not only in the console. To work on it again, edit the project and set its status to Active — Edit and Delete stay available on an archived project.
Open More in the project header and choose Delete to open a confirmation dialog. Deleting a project is permanent, so AskRAI asks you to confirm.
Deleting a project needs Admin access to it, which every Platform Admin holds. Anyone else sees Delete disabled, with a reason naming the Admin access it needs.
Deleting a project permanently removes it and cannot be undone. The confirmation dialog names the project and warns that it will be permanently deleted with its agents, its team and its workspace files, and every task, message and activity entry on it — make sure you have selected the right project before confirming.
The project's team and its work go with it:
Its agents are deleted, together with their skill pins, tool grants and governance attachments. The skills, tool servers, guardrails, policies and egress allowlists themselves stay, and stop counting those agents as users, so an agent of a deleted project never holds up deleting one.
Its people come off the team. They stay in your directory.
Its workspace files are deleted.
Its tasks, messages and activity are deleted.
Its notifications and run state are removed.
Its proposals and beat transcripts are kept as the record of what its agents did, but no screen can reach them once the project is gone. To remove them too, Reset the project before you delete it.
Anyone else with the project open learns of the delete within a few seconds. Their workspace is replaced by a page saying This project was deleted, which offers no control but Back to projects, and the project leaves their project list. Someone whose connection had dropped meanwhile, or who stops being able to read a project while it is open because it is no longer shared with them, sees This project is no longer available to you instead, within about 30 seconds.
You see no organizations or projects, and Projects reads Nothing is shared with you yet
No organization or project is shared with you
Ask one of the Platform Admins the message names to share an organization or a project with you, then reload the page
No organizations yet appears instead of projects
The tenant has no organizations, which projects require
Create an organization under Admin → Organizations, then return to Projects
The project list is empty or unexpected
A different organization is active, or the project is not shared with you
Confirm the active organization in the header org switcher — the list is scoped to it — and ask one of the project's Admins to share it with you
The + button, New project or Create → Project is disabled, with a reason naming Write access to this organization
You hold less than Write on the active organization
Ask one of its Admins, or a Platform Admin, to share it with you at Write, then reload the page
Edit in the project header's More menu is disabled, with a reason naming Admin access
You hold less than Admin on the project
Ask one of its Admins, or a Platform Admin, to make the change
Name reads This organization already has a project named '…', and Create or Save changes is disabled
Another project in the organization goes by that name, differing at most in case, symbols or extra spaces
Choose a name that differs by more than that. The project the message names may not be shared with you
Save changes is disabled and Budget total reads Enter an amount above $0, or leave it blank for no cap.
Zero, a negative value, or text that is not a number was entered in the edit dialog
Enter a number greater than zero, or clear the field for no budget
The Budget tile reads Budget exhausted and Start team is disabled
The project spent its budget total and hard-stopped, which also set its status to On hold, or its budget total was lowered below what it has spent, which leaves it Active
Raise the Budget total (USD), set the status back to Active if it is On hold, then press Start team
Start team or Resume is disabled and reads Project is on hold — set its status to Active to run the team (or Project is archived — …)
Only an Active project's team can run
Set the status back to Active when editing the project, then press Start team or Resume
The team stopped beating right after you saved the project
You saved its status as On hold or Archived, which stands a running team down at once
If that was not intended, set the status back to Active and press Resume (On hold) or Start team (Archived)
A project is missing from the sidebar
It is Archived, which the list leaves out
Switch on Show archived under the search box
Nothing on a project can be changed, and the header reads Read-only
An agent says it wrote a file, but the Workspace tab does not show it
The tab lists what was there when you opened it, or the tool linked a file it never finished uploading
Open the tab again; a file the tool never finished uploading is not added
An agent says it saved a file itself, but the Workspace tab does not show it
The agent is at Manual approval, so the file waits in Pending approvals, or the folder left the agent's write access before the file was saved, which the Activity tab names
Only PNG, JPEG and WebP images, Markdown, plain-text, CSV and JSON files, Word documents, Excel workbooks, PDFs and PowerPoint decks are shown in the console
Use Download to open it on your computer
A PDF says The file is protected by a password
The PDF needs a password to open, which the preview never asks for
Use Download and open it on your computer with its password
A link in a message or a task's result reads deleted file
The file the agent cited has been deleted since, or was never one of this project's files
A delete is final; ask the agent to write the file again if it is still needed
An upload is refused with This organization's workspace storage is full
Your tenant's files use its whole file storage allowance, which the bottom of the Workspace tab shows
Delete files you no longer need, whose room frees once AskRAI removes them and their kept copies expire, or ask AskRAI to raise the allowance
A file you chose to upload is refused as larger than 100 MB
A workspace file can be at most 100 MB, but for an Outlook mailbox archive (.pst, .ost), which can be 20 GB
Split it, or share it from where it already lives
A mailbox archive is refused with This organization's workspace storage cannot hold this archive
The archive is larger than the room left in your tenant's file storage allowance
Ask AskRAI to raise the allowance, then upload it again
A mailbox archive's upload ran out of time
It did not finish within 23 hours of starting
Upload it again from a faster connection
A .pst or .ost larger than 100 MB is refused as no Outlook mailbox archive
Its first bytes are not an Outlook data file's, though its name says so; nothing of it is uploaded
Export the mailbox from Outlook again, and upload that file
A mailbox archive reads Not indexed: it is encrypted and cannot be read
An .ost that Windows encrypted for its own computer, which only that Outlook can open
In Outlook, export the mailbox as a .pst file, and upload that
A mailbox archive reads Not indexed: its format cannot be read
The file is damaged, or is not an Outlook data file at all
Repair it with Outlook's Inbox Repair Tool, or export the mailbox again, and upload that file
A mailbox archive reads Not indexed: indexing kept failing
Indexing failed five times in a row on AskRAI's side
Upload it again as a new version; if that fails too, contact AskRAI
A mailbox archive reads Not indexed: no message in it could be read
The archive opened, but every folder holding mail is damaged
Repair it with Outlook's Inbox Repair Tool, or export the mailbox again, and upload that file
An indexed archive says some folders or messages could not be read
Those parts of the archive are damaged
Repair it with Outlook's Inbox Repair Tool and upload it again as a new version
A Word, Excel or PowerPoint file shows as a plain download of no particular type
Its contents are not the file its extension names, such as a renamed ZIP
Open it in its application, save it again under its proper type, and upload that
A macro-enabled (.docm, .xlsm, .pptm) or Excel 97-2003 (.xls) file shows as a plain download of no particular type, though its contents are right
It was uploaded before AskRAI previewed these files
Upload it again as a new version
An .xls file's preview says the file could not be read
It is another Office 97-2003 file under an .xls name, such as a Word .doc, or a workbook locked by a password
Use Download to open it on your computer
An agent beats far less often than its interval says
The project's team has been idle, so the agent has backed off toward Idle check-in
Send the agent something, or lower Idle check-in when editing the project
Save changes is disabled and Idle check-in reads Enter a whole number from 1 to 525600.
A fractional or out-of-range value in the edit dialog
Enter a whole number of minutes within the range
Delete in the project header's More menu is disabled, with a reason naming Admin access
You hold less than Admin on the project
Ask one of its Admins, or a Platform Admin, to delete it — or to share it with you at Admin, then reload the page
A workspace control, such as Upload, New folder or Restore, is disabled, with a reason naming Write access
You hold less than Write on the project
Ask one of its Admins, or a Platform Admin, to share it with you at Write, then reload the page
Build a project team of people and AI agents, organize them into a reporting hierarchy, and configure each agent's model and behavior from the project's Team tab
The Team tab is where you staff a project with the people and AI agents that do its work, and arrange them into a reporting hierarchy. People come from your directory; agents are configured here with a model and behavior. Open it from the Team tab inside any project workspace.
The org chart shows the whole team at a glance — people and AI agents (tagged AI, labeled with their model) connected by reporting lines.
People — members drawn from your organization's directory. Each carries their directory identity (name, email, job title, department). The project's agents know each person by their directory name, too. Someone your directory has deprovisioned or suspended stays on the team, and agents are told so: an agent that messages them or gives them work is refused, and has to address a current teammate instead. Nobody else can message them or give them work either, since they cannot sign in to see it. The tasks they already hold stay theirs until someone reassigns them, because a suspension can be lifted.
Agents — AI agents you create on the project, each backed by a model and an optional behavior prompt.
Both kinds share one reporting hierarchy: any member can report to any other member, whether person or agent. The Team header shows the total member count for the project.
A place on the team grants nothing by itself: what someone may decide on a project comes from their access level on it. Adding a person, changing a person's reporting line and removing one need Write access to the project, and the person you add must already hold Write or above on it, so Add person offers only those people. To add someone who does not, share the project with them at Write first.
Anyone with Read access still sees the whole team, but Add person, a person's Reports to (org chart) and Remove from project are disabled for them, with a reason naming the Write access they need. A project starts with whoever created it on its team, unless a Platform Admin created it.
Agents follow the same levels. Adding an agent and changing its settings need Write. Changing an agent's autonomy, deleting an agent and deleting the project with its whole team need Admin. Levels are given per project, from its Share dialog. Admin on the project's organization, or a role on Access holding Administer every organization or Administer every project, also gives Admin on it.
Switch between two views of the team using the toggle in the Team header:
Org chart — a visual hierarchy. People appear as cards with their initials; agents appear as cards tagged AI and labeled with their model. The chart fills what the tab has left of the window and refits when the window changes. Paused agents are dimmed, and a dimmed agent is genuinely idle: it is not beating and not spending. While the team runs, a running agent's card is ringed in green with a dot before its name, and while its latest beat has recorded an action, the line under its name shows that action in place of its model: in green, or in red when the beat failed. Hover the dot to read Running, or the line to read the whole action. Every member with no manager sits at the top of the chart, with no line to anyone: a line is drawn only where a member reports to another. Click any card to open that member's details. When viewing the chart, use Fit to screen, Expand all, and Collapse all to navigate large teams.
List — a sortable table of every member. A running agent carries a Running badge in its Status column.
A person who has left your organization — your directory has deprovisioned them — stays on the team until you remove them, but reads Name (former user) and is dimmed, here, in their detail panel and on the project's Overview graph. A person your directory holds no record of is named the way the Interactions tab names them, and reads Former user when the directory cannot name them.
List view shows people and agents together. The Title / Model column holds a person's job title or an agent's model, which is why one column carries both.
In the list view you can:
Search members by name, title, email, or model.
Filter by type — All types, People, or Agents.
Filter by status — All statuses, Active, Paused, or Archived (agents only; people have no status).
Beside the org chart, a narrow strip holds the project's assistants: the Dashboard Assistant, Team Builder and the Integrations Assistant. They aren't on the team, take no tasks and message no agents. Click one to open its chat, or + to add one.
Click Add person to assign someone from your directory to the project. It needs Write access to the project, and offers only the people who hold Write or above on it — see Who can change the team's people.
Search your directory, select a person, and choose who they report to before adding them to the project.
Open the panel. Click Add person in the Team header. The panel explains that you are adding someone from your directory.
Search the directory. Type a name, email, or department in Search directory. People already on the project are excluded from the results, and so are people who hold less than Write on it.
Select a person. Click a candidate in the Select person list to choose them.
Choose a manager.Reports to starts at a person at the top of the org chart who has not left, or at No manager (top level) when there is none. Pick another team member to place the person under, or No manager (top level) to add them at the top.
Add to project. Click Add to project. The person joins the team and appears in both views.
You choose a person's manager when you add them, and you can change it later: open the person from the org chart or list, pick a new manager under Reports to (org chart) in their Project assignment card, and click Save and close at the foot of the panel. Agents' reporting lines are editable the same way (see Configuring an agent).
Click Add agent to create an AI agent on the project, or choose Create → AI Agent at the right of the top header, which opens the Team tab and the same panel from any tab of the project you have open. It needs Write access to the project: anyone else sees it disabled, with a reason naming the Write access it needs. On an Archived project it is disabled for everyone, and Create → AI Agent is also disabled while no project is open.
Give the agent a name and the model that powers it. Its heartbeat and governance start from safe defaults, which you can change before you add it.
Open the panel. Click Add agent. The From scratch tab is selected by default. To start from a configuration your organization already has, use From template instead.
Choose an avatar. Pick Initials (auto-derived from the name) or an Icon.
Name the agent. Enter a Name of up to 120 characters — this is required. It must differ from the name of every other agent, and every person, on the project's team by more than case, symbols or extra spaces.
Describe it (optional). Use Description to note what the agent does on the project.
Pick a model. Select the Model that powers the agent. The list comes from the chat models available to your tenant, each named with the provider it runs on, so two providers' models of one name read apart — see Model Providers. A decision model writes no text, so it cannot run an agent and is not listed. The optional Decision model offers decision models only: see Decision model.
Set behavior (optional). Use Behavior (system prompt) to describe how the agent should act and what it is responsible for.
Choose a manager (optional).Reports to starts at a person at the top of the org chart who has not left, or at No manager (top level) when there is none. It never starts at an agent, because an agent manages its reports' tasks. Pick another member, agent or person, to place the agent under, or No manager (top level) to add it at the top.
Set its heartbeat (optional). Under Heartbeat, switch on Automatic heartbeat to let the agent beat by itself while the project is running, and set its Interval (seconds), Autonomy, Max actions per beat, Max tool calls per beat and Events per beat. They start from the defaults of its Heartbeat settings: off, 300 seconds, Manual approval, 3 actions, 5 tool calls and 10 events, and take the same ranges. Only someone with Admin access to the project can choose an autonomy above Manual approval: for anyone else Autonomy is disabled, with the reason.
Choose its governance (optional). Under Governance, choose the policies, guardrails and egress allowlist the agent starts under. Baseline safety is ticked for you. This section needs the governance permission: without it the panel says the agent starts with nothing attached, and someone who manages governance attaches it on the agent's Guardrails tab.
Add the agent. Click Add agent. While it is disabled, the line under it names what it still needs, such as a name. The agent joins the team with Active status. If you switched on Automatic heartbeat and the team is running, it starts at once, with its first beat due straight away.
An agent template is a complete agent configuration your template admins, the holders of Manage agent templates, keep once and grant to organizations. The From template tab lists the published templates granted to this project's organization, and the platform's own, with a badge on each: Ready when everything it names applies here, or how many items are not available.
What the template applies here, and what it does not and why, is shown before anything is created.
Pick a template. Search the gallery or narrow it by category, and select a card. The panel shows what the template will be applied as here: each skill, tool, policy, guardrail, egress allowlist, workspace folder and knowledge pack it names, under Applied or Not applied, and why each one is not applied — not granted to this organization, not adopted, a draft, unpublished, and so on. An item matched by an equivalent, such as a skill or knowledge pack of the same name, says so. Folders the template names that this project does not have yet are listed as folders it will create, for people with Write access to the project or above, who may create folders; for anyone else they are not applied.
Fix what you can (optional). Someone who manages the item sees how to fix it beside it: Grant to this organization for a tool server or a knowledge pack, Adopt for a platform skill, Activate for a draft guardrail, policy or allowlist. The panel then reads the template again.
Name the agent. Enter its Name, and change its description, avatar and manager if you like. When the template's model is not one of your tenant's, pick a Model: the template's is shown as a hint.
Check its heartbeat. The Heartbeat section starts from the template's. The autonomy line says what the agent will start at.
Acknowledge what will not be applied. When anything is not applied, tick I understand N items will not be applied, and the button reads Add agent (partial).
Add the agent. While the button is disabled, the line under it names what it still needs (a name, a model, heartbeat settings in range or your acknowledgement), and the panel says so when no agent can be made from this template here: among other reasons, when it gives the agent a knowledge pack the organization holds that no group of yours grants, since an agent gets only the packs the person making it can read. The agent is a copy of the template's published version, with the template's prompt, goals, model settings, skills, tools, governance, workspace access and knowledge packs, with their notes, as the panel showed them. If any of that changed since you opened the template — a tool granted, a guardrail activated, a new version published — the panel says so and shows the template again, so you never add an agent you have not reviewed.
Two things keep an agent made from a template safe:
A missing control starts it at Manual approval. When a guardrail, policy or egress allowlist the template names is not applied, the agent starts at Manual approval whatever the template's autonomy, so every action it takes is a proposal until the control is attached, or a project Admin decides to do without it, and an Admin raises its autonomy. A knowledge pack not applied does not: it only takes away what the agent could look up.
Only someone with Admin access to the project starts it above Manual approval, as with any new agent. For anyone else the agent starts at Manual approval, and the panel says why.
The template's guardrails, policies and allowlist are attached even when you do not have the governance permission: a template admin chose them when they published the template, and a control only ever narrows what an agent may do.
The agent's Overview tab shows which template and version it was made from — From Corporate Writer · v3. The agent is a copy: a later version of the template, or a change to it, never changes the agent. The same line tells you what has happened since:
A newer version. When the template has published a later version, the line reads v5 available. What changed opens what that version changed against the one the agent was made from, by the template editor's tabs: Overview, Behavior, Skills & Tools, Guardrails, Heartbeat & Budget and Workspace. It is read-only, and nothing in it changes the agent.
A deleted template. The agent keeps the template's name, and the line says template deleted. When the template is no longer granted to this project's organization, it says so, and shows no newer version.
Items not applied.3 not applied lists what the agent was made without, each one looked up again as you open the pane: Available now, or why it still is not. Someone who manages the item sees its fix beside it — Grant to this organization, Adopt or Activate — as when the agent was added.
The tool server granted to this organization since the agent was made is available now; the guardrail is still a draft.
What a newer version changed, shown beside what the agent was made from. Nothing here changes the agent.
When something has become available, the line reads 1 now available, and Apply adds it to the agent as it applies here now: a skill at its published version, a tool server's tools that are approved, a guardrail, policy or allowlist, a workspace folder where the template gave it access, a knowledge pack with the template's note. Applying an item takes it off the list. Applying never raises the agent's autonomy: an agent held at Manual approval for a missing control stays there until someone with Admin access to the project raises it.
Applying needs Write access to the project, as any edit to the agent does. A guardrail, policy or allowlist applies without the governance permission: a control only ever narrows what an agent may do.
A tool never widens a grant. When you have narrowed the agent's access to a tool server by hand, applying the template's tool adds it beside your choice, and applying the whole server leaves your narrowing as it is.
An item you added by hand stays listed until you next choose Apply, which finds it already on the agent and takes it off the list.
The agent's display name, up to 120 characters. Agents are told their own and each other's names on every run, in a plain form: on one line, without punctuation such as :, / or quotes. An agent named Sales: EMEA reads to them as Sales EMEA, and that is the name they use when they write about it. Because agents address each other and the project's people by name, an agent may not share one with another agent or a person on the team: names that differ only in case, symbols or extra spaces, such as Sales: EMEA and sales emea, count as the same. A person goes by their name in your directory
Yes
Description
A short summary of what the agent does, up to 1,000 characters
No
Model
The model that powers the agent, chosen from the tenant's available models
Yes
Decision model
A decision model that checks whether a scheduled beat has anything to act on, and whether a task the agent creates is one it already has. See Decision model
No
Behavior (system prompt)
Instructions describing how the agent should behave, up to 40,000 characters
No
Status
Active, Paused, or Archived (set when editing). A Paused agent stops beating and stops spending as soon as you save; a beat already under way finishes. Setting Status back to Active restarts it straight away, if the team is running, its automatic heartbeat is on and it is within its budget. Archived is the permanent form of the same thing
Defaults to Active
Reports to
The member this agent reports to, or top level
No
Heartbeat
Automatic heartbeat, Interval (seconds), Autonomy, Max actions per beat, Max tool calls per beat and Events per beat, as on the agent's Heartbeat tab
Defaults to off, 300, Manual approval, 3, 5 and 10
Governance
The policies, guardrails and egress allowlist the agent starts under, as on its Guardrails tab. Shown to someone with the governance permission
Click an agent — a card in the org chart or a row in the list — to open its detail panel.
The reporting line is what the org chart draws, and it is how a manager agent knows whose work to oversee: each of its beats includes what its direct reports have been doing.
The agent's avatar sits in the panel header — click it to open Edit avatar and choose an Initials or Icon avatar. Below the header, the settings are split across two tabs, each saved with Save and close:
The Overview tab is the agent's identity: Name, Description, Model, Status (Active, Paused, or Archived — see Status), Reports to, and Decision model. An agent's reporting line is editable here at any time; AskRAI prevents a reporting loop by excluding the agent and everything beneath it from the options. This tab also holds Delete agent.
The Behavior tab shapes how the agent works: Goals (one per line, at most 50, each up to 1,000 characters), the System prompt prepended to every run (up to 40,000 characters), and an Advanced section for model parameters (temperature, max tokens, top P) and response settings (format, language, citation style). On an Anthropic or Amazon Bedrock provider, or a Custom provider whose model name is a Claude model ID, alone or with a gateway's prefix or suffix (such as anthropic/claude-opus-5-5), a Claude model is sent the temperature but never top P, which Claude 4 and later refuse beside a temperature, and Claude Opus 4.7 and every Claude model after it take neither, so they run on their own sampling settings. On Amazon Bedrock, an OpenAI GPT model that reasons, such as GPT-6, refuses both temperature and top P, so it is sent neither and runs on its own sampling settings; the open-weight gpt-oss is sent both. A GPT model's reasoning counts against max tokens, so where it offers a low reasoning effort, it reasons at that. An agent that already holds a longer prompt or more goals, from a template say, keeps them, and saves its other settings as before; only text you add past a limit is refused.
Changing either tab needs Write access to the project.
A holder of Manage agent templates, Platform Admins among them, also sees Save as template in the panel header. It copies the agent's saved configuration into a new, unpublished agent template, granted to this project's organization, and offers a link to open it in Admin. The agent itself is not changed.
Someone with Write access to the project who cannot manage agent templates sees Suggest as template there instead. It sends the agent's configuration as it stands, with an optional note, to your template admins, who may edit it before they publish it, or reject it with a reason — and the bell tells you which. The dialog says what publishing means: everyone in the organizations the template is granted to can create agents from it, its prompt included. For an agent made from a template, you can suggest it as a new version of that template instead. While a suggestion waits, the panel says so, and you can Withdraw suggestion, once you confirm: your template admins can no longer approve it, and suggesting the agent again sends it as it stands then, with its note written afresh. See Suggestions.
Save and close writes only the fields you changed on that tab, so another admin's change to any other field of the agent stands. Model parameters are written as a set when any one of them changed, and so are response settings. Saving without changing anything closes the panel and writes nothing. If you both changed the same field, the later save wins. When the panel learns that the agent was changed in another session after you opened it — as it does when you save the avatar — the tab says so; close the agent and open it again to see the current values.
Goals are what the agent is told to pursue on every beat, so editing them changes the agent's behaviour from its next beat onward — there is nothing to restart.
The Heartbeat tab is where you set how often the agent acts and how much it may do without you — see Agent Heartbeat & Autonomy.
The panel header also holds the agent's own run controls. Start agent starts this agent; once it runs, the header shows Running with Pause agent and Stop agent beside it, and a paused agent shows Resume. Each acts on this agent alone and leaves its teammates where they are. While the agent runs, the line under its name shows what its latest beat did.
The team follows its agents. Starting or resuming an agent on a stopped or paused team runs the team with it, and the project header reads Running, while every other agent stays where it was. Pausing or stopping the last agent that runs pauses the team, or stops it once none of its agents is paused either. To start every agent that may run at once, use Start team in the project header.
Start agent and Resume are disabled, with the reason under them, when the agent may not run: its status is not Active, its automatic heartbeat is off, the project is not Active or has spent its budget, the agent has spent its own spend cap, or no chat model is connected. Pause agent and Stop agent stay available, so you can always wind an agent down. All of them need Write access to the project; anyone else sees them disabled, with that reason.
On a wide screen the tabs stand in a rail beside the settings, grouped as Profile, Capabilities, Safety & cost and Monitor. On a narrower one they sit in a row above the settings, which scrolls sideways when they outrun it.
Tab
What it does
Overview
Name, description, model, decision model, status, and reporting line — plus Delete agent
Behavior
Goals, the system prompt, and (under Advanced) model parameters and response settings
Attach policies and guardrails, choose an egress allowlist, and read what the selection composes to. Platform Admins and holders of Manage policies, guardrails and egress only: a holder of View policies, guardrails and egress also sees what the selection composes to, and anyone else sees what is attached, read-only
Whether agents outside AskRAI may hand this agent work over the A2A protocol, the API keys they call with (Create key makes an A2A credential, which calls only the agents that list it), the skills and input it offers them, the limits their requests are held to, and a preview of the agent card they read. Changing it needs Admin access to the project; anyone else sees it read-only
Only people with Write access to the project or above, whatever the agent's autonomy: everything on its Overview tab but Delete agent, everything on its Behavior, Skills & Tools, Budget and Access & Data tabs, and everything on its Heartbeat tab but Autonomy. Anyone with Read access sees those controls disabled, with a reason naming the Write access they need.
Two things are held further:
Autonomy and deleting need Admin.Raising autonomy lets the agent act without the proposals that Write decides, and deleting it rejects the ones it has waiting.
Skills and governance need a permission. Pinning skills takes View skills or Manage skills, so anyone else sees a note on the Skills card instead of a picker — see Skills. The Guardrails tab is held as its row above says.
Whoever raises an agent's autonomy takes the agent as it then reads. Nothing asks you to re-read an agent before it starts acting on its own, and until that moment anyone with Write access to the project could have edited it. Review its name, goals, system prompt, model parameters, skills, tools, workspace access and knowledge packs each time before you raise its autonomy above Manual approval.
The three response settings under Advanced on the Behavior tab say how the agent writes. They take effect on every heartbeat: each beat tells the agent's model all three.
Setting
What the agent is told
Options
Default
Format
How to format what it writes for others: messages, task results and activity notes
Markdown, Plain text, JSON
Markdown
Language
Which language to write in
A BCP-47 language tag such as en or fr-CA, at most 35 characters
en
Citation style
How to cite a source it relies on
Inline, Footnotes, None
Inline
They are instructions to the model, like the agent's system prompt — not a filter applied to its output afterwards.
Every agent has all three, whether or not anyone has set them. An agent left on the defaults is told to write in en, so if its instructions ask for another language, set Language to match.
The Workspace card on the Access & Data tab decides which of the project's workspace folders the agent may read and write, and where the files it writes itself and the files its hosted tools save land.
Read and Write each take No access, Full project workspace or Specific folders. Specific folders shows the project's folder tree with a checkbox per folder. Ticking a folder grants it and everything inside it, folders created there later included, and a folder keeps its grant when it is moved, so the folders inside a ticked one show as covered rather than ticked.
The agent writes only where it may also read.Write cannot reach further than Read: a full workspace to write needs a full workspace to read, and each folder it may write must be one it may read or inside one.
Default folder is where the agent's tools' files land, and where a file the agent writes itself goes when it names no folder. It must be a folder the agent may write, and it is required while Write is Specific folders. With a full workspace to write and no default folder, its tools' files land in tool-outputs, in a subfolder per tool server, and a file it writes naming no folder lands at the top of the workspace.
With no write access, the agent cannot save a file itself, and its hosted tools still run but save no file. The agent is told, and the call's row in the tool's Calls tab reads Not saved: the agent has no write access to the project’s workspace.
Atlas may read every file in the project but writes only to screens, where its tools' files land.
An agent nobody has restricted reads and writes the whole workspace, with no default folder. Save workspace access saves the whole card. If someone else changed the agent's workspace access after you opened it, the save is refused and nothing changes: Reload agent shows their change, and you make yours again.
A folder that is an agent's default folder cannot be deleted, or moved where that agent may not write: AskRAI names the agents, and you change their default folder first. A tool's file that arrives after its agent was deleted, or once its default folder can no longer take it, lands in tool-outputs instead, and the project's Activity tab says why.
Each heartbeat, an agent sees the files it may read:
What it is shown. Its inbox lists the 20 files inside its Read access that changed most recently, each with its path, type, size, who wrote it and when. The inbox also says, in words, what the agent may read and write and where its tools' files land.
What it can open. An agent with at least one file to read can list a folder and read a file by its path or its link.
Which files it reads as text. It reads the text of a Markdown, CSV, JSON or plain-text file, a part at a time from where it left off. For any other file it learns only its type, and that a hosted tool can read it.
PDF and Word documents. It reads a PDF's or a Word (.docx) document's text, a part at a time, once AskRAI has extracted it, a few seconds after the document lands. Each new version's text is extracted again. Until then the agent is told the text is still being extracted, and it is told instead when a document has no text to read (a scanned page is a picture, and there is no OCR), is too large to extract, as any document over 25 MB is, or could not be read. The text kept is a document's first 2,000,000 characters. A document saved before AskRAI extracted document text has none until a new version of it is uploaded.
How much it reads. Reading costs none of the agent's actions, but each read uses one of the heartbeat's turns. One heartbeat makes at most 8 reads and reads at most 128 KiB between them, because each later turn of the heartbeat sends what was read to the model again. Past either limit the agent is told to work with what it has read.
What it can never reach. A file outside its Read access, or in another project, does not exist for the agent: asked to read one, it is told there is no such file.
What an agent reads is treated as information, never as instructions it must follow, as a teammate's message or a tool's result is.
An agent saves files into the workspace itself, as well as through its hosted tools:
What it writes. A Markdown, CSV, JSON or plain-text file, named with its extension (.md, .csv, .json or .txt), of at most 1 MiB once any redaction is done. An agent never deletes, renames or moves a file.
Where it writes. Only inside its Write access. It names a folder by its path from the top of the workspace, and a folder on that path that does not exist yet is created there, inside its write access. Naming no folder, it writes to its Default folder, or to the top of the workspace when it may write all of it and has no default folder.
A name already taken. Writing to the name of a file makes the write that file's next version, so the earlier ones stay in its version history. The name of a folder is refused.
What governs it. The file's name, its folder and its content pass your Output guardrails as a message does: a guardrail that blocks stops the write, and one that redacts saves the redacted text.
What it costs. Each write spends one of the agent's Max actions per beat, and the file counts against your tenant's file storage allowance. A write refused for its name, its size, its folder or a guardrail spends no action, and the agent is told why.
What happens to the file then depends on the agent's autonomy:
At Manual approval, the write is a proposal. It waits in Pending approvals with a preview of the file, and nothing is saved until a person approves it. The agent proposes one write per file in a beat, and does not propose a file again while its earlier write to it is waiting.
At Full autonomy, the file is saved when AskRAI applies the beat. The project's Activity tab reads saved file 'report/summary.md', or saved version 2 of file 'report/summary.md' for a file that was already there. A write whose folder or file is no longer inside the agent's Write access by then — its access narrowed, or the folder moved — is not saved, and the Activity tab says why: did not save file 'report/summary.md': it is outside the folders the agent may write.
The agent is told the file's path and its link, which it can cite in a message or a task's result, where the console shows it as a link that opens the file. The file's Versions tab shows each version the agent saved as Written by the agent, and approved by the person who approved it when it was a proposal.
The Knowledge card on the Access & Data tab attaches the knowledge packs the agent searches when its work needs a fact they hold: a policy, a procedure, a product detail, a figure.
Which packs. The picker offers the packs granted to the project's organization, in each pack's Organizations section, that one of your groups also grants you. An agent gets only the packs the person giving them can read, so the card says how many of the organization's packs it leaves out for that reason: someone who manages users and access can grant one to a group of yours. With none granted to the organization, the card says so: someone who manages users and access grants a pack on the Knowledge Packs page. An agent holds at most 50 packs.
When to search it. Each pack you attach takes an optional When to search it note, at most 300 characters, in your own words: Search it for anything a customer could quote back at us. The agent reads it beside the pack's name and description, and a note only ever tells it when to search.
A pack with no approved items answers nothing. A QnA pack's generated pairs start as drafts, so the card flags a pack with none approved until its items are approved.
A pack that is no longer available. Revoking the organization's grant, or deleting the pack, takes it off the agent. A pack the card still shows after that reads No longer available to this organization, with Remove. A pack the agent already holds stays whoever saves the agent next, whatever their groups grant.
Who sees what it finds. Everyone on the project reads what the agent writes, and its tools receive what it sends them, so attaching a pack shares what the agent finds in it with them. The card says so above its packs. A heartbeat's transcript keeps what each search returned, and everyone with Read access to the project can open it.
Atlas searches Refund policy for anything a customer could quote back; Product manuals answers nothing until its items are approved.
Save knowledge packs saves the whole card. If someone else changed the agent's knowledge packs or their notes after you opened it, the save is refused and nothing changes: Reload agent shows their change, and you make yours again.
Each heartbeat, an agent holding packs is told what each one holds: its name, its kind, how many sources it has, when it was last updated, its description and your note. Nothing is searched until the agent asks:
When it searches. When its work needs a fact one of its packs may hold, before it puts that fact in a task, a message, a proposal or a file, rather than stating it from memory. It does not search for what its inbox already says, or on a heartbeat with nothing to act on.
What it gets back. The curated answers and document passages that clear your tenant's minimum relevance threshold, ranked together across the packs it chose, at most two passages from any one document, each labelled with its pack and source. The agent cites what it relies on by that label, in its citation style.
Reading on. When a passage from a documents pack is the start of what the agent needs, a policy section say, it can read on through that document from the passage, in order, and is told where to continue. It reads only documents its searches found in this heartbeat; a curated answer is whole already.
When nothing matches. The agent is told nothing cleared the bar, rephrases once at most, then carries on and says the packs did not cover it. If the search fails on AskRAI's side, it is told that nothing was searched, and never that the packs lack the answer.
How much it searches. Searching and reading on cost none of the agent's actions, but each uses one of the heartbeat's turns. One heartbeat makes at most 4 searches and reads between them, returning at most 48 KiB, because each later turn of the heartbeat sends what was found to the model again. Asking for the same thing twice in a heartbeat costs nothing: the agent is pointed back to what it already has.
Where you see it. Each search and each read is a line in the heartbeat's log: what it asked for or read on from, which packs or document, what came back and the labels it returned, the opening of what it found, and, unless its citation style is None, the line telling the agent which labels to cite.
What an agent finds in a pack is treated as information, never as instructions it must follow, as a teammate's message or a tool's result is.
An agent's Decision model is a decision model your tenant connected under Model Providers, such as TypeSafe's Jev, which makes two checks for it: whether a scheduled beat has anything to act on, and whether a task it creates is one it already has. It is optional and offers decision models only. An agent without one makes neither check, and neither check ever lets an agent do more than it could without it.
Templates do not carry it. An agent made from an agent template starts without one, and Save as template leaves it out.
It is a model in use. It cannot be removed or disabled while the agent names it, and correcting its model ID moves the agent with it, as for the agent's Model.
What it costs. Each check is charged at the decision model's Input $ / 1K tokens price, since TypeSafe charges for input tokens only. It counts in the beat's cost on the Logs tab, and so against the project's budget and the agent's spend cap.
Before a scheduled beat, the decision model reads the agent's inbox and answers how likely it is that something there asks or needs the agent to act.
Scheduled beats only. A beat woken by something happening to the agent — a message to it, a task assigned to it, a proposal of its decided, the work one of its tasks waits on finished — always runs, though its Logs line reads scheduled too. So does a beat you start with Run heartbeat.
After your Input guardrails. It reads the inbox once your Input guardrails have run on it, so it reads what they redacted, and never a message they blocked.
Below 0.2, the beat is skipped. It ends without a turn, and counts as idle, so the idle backoff keeps doubling the agent's interval.
Never more than three in a row. The fourth scheduled beat runs whatever the check answers, so a check that is wrong about an agent cannot silence it. A beat that runs, or anything that wakes the agent, starts the count again.
A check that fails runs the beat.
Where you see it. The beat's entry on the Logs tab says it was skipped, and its transcript gives the probability, the threshold and the versioned model that answered, such as jev-1.14.0. The agent's Activity and its Last action read skipped a scheduled beat: its decision model found nothing in its inbox to act on.
When the agent creates a task, or proposes one at Manual approval, AskRAI first refuses it if the agent already has one of the same title for the same owner. When nothing matches exactly, the decision model compares the new task's title with the agent's open tasks, its waiting tasks, its reports' tasks in flight and the tasks it created earlier in the beat, among those held by the new task's owner. A new task with no assignee matches any owner.
At 0.85 or above against any of them, the create is refused as an exact match is, naming that task. The agent is told within its beat, which the beat's transcript shows.
Below 0.85, or when the check fails, the task is created.
Titles go as they are stored. An Input guardrail that redacts does not cover what this check reads.
The Activity tab answers what has this agent been doing? It lists the actions the agent has taken on this project — beats, messages it sent, tasks it created, status changes it made, and files it saved — newest first, each marked agent.
The Activity tab is the agent's own slice of the project activity feed — the fastest way to see whether an agent is pulling its weight.
The feed is not streamed entry by entry: it reloads after each of the agent's beats, and Refresh pulls the latest actions at any time. It shows the 50 most recent.
When an agent closes a task, its entry here records what the work produced — for example status → done — Welcome pack published to the People Ops wiki; 14 checklist items, IT and Security sections signed off. Read those lines to judge the quality of an agent's output, not just its volume.
The Logs tab is the operational view: one entry per heartbeat, with the cost and outcome of each.
Each log entry is one beat — its outcome, what triggered it, how long it ran, how many actions it took, and what it cost. The failed beat records why.
Every entry carries a level badge, the time the beat started, and a one-line summary in the form succeeded — beat #42 · scheduled · took 38.2s · 3 actions · 4,830 tok · $0.02 · Claude Sonnet 4.5. The model goes by the name the agent's Model list gives it, or by its internal id (byom:…) once your tenant can no longer run it: its provider deleted or no longer active, or the model disabled. An entry recorded before beats reported their own start and end shows no duration. A beat that the wake check skipped says so. A beat that failed appends the reason, as in — model provider returned 429 (rate limited). A beat whose agent asked for more actions than its cap allows says so after its action count, as in 3 actions · action cap reached — 1 call not recorded: the extra actions were never recorded, and the beat's transcript names them. The cap is the agent's Max actions per beat, or a lower Actions per beat on a policy attached to it. If the agent keeps reaching it, raise whichever is lower. A beat that recorded events counts them next, apart from its actions, as in 2 events. Then come any refused as the beat's work was saved, such as an event whose type was retired meanwhile, as in 1 refused (or 1 event refused when none was recorded), and any past its Events per beat, as in event cap reached — 1 event not recorded. The beat's transcript gives each refused event's reason. For a moment after a beat ends, while what it did is still being saved, its entry and its transcript read applying in place of the outcome. The list checks again by itself and shows the outcome once the beat's proposals, tasks and messages are in place.
Level
Meaning
INFO
The beat succeeded, is still running, or is queued
WARN
The beat timed out or was cancelled
ERROR
The beat failed — the summary line ends with the error
A beat stopped by an Inputguardrail that Blocks names the message that tripped it and the guardrail that stopped it: who wrote it, when, and its opening words, with anything a word, pattern or detector guardrail matched masked (an LLM judge points at nothing to mask), as in — No fruit: 1 match(es) — in Ada Lovelace's message of 2026-10-22 07:40 UTC: “I brought a [REDACTED] for everyone”, which this agent's later beats leave out. That beat fails, and from the next one on the agent reads the rest of its inbox without that message, so one message cannot stall an agent however long it stays among the newest. The message stays out for as long as that guardrail governs the agent: detach it, and the agent reads the message again from its next beat. The message stays in the project's thread, marked as set aside from the agent and naming the guardrail, and other agents still read it unless it blocks them too. An entry of the project's recent activity that trips the guardrail on its own, such as a task someone created under a name holding a denied word, stops no beat: each beat the entry would block runs without it while it stays among the newest, and its transcript names the entry, masked, as in No fruit: 1 match(es) — in the activity row “Ada Lovelace: created task 'Plan the [REDACTED] tasting'”, which this beat leaves out. When an LLM judge is what blocks the entry, each of those beats asks the judge about the inbox twice, and about the entry once more. A block that no single message or activity entry trips, such as a word in one of the agent's tasks, names no message: edit the task, or detach the guardrail. When only several messages or activity entries taken together trip an LLM judge, the line says so, as in — the messages and the activity rows together: none blocks on its own, so none is set aside. Until the inbox or the guardrails change, each later beat asks the judge about the inbox once, not about every part of it again.
Select any entry to open its transcript — the record of what the agent read, reasoned, and decided on that beat. The agent always reads a result whole, but the transcript keeps each entry short: a long one is cut and says so, as in … [cut: 3412 more characters], and a tool's or a knowledge pack's text may be kept shorter than the agent's own words. A transcript holds at most 8,000 characters, and one that runs longer ends by saying how many of its entries it leaves out. A beat that recorded events lists them under Events, each with its type and fields, and Not recorded with the reason for one that was refused. Some beats have no transcript captured, in which case the dialog says so.
The levels map onto the beat's outcome: see beat statuses for what each one means, and what triggers a beat for the trigger named in each line.
The Logs tab is where a misbehaving agent gives itself away. A run of WARN or ERROR beats usually points at the model provider rather than the agent's prompt; a long run of successful beats that took 0 actions usually means the agent has nothing in its inbox — give it a task or a message.
Logs is the only place an agent's beat history is listed — the Heartbeat tab sets the cadence and shows live state, and sends you here for the record of what those beats did and cost.
If an agent's model later becomes unavailable (for example, its provider is switched inactive), the agent's beats fail until the provider is active again or you pick a new model, and the form shows its selection as (unavailable). A model an agent runs on cannot be removed or disabled, and correcting its model ID moves the agent with it: see Model Providers.
The agent's Budget tab is where you bound what a single agent costs, inside the budget the whole project runs against.
A cap is a ceiling drawn against the project pool — not an allocation carved out of it.
Project budget pool. What the project has spent against its total, so you can see how much room the cap is being drawn from. If the project itself is out of budget, the card says so — no agent on the team runs until the project budget is raised, its status is set back to Active and the team is started again from the project header, whatever its own cap says.
Agent spend cap. Off by default: an agent with no cap draws on the project budget until the project's own limit is reached. Turn on Limit this agent's spend and enter an amount above $0 to bound it; turning the switch back off clears the limit. The card also shows what this agent has spent so far, and how much of its cap remains. An amount under a cent is shown to two significant figures, such as $0.004, so a cap smaller than a cent can still be compared with the spend.
Two properties are worth knowing before you rely on a cap:
It is checked after each run completes, so a run already in flight can carry spend slightly past the cap.
It bounds what this agent spends on its own runs. Work it hands to another agent is charged to that agent.
An agent that hits its cap stops on its own — the rest of the team keeps running. The Budget tab then shows Stopped — budget exhausted with a Resume button beside it. The people on the project's team who hold Write access or above — or, when none does, the next in line — also receive a notification naming the agent; it opens the project's Budget tab, not this one.
Raise or clear the cap first, then press Resume: until the cap is above what the agent has spent, Resume is disabled, and the banner beside it names the cap as the step still outstanding. Resume returns this agent to its schedule and leaves the rest of the team where it is — unlike Start team in the project header, which restarts every agent that may run within its budget. On a project whose status is not Active, Resume is disabled and the reason is shown beside it: set the project Active, then use Start team or Resume in the project header. Resume is disabled too, with its reason beside it, on a project whose own budget is exhausted, for an agent whose status is not Active, and for one whose automatic heartbeat is off.
Cadence & tokens. A read-only summary of the other things that decide what an agent costs: how often it beats and how many actions each beat may take (both set on Heartbeat), the hours it is active, and the token ceiling per model call (set under Advanced on the Behavior tab). An agent whose automatic heartbeat is off shows no cadence, because it does not beat at all.
Click a person in the org chart or list to open their detail panel. Alongside their read-only Directory profile (display name, email, job title, department, and project role, all managed in your corporate directory) and their Project assignment, an Inbox on this project card shows what the team has sent their way:
Assigned tasks — every task currently assigned to them, with its status and when it last changed.
Direct messages — messages addressed to them specifically, with the sender and date.
This is the quickest way to see whether an agent has been handing work to a colleague who has not picked it up. Agents have no inbox card — use their Activity and Logs tabs instead.
The org chart is built from each member's reporting line, which can span both people and agents:
People and agents alike get their manager, or the top level, when added, and you can change it later from the member's detail panel. A new member starts under an agent only when you pick one.
No loops — a member can't be set to report to one of its own reports.
When you remove a person or delete an agent who has direct reports, those reports are not deleted — they move up to the top level so the rest of the hierarchy stays intact.
Remove a person — open the person's detail panel and click Remove from project, then confirm. The person is removed from the team but remains in your directory. Their unfinished tasks become unassigned and keep their status, and adding them back does not restore them. From then on, neither an agent nor the task board can give them work, though you can still message them.
Delete an agent — open the agent's detail panel, click Delete agent, and confirm. The agent is permanently removed from the project, and the proposals it still had waiting for approval are rejected, since none can be applied without it. Its unfinished tasks become unassigned and keep their status; no agent picks up an unassigned task on its own, so assign each one to whoever should do it. Its finished tasks still show who did the work. A teammate's proposal that messages the deleted agent or gives it work can no longer be approved — reject it, and address the work to a current member instead. Because deleting an agent disposes of its proposals, it needs Admin access to the project. Anyone else sees Delete agent disabled, with a reason naming the Admin access it needs.
In both cases, any direct reports move to the top level of the org chart.
Removing a person from a project does not delete them from your directory — it only takes them off this project's team. Deleting an agent is permanent and cannot be undone.
Saving an agent is refused, naming the Write access it needs, though the controls were not disabled
Your level on the project was lowered after you opened it. Nothing in that save was applied
Reload the page. The controls then show as disabled, and the change is one for someone with Write
Adding or renaming an agent is refused under Name with This project already has an agent named … or A person on this project's team is named …
Another agent or a person on the project's team holds that name, or one that differs from it only in case, symbols or extra spaces. Nothing was saved
Choose a name that differs in its letters or digits. An agent that shared a name before this rule, or whose name a person took later by joining the team or being renamed in your directory, keeps it until it is renamed
Adding an agent shows Configure a model provider instead of the form
The tenant has no enabled chat model
Connect one under Model Providers and enable at least one chat model
An agent's model shows (unavailable)
The selected model is no longer available to the tenant
Open the agent and pick an available model
Saving an agent's workspace access is refused
Write reaches further than Read, a folder you ticked was deleted meanwhile, or the default folder is missing or outside what the agent may write — the card says which
Correct the card and save again
Deleting or moving a folder is refused, naming agents
The folder is, or holds, those agents' default folder, which the change would remove or put where they may not write
Change their default folder on the Access & Data tab first
The project's Activity tab reads did not save file '…': it is outside the folders the agent may write
The agent's Write access was narrowed, or the folder or file was moved out of it, between the agent writing the file and AskRAI saving it
If the agent should write there, widen its Write access on the Access & Data tab, and ask it to write the file again
An agent never searches a pack it holds
The pack is not granted to the project's organization any more, it has no approved items, or the agent's work has not needed a fact it holds
Check the pack's Organizations and approved items, and say in the pack's When to search it note when the agent should search it
The org chart can't be drawn
The team's structure can't be laid out as a chart
Switch to the List view to see and manage all members
Organizations — the organizations that contain your projects
Agent Heartbeat & Autonomy
Set how often an AI agent acts and how much it can do without you — configure an agent's cadence, autonomy level, and per-beat limits, and review the beats it has run
An agent works in heartbeats: a beat is a single, bounded turn in which the agent reads its inbox, plans, takes a few actions — sending messages, creating or updating tasks, saving files — records the events its work achieved, and then stops until its next beat. This page is where you decide how often that happens, and how much the agent is allowed to do on its own.
Open the Team tab, select an agent, and choose the Heartbeat tab of its detail panel.
The Heartbeat tab pairs the agent's cadence and autonomy settings with its run state, which follows the agent's beats live. The history of past beats lives on the Logs tab.
Starting a project's team is not enough on its own. An agent only beats if its ownAutomatic heartbeat is on, and that is off by default — so a new agent sits idle on a running team until you enable it here, or switch it on when you add the agent. This is the most common reason a team appears to do nothing after you press Start team.
Saving the setting takes effect on a running team straight away. Switch it on and save, and the agent joins the beat schedule with its first beat due at once. Switch it off and save, and the agent stops, with no further scheduled beats; a beat already under way finishes. The rest of the team is not touched. There is no need to stop and start the team. An agent over its own spend cap stays stopped until you raise the cap and press Resume.
An agent's autonomy decides what happens to the actions it produces on each beat.
Autonomy
Behavior
Manual approval
Every action except an activity post — a message, a task created or changed, a file saved — becomes a proposal that someone with Write access to the project must approve before it applies. Activity entries always apply, being a log rather than a change, and so do the events it records. A tool that only reads runs; one that changes something in another system is refused. New agents default to manual.
Full autonomy
Every action applies at once, within the agent's per-beat limits, and each is recorded on the project's Activity tab. A tool that changes something in another system runs, unless a policy requires approval for it.
The help under the Autonomy select says this for the level chosen, wherever you pick one.
Suggest is no longer offered. It applied an agent's actions exactly as Full autonomy does, so an agent, template or policy set to Suggest before now shows and runs as Full autonomy, and does what it did before. Use Manual approval when you want a gate.
Only someone with Admin access to the project, which every Platform Admin holds. Raising an agent's autonomy lets it act without the approval that people with Write access decide, so it is held to the level above Write.
Everyone else sees Autonomy disabled, with a reason naming the Admin access it needs. The rest of this tab, such as Automatic heartbeat, the interval and Run heartbeat, stays open to the people with Write access, and read-only to anyone with Read.
Anyone with Write can still add an agent. The Add agent panel offers the same Autonomy select, held at Manual approval for anyone below Admin, with the same reason.
Raising it takes the agent as it then reads. Anyone with Write access to the project can edit its name, goals, system prompt, model parameters, tools and workspace access, and nothing asks you to re-read them when you raise it. Review its Overview, Behavior, Skills & Tools and Access & Data tabs first: above Manual approval, it saves files wherever its Write access reaches without asking.
For a ceiling that holds whoever edits the agent, attach a policy whose Maximum autonomy is Manual. It narrows every beat of the agents it governs, and only Platform Admins and holders of Manage policies, guardrails and egress can write or attach one.
The Heartbeat protocol card configures the agent's cadence. Edit the fields and click Save changes.
Field
Description
Default
Automatic heartbeat
When on, the agent beats automatically while the project is running. Off by default, here and in the Add agent panel, so a new agent never acts until you enable it.
Off
Interval (seconds)
The agent's own cadence, from 30 seconds to 24 hours — and the floor the idle backoff never goes below.
How many actions the agent may take in a single beat (1–20). Caps the work — and cost — of each turn.
3
Max tool calls per beat
How many calls to granted tools one beat may make (1–20). The recording intents every agent already has are never counted, and a call that changes something also spends one of the actions above.
5
Events per beat
How many events the agent may record in a single beat (1–20), once the project declares an event type. An event never spends an action or a tool call, so a beat that reaches its action cap still records what it achieved. An event past this cap is not recorded, and the agent is told so.
10
A policy attached to the agent can hold Autonomy, Max actions per beat and Max tool calls per beat lower: a beat runs on the lower of the field and the ceiling of every active policy. Where a ceiling is the lower, the field says so beneath it and names the policy — for example Held to Manual approval by Strict. under Full autonomy. This shows to anyone with Write access to the project or above, and to anyone who can open Admin → Policies. It names the policy and the ceiling, never the rest of what the policy carries.
Enable automatic heartbeat only after you have set the agent's model and behavior. Start a newly enabled agent on Manual approval so you can review its proposals. Once you trust how it works, re-read what it is told and granted, then raise its autonomy to Full autonomy.
A beat is a model call whether or not there is anything to do, unless the agent's decision model skips it, so an agent that has finished its work does not keep asking at its full rate. A beat that changes nothing doubles this agent's interval, and it keeps doubling — one idle beat after another — up to the project's Idle check-in ceiling, which defaults to 60 minutes and is set when you edit the project.
A beat counts as changing something when it applied an action or raised a proposal for you to decide. A beat that produced nothing — including one that failed, and one its decision model's wake check skipped — counts as idle.
Three things reset the backoff and put the agent straight back on its own interval:
Anything sent to the agent. A message, a reply, or a task assigned to it. Any of these wakes it immediately and clears the streak — including a nudge that arrives while a beat is already running.
A beat that changes something. Doing real work is itself the reset.
Starting or resuming the team. Every agent comes back on its own interval, however long the team was paused.
The ceiling never speeds an agent up. The backoff is floored at the agent's own interval, so a daily digest agent under a one-hour Idle check-in still beats daily. A ceiling lower than an agent's interval changes nothing for that agent.
Run heartbeat is outside all of this: a beat you run by hand neither moves the schedule nor resets the idle streak, whatever it does. Use it to test an agent without disturbing its cadence.
It overrides the run state — it works on a stopped team — but never the configuration, the agent's or the project's. It is refused for an agent whose Status is Paused or Archived, for one that has spent its whole spend cap (Agent budget is exhausted), and for every agent of a project whose status is not Active or whose budget is exhausted. In each case the console disables Run heartbeat outright and shows the reason beside it. A beat run by hand therefore cannot spend money that the agent, or its project, has been stood down from spending.
The Heartbeat tab shows this agent's run state: whether it is Running, how many Beats it has completed since the project was last reset, when its Last beat ran, when its Next beat is due while it runs, and its Last action. They follow the agent as it beats, including a beat you run by hand while the team is stopped. Click Run heartbeat to queue a single beat immediately — useful for testing an agent without waiting for its timer. The tab says Heartbeat queued until the beat lands.
Last action is the last thing the agent's latest beat did, with that beat's time, or the error it ended on. A beat's actions are recorded as it ends, so this is never what the agent is doing right now. Under Manual approval it reads proposed: …, and still does once someone approves or rejects the proposal: the decision shows in Pending approvals and on the project's Activity tab. An action that changed nothing, or that the agent was not allowed to take, says so. It stays when you stop the team, and a reset clears it along with the activity it describes. After a beat its decision model skipped, it says so. A dash means the agent has not beaten yet, its latest beat took no action, or a reset has cleared it since.
When the agent has backed off, the tab says so under its run state: how many scheduled beats in a row changed nothing, and the project's Idle check-in it is backing off toward. That is why its next beat can be further out than its interval. An agent given an active window reads Outside its active window in place of its next beat while the window is closed, since it does not beat until the window opens.
While the team is running, an agent whose automatic heartbeat is on and whose status is Active but which is not running shows Resume. That is an agent stopped on its own — for example one that ran out of its budget before you raised its cap. Until its cap is above what it has spent, Resume is disabled, with the reason beside it. Saving its settings again does not restart it, because a save only starts an agent when it changes whether the agent may run. Resume returns this one agent to its schedule and leaves the rest of the team where it is. The panel header starts, pauses and stops one agent too.
Pausing the team pauses every agent, and Start team returns only the agents that may run. An agent that may not — its automatic heartbeat off, or its status Archived — then reads Stopped, never Paused on a running team. One whose status is Paused, with its heartbeat on, stays Paused until you set it Active.
On a project whose status is not Active, Resume is not offered, because the team is not running. Set the project Active and press Start team or Resume in the project header, which returns every agent that may run within its budget.
The history is on the agent's Logs tab, not here. Each entry there is one beat, with what triggered it, its outcome, and the actions, tokens and cost it consumed; select an entry to read its transcript.
A beat is triggered by one of several events, shown next to each entry on the Logs tab:
Trigger
What happened
Scheduled
The agent's interval timer came due.
Run by hand
You ran a beat on demand with Run heartbeat.
Sending the agent a message, replying to it, or assigning it a task does not produce a trigger of its own — it brings the agent's next Scheduled beat forward to now.
Each agent runs on the model you chose for it, including your own bring-your-own model. The Logs tab makes the trade-off visible: compare tokens and cost per beat across agents so you can safely run cheaper models where they perform well.
Set the cadence and the per-beat limits here; read what they cost on Logs, and cap the spend they add up to on the agent's Budget tab.
The interval is 5 minutes but the agent has not beaten in 40
It has backed off — several beats in a row changed nothing, so its interval has doubled toward the project's Idle check-in. Its Heartbeat tab says Idle and backing off and shows its Next beat. Send it something to wake it, or lower Idle check-in on the project.
A new agent never acts on a running team
Its own Automatic heartbeat is off. It is off by default. Switch it on and save; the agent starts at once.
Other symptoms and fixes for a team that is not behaving are collected in one place — see Interactions → Troubleshooting.
Team — staff the project with people and agents, and configure each agent's model and behavior
Interactions — run the team, exchange messages, work the task board, and approve proposals
Projects — the project's status and budget, either of which stands the team down
Project Events — the events agents record as they work, and the Dashboard charts they feed
Model Providers — the models an agent can run on, and their token prices
External Access (A2A)
Open a project's agent to AI agents outside AskRAI, which hand it work over the A2A protocol with an API key, an OAuth 2.0 client or a signed JWT, and, for the outside agent's developer, read its card, send a request, and read the answer, every refusal and the timing
An agent's External access tab opens it to AI agents outside AskRAI. An outside agent reads the agent's agent card, then hands it work with the A2A protocol, version 1.0 over JSON-RPC, authenticated as the agent's Method says: with one of your tenant's API keys, a short-lived token an OAuth 2.0 client obtains, or a JWT signed by a key you registered. AskRAI answers at once with a reference, and the work becomes a task in the agent's inbox, which its team works like any other.
The first sections are for the project Admin who opens the agent; from The addresses on, the page is for the developer of the outside agent that calls it. The example throughout is LumiCX, a voice agent that keeps a pay-TV customer who called to cancel, and then hands the customer's follow-up to a Retention Coordinator agent with the number they called from.
Open the Team tab, select the agent, and choose External access, the last of its Capabilities tabs. Changing anything on it needs Admin access to the project, because it lets callers outside AskRAI give the project work. Anyone else sees the tab read-only, with a line saying an Admin can change it.
Once access is on, the tab shows the two addresses the outside agent needs, and the keys it may call with.
Tick Accept requests from outside agents. The first time, Description for outside agents starts from the agent's own description, and every skill the agent has pinned is checked under Published skills.
Under Authentication, choose the Method, then add the credentials that may call, or create one there.
Under Expected input, add a field for each piece of data a caller sends.
Read the Agent card preview at the foot of the tab, then press Save external access. The badge beside Agent-to-agent access reads Live.
Give the outside agent's developer the Agent card URL and the key's secret over a secure channel, and send them to this page.
Save external access stays disabled, with the reason beside it, until the agent has a description for outside agents and at least one key. A project that is Archived cannot be opened. To close the agent again, untick Accept requests from outside agents and save: its card is no longer served, every request to it is refused as one to an address that names no agent, and what you set on the tab stays saved for the next time you open it.
Endpoint and Agent card URL, each with a copy button: the agent's addresses.
Description for outside agents, up to 1,000 characters: the card's description, which tells an outside agent what this agent does and when to send it work. It is kept apart from the agent's own description, which is written for its team.
Method says how callers prove who they are, and the card says it to them. Each method takes its own kind of credential, at most 20 listed:
Method
Callers send
You list
API key (Bearer)
one of the listed keys, as a Bearer token
API keys: credentials with Channel A2A, and those with Channel API that are not Personal Tokens
OAuth 2.0 (client credentials)
a token that lasts 15 minutes, which an OAuth client obtains from the Token URL shown under Method
OAuth clients
Signed bearer token (JWT)
a JWT they sign with their own private key
Signing keys: the public halves of their keys, which you register
Changing the method removes the listed credentials of the other kinds, and changes the card, so tell your callers before you save it.
Searching lists your tenant's active credentials of the method's kind. It needs View credentials.
Create key, Create client or Register key opens the Create Credential dialog for that kind on Channel A2A, then lists the new credential on the agent, as Programmable Access does. It needs Manage credentials. A key's secret, or an OAuth client's Client ID and Client secret, are shown once. A signing key asks for the Issuer and Audience its tokens carry and its Public key, and then shows its Key ID, which the caller puts in every token. An A2A credential calls only the agents that list it, and nothing else on the API.
Each listed credential shows its state. A key works only while its Channel's interface is on in the Interfaces panel, so turn on A2A there before you hand out an A2A key; until then the key reads Interface off. A key revoked, expired or deleted after it was listed stays listed, marked, and is refused.
Everything else that holds a key back holds an OAuth client or a signing key back here too: its IP allowlist, its expiry, its group, and its request budgets. Revoking or deleting one stops it at once, tokens it already obtained included, and rotating an OAuth client's secret ends its tokens. A key's group decides which knowledge packs and guardrails answer its queries; what governs the work an A2A request starts is the receiving agent's own guardrails and policies, on its beats.
What callers can ask for: a checklist of the skills the agent has pinned on its Skills & Tools tab, with Select all and Select none. An unchecked skill stays private to the project. The card shows each published skill as the agent's pinned version reads it, so an edit not yet published changes no card, and a skill unpinned from the agent leaves the card at once.
The fields of the data a caller sends, at most 20. Each has a Name (lowercase letters, digits and underscores, starting with a letter, unique on the agent), a Type (string, number, integer, boolean, object or array), Required, a Description and an Example. A request missing a required field, or holding a declared field of another type, is refused before it becomes a task. Fields the caller sends that you did not declare reach the agent with the rest.
The examples you give make up the example request on the agent's card.
The Retention Coordinator expects what LumiCX sends:
Name
Type
Required
Description
Example
phone_number
string
Yes
The number the customer called from, in E.164 with the leading +
+13105550142
language
string
No
The language of the call: es, en or pt
en
retention_offer
object
No
The discount applied on the call
{"percent": 25, "months": 6}
customer_id
string
No
The customer's id, when the call found the customer by it
DTV-C-7731904
Beneath the fields, What callers get back shows, read-only, the acknowledgement every accepted request is answered with.
Approve each task before it starts holds each request's task until someone on the project approves it: see Approving each request. It is ticked when you first turn access on, and unticked on an agent opened before it existed.
Stream progress to the caller: the agent's card offers SendStreamingMessage and SubscribeToTask, and a caller receives each task's result once the agent marks it done. Off, a caller follows a request's status through GetTask alone, and the result stays in the project. See Following a request.
Requests per minute, Cost cap per task ($) and Max open requests: the agent's limits on outside requests, opened on what was saved or on their defaults. See Limiting what outside agents ask of an agent.
When the agent needs more input: who answers the agent's question about a request, The agent's manager answers (the default) or The calling agent answers. Only a caller following its request over a stream can answer; any other request's question goes to the manager. See When the agent needs more input.
Marked Coming soon, shown disabled: notifying the caller when a task changes.
The card outside agents read, previewed for the tab as you edit it, before you save, with Copy JSON.
The preview is built exactly as the served card is, so what you read here is what a caller reads.
The card's version changes when, and only when, the card's content does: renaming the agent or its organization, editing the description for outside agents, checking or unchecking a published skill or moving the agent to a version of one that reads differently, and, while a skill is published, changing the example request it carries (the names and examples of the expected-input fields that have an example) or adding the first field or removing the last. An outside agent may stop sending work until it has read a card that changed, as LumiCX does, so tell its developer before you change one. Some changes reach callers without moving the card: which keys may call, and an expected-input field's type, Required and description, and any field without an example, which the card does not carry. Tell the developer of those too, since a field made required refuses the requests that leave it out.
The three ids are the agent's organization, project and agent, each 24 hexadecimal characters. A trailing slash names the same address.
The card is public: it is read with no key, and counts against no request budget. It holds the agent's name, its organization's name, the description for outside agents, the published skills and the example input, and nothing secret.
The card is served with Cache-Control: public, max-age=300 and an ETag. Send that ETag in If-None-Match and an unchanged card is answered 304.
A card that is not served is answered 404 with {"error": "not_found"}: the agent's access is off, the agent or its project is archived, or the address names no agent.
Neither route is in the API Reference, and an A2A client finds the endpoint on the card.
The Retention Coordinator's card:
{ "name": "Retention Coordinator", "description": "Takes over customers LumiCX retains on the phone: verifies the discount, opens the case, runs the specialists, and owns the retention plan.", "supportedInterfaces": [ { "url": "https://public.askrai.ai/a2a/org/6650f1c2a9e4b3d2c1f0a001/proj/6650f1c2a9e4b3d2c1f0a002/agent/6650f1c2a9e4b3d2c1f0a003", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" } ], "provider": { "organization": "Acme", "url": "https://askrai.ai" }, "version": "1.0.0+5f3a9c1e", "capabilities": { "streaming": false, "pushNotifications": false, "extendedAgentCard": false }, "securitySchemes": { "askrai_api_key": { "httpAuthSecurityScheme": { "scheme": "Bearer", "description": "An AskRAI API key, sent as Authorization: Bearer askrai_..." } } }, "securityRequirements": [{ "schemes": { "askrai_api_key": { "list": [] } } }], "defaultInputModes": ["application/json", "text/plain"], "defaultOutputModes": ["application/json", "text/plain"], "skills": [ { "id": "retention-followup", "name": "Retention followup", "description": "Take over a customer another agent kept on a call, confirm the retention discount, and plan the follow-up that keeps them. Use when a retention handoff arrives with the customer's phone number.", "tags": ["retention", "churn", "customer-success"], "examples": ["{\"phone_number\": \"+13105550142\", \"language\": \"en\", \"retention_offer\": {\"percent\": 25, \"months\": 6}, \"customer_id\": \"DTV-C-7731904\"}"], "inputModes": ["application/json"], "outputModes": ["application/json", "text/plain"] } ]}
A skill's id is its name in the skill library, and its name that name with spaces for dashes and underscores. Its tags are the published version's tags, else its category, else general.
examples holds one JSON object built from the expected input's examples, when any field has one. inputModes is application/json when the agent declares expected input.
securitySchemes names the agent's method. The card above takes API keys; an agent taking OAuth 2.0 names askrai_oauth2, an oauth2SecurityScheme whose clientCredentials flow gives the tokenUrl, and one taking signed tokens names askrai_jwt, an httpAuthSecurityScheme with bearerFormatJWT.
Only A2A 1.0 is offered: there is no 0.3 card or endpoint.
Every request to the endpoint carries Authorization: Bearer <credential>, the kind the agent's card names. Whatever the kind, it is checked as a key is on every other AskRAI endpoint, and refused with the same HTTP answers. A valid credential that the agent does not list, or that is of another kind than its method takes, is refused as an address that names no agent, so a caller never learns of an agent it may not call.
Exchange the client's id and secret for an access token at the card's tokenUrl, https://public.askrai.ai/a2a/oauth/token, with HTTP Basic or with both in the form body:
Send Authorization: Bearer askrai_at_... until it expires, 15 minutes later, then ask for another. Each token asked for counts once against the client's and your tenant's request budgets. Ask for no scope: the card declares none. The client secret itself is refused on the endpoint, with 403KIND_DENIED.
A refused token request is answered as OAuth 2.0 has it, {"error": ..., "error_description": ...}:
HTTP
error
When
400
invalid_request
The body is not application/x-www-form-urlencoded, a parameter is missing or repeated, or the client authenticated both ways at once
401
invalid_client
The id or secret is wrong, or the client is revoked, expired, out of its IP allowlist or its group, or its interface is off
400
unsupported_grant_type
grant_type is not client_credentials
400
invalid_scope
A scope was asked for
429
RATE_LIMITED
A request budget is spent, or too many secrets from your address were refused within a minute, in the API's error envelope with Retry-After
Sign a compact JWT with the private half of the key the agent lists, and send it as Authorization: Bearer <jwt>:
the header's kid is the signing key's Key ID, and its alg one the key's type signs: RS256, RS384, RS512, PS256, PS384 or PS512 for RSA of at least 2,048 bits, ES256 for EC P-256, ES384 for P-384, EdDSA for Ed25519;
iss is the registered issuer and aud the registered audience, or a list holding it;
exp is required and at most an hour ahead, and nbf and iat, when present, not in the future. Each time is allowed a minute of clock difference.
POST the JSON-RPC request to the endpoint, with Content-Type: application/json and A2A-Version: 1.0. A body may be up to 8,192 bytes, sent with a Content-Length header or chunked.
{ "jsonrpc": "2.0", "id": "0b6f0c1e-5d8e-4a8f-9a6e-2f1d3c4b5a67", "method": "SendMessage", "params": { "message": { "messageId": "9d3e7a10-2c4b-4f8e-8a51-6b0c2d1e3f47", "role": "ROLE_USER", "parts": [ { "text": "Customer retained on the call with a discount; please take over the follow-up." }, { "data": { "phone_number": "+13105550142", "language": "en", "retention_offer": { "percent": 25, "months": 6 } } } ] } }}
message.role is ROLE_USER, and message.messageId a string of 1 to 128 characters, new for every handoff: it is how a retry is told from a new handoff.
message.parts holds 1 to 20 parts, each exactly one of text or data, where data is a JSON object. The text parts are joined, and the data objects merged in order, a later key winning: the merged data is what the expected input is checked against. A file part (raw or url) is refused.
Leave out message.taskId: a new message starts a new task. A message naming a task is only ever an answer to the agent's question about it: see When the agent needs more input.
contextId is echoed in the answer, and a new one is made when you send none. referenceTaskIds, extensions and metadata are kept with the request and never acted on.
params.configuration.acceptedOutputModes, when you send it, must include application/json or text/plain. configuration.historyLength above 0 returns your message in the answer's history. configuration.returnImmediately changes nothing, as the answer is final either way.
The handoff is the A2A task, and it is complete once accepted.TASK_STATE_COMPLETED means the request is the team's now. GetTask then tells you where the team's work on it stands; its result reaches you only from an agent that streams progress.
The reference, RAI- and six characters of digits and capital letters (never I, L, O or U), is unique in the tenant. The project's people see it on the request and on the task it becomes, so quote it when you talk to them about this customer.
An answer is never TASK_STATE_INPUT_REQUIRED or TASK_STATE_AUTH_REQUIRED: nobody can answer either in the middle of a call.
Enums are written by their names, TASK_STATE_COMPLETED and ROLE_AGENT, as A2A 1.0 writes them.
A request the agent isn't taking is answered 200 too, with status.stateTASK_STATE_REJECTED, a status.message from the agent (ROLE_AGENT, one text part) saying Retention Coordinator isn't taking requests right now., and {"accepted": false, "reference": ...} in the acknowledgement. That is the answer while the agent is Paused or Archived, or its project On hold or Archived. A rejected request makes no task. A team that is merely stopped still accepts requests, and works them when it is started.
The answer waits for nothing about the work: only for the key, the address, the request budgets and the request being recorded. Each answer past the key's check carries Server-Timing: app;dur=<ms>, how long AskRAI took from your request's arrival to its answer, which tells its share from your network's.
A request answered late is still accepted. Once it is recorded, its task is made and the team works it, even if your client stopped waiting. Nothing cancels it, as CancelTask refuses every task the agent answered: send the same message again, with the same messageId, and you get the original answer.
A SendMessage repeating an earlier one's key, agent and messageId is answered with the earlier answer: the same task id, reference and state, under your new request's JSON-RPC id. Nothing is recorded again, no budget counts it, and no second task is made, however often you retry. A retry is checked again before it is answered, so it is refused if the agent no longer lists the key, or if the message no longer matches the agent's expected input.
After a timeout, a dropped connection or a 503, retry with the samemessageId. Never call CancelTask to give up on a handoff.
A new handoff, even about the same customer, takes a newmessageId. So does sending again a request that was rejected: the same messageId gets the same rejection back.
The same messageId sent with another key, or to another agent, is a new request.
params: {"id": "<task id>", "historyLength": 1}: the task as it stands, with metadata.followUp, for the key that sent it. Another key's task, an unknown id, or a request the project's reset or deletion has since cleared is -32001
CancelTask
-32002 for a task this agent answered: a caller cancels none of the team's work; -32001 for an unknown one
From an agent that streams progress: params: {"id": "<task id>"}, the stream of a task still running. A task that has ended, a SendMessage handoff among them, is -32004
SendStreamingMessage and SubscribeToTask of an agent that does not stream, ListTasks, GetExtendedAgentCard
-32004: the agent streams nothing, or has no extended card
Every task GetTask and a stream answer with carries where the team's work on it stands, as metadata.followUp:
"metadata": { "followUp": { "state": "done", "updatedAt": "2026-11-12T15:40:02.118Z", "result": "Retained on the 20% offer." } }
state is waiting until the request is a task, then the task's status on the board (todo, in_progress, blocked, done, cancelled), input_required with the agent's question while it waits for your answer, failed if no task could be made, or removed once its task was deleted.
result is what the agent wrote when it marked the task done. It is sent only by an agent with Stream progress to the caller on, which its task tells it, and only while that stays on.
A request awaiting approval reads waiting, with no result, until someone approves it. Declined, it reads cancelled, and a stream ends TASK_STATE_CANCELED, saying nothing of why.
Streaming. An agent with Stream progress to the caller on lists "streaming": true in its card's capabilities. A SendStreamingMessage is checked and recorded as a SendMessage is, and answered with Content-Type: text/event-stream: each event a data: line holding a JSON-RPC answer whose result is the task, a statusUpdate or an artifactUpdate, as A2A 1.0 streams them. Its task starts TASK_STATE_SUBMITTED, is TASK_STATE_WORKING while the team works it, and ends TASK_STATE_COMPLETED, with a result artifact holding the result, or TASK_STATE_CANCELED or TASK_STATE_FAILED, after which the stream closes. That end is kept: a task reopened on the board moves followUp alone.
A stream holds one of your key's concurrent streams, as a streamed query does: past its limit it is answered 429 before the request is recorded.
A quiet stream sends a : keepalive comment every 4 seconds.
A stream may close before its task ends, as when AskRAI deploys, or when the key is revoked or the agent stops streaming. Send SubscribeToTask with the task's id to pick it up where it stands: its first event is the task as it is now.
An agent working a request can ask a question it cannot answer from what it was sent. Its question passes the agent's output guardrails, as everything it writes does, and at Manual autonomy it waits for a person's approval like any message. Who answers is the tab's When the agent needs more input.
The agent's manager answers (the default). The question arrives as a message from the agent to the person or agent it reports to, reading Question about request RAI-7K3Q9X (Request RAI-7K3Q9X from LumiCX): …, and a person is notified of it. An agent that reports to nobody asks the first of the people the project's decisions go to, never the whole project. Reply to the message as to any other: the reply reaches the agent the next time it works. The task carries on meanwhile, and the caller is told nothing.
The calling agent answers. Only a caller that sent SendStreamingMessage follows its task, so only it is asked, and only while its task has not ended for it and its key may still call the agent. Any other question goes to the manager instead, a request sent with SendMessage, whose task was final when answered, among them. While the agent waits, no agent works the task. The caller reads:
the task TASK_STATE_INPUT_REQUIRED, its status.message the question, on GetTask, SubscribeToTask or the stream, which closes there;
metadata.followUp as {"state": "input_required", "question": "…"}.
Answer with SendMessage, or SendStreamingMessage to follow the task on, sending a new messageId and the task's id as message.taskId:
{ "jsonrpc": "2.0", "id": "4c1f1f7e-2b8e-4f0a-9c3d-7e6a5b4c3d2e", "method": "SendMessage", "params": { "message": { "messageId": "a7d0c2f4-9e1b-4c6d-8f3a-2b5e7c9d1a0f", "role": "ROLE_USER", "taskId": "3f2b6c1e-8d4a-4f6e-9b1c-2a7d5e8f0c34", "parts": [{ "text": "They took the 20% offer for six months." }] } }}
An answer is checked as a request's message is, its body held to the same 8 KiB, and a field of the expected input it carries must be of its type. It counts against no budget.
Only the key that sent the request can answer. Any other key, even one the agent lists, is answered -32001.
The task reads TASK_STATE_WORKING from your answer on. Within a few seconds the agent wakes with your question and answer beside its task, and works on. Sending the same messageId again is answered with the task as it stands; one task question takes one answer.
The project's Activity tab reads asked request RAI-7K3Q9X's caller: … and request RAI-7K3Q9X's caller answered. Someone on the project who changes the task's status while it waits takes it over: it no longer waits for your answer, you read the task where it stands, and an answer is then refused -32004.
A refusal of the key, of a spent budget or of the body is an HTTP answer in the API's error envelope, {"error", "code", "detail"}, as on every other AskRAI endpoint:
HTTP
code
When
401
UNAUTHORIZED
The key is missing, malformed, unknown, revoked or deleted, or its Channel's interface is turned off, which its detail then names
403
CREDENTIAL_EXPIRED
The key has expired
403
IP_DENIED
The calling address is not in the key's IP allowlist
403
CREDENTIAL_UNGOVERNED
The key's group no longer exists, is inactive or does not list the key
403
CHANNEL_DENIED
The key's Channel is CLI or MCP, for example A CLI key cannot call an agent over A2A
403
KIND_DENIED
An OAuth client's secret was sent as a key: send the access token it obtains instead
404
The address names no agent this key may call: an id that names nothing, an agent whose access is off or that does not list the key, or three ids that do not belong together. The body is the JSON-RPC error -32601No A2A agent at this address.
413
CONTENT_TOO_LARGE
A chunked body grew past 8,192 bytes. A body whose Content-Length declares more is refused before it reaches the API, with 403 and an HTML page
429
RATE_LIMITED
A request budget is spent, or too many keys from your address were refused within a minute. Retry-After says when to try again, and is absent for a budget of 0, which no window renews
503
SERVICE_UNAVAILABLE
AskRAI could not record the request just then. Retry after Retry-After with the same messageId
Past the address, every answer but a spent budget's 429 and a 503 is a JSON-RPC answer with HTTP 200, echoing your request's id, or null when it had none:
Code
Message
When
-32700
Parse error
The body is not JSON
-32600
Invalid Request
The body is not one JSON-RPC 2.0 request object: a batch, or one with no jsonrpc: "2.0" or method
-32009
Version not supported
A2A-Version, as a header or a query parameter, is not 1.0. With none, A2A reads version 0.3, which is refused too
-32601
Method not found
A method A2A does not define
-32602
Names the first failure
The message is malformed (message.role must be ROLE_USER.), or the data misses a required field or holds a field of another type (phone_number is required., phone_number must be a string.)
-32005
Incompatible content types: …
A file part, or acceptedOutputModes that names neither application/json nor text/plain
-32004
This task isn't waiting for input. Send a new message without taskId.
message.taskId names a task of this key's that is not waiting for your answer
-32001
Task not found
message.taskId, or GetTask's or CancelTask's id, names no task this key sent this agent
A refused request is not recorded, makes no task and counts against no budget. An error's data holds A2A's typed details, so an A2A SDK can read them: -32009 carries a google.rpc.ErrorInfo with "reason": "VERSION_NOT_SUPPORTED" and "metadata": {"supported": "1.0"}, and -32602 a google.rpc.BadRequest naming the field:
Each request is answered on its own, whatever the agent is doing, so ten callers at once get ten answers in the time one takes.
Each accepted request becomes a task in the agent's inbox. The agent takes them most urgent first, as many a beat as its Max actions per beat allows, and hands parts of the work to its team.
Three limits under How outside tasks run bound what many callers at once can ask of one agent. Each counts every key that calls the agent together.
Limit
Default
Past it
Requests per minute
10
429 with RATE_LIMITED, a Retry-After of the seconds until the next UTC minute, and the detail This agent's budget of 10 requests per minute is spent. It renews in 23 seconds.
Max open requests
50
TASK_STATE_REJECTED, its status message Retention Coordinator is busy. Retry later with a new messageId., and no task. A request is open from its arrival until the task made of it is finished, and one stopped at its cost cap stays open until someone finishes it
Cost cap per task ($)
$0.50
The request's work stops. Leave the box blank for no cap
An agent opened before these limits existed is held to the defaults until an Admin changes them. A repeat of an earlier messageId is answered as it was, a rejection included, so a caller told the agent is busy retries with a new one.
A SendMessage also counts against the calling key's and your tenant's per-minute and per-day request budgets, as a query does, once it has passed the checks of its key, its address and its message, a rejected one included. Past them it is answered 429 with Retry-After. To give an outside agent a budget of its own, give it a key of its own, with limits set on that key.
A request's cost is what the agent's runs spent working its task, and the runs of any teammate working a task delegated under it. A run working several tasks at once shares its cost between them. Once a request's cost reaches the cap:
every unfinished task of that request is set Blocked, and its result reads Stopped: the work on request RAI-7K3Q9X reached its cost cap of $0.50 ($0.53 spent).;
the project's Activity tab reads stopped request RAI-7K3Q9X's work: it reached its cost cap of $0.50;
no agent works those tasks again. A run already under way when the cap was reached can carry the cost a little past it.
To let the work go on, raise or clear the cap first, then move each stopped task out of Blocked: each one you move is resumed on its own. Moving one without raising the cap lets one more run work it, and that run stops it again.
Within a few seconds of the answer, an accepted request is a task in the agent's inbox:
titled Request RAI-7K3Q9X from LumiCX, LumiCX being the name of the key that called;
described by the request's text, then the line From LumiCX, over A2A (reference RAI-7K3Q9X). The caller already has its acknowledgement; nothing written here reaches it., or, from an agent that streams progress, … The caller follows this task's status, and receives your result when you mark it done., then its data as JSON;
with the acceptance criteria Work this request as your instructions and skills say., High priority, and the agent as both its assignee and its creator.
The project's Activity tab reads received request RAI-7K3Q9X from LumiCX over A2A. While the team runs, the agent wakes for the task within seconds; a stopped team finds it when it is started. The caller's text and data reach the agent marked as the caller's words, apart from its own instructions. The task's drawer reads FromLumiCX, over A2A · reference RAI-7K3Q9X, and its View request opens the request it came from.
With Approve each task before it starts ticked, the caller is still answered at once, exactly as above, and its request still becomes a task. But no agent is shown the task, its manager included, until a person approves it:
The project is told. The people a proposal notifies get one notification, Retention Coordinator needs approval, naming the task, and the request waits in Pending approvals on the project's Interactions tab, counted with the agents' proposals.
Approve releases it: the agent wakes for it and works it like any other task. The Activity tab reads approved request RAI-7K3Q9X, and only then the request's own entries, created task and received request, which every agent on the project can read.
Decline closes it, as Done, with your optional reason as its result, Declined: Not one of our customers, and no agent ever sees it. The caller is not told: nothing of the decision goes back to it.
Deciding needs Write access to the project. Until someone decides, the task sits under Awaiting approval on the board, and a dashboard's tasks by status counts it under the same heading. Changing its status or assignee does not release it: only Approve does. A declined request moved back to To do returns to Pending approvals, still unseen by any agent. Unticking the box releases no request already waiting. A waiting request counts against the agent's Max open requests, so decide them as they come.
On the project's Interactions tab, above Pending approvals, the Incoming A2A requests card lists the requests outside agents sent the project's agents, newest first, with the exact messages exchanged. It shows once one of the project's Active agents is open to outside agents, or a request has arrived, to anyone who can read the project.
Each request keeps what was received and what was sent back, so a handoff can be traced from either side by its reference.
Before any request arrives, it reads No requests yet, and a line per open, Active agent naming the active keys it lists, such as Retention Coordinator is listening for LumiCX.
Each row reads the key's name, the reference and the agent, the method (SendMessage or SendStreamingMessage) with · received and how long ago, and Acknowledged or Rejected. The card first shows the newest five, the newest open, and the header counts how many have arrived, as Showing 5 of 12 received while more are left to show. Load More adds the next five, and the rows scroll inside the card, so Pending approvals stays in reach below it.
An open row shows the request's history, then the Request and the Response sent, as JSON. The history reads Received, then Acknowledged in so many ms, or Rejected with why; then, for an accepted request, Waitingfor the team to start in the seconds before its task is made, Task created with Open task, which opens it on the board, or Couldn't create the task with why: the agent or the project was deleted or archived in the meantime, or the task was refused. For an agent approving each request, a last line reads Waiting for approval, then Approved by or Declined by whoever decided, with their reason.
The card updates live while the project is open, as each request arrives and as its task is made. A project's Reset and its deletion clear its requests with the rest, after which GetTask no longer finds them. Deleting an agent keeps its requests as history.
The request was Rejected, or Couldn't create the task, on the Incoming A2A requests card
Read the request's history there. Set a paused agent or an on-hold project back to Active, then ask the caller to send the request again with a new messageId
Ask a project's assistants to build dashboards, propose agents and install connectors, and let them speak up when a run hits something the team can't get past
A project's assistants help you shape and watch its team: you ask, and they offer a dashboard, an agent to add or a connector to install, which you accept or not. They never act on their own.
Assistants stand in a strip at the edge of the Team tab, and each opens its chat beside the org chart.
Open one from that strip on the project's Team tab. An assistant reads what the project's agents can read. It sits beside the team rather than on it: it isn't on the org chart, takes no tasks and messages no agents. A project holds at most one of each kind:
Assistant
What it does
Dashboard Assistant
Builds dashboards from the project's data, for you to read and share.
Team Builder
Suggests agents and reporting lines to help you shape the team.
Integrations Assistant
Sets up MCP connectors so the team can reach the tools it needs.
Add an assistant. Click + on the strip, pick a kind and click Add assistant. You can also choose Create → Assistant at the right of the top header, from any tab of the project you have open: the same dialog opens, and the assistant you add opens on the Team tab. A kind already on the project shows as Added. The assistant gets the Assistant Model your routing configuration sets, or its Summarization Model when there's none, so it runs on one of your organization's own models.
Each kind is a card to pick, and one already on the project shows as Added.
Remove an assistant. Click it on the strip, click the bin icon and confirm. What it made, its spend and its entries on the Activity tab stay on the project, and adding that kind again brings it back as it was.
Click an assistant on the strip to open its chat, then pick one of the suggested requests or type your own and press Enter. Its reply appears in the chat once it's written. Your chat with an assistant is yours alone: nobody else on the project reads it, an Admin included, and someone else who opens the same assistant starts a chat of their own. A dot on an assistant marks a reply you haven't read yet.
Every request is checked by guardrails before it reaches the model, and every reply before it reaches you. They're the guardrails of every agent on the project, whether it's running or not, together with those of your own groups. When one stops a message or a reply, the chat says which guardrail did, and so does the project's Activity tab. A reply's cost counts against the project's budget, and a project that is over its budget, on hold or archived can't be asked.
What an assistant reads. An assistant reads the systems the project's active agents are connected to, through their tools that only read: it never offers a tool that changes anything, nor one a policy holds for approval or an allowlist blocks. It reads nothing in the project's workspace, so a Mailbox archive's tools and a SQL connection's export_query never reach it, though a SQL connection's other tools do. Before you ask, its chat lists those systems under Can read. A reply that read one shows it as a step above the answer, such as Read Zendesk. Its tool calls appear on the tool server's Calls tab under the assistant's name, and they pass the same guardrails an agent's do. Team Builder also reads who is on the team, a step its reply shows as Read team structure. Every assistant can also read the project itself when your question needs it: its task board, its latest activity and its budget, with what each agent and assistant has spent. A reply shows each as a step: Read task board, Read project activity or Read project budget. It lists the board's most urgent open tasks and its latest finished ones, and the activity leaves out your agents' tool calls.
When you ask Team Builder for an agent, or agree to one it suggests, it proposes one as a card under its reply: the agent's name, whom it would report to, what it would do and its skills. A skill with a dashed outline matches no skill your organization can attach yet, and the agent is added without it. Until someone decides, the proposed agent also stands on the org chart with a dashed outline and a New tag, and clicking it opens the chat it was proposed in.
A proposed agent waits on the chart, dashed, until someone adds it or dismisses it.
Click Add to team to add it as Add agent would: it starts at Manual autonomy with its heartbeat on, so whatever it wants to do waits for someone's approval, and it starts at once if the team is running. Your approval shows on the Activity tab. Click Dismiss to drop it, and its card stays in the chat, dimmed. A proposal belongs to the project, not to your chat: anyone who opens Team Builder sees the open ones their chat doesn't show, other people's among them, above it under Other open proposals, and never what anyone said. Removing Team Builder dismisses its open proposals.
When you ask the Integrations Assistant to connect a system, it proposes a connector as a card under its reply. Connectors come only from AskRAI's own vetted catalogue, which holds Jira, GitHub and Linear today, and the assistant never offers an address of its own. The card shows the MCP server, its tools and the agents it would be installed for. A connector starts Read only. Choose Read and write to install the tools that change things too. Each tool shows Reads or Writes as its server's approved settings under Tools say. Until a tool is approved there, it shows no mark. Pick the agents under Agents with access, then click Install.
A proposed connector starts read-only, and its tools carry no mark until they're approved on their server.
If your organization already has that tool server, Install grants the agents its approved tools at once. A tool that changes things still waits on each agent's autonomy, as any tool does. If it doesn't, connecting a new tool server needs the Manage tools permission. Someone who holds it enters the server's credential on the card, and the server is connected as Settings → Tools connects one. The card then waits until its tools are approved and switched on there. Once they are, click Install again. Without that permission, the card names who holds it. Your install shows on the Activity tab.
Ask the Dashboard Assistant for one, such as "Build me a dashboard of the task flow". Its reply carries a card with the dashboard's title and the shape of its trend; click it, or Open, to see the whole dashboard: up to three headline figures, a trend of one or two lines over time, and a breakdown, largest first. Each chart has a table view, from the button at its top right. To change it, say what to change in the same chat, such as "Show it per week instead": each change is a new version, and the version buttons at the top of the dashboard switch between them.
A dashboard the Dashboard Assistant built, at its second version.
The project's own figures, such as open tasks, spend or tasks done per week, are computed by AskRAI from the project itself whenever you open a dashboard, so they're always current and never written by the model, and read Computed by RAI beneath them. Once the project declares event types, the assistant can chart its events too, such as the share of closed cases saved each week: AskRAI computes those as well, and each reads Reported by agents, Recorded by people or both, by who recorded the events it counted. A figure the assistant read from one of your connected systems shows that system's name beneath it. Dashboards belong to the project: anyone with Read access sees them, and above your conversation the chat lists the dashboards built in other people's chats, and any of yours too old for it to show.
Pin a dashboard. Click Pin on its card, or in the dashboard itself, and choose where. Pin to Overview shows it as a card above the graph on the project's Overview tab for everyone on the project, with its newest version's title, first figure and trend: click the card to open the dashboard. Pin to Dashboard adds its figures and charts to the project's Dashboard tab, where they can be arranged beside the rest. Once pinned, the button reads Pinned, and the menu checks each place it is pinned to: choose a checked place to take it off.
An assistant speaks up, unasked, when the team's work needs something it can help with: the Integrations Assistant when an agent needs a system the team can't reach, Team Builder when an agent finds work nobody on the team owns, and the Dashboard Assistant once the task board holds 20 open tasks. Its offer appears in its chat with a suggested reply, such as Connect the team to Jira, and for 12 seconds in a notice at the corner of the screen whose Open takes you to that chat. A dot on the Team tab marks it until you read it.
Team Builder speaks up when a run finds work nobody on the team owns.
It offers and changes nothing: pick the suggested reply or ask in your own words. Each speaks up once per project for each system, for a missing owner and for the board, until the project is reset, and only for a system in AskRAI's catalogue. Its words are written by the project's assistant model and pass the guardrails the project's agents run under. Each offer is charged to the project's budget, though it isn't counted as a reply, and everyone with Write access sees the same offer in their own chat. To turn offers off, edit the project and switch off Assistant suggestions: the assistants then wait to be asked.
A support team that speaks up. An Intake Agent triages a Zendesk backlog, a Routing Agent hands each ticket to its owner, and a Resolution Agent answers how-to tickets and escalates bugs. The run reaches two walls. Routing finds billing disputes that nobody on the team handles, and Team Builder offers an agent for them: ask it for a billing specialist, and add the one it proposes. Resolution has bugs to escalate and no way into Jira, and the Integrations Assistant offers the Jira connector: pick Connect the team to Jira, give it to the Resolution Agent with Read and write, and install it. The routed disputes go to the new agent, and the Resolution Agent files the bugs in Jira through the connector.
Release notes that wait to be asked. With Assistant suggestions off, a Changelog Agent collects what was merged and a Release Writer turns it into customer-facing notes. The Changelog Agent stops: it can't read the repository, and says so on the Activity tab and in a message to its lead. Ask the Integrations Assistant to connect the team to GitHub and install the connector for the Changelog Agent, and its next beat reads the merged pull requests and saves the changelog. The Release Writer then stops: nobody on the team reviews notes before they go out. Ask Team Builder whether you need a reviewer agent and add the Quality Reviewer it proposes. It starts at Manual, so its approval of the draft waits for yours on the Interactions tab. Once you approve it, the Release Writer publishes the notes to the workspace's release-notes/ folder.
The notes land in the workspace once the run has what it was missing.
Adding, removing or asking an assistant, adding or dismissing a proposed agent, changing, installing or dismissing a proposed connector, and pinning or unpinning a dashboard need Write access to the project. Anyone with Read access still sees the assistants on it and can open one. Its suggested requests, message box, Add to team, Install, Dismiss, Pin, a connector's access and its agents are disabled, as are + and Create → Assistant, each with a reason naming the Write access it needs. While a project has no assistants, they don't see the strip at all, and an assistant's offers never reach them. On an Archived project, Create → Assistant is disabled for everyone, and it is also disabled while no project is open.
Interactions
Run a project's team of AI agents and people as a live, autonomous workspace — start and stop the team, exchange messages, manage a shared task board, watch activity, and approve agent proposals
The Interactions tab turns a project into a live workspace where its AI agents and people collaborate: they message one another, create and hand off tasks, and post activity, all driven by a multi-agent heartbeat loop that you start and stop. Open it from the Interactions tab inside a project, alongside Overview, Team, Workspace, Activity, and Budget.
With the team running, the Interactions tab pairs a Pending approvals card with a live message thread between the project's agents — here Atlas and Beacon coordinating a new-hire onboarding run.
Each agent on a project runs a heartbeat: a single, bounded turn in which it reads its inbox, plans, takes a few actions (sending messages, creating or updating tasks, saving files to the project's workspace, posting activity), and stops until its next beat. Agents coordinate only through the project's shared state — the message thread, the task board and the workspace's files — so the team behaves like a set of collaborators working from a common board rather than one monolithic process.
People and agents share one workspace. The same team you staff on the Team tab is the cast here. Agents act on their own cadence; people message, create tasks, and decide agent proposals.
You control the loop. Nothing runs until you press Start team, or start one agent, which runs the team with it. An explicit Pause or Stop stands it down, and so do a hard budget stop and saving the project's status as On hold or Archived — the team runs only while that status is Active.
Autonomy is per agent. Each agent's autonomy level decides whether its actions apply immediately or wait for your approval.
Stopping the team does not erase anything. The message thread, task board, and activity feed keep showing the project's history, and keep updating live, whether the team is running or not — what stops is the agents' scheduled beats. While the team is stopped, a strip above the feeds reads Team is stopped — agents take no scheduled beats until you press Start team.
A stopped team with no messages and no tasks yet shows The team is resting in place of the thread and the board, with a Start team of its own and no composer. A brief waiting to be sent keeps the composer on Messages. That Start team is held for the same reasons as the header's, and says why. Starting the team, or a message or task arriving, brings the composers back, with anything you had typed; a brief arriving brings back only the composer on Messages.
The project header carries the run controls: Start team on a stopped team, and on a running or paused one a chip showing its state beside Pause or Resume and Stop. Reset is the icon button beside them, and the Team tile counts how many agents are currently working, with a green dot on each one's avatar, or reads Idle while none is. While the team runs, the Activity tile reads Live, and its pace line ends in a dot at the minute now; the line falls as the team goes quiet. Running the team needs Write access to the project, and Reset needs Admin: anyone without the level a control needs sees it disabled, with a reason naming that level.
While the team runs, the header shows a green Running badge, how many agents are working, how many approvals wait on you, and its pace, Live.
Start the team. Click Start team. A Running chip appears, and agents with automatic heartbeat enabled begin to beat on their own cadence.
Starting the team is necessary but not sufficient: an agent only beats if its ownAutomatic heartbeat is on, and that is off by default. A brand-new agent therefore sits idle on a running team until you enable it, when you add it or on the agent's Heartbeat settings. Saving the setting starts the agent on the running team straight away, with no restart. If you pressed Start team and nothing happened, check this first.
Pause when you need to. Click Pause to hold the team. The chip reads Paused, scheduled beats stop, and the control changes to Resume. The existing messages, tasks, and activity stay visible.
Resume or stop. Click Resume to continue, or Stop to end the run. Stopping removes the chip and its Stop button, leaving Start team. Your messages, tasks, and activity history stay exactly where they were.
The team runs only while the project's status is Active. Saving the project as On hold while the team runs pauses the team as soon as you save — the chip reads Paused and every running agent stops beating and spending, though a beat already under way finishes. Saving it as Archived does the same, except that the run state becomes Stopped, so the chip goes, and the project becomes read-only: no message, task or decision can be made on it until it is set Active again.
On a project that is not Active, Start team and Resume are disabled, and the reason is shown under the run controls: Project is on hold — set its status to Active to run the team, or Project is archived — set its status to Active to run the team. Pause and Stop stay available whatever the status.
Setting the status back to Active restarts nothing. Press Resume for a paused team or Start team for a stopped one, exactly as after a budget stop.
The team is idle. No agent beats are scheduled, but the feeds stay live: the existing messages, tasks, and activity remain on screen, and anything written meanwhile still arrives.
Running
Agents beat automatically on their configured cadence, and the feeds stream updates as they happen.
Paused
The run is held — no new beats are scheduled — but the workspace and its history remain visible.
Reset, the circular arrow beside the run controls, is the broadest of the three destructive controls on this page — the other two are Delete on a single task card and Clear all on the task board. It clears everything the run produced: every task, message, activity entry, approval request, incoming A2A request and beat transcript on the project is permanently deleted. This cannot be undone.
The confirmation names both halves — what is destroyed, and what survives.
The confirmation counts what the reset will clear as it opens: the project's Messages, Tasks, Activity entries, Approval requests and Incoming A2A requests, listing only those it holds. Reset run waits for those counts. If they cannot be read, the confirmation says so and Reset run stays off, so cancel and press Reset again. Beat transcripts go too, though they are not counted.
Once the reset is done, the line under the run controls says how many tasks, messages and proposals it removed, until you leave the project.
On a project with nothing to clear, Reset is off, and its tooltip says Nothing to reset yet. A project you have just reset is one of these: the one activity entry a reset leaves behind does not turn it back on, though once there is something else to clear, that entry is counted and cleared with it.
The project itself is kept: its agents, goals, budget, connections and workspace files are untouched. So is the work of its assistants: your chats with them, their dashboards and proposals, and the agents and connectors added from them. On a project with assistants, the confirmation says so. That is what Reset is for — a demonstration or a trial run whose output you no longer want, on a team you do want to keep.
Each agent's Beats count on its Heartbeat tab goes back to zero with the transcripts it counted, and its Last action is cleared. What the agents spent does not: it stays counted against the project's budget and each agent's cap, so a reset never frees budget for another run. The confirmation says so, and on a project whose budget is exhausted it adds that the team cannot run until the budget is raised.
Because it deletes every pending proposal, Reset needs Admin access to the project, a level above the Write that decides them. Anyone else sees it disabled, with a reason naming the Admin access it needs.
Reset does not stop the team, as its confirmation says. Clear a run you are still watching and the agents keep beating into an empty workspace — Stop first, then Reset.
A running team spends money on every beat, so AskRAI will stop it for you.
Spending is enforced against the project's budget. When the budget is exhausted, AskRAI hard-stops the whole team: every agent stops, the project run state becomes Stopped, and the project's status is set to On hold. Recovering therefore takes two steps — raise the Budget total (USD)and set the status back to Active — and then a press of Start team, because neither edit restarts the team. Until the budget is raised, Start team is disabled and reads Project budget is exhausted — raise it, then set the project Active to run the team; after that it stays disabled, reading Project is on hold — set its status to Active to run the team, until the status is Active. A budget total lowered below what the project has spent changes no status, so on a project still ActiveStart team reads Project budget is exhausted — raise it to run the team, and raising the budget is the only step. The second step is not budget-specific: only an Active project's team can run, so a project you put on hold by hand needs it too.
The Messages view (the default toggle in the Interactions tab) is the team's conversation. A composer sits at the top, with the reverse-chronological thread below. Anyone who can open the project reads the thread, and sending needs Write access to it. Every message shows its author, an AI badge for agents, the recipient when it is a direct message, and how long ago it was sent.
A reply opens with whom it answers and their message, its opening words ending in … when it runs longer, as in In reply to Atlas “Beacon, can you draft the checklist?”. A reply you send with Reply names the very message you pressed it on, however deep in its thread, so a reply to a reply opens with that reply's author and words. A reply whose message is older than the oldest one loaded reads In reply to an earlier message. An agent's message, and one sent before replies named their message, records only the thread it belongs to: the first reply in a thread answers the message the thread began with, and a later one, which may answer any message in it, opens with In a thread with Atlas and the words of the message the thread began with. In a thread an agent started, such a message opens with In a thread with and the earliest of that thread's messages on screen.
A message keeps its paragraphs and line breaks, and Markdown in it — bold, lists, tables, code — renders as a task's result does, whether a person or an agent wrote it. HTML in a message is shown as text, never run, and an image it embeds is never loaded: its description shows instead.
A message an agent's Input guardrail blocked is marked under its text, for each agent it is set aside from, as in Set aside from Scout: its beats leave this message out while No fruit governs its input. The mark appears on an open console as soon as the beat that blocked it fails. That agent reads the rest of its inbox without the message while the named guardrail governs it; detach the guardrail and the agent reads the message again from its next beat, though the mark stays. Other agents still read it. The mark goes once the agent it names is deleted, and once the guardrail it names is deleted, from the next time the page loads. See what a blocked beat reports.
Choose a recipient. In the composer's To selector, pick Everyone on project to broadcast, or a specific person or agent to send a direct message.
Write and send. Type your message and press Ctrl+Enter (⌘Enter on a Mac) or click Send, and it appears in the thread immediately. Enter starts a new line, and the message keeps its lines as you wrote them. On a phone, tap Send.
Reply to nudge an agent. Use Reply on any message to prefill the composer with that author and thread. A reply or direct message to a running agent nudges its next heartbeat, so it picks up your input on its next beat rather than waiting for its timer.
A project can keep a brief: the team's first message, written ahead in the edit dialog with whom it goes to. While the project has no messages, the composer opens filled with it, addressed to that person or agent, so starting the work is one press of Send. You can change the words or To before you send. Nothing is sent until someone sends it, and Start team does not send it: an agent reads the brief only once it is a message.
Once any message is in the thread, the composer opens empty. A Reset that clears the messages brings the brief back, ready to send again. If the person or agent it was written for has left the team since, the brief starts addressed to Everyone on project, and a line under To says why. Only someone who can send messages sees the brief in the composer. An archived project's brief can't be changed: in the edit dialog, set its status to Active, and change the brief in the same save.
Switch the Interactions tab to the Tasks view to see the shared task board — the unit of work agents hand off to one another and to people.
Each task shows its title, description, assignee, when it was last updated, and its status, under its group's heading — in-progress work first, then what is ready, what is planned, what is blocked and what is done. The header counts the board as 8 total · 7 open.
Each task carries a title, an optional description, an assignee, and a status. Under the title, a meta line names its assignee, followed by its priority (for example High priority) and a due date if either is set, and the time of the last update. Its details record Created by, so you can always tell whether a person or an agent raised the work. Use the inline controls on any task to reassign it (to a person, an agent, or Unassigned) or to move it between statuses. The icon that starts each task marks it Done in one click, and on a done task reopens it to To do; its shape shows where the task stands — an empty circle for To do, a dashed one for In progress, a struck-through one for Blocked, a check for Done, or a planned task's own icon. Add one yourself from the line above the board. Creating, changing and deleting tasks needs Write access to the project; anyone with Read sees the board and changes nothing on it.
Name the work. Type its title (required, up to 500 characters) in the line that reads Add a task and press Enter.
Assign it. Pick a person or agent on the chip beside the line, or leave it Unassigned. No agent sees an unassigned task on its own, so point an agent at it in a message if you want one to take it up. The chip keeps your pick for the next task you add.
Add the rest (optional). Click Details for an optional Description (up to 20,000 characters) and Acceptance criteria (up to 20,000) to say how to tell the work is done (an agent checks its work against them before marking the task Done), a Priority of Urgent, High, Medium or Low (or None), a Start date if the work should wait for a day (see Tasks that start later), and a Due date if it has one. An agent works on its most urgent open task first, and a task with no priority after every Low one.
Order it (optional). Under Details, when the board holds open tasks, Waits on lists them: tick the ones that must be done before this one can start. Search the list by title.
Add it. Press Enter, or click Add. It joins the board, and an assigned, running agent is nudged to act on it — unless it waits on unfinished work, in which case the agent is woken when that work is done, or starts later, in which case it is woken on its start date. The line empties and Details closes, ready for the next task.
Stalled — someone marked it as unable to continue. To make a task wait for other tasks, use Waits on instead (see Waiting on other tasks).
Done
Completed.
The board groups tasks under headings, in this order: In progress, To do, the planned tasks'Awaiting approval, Scheduled and Conditional, then Blocked and Done. Within each group it lists Urgent tasks first, then High, Medium, Low and those with no priority, and orders tasks of one priority by most recently updated.
Tasks need only a title. Agents are instructed to give every task they create acceptance criteria — a concrete definition of done to verify against before marking the task complete — which is what keeps autonomous work checkable rather than open-ended. It is guidance to the model rather than a rule the server enforces, so a task can arrive without them. You can add or change them from the task's drawer.
A task can wait on other tasks on the same board, so work runs in order without anyone spelling the order out in each agent's instructions. Pick them under Waits on when you create the task, or change them later from the task's drawer.
While any task it waits on is not Done, the task is waiting:
The board says so. The task sits under Conditional — or Awaiting approval when one of the tasks it waits on is a person's — and a line on its card names each task and its status: Waits on Collect the survey (In progress). Waiting does not change the task's own status.
Its agent does not start it. A waiting task is left out of its assignee agent's inbox, and an agent that tries to move it to In progress or Done anyway is refused; the task's Activity & logs records not started.
The last one finishing wakes the assignee. When the final task it waits on reaches Done, a running assignee agent is woken to pick it up straight away, rather than at its next scheduled beat.
If a task it waited on is reopened, the task waits again. If one is deleted, the task simply stops waiting on it.
A task can only wait on tasks of its own project. It cannot wait on itself, nor on a task that — directly or through others — already waits on it: when you edit what a task waits on, such a task can't be ticked, and says Already waits on this task, so picking it would make a cycle. Should one get through anyway — through a task the board hasn't loaded yet, or someone else's edit landing while yours is open — saving fails with the reason, and nothing changes.
Two people saving at the same moment can still leave tasks waiting on each other in a loop, so no agent will start any of them. Each card on the loop says so in red — Waits on itself through Collect the survey — and its drawer says how to break it: Edit what one task on the loop waits on so it no longer waits on the next, or mark one of them Done. Every card on the loop then clears.
People can still move a waiting task between statuses by hand; only agents are held to the order.
Agents can set this up too. An agent that creates tasks can make one wait on another, including one it created a moment earlier in the same beat — so a lead can hand out draft the brief, then review the brief once it is drafted, in one go.
A task can wait for a day — check in with the customer a week from now — so the step goes on the board today and is worked on its day, not straight away. An agent laying out a plan gives its later steps one, and you can too: pick a Start date under Details as you add the task, or change or clear it later with Edit in the task's drawer.
The board says so. While the date is ahead, the task sits under Scheduled and reads Scheduled for Nov 18, 2026 — with the time too when it is less than three days away — and keeps the status it was given.
Its agent does not see it until then. The task is left out of its assignee agent's inbox until the start date.
The date wakes the agent. When it comes, a running assignee agent is woken to pick the task up within seconds, rather than at its next scheduled beat. A task that also waits on other tasks is picked up once the last of them is Done. Moving the date to today wakes the agent at once.
Tasks that are not ready to be worked yet sit apart, between To do and Blocked, each under the reason it waits:
Group
The task
Its card reads
Awaiting approval
Waits on a task assigned to a person, such as a sign-off
Needs approval · waits on Approve the offer (To do)
Scheduled
Has a start date still ahead, and waits on nothing
Scheduled for Nov 18, 2026
Conditional
Waits on other tasks that are not Done
Waits on Fix the picture (In progress)
A waiting task that also has a start date ahead ends its line with it — · starts Nov 18, 2026. A task leaves its group as soon as nothing holds it, and a Done task is never in one.
An agent changes a task's status, or reassigns it, only when the task is its own, unassigned, or assigned to someone who Reports to it on the Team tab:
A lead manages its reports' tasks. It can move a direct report's task to any status — including Done, which also releases every task waiting on it — or reassign it, to itself or to anyone else on the team, which is how it takes back a task that has stalled. Each change shows in the task's Activity & logs. Reports of reports are not included.
Nobody else can. An agent that tries to change a teammate's task it does not manage — a peer's, or its own manager's — is refused, and nothing changes. It is usually told so within its beat, which the beat's transcript shows; otherwise the task's Activity & logs records the refusal.
Unassigned tasks are open. Any agent may pick up a task nobody is assigned to, so you can point an agent at one in a message instead of assigning it.
The rule holds for proposals too. Approving one for a change its agent may not make — typically on a task you reassigned while the proposal waited — fails with the reason, and the proposal stays pending for you to reject. People are not held to any of this, and can move or reassign any task by hand.
Assigning a task never makes it happen by itself. An agent only picks work up on its next heartbeat, so if the assignee is an agent that is not running, AskRAI tells you so as soon as you assign, and names what is still missing:
Task created, but Atlas won't work it until its heartbeat is running. Enable its heartbeat to act on it.
The steps it can name are set its status to Active, enable its heartbeat, raise its budget, resume it from its Heartbeat tab, and start the project (or resume the project when the team is paused). On a project whose status is not Active, that last step reads set the project Active, then start it (or set the project Active, then resume it), since the team cannot run until it is. On a project that has spent its budget, raise the project budget comes first — the same steps as the disabled Start team button's own reason. It names every one that applies, for example Enable its heartbeat and start the project to act on it. The same notice appears (worded Reassigned, but…) when you move an existing task to such an agent. The assignment always goes through — the message is advisory, not a block.
The task's card and its drawer keep saying so, in the same words, until the agent is running or the task is Done — whoever created the task, including a task an agent proposed and you approved, which raises no notice of its own.
Assigning a task to a person raises no notice. People are never woken by the heartbeat loop; a task assigned to a colleague waits for them to act on it, exactly as it would on any other board.
The drawer pairs the task's details with its own activity trail — here the agent's closing entry records exactly what the finished work produced.
The drawer has three parts:
The task's details — its status, description, Assignee, Created by, Priority, the day it Starts and its Due date, when it was last Updated, its Acceptance criteria when one was set, From for a task an outside agent's request became, with View request opening that request, and what is missing when its agent assignee is not running. Click Edit beside the status to change its Title, Description, Acceptance criteria, Priority, Start date or Due date, whoever created it, then Save. The task's Activity & logs records each edit and names the fields it changed, and an agent working the task reads the new wording on its next beat.
Waits on — each task this one waits on, with its status, or Nothing when it waits on no other task. Click Edit beside the heading to change the list, then Save.
Activity & logs — everything that has happened to this task, newest first. Entries raised by an agent during a beat carry a View transcript link; clicking it opens the full transcript of that beat, so you can read the agent's reasoning behind the change. Entries made by a person have no transcript. Use Load More to page back through a long trail.
Where an agent's result shows up. When an agent finishes a task, it records what the work actually produced, and the drawer renders that report in its own Result section above Activity & logs. It is displayed as markdown, and Markdown is the Format an agent is told to write in unless you choose another, so an agent can hand back headings, lists and emphasis rather than one flat line — which is what makes the drawer the place to check what an agent delivered, not just that it finished.
A task that is not finished, or one whose agent recorded nothing, has no Result section at all. The Activity & logs trail beneath it is the separate record of how the task got there: who created it, who it passed through, and every status change, each with a link to the beat transcript behind it.
Each task card has a delete button. Deleting is immediate and permanent — there is no confirmation step, and the task cannot be recovered.
To clear the board completely, click Clear all above the task list and confirm in the Clear all tasks? dialog. This deletes every task on the project regardless of status — not just the completed ones.
Deleting a task removes it for everyone. Anyone else with the project open sees it disappear from their board within seconds, without refreshing.
Deleting a task also releases any task that was waiting on it: that task stops listing it under Waits on, and if nothing else holds it, its assignee agent is woken to start.
The Activity tab is a reverse-chronological feed of everything happening on the project — agent beats, messages, task creation and hand-offs, and submitted proposals. Each entry names the actor and timestamps the action. It streams live while the team runs, and keeps showing the project's history when it is stopped.
The message thread and activity feed each hold the 10 most recent entries, with a Load More button at the bottom to pull in the next ten older ones. New entries always arrive at the top while the team is running, so you never page forward.
The task board holds its first 10 tasks in the board's own order, so the most urgent open work is there before you load anything more, however old it is. Load More pulls in the next ten, below the ones shown. A task created or changed while you watch takes its place in that order.
The Activity feed is the audit trail of the running team — useful for seeing what the agents did and when. A condensed version also appears under Recent activity on the project Overview tab.
Changes to the team are entries too, under the person who made them: an agent created or deleted (deleted agent 'Scout'), a person added to or removed from the team, and each change to an agent's governance, with what it was before where that is short. That covers its autonomy (raised the autonomy of agent 'Scout' from manual to full), its heartbeat turned on or off, its model and status, each policy and guardrail attached or detached, its egress allowlist, and each tool server granted or revoked, or the tools it may call there changed. An entry keeps the names as they were when it was written, so it still reads after the agent or control is renamed or deleted. A change made outside the project reaches its agents with no entry here: deleting a guardrail, policy, egress allowlist or tool server, withdrawing a tool server from the organization, or editing a model on its provider.
A file an agent saves is an entry too: saved file 'report/summary.md', or saved version 2 of file 'report/summary.md' for a file that was already there. One the agent was no longer allowed to write by the time it would be saved reads did not save file 'report/summary.md', with the reason — see what an agent writes.
A file an agent cites in a message, a task's result or an activity entry shows as a link, usually reading as the file's path, which opens the file's preview and its versions, as the Workspace tab does. A file deleted since reads deleted file.
An agent opened to agents outside AskRAI on its External access tab takes their requests over the A2A protocol, and each one it accepts becomes a task in its inbox, titled with the request's reference and the calling key's name, such as Request RAI-7K3Q9X from LumiCX. The Incoming A2A requests card, at the top of the Interactions tab above Pending approvals, lists those requests newest first, with the exact messages exchanged and what became of each: see Incoming A2A requests.
An agent can be set to approve each such task before it starts. Its requests then wait in Pending approvals, after the agents' proposals, each with Approve, which releases the task to its agent, and Decline, which closes it with your optional reason. No agent sees a waiting request until someone with Write access approves it: see Approving each request.
Agents set to manual autonomy do not act directly — every action they want to take becomes a proposal that waits for a person's decision, apart from an activity post, which is a log entry and always applies. Pending proposals appear in the Pending approvals card at the top of the Interactions tab, as a count badge in the project header, and as a purple count on the Interactions tab itself, which lights the moment one arrives. You need not keep the tab open to catch them: each beat that proposes sends one notification to the people on the project's team who hold Write access or above — or, when none does, to the next in line — and opening it lands here. Everyone it notifies can decide it, and so can anyone else with Write access to the project.
Each proposal shows what approving it applies — here Beacon proposing to mark a task done with its report, create a task, and send a message — with Approve and Reject controls.
Approve applies the proposed action — the task is created, the message is sent, the task update lands, or the file is saved — and removes the proposal from the list.
Reject discards the proposed action without applying it. A rejected file is never saved. It asks for an optional Reason first, and nothing is rejected until you confirm.
The agent is told of each proposal you reject, with your reason, for the next 7 days. In that time it cannot propose the same action again unchanged: the same message to the same teammate, the same task, the same reassignment or the same status change, every detail alike. An action that differs in any detail can be proposed, so say in your reason what would make it acceptable. A file the agent proposes again is not held back this way, though the agent is still told it was rejected.
If applying an approved action fails on our side, the approval stands but its action has not landed. You are told This proposal is approved, but applying it failed on our side. Approve it again to apply it: nothing is applied twice., and the proposal stays in the card, marked Approved, but not applied yet, with Retry and Set aside in place of Approve and Reject. Another session can briefly show an approval this way while it is still being applied. Retry applies it once, however often it is pressed and by whoever: the message is sent once, the task created or updated once, the file saved once. A task someone changed since the approval is not changed back. A file's content is kept for at least a week after the approval. Retried later than that, the approval completes with nothing saved. Either way you are told Approved, but applying it again changed nothing, and its Activity entry reads approved: … — nothing was changed.
An approved action that can never be applied, because the change itself is refused rather than our side failing, is not left to retry. You are told This approval cannot be applied, and retrying it would not change that, with the reason, and the proposal leaves the card. Its Activity entry reads approved: … — failed: and the reason.
Set aside ends an approval that is not applied yet, so it is no longer retried, for one whose Retry keeps failing or that you no longer want. You are asked to confirm it, since it cannot be undone. It leaves the card, and its Activity entry, under your name, says what of it had already landed, for instance set aside: … — the message was sent, or — nothing of it was applied. It does not stop an approval still being applied in another session, which can show this way meanwhile. If that one's change lands after all, its own Activity entry reads approved: … — landed as it was set aside, and whoever approved it is told so. A set-aside or failed approval no longer holds the tasks proposed to wait on it: approve them, and a task it never created holds nothing.
A proposed task can wait on another task the same agent has proposed. Approve them in order: approving the waiting one first is refused with Approve "…" first: this task waits on it, and it stays in the list. Rejecting the task it waits on releases it — approved later, it waits on nothing.
A proposed task update is refused the same way when its agent may not make it — for instance on a task you reassigned while the proposal waited. It stays in the list until you reject it.
A proposal that names nothing to change, such as a message with no content, is refused too: This proposal names nothing to change, so approving it would change nothing. Reject it. An agent does not raise one in the first place. When it puts forward such an action, the Activity feed says so, with an entry ending nothing was proposed, and nothing reaches this card. If an approved action turns out to change nothing, for instance on a task deleted since, you are told Approved, but nothing was changed, with the reason when AskRAI knows it, such as its task is no longer on the board, and its Activity entry reads approved: … — nothing was changed. Deleting a task leaves a proposed update to it in the card, marked A task no longer on the board: reject it, since approving it changes nothing.
The card lists each proposal's summary, the agent that raised it and how long ago, and what approving it applies, so you never approve what you have not seen:
A task update names the task it touches and the status or assignee it sets. The result a status change writes on the task, often the agent's whole report, opens in full under Show the result.
A new task shows its title, assignee, description, acceptance criteria and the tasks it waits on. One that another pending proposal would create is marked Proposed.
A message shows who it goes to, or Everyone on the project, and its full text under Show the message.
A file shows its path from the top of the workspace, whether it is a New file or Replaces versionn of the file at that path, and its size. Preview opens what the agent wrote beside the card: Markdown rendered, and CSV, JSON and plain text shown as written.
Approving a file saves it to the Workspace tab, as a new file or as the next version of the one at its path, and the file's Versions tab records who approved it. A file that can no longer be saved where it was proposed — the agent's write access narrowed, or the folder moved out of it, since — is refused with the reason, beginning This file cannot be saved, and stays in the list for you to reject. An agent proposes one write per file in a beat, and does not propose a file again while its earlier write to it is waiting here.
The card is hidden entirely when nothing is pending. A proposal someone approves or rejects in another session leaves your list too, without a reload.
Deleting an agent rejects every proposal it still has waiting, so they leave the card and the header count without a reload, as a decision from another session would. A proposal is applied as the agent that raised it, so none can be approved once that agent is gone: an approval still open in another console is refused with This proposal's agent has been deleted, so it can no longer be approved., and nothing is applied. Another agent's proposal that messages the deleted agent, or gives it work, cannot be approved either: it stays pending, with the reason, for you to reject.
Whether an agent proposes or simply acts is decided by its autonomy: Manual approval agents propose, while Full autonomy agents apply their actions directly. Autonomy is set per agent — see Agent Heartbeat & Autonomy.
A project's proposals are approved, rejected or set aside only by the people with Write access to it or above, which every Platform Admin holds. Access is given per project, from its Share dialog: Write on one project gives you no say over another's, and a place on its Team tab gives none by itself. Admin on the project's organization, and a role on Access holding Administer every organization or Administer every project, also give Admin on the project, and so a say over its proposals.
Read still sees the card. Anyone with Read access can read the project and its pending proposals, but for them Approve and Reject are disabled, with the reason: Approving or rejecting proposals needs Write access to this project. Someone with no level on the project does not see it at all.
Whoever creates a project is its Admin, and shares it with the people who should decide it — see Sharing a project. Everyone on a project's team when access levels arrived was made its Admin, so they still decide it.
Admin changes what reaches this card. Only someone with Admin access can change an agent's autonomy, which decides whether it proposes at all, or Reset the project, which deletes every pending proposal.
Deleting an agent or the project needs Admin. Deleting an agent rejects every proposal it had pending, applying none, and deleting the project takes its agents with it. Anyone else sees Delete agent and the project's Delete disabled, with a reason naming the Admin access they need. See Removing people and agents and Deleting a project.
The rest of this tab needs Write too. Starting, pausing and stopping the team, sending messages, and creating, reassigning and deleting tasks are for the people with Write access or above; anyone with Read sees them and changes nothing.
The console checks your level when you open the project. If an Admin shares it with you while you have it open, reload the page to get the controls.
The feeds show Team is stopped — agents take no scheduled beats until you press Start team
The team is not running. The feeds are still live, and a beat you run by hand still lands; only the agents' own schedule has stopped
Press Start team in the project header
Start team is disabled and reads Project budget is exhausted
The project hit its budget limit and hard-stopped, which also set its status to On hold, or its budget total was lowered below what it has spent, which leaves it Active
Raise the Budget total (USD) on the project, set the status back to Active if it is On hold — the sentence under Start team names each step left — then press Start team
Start team or Resume is disabled and reads Project is on hold or Project is archived
The project's status is not Active, and only an Active project's team can run
Set the status back to Active on the project, then press Start team or Resume
The team paused or stopped just after the project was edited
Its status was saved as On hold (the team pauses) or Archived (the team stops)
Set the status back to Active, then press Resume or Start team — saving Active restarts nothing
Start team is disabled and says no chat model is enabled
Open the agent's Heartbeat tab, enable Automatic heartbeat and Save changes — the agent starts at once, with no restart
An agent's actions never appear, only proposals
The agent is on Manual approval autonomy
Approve its proposals, or raise its autonomy to Full autonomy
Approving a file is refused with a reason beginning This file cannot be saved
The workspace changed since the agent proposed it — most often, the folder left the agent's write access, or a folder now holds the file's name. The reason says which
Reject the proposal. If the agent should write there, widen its Write access on its Access & Data tab first
Approve or Reject is disabled and reads Approving or rejecting proposals needs Write access to this project., or Reset is disabled with a reason naming Admin access
You hold less than Write on the project, or less than Admin for Reset
Ask someone who holds that level to do it — or one of the project's Admins to share it with you at that level, then reload the page
The view reads The team is resting, with no composer
The team is stopped, and has no messages or tasks yet
Press Start team there or in the project header
Start team, Stop, the message composer or a task's controls are disabled, with a reason naming Write access
You hold Read on the project
Ask one of the project's Admins to share it with you at Write, then reload the page
A task sits untouched after you assigned it
The assignee is a person, or an agent that is not running — neither is woken by the heartbeat loop
Take the steps the task's card names. A task assigned to a person waits for that person
A task sits under Conditional or Awaiting approval and its agent never starts it
A task it waits on is not Done yet
Open the task and check Waits on: finish that work, or Edit the list to drop it
A card reads Waits on itself through …
Its tasks wait on each other in a loop, so no agent will start any of them
Open a task on the loop and Edit what it waits on, or mark one of them Done
Assigning a task fails with That person is not on this project's team
The person is not on the project's Team tab — removed from it, or never added
Add them on the Team tab, or choose a current member. A message to them still sends
A message or a task fails with That person has left the organisation or is suspended
Your directory holds them as inactive, so they cannot sign in to see it
Choose a current member. Reassign the tasks they already hold
A message to an agent gets no response
The team is paused or stopped, or the agent's heartbeat is disabled
Ensure the team is running and the agent's automatic heartbeat is enabled
You cannot find what an agent actually produced
The task has no result recorded — it is unfinished, or the agent closed it without writing one
Open the task: a recorded result renders as a Result section above Activity & logs. With no Result section, read the trail and the beat transcript behind its closing entry
Agent Heartbeat & Autonomy — set each agent's cadence, autonomy, and per-beat limits, and review the beats it has run
Projects — the project workspace and its budget that the team runs against
Sharing & Access — the access levels that decide who approves proposals, resets and deletes
Team — staff the project with the people and agents that collaborate here, and configure each agent
External Access (A2A) — open an agent to agents outside AskRAI, whose requests become its tasks
Model Providers — manage the models, including bring-your-own models, that power your agents
Organizations — the organizations that contain your projects
Dashboard
Arrange a project's Dashboard tab of cards and charts — pin an assistant's dashboards to it, chart the project's events, follow the figures live, and write widgets through the API
A project's Dashboard tab is one grid of cards and charts, arranged by the people on the project for everyone who reads it. You fill it by pinning the dashboards the Dashboard Assistant builds, by charting the project's events, and through the API.
Here agents recorded the last four weeks and people the history before, so the four-week figures read Reported by agents and the weekly charts read both.
Each widget is a card holding one figure, or a chart: a line, area or bar chart over time, or a donut, pie or bar chart of a breakdown. A chart's button at its top right shows it as a table. On a narrow screen the widgets stack in one column, row by row, each row's widgets from left to right.
Under each widget a line says where its figures came from:
Line
The figures are
Computed by RAI
AskRAI's own, computed from the project itself, such as its open tasks or its spend
Reported by agents
Computed from events the project's agents recorded
Recorded by people
Computed from events people recorded
Reported by agents and recorded by people
Computed from both
From a source, with As of a date
A third party's, as the system that wrote them through the API names it, and when they were read
AskRAI computes every figure of its own, and every figure over the events, each time the Dashboard is read, so they are always current and never written by a model.
A widget whose figures can no longer be read says why instead, such as Its assistant dashboard is gone. or Its event query reads nothing: its event type may be gone. It stays where it is until someone removes it in Edit layout.
While the project has no widget, the tab reads No widgets yet and says how to add one.
An open Dashboard tab follows the project with no reload. When an event is recorded, a widget charting its type reads its figures again within a few seconds, and so does a pinned piece whose figure rests on the project's tasks, its agents or its spend when those move. A figure reads again in place, so a chart you are hovering keeps its place. The Overview's pinned dashboards follow the work the same way.
A dashboard the Dashboard Assistant builds can be pinned to the Overview, to the Dashboard, or to both. Click Pin on its card in the assistant's chat, or in the dashboard itself, and choose:
Pin to Overview — adds it as a card above the graph on the project's Overview tab.
Pin to Dashboard — adds its pieces below the Dashboard's lowest widget: each of its figures as a card, side by side, then its trend as a line chart and its breakdown as a bar chart.
A place it is pinned to is checked in the menu, and the button reads Pinned. Choose a checked place to take it off: from the Dashboard, that removes every piece of it.
A pinned piece shows the dashboard's newest version, so a change you ask the assistant for appears on the Dashboard too. A piece the newest version no longer has, such as a third figure that a later version dropped, says so until someone removes it.
Click Edit layout at the top right of the tab. Each widget gains a handle, its controls and a corner to resize from.
In Edit layout every widget can be moved, resized, switched to another chart, or removed; nothing changes for anyone else until you save.
Move a widget by dragging its handle, at its top left. The widgets below make room.
Resize it by dragging its bottom right corner. A widget spans 2 to 12 of the grid's 12 columns.
From the keyboard, Tab to a widget's handle: the arrow keys move it, and Shift with an arrow key resizes it.
Switch a chart among the charts its figures take: Line, Area or Bar over time, and Donut, Pie or Bar for a breakdown.
Remove a widget with its ×.
Add a widget over the project's events with Add widget, and change a widget built that way with its Edit (the pencil): see below. A pinned piece or a widget written through the API has no Edit.
Opening Edit layout moves widgets up to close any gap above them. Click Save to keep the layout for everyone, or Cancel to put it back as it was. Two people editing at once are not warned: the later save wins. A Dashboard holds at most 40 widgets.
Edit layout is offered on a screen wide enough to show the grid, and needs Write access to the project. Anyone with Read access sees Edit layout disabled, with a reason naming the Write access it needs. On an Archived project it is disabled for everyone.
Add widget builds a card or a chart over one of the project's event types, and shows its figure before you place it. A project that declares no event type yet is told to declare one on its Events tab first.
Add widget previews the figure as it would read, so only a widget you have seen is placed.
Choose the event type and the measure.Count counts its events. Sum, Average, Minimum and Maximum read one of its number fields, chosen under Of the field. Rate is the share of its events that meet a condition, as a percent.
Narrow it (optional). Under Only the events where, Add filter keeps only the events whose field is, is not, is more than or is less than a value, or is any of several. A rate's conditions go under The rate is the share of those events where: Outcome is saved makes a save rate. A widget takes at most 5 of each, holding at most 50 values in all.
Choose how it reads. Under Show as, Card: one number, Series: over time, by the Day, Week or Month you choose under Period, or Breakdown: by a field, ranked by a text, yes-or-no or choice field under Group by. A series or a breakdown takes the Chart you pick.
Title it and place it.Title follows your choices until you write your own, up to 120 characters. The Preview reads the figure once your choices hold still. Click Add widget: the widget lands below the lowest one, a card 3 columns wide and a chart 6. Save keeps it on the Dashboard.
A card or a breakdown reads the last 365 days, and a series its last 7 days, 8 weeks or 6 months. A retired event type is not offered for a new widget, and a widget already charting one keeps counting its events.
A system of yours can put its own figures on the Dashboard: a card, a series or a breakdown it computes, beside the ones AskRAI computes. Calls go to the console's API, https://api.be.askrai.ai, with a person's console sign-in as the bearer token, as for recording events: there is no Programmable Access API key for these routes yet. Reading takes Read access to the project, and writing Write: a write with Read alone is answered 403.
Route
GET /api/v1/projects/{project_id}/dashboard
Every widget with its layout, and who saved last
PUT /api/v1/projects/{project_id}/dashboard
Replaces every widget at once, as Save does
POST /api/v1/projects/{project_id}/dashboard/query-preview
Computes an event figure now and saves nothing, as Add widget's preview does
PUT /api/v1/projects/{project_id}/assistant-dashboards/{dashboard_id}/dashboard-pin
Pins an assistant dashboard's pieces, as Pin to Dashboard does
PUT /dashboard replaces the whole Dashboard, so read it first, change the widgets you own, and send every widget back: one you leave out is removed. Drop each widget's reading before you send it, since only an answer carries it and a save that holds one is refused. The later of two saves wins.
id is 32 lowercase hexadecimal digits you choose, such as a UUID without its dashes, unique on the Dashboard.
shape is stat (a card), series (lines over time) or categories (a breakdown). Its chart is null for a stat, line, area or bar for a series, and donut, pie or bar for categories.
layout places it on a grid of 12 columns: x from 0, w from 2 to 12 with x + w at most 12, y from 0 to 1,000, and h from 2 to 8 rows. A gap left above a widget closes the next time someone saves Edit layout.
data carries its figures, a title of up to 120 characters and a unit of count, usd, percent (0 to 100) or null. A stat sets value, a number or a short text, and may set a detail line under it. A series sets series, one to three lines of {label, points} over the same periods, oldest first, each point {label, value}, 60 at most. categories sets points, up to 12, largest first. source names where the figures came from and as_of when, and the widget shows both.
A widget the console placed carries ref (a pinned piece) or query (an event figure) in place of data. Send it back as you read it, less its reading, to keep it.
A save that breaks a bound, gives a shape a chart it does not take, or charts an event type or field the project does not declare is refused with 422, and changes nothing. One on an Archived project is refused with 409.
Project Events — declare what the project records, and how agents and the API record it
Assistants — ask the Dashboard Assistant for a dashboard to pin
Projects — the Overview tab and its pinned dashboards
Project Events
Declare the events a project records, let its agents record them as they work, record your own through the API, and chart them on the project's Dashboard
A project keeps a log of events: typed facts about what its work achieved, such as a case closed and whether the customer stayed. You declare the event types a project records, its agents record events of those types as they work, and people and integrations record them through the API. The project's Dashboard charts the log, so its figures move as the team works.
Open a project and choose its Events tab.
The Events tab lists the types the project declares, each with its fields, and the newest events recorded against them.
A project records only the event types it declares. Click Add event type on the Event types card to open New event type.
The Preview shows each field as the project's agents are told it.
Name the type.Name is how agents and the API refer to it: lowercase letters, digits and underscores, starting with a letter, such as case_closed. A name is never changed once saved, so choose it with care. Label is what the console shows, such as Case closed.
Say what it means.Description is what an agent is told the event means, so write it for them: A customer's case is closed, saved or not.
Add its fields. Click Add field for each value an event of this type carries, and give it a Field name (snake_case, as the type's name), a Field label, a Kind, and whether it is Required. A type with no field records only that something happened.
Create it. Click Create event type. Its card appears on the tab, and agents can record it from their next beat.
Kind
Holds
Text
Text of up to 200 characters
Number
Any number
Count
A whole number, 0 or more
US dollars
An amount in US dollars
Percent (0–100)
A percent from 0 to 100
Yes or no
Yes or no
Choice
One of the Values you list, separated by commas, such as saved, churned
Click Edit on a type's card. You can change its label and description, add fields, change a field's label or whether it is required, and give a Choice more values. A type's name, a field's name and a field's kind never change, and a choice never loses a value, because the events already recorded, and the figures charted from them, rest on each. To record something else, add a field or a type under a new name.
Click Retire on a type's card to stop it being recorded. Its agents no longer see it, the API refuses new events of it, and Add widget no longer offers it, while its events stay in the log and every chart already drawn from them keeps counting them. Restore brings it back. A type is never deleted: a project declares at most 20, retired ones included.
Declaring, editing, retiring and restoring a type need Write access to the project. Anyone with Read access sees the types and their events, with Add event type, Edit and Retire disabled and a reason naming the Write access they need. On an Archived project they are disabled for everyone.
The Recent events card lists the project's events, newest first by when they happened: When, the Type, its Fields as label and value, and Recorded by, which names the person, or the agent by its name on the team. Choose a type under Type to list only its events, and Load More at the end of the list to read older ones.
Once a project declares a type that is not retired, every agent on it can record events as it works, from its next beat. The agent is told each type's label, its description and its fields, with their kinds, their choices and which are required, and records an event when what it describes happens: when it closes a case, say. An event happens when the agent records it, and it can name one of its tasks as the event's task.
An event costs no action and no tool call. It is apart from the agent's Max actions per beat and Max tool calls per beat, so a beat that spends all its actions still records what it achieved.
Each agent has a cap of its own, Events per beat on its Heartbeat tab: 10 unless you change it, from 1 to 20. An event past the cap is not recorded, and the agent is told so.
Autonomy does not hold events. An event records what the agent did, so an agent at Manual approval records its events while its actions wait for approval.
An event is checked against its type. One naming a type the project does not declare, a field the type lacks, a value its kind does not hold, or no value for a required field is refused, and the agent is told why within the beat, so it can correct it.
Text passes the guardrails that govern the agent's other output. One a guardrail blocks refuses its event, and one it rewrites is recorded as rewritten.
The agent's Logs tab says what each beat recorded, such as 3 actions · 2 events · event cap reached — 1 event not recorded, and the beat's transcript lists each event with its fields, and why one was not recorded.
People and other systems record events through the console's API, https://api.be.askrai.ai. A request carries a person's console sign-in as its bearer token: the token your identity provider issues when that person signs in to the console. There is no Programmable Access API key for these routes yet, so a script runs as a person, and stops working when that sign-in expires. Each event it records is recorded as that person's, under Recorded by. Recording needs Write access to the project, and reading Read: a write with Read alone is answered 403.
Route
GET /api/v1/projects/{project_id}/event-types
The types the project declares, retired ones with their archived_at
PUT /api/v1/projects/{project_id}/event-types/{name}
Adds the type of that name, or replaces it, and answers every type. "archived": true retires it, and a body without it restores a retired type, so send it again to edit one. With If-None-Match: * it only adds, and answers 409 for a name the project declares
POST /api/v1/projects/{project_id}/events
Records 1 to 100 events, all or none
GET /api/v1/projects/{project_id}/events
The project's events, newest first, a page at a time
PUT /api/v1/projects/{project_id}/event-types/case_closedAuthorization: Bearer {sign_in_token}Content-Type: application/json
{ "label": "Case closed", "description": "A customer's case is closed, saved or not.", "fields": [ { "name": "outcome", "label": "Outcome", "kind": "choice", "values": ["saved", "churned"], "required": true }, { "name": "monthly_usd", "label": "Monthly price", "kind": "usd" } ]}
A field's kind is text, number, count, usd, percent, bool or choice, and only a choice lists values. The body replaces the type whole, so a description left out is cleared. A replacement is held to the same rules as an edit in the console: removing a field, changing its kind or dropping a choice's value is refused with 422.
The answer, 201, counts what was stored: {"recorded": 2, "duplicates": 0}.
occurred_at is when it happened, with its time zone (Z for UTC), now when left out. It may be up to 90 days ago, and never ahead of now.
dedupe_key, up to 200 characters, makes a retry safe: an event whose key the project's log already holds records nothing and counts under duplicates. Give each event a key of your own system's, such as its case id.
All or none. One event refused refuses the whole request with 422, naming the first by its place and why, such as Event 0: outcome is one of saved, churned. Each is checked as an agent's is, and a retired type takes no new event.
409 answers a request on an Archived project, or one that would take the project's log past 1,000,000 events. 404 answers a project you cannot read.
GET /api/v1/projects/{project_id}/events lists events newest first by occurred_at. type keeps one type's, since and until bound when they happened, and page_size takes 1 to 200, 50 by default. Each event carries its type, fields, occurred_at, recorded_at and source, which says whether an agent or a person recorded it. While more remain, page_info.next_cursor is set: pass it as cursor, with the same filters, for the next page.
The project's Dashboard charts its events. In Edit layout, Add widget builds a card or a chart over one event type: a count, a sum, average, minimum or maximum of a number field, or a rate, the share of the events that meet a condition, such as the share of closed cases saved. It reads as one number, a series by day, week or month, or a breakdown by a text, yes-or-no or choice field. The Dashboard Assistant can chart the project's events too.
An event figure is computed whenever it is read, so it is always current, and under it a line says who reported what it counted:
Line
The figure counted
Reported by agents
Events the project's agents recorded
Recorded by people
Events people recorded, through the API
Reported by agents and recorded by people
Both
Computed by RAI
Nothing from the log: AskRAI computed it from the project itself, such as its open tasks or its spend
An event figure that counted no event shows no line. An open Dashboard or Overview tab follows the work: a chart of an event type moves within a few seconds of an event of that type being recorded, with no reload.
Events stay for as long as the project does. A reset keeps them, so a dashboard keeps its history across runs, and deleting the project deletes them. A project holds at most 1,000,000 events: past that, nothing more is recorded, and its agents are told the log is full.
Team — read what each beat recorded on an agent's Logs tab
Assistants — ask the Dashboard Assistant for a dashboard of the project's events
Sharing & Access
Share a project with people, groups or everyone in your tenant at Read, Write or Admin, and see what each access level lets them see and do in it
A project's access levels decide who can see it and what they may do in it: Read opens it, Write works in it, and Admin makes its weightiest decisions. A project's Admin shares it from Share on the project header, granting a person, a group or everyone in your tenant Read, Write or Admin. An organization is shared the same way, and its Admins hold Admin on every project in it.
You see only the projects shared with you. A project you hold no level on is in none of your lists, and you cannot open it, even from a link. A tenant starts closed: someone who holds no grant, and no role reaching every organization or project, sees no organization and no project until one is shared with them.
Projects from before sharing are shared only with their teams. Everyone on a project's team when access levels arrived was made its Admin, and nothing else was granted: no organization is shared, and no project has General access. Before your members sign in, a Platform Admin shares each organization at Write with the people who should create projects in it, and each project with the people who should work in it, or sets its General access to the level everyone should hold.
Each level includes everything the one before it allows.
Level
Adds
Read
Open the project and see everything in it: its agents, team, graph, tasks, messages, proposals, activity, workspace files, runs and budget, and who it is shared with, in the Share dialog. Change nothing
Share the project, and change or remove its grants. Change an agent's autonomy, which includes adding an agent above Manual approval, from scratch or from a template. Edit the project: its name, description, status, budget and idle check-in. Reset the project. Delete an agent, or the project
A control your level does not reach stays in place, disabled, and its reason names the level it needs, such as Approving or rejecting proposals needs Write access to this project. AskRAI refuses the change however it is made, not only in the console, and answers for a project you cannot read as for one that does not exist. Two agent settings also need a permission from a role, whatever your level: pinning skills and attaching governance.
Platform Admin. A Platform Admin holds Admin on every project.
A role reaching every project.Administer every organization and Administer every project each give Admin on every project, and View every organization and project gives Read on each. These permissions come from roles assigned on Access.
Admin on the project's organization. An organization's Admins hold Admin on every project in it. Read or Write on the organization reaches none of its projects. See Organizations.
A grant to you.
A grant to a group you are in. Groups are the ones on Users, Roles & Groups. A group that is inactive grants nothing, and deleting a group removes its grants. Because a group's members hold its grants, changing who is in a group shared with an organization or a project needs Admin on each of them, as well as the permissions its roles need.
General access. The level the project gives everyone in your tenant, if any.
The Share dialog lists the first three under Also has access, and does not change them: they come from roles and from the organization, not from the project's own grants.
Without any of these you hold no level on the project: it is not listed to you, and you cannot open it.
Whoever creates a project is its Admin. Creating one needs Write on the organization it goes in, and grants its creator Admin, a grant like any other that an Admin can change or remove.
One grant each. A person or group holds at most one grant on a project. Giving them another level changes the one they have.
A change holds at once. AskRAI checks the level on every change anyone makes, so a grant you lower or remove stops working on that person's next action. Someone whose level you raise while they have the project open reloads the page to get the controls it opens.
Click Share on the project header to open the dialog. Only the project's Admins can change anything in it: below Admin, it shows who the project is shared with, read-only.
Review who has access. The dialog lists each person and group the project is shared with, each with its level, then General access, then Also has access: its organization's Admins, the holders of Administer every organization, Administer every project and View every organization and project, and the tenant's Platform Admins. To change an organization Admin's access, share the organization instead.
Add people or groups. Search in Add people or groups, pick a person or group from your directory, choose Read, Write or Admin, and add them.
Change or remove a grant. Pick another level in a grant's level select, or remove the grant with its remove control. A removal asks you to confirm first, naming who loses which level, since getting it back means adding them again.
Set General access. Under General access, choose what everyone in your tenant holds: No access, Read, Write or Admin. Anyone who holds more through a grant of their own keeps the higher level. Choosing No access asks you to confirm first.
Removing the last Admin grant, or lowering it below Admin, asks you to confirm that the project is left with no Admin. A project with no Admin grant can still be shared, but only by its organization's Admins, the holders of Administer every organization or Administer every project, and the Platform Admins.
Each grant made, changed or removed is recorded in the Change Log under Access, naming the project, who it was given to and the level: granted Write on project 'Onboarding Automation' to user 'Nadia Rahman', changed … from Read to Write, removed …. Deleting a project deletes its grants.
The Team tab is the project's org chart, which its agents read to know who they work with and who reports to whom. A place on it grants nothing by itself.
Share before you add. Adding a person to the team needs Write, and the person you add must already hold Write or above on the project. The Add person picker offers only those people, so share the project with someone at Write first, then add them.
A lowered level leaves the chart alone. Someone whose level falls below Write stays on the team, but can no longer decide its proposals, and its notifications pass over them.
Monitor platform activity with usage charts, programmable access analytics, and top credential usage
The Dashboard gives you an at-a-glance view of your AI assistant's activity and performance. Four metric cards summarize request volume, response speed, answer quality, and user engagement. Below them, interactive charts break down usage by time, channel, confidence level, and response time — and when programmable traffic is present, additional charts surface interface mix, block rate, caller type, and the credentials driving the most requests.
The Dashboard combines interactive KPIs with usage charts and programmable access analytics.
Four cards at the top of the page show your tenant's key performance indicators for the selected filter range.
Metric cards update automatically whenever you change the date range or interface filter.
Metric
Description
Unit
Total Requests
Number of AI requests (question/answer turns) in the selected period — a multi-turn conversation contributes one request per turn
Requests
Avg Response Time
Mean time the AI takes to generate a response
Seconds
Success Rate
Percentage of scored responses at or above the high-confidence threshold
Percentage
Active Users
Count of distinct user IDs across the audit records in range
Users
Active Users / Credentials
Shown when a credential-issued request is present — distinct user IDs and distinct active service credentials
Users / Credentials
When the selected period holds no scored response, the Success Rate card reads Not measured rather than a percentage, and when it holds no timed response, the Avg Response Time card reads the same. A 0.0% or 0.0s is always a measurement.
The Success Rate metric uses your tenant's configured confidence thresholds. Adjust them in Confidence Thresholds to change what counts as a high-confidence response.
When a service credential produced at least one request in the selected range, the fourth metric card changes its label from Active Users to Active Users / Credentials and displays a compound value such as 1,284 / 7. The first number is the count of distinct user IDs across every audit record in the range — credential-issued requests carry a user identity too, so this is not a count of interactive humans only. The second number is the count of distinct service credentials that produced at least one request.
A line chart showing daily request volume across the selected range. Use it to identify usage patterns, spot traffic spikes, and track adoption trends.
X-axis — date in MM/DD format
Y-axis — number of requests
Days with no requests render as zero rather than gaps
A toggle in the top-right of every chart switches the view between the visual chart and an accessible data table
A bar chart breaking down request volume by messaging channel. Each bar is named on the axis under it, and every bar takes the same colour. Use this to understand which channels your users prefer — for example, whether Teams traffic is eclipsing Web Chat.
A donut chart categorizing response times. It normally shows three buckets:
Bucket
Range
<2s
Responses generated in less than 2 seconds
2-3s
Responses taking 2 to 3 seconds
>3s
Responses taking more than 3 seconds
Each bucket shows the count and percentage of total responses. Those three strings are the exact labels the UI renders — the legend, the tooltip and the accessible table all print them verbatim — and the table's columns are Range, Count and Percentage. There is no fourth bucket: the ranges are open-ended at the top and response times cannot be negative, so every measured response falls into one of the three.
When at least one request in the selected range came from a service credential — an API, CLI, or MCP integration — an additional row of three charts appears below the core charts. This row is hidden whenever no programmable traffic is present, so tenants that only use Teams or Web Chat continue to see the classic dashboard without visual clutter.
The Programmable Access row appears whenever programmable traffic is detected in the selected range.
Each of these three cards has the same chart/table toggle as the core charts. Use the table view when you need exact values — the charts are sized for a quick read.
A bar chart showing the percentage of requests that were blocked by a guardrail. Despite its title, the breakdown is by channel, not by interface: the chart draws one bar per channel present in the range, with no programmable/traditional bucketing — so traditional channels such as Teams and Web Chat appear alongside API, CLI and MCP.
There is no aggregated programmable-vs-traditional block rate anywhere on the Dashboard. To judge "the programmable side", read the API, CLI and MCP bars individually, or set the Interface filter to Programmable Only, which restricts the chart to those channels. The accessible table's first column is headed "Interface", but its values are channel names — not the programmable / traditional buckets used by Requests by Interface.
In the table view, the rows are channels — the "Interface" column header notwithstanding.
The table view also reports the Total requests and the count of Blocked requests per channel, so you can contextualize the percentage against traffic volume. A sustained high block rate on a programmable channel typically indicates that an integration is sending malformed input or hitting a content-safety rule — review the blocked requests in Conversation Logs to confirm.
A bar chart grouping traffic by the caller type declared on the service credential that issued the request. Caller type is a property of the credential, so only programmable requests (API, CLI, MCP) carry one:
Caller Type
Description
Human
A credential operated by a person — for example, a personal token an engineer drives from a script
Application
Back-office services, automations, and integrations
Agent
AI agents that consume AskRAI through the MCP server or API
Not declared
Requests that arrived without a declared caller type — that is, all traditional-channel traffic, such as Teams and Web Chat
Human does not mean "interactive user". Teams and Web Chat requests never declare a caller type, so they are counted in the Not declared bar, not the Human one. The chart counts every request in the range — not only credential-issued ones — so in a tenant with mixed traffic Not declared is normally the largest bar. Set the Interface filter to Programmable Only to exclude the traditional-channel traffic that fills it.
This chart lets you see at a glance whether your agentic traffic is growing relative to human-operated and application traffic.
Below the Programmable Access row, a Top Credentials table lists the service credentials with the highest request volume in the selected range. The table is hidden when no credential usage exists.
The Top Credentials table is sorted by request volume and color-codes block rate for quick triage.
Column
Description
Name
The display name of the credential, as configured in Programmable Access. A credential deleted since its requests is marked (deleted) and keeps the name they recorded, or its ID where none did; two deleted credentials that recorded the same name also show the end of their IDs
Type
Credential type — Personal Token, Service Account, Agent Credential, or Scoped API Key. For a deleted credential, the caller type its requests recorded (Human, Application or Agent), or Unknown
Requests
Total request count in the selected date range
Block Rate
Percentage of the credential's requests blocked by a guardrail
The Block Rate column uses a color dot next to the percentage:
Green — block rate at or below 5% (healthy)
Yellow — block rate between 5% and 20% (investigate soon)
Red — block rate above 20% (urgent — the credential is producing frequent guardrail violations)
Click any row to jump to Programmable Access. The click opens that page, not the specific credential — locate the credential in the table there to open its details drawer or rotate its secret.
Use the filter row in the sticky header to refine every metric and chart simultaneously.
Filter
Options
Default
Interface
All Channels, Programmable Only, Traditional Only, plus an entry for every specific channel (Web Chat, Mobile App, Teams, WhatsApp, SMS, Phone, Email, API, CLI, MCP)
All Channels
From Date
Date picker
30 days ago
To Date
Date picker
Today
The Interface filter is the quickest way to isolate programmable traffic — pick Programmable Only to hide interactive users from every chart and metric, or pick a specific channel like MCP to focus on a single integration type.
The date range spans at most 30 days, and From must be on or before To. A range that breaks either rule is not applied: the reason appears under the date inputs, and every metric and chart keeps showing the last valid range. A shared link carrying such a range opens on the last 30 days.
From, To and each day on a chart run from midnight to midnight in your browser's time zone, the one the conversation logs show their times in: a question asked at 12:30 AM counts on that day.
All metric cards and charts update whenever you change any filter. Filter selections are preserved in the URL as query parameters, so you can bookmark or share a filtered view.
Click the refresh icon next to the page title to re-fetch all metrics and charts without changing any filters. This is useful after a burst of traffic — for example, right after a product launch — when you want to see the latest numbers without losing your current filter state.
Conversation Logs — drill into individual conversations and filter by caller type
Programmable Access — manage service credentials surfaced in the Top Credentials table
Tickets — review escalated conversations driven by low-confidence responses
Confidence Thresholds — adjust the bands that drive Success Rate and the Confidence Level chart
Conversation Logs
Browse, filter, and review user conversations with audit details, caller type filtering, and false positive marking
Conversation Logs give you a complete view of every interaction between users — and service integrations — and the AI assistant. Browse conversations, filter by channel, caller type, or confidence, review audit details for individual messages, and flag guardrail triggers as false positives. The page is reachable from the Log item in the main navigation.
One card is a whole conversation, not a single question. Every summary figure on it — message count, confidence, response time, the preview text — describes only the turns that match your current filters, not the whole thread.
The page header carries a List / Table view toggle. The page opens in List view, which renders each conversation as a card; Table view renders the same conversations as rows and is the only view with sort controls.
The user or credential that started the conversation
Channel badge
The interface or messaging channel (Web Chat, Teams, API, MCP, and more)
Message count
Number of messages in the conversation thread
Timestamp
When the conversation occurred
Question text
The user's query
Confidence score
AI confidence as a percentage with a color-coded progress bar
Response time
Processing time in milliseconds
A Refresh button beside the filters re-runs the current query — the page loads once and does not poll, so this is how you pick up conversations that arrived since.
Click any card to open the details drawer on the right side of the page. Every card carries a coloured left border already — that is its confidence band — so the selected one is marked differently, with a tinted background and a ring around it.
Switch the header toggle to Table to see the same conversations as a sortable table:
Table view adds the Last Answer column and the sortable column headers; the active sort column shows a single arrow.
Column
Description
Sortable
User
The user or credential that started the conversation
Yes
Channel
The interface or messaging channel
Yes
Messages
Number of messages in the conversation thread
No
Last Question
The most recent user query in the thread
No
Last Answer
The most recent AI answer in the thread
No
Response Time
Processing time in milliseconds
Yes
Confidence
AI confidence as a percentage
Yes
Last Activity
Date and time of the most recent message
Yes
Last Answer appears only in Table view — the conversation cards do not show it. Clicking a row opens the same details drawer as clicking a card.
The view mode is not persisted. It is in-memory state only and is never written to the URL, so the page returns to List view on a full page reload, and it opens in List view for anyone you send a filtered URL to — they will not see the Last Answer column or the sort controls until they switch to Table view themselves. The filters and the sort in the URL still apply.
The list loads 10 conversations at a time. A Load More button below the list (or table) fetches the next 10. Paging is cursor-based, so changing a filter or a sort restarts the list from the top. The message thread inside the details drawer pages the same way, through a Load More Messages button at the bottom of the thread.
Use the search bar at the top to find conversations by user name, question text, answer text, or session ID. Search is debounced — results refresh roughly half a second after you stop typing.
Click Filters to open the advanced filters popover. It holds five controls — Channel, Caller Type, Response Time, Confidence Level (%), and Show false positives only — which you can combine without leaving the page. Search is a separate control in the page header, and the page has no date-range filter.
Every filter set here is written into the page URL, so a filtered view can be shared with a colleague as a link.
Filter
Options
Purpose
Channel
Web Chat, Mobile App, Teams, WhatsApp, SMS, Phone, Email, API, CLI, MCP, or All
Restrict conversations to a single messaging or integration channel
Caller Type
Human, Application, Agent, or All Caller Types
Restrict to conversations produced by a specific caller class
Response Time
Any, Less than, or Greater than, then a number of seconds
Show only conversations faster or slower than a bound — Greater than finds the slow ones. At Any, the default, no response-time bound is applied
Confidence Level
0–100% (slider)
Cap the maximum confidence score shown; at the 100% ceiling no confidence bound is applied
Show false positives only
Toggle
Show only conversations that contain at least one guardrail result flagged as a false positive
Active filters appear as chips below the search bar. Click the X on any chip to remove that filter.
Apply commits the draft selections in the popover and closes it. Once you pick Less than or Greater than, Apply waits until the Seconds box holds a number of zero or more.
Clear All immediately resets the five filters owned by the popover (Channel, Caller Type, Response Time, Confidence Level, False Positives Only) — their chips disappear and the query re-runs at once, so you do not need to press Apply afterwards — and the popover stays open so you can pick a new filter. It does not clear the search box or the current sort.
False Positives Only keeps just the conversations that contain at least one guardrail result a reviewer has flagged as a false positive. One subtlety to expect, and it is not specific to this toggle: every summary figure on a card describes only the turns matching your current filters, because the filter is applied before the conversation is grouped. With this toggle on, a row can read "1 message" though the thread has more; the search box, a response-time bound and the confidence slider narrow the same figures the same way. The details drawer is deliberately unfiltered and still shows the whole thread. To see how often a specific guardrail has been flagged across all conversations, use the per-guardrail false-positive rate on the Guardrails page.
The Caller Type filter is most useful when combined with the Channel filter. For example, selecting MCP channel and Agent caller type isolates traffic from AI agents connected through the MCP server — a common first step when investigating an automation issue.
The Channel filter includes every interface that can produce a conversation, not just the traditional human-facing channels. This makes it possible to investigate programmable traffic directly from the log view:
Channel
Origin
Web Chat
Reserved for the embeddable web widget, which is not shipped yet. The Sandbox simulates this channel
Mobile App
Reserved for a native mobile SDK, which is not shipped yet
Teams
Microsoft Teams bot
WhatsApp
WhatsApp Business integration
SMS
SMS gateway
Phone
Voice channel
Email
Email-to-ticket integration
API
Direct calls to the public API with a credential
CLI
Requests made with a credential created with Channel CLI. The askrai command-line client is not generally available yet
Caller Type describes who produced the request. It is declared by the credential the request was made with, so only programmable traffic carries one:
Caller Type
Description
Human
A person calling through the API, CLI or MCP with a credential issued to a person
Application
A back-office service or automation calling with a service credential
Agent
An AI agent calling through MCP or the API with an agent credential
(none)
Traditional-channel traffic — Teams, Web Chat and the rest — which declares no caller type
Human does not mean "a person asked this". A question typed into Teams or Web Chat carries no caller type at all, so filtering on Human narrows the list to credential-issued traffic and hides every conversation from your traditional channels. The Caller Type chart on the dashboard counts the same way.
Filters are persisted in the URL as query parameters. Share the URL with a teammate to give them the same filtered view.
Sorting is performed in the Table view, reached through the List/Table toggle in the page header — the page opens in List view, and the card list has no sort control. In Table view, click a sortable column header — User, Channel, Response Time, Confidence, or Last Activity — to sort by it. Clicking the active column flips its direction; clicking a new column starts it ascending. The active column is announced to assistive technology through aria-sort. The default sort is Last Activity descending (newest first).
The sort itself is not tied to the view: it is sent to the API in both views and persists in the URL (sortField and sortDirection), so a sort chosen in Table view still orders the cards after you switch back to List. Only the control is missing from List view.
Click a conversation card to open the details drawer with two tabs: Overview and Audit.
This drawer is also where a guardrail trigger is marked a false positive, which is what feeds the per-guardrail false-positive rate on the guardrail analytics.
Select a message in the conversation thread (listed below the tabs) to view its audit record. The Audit tab opens with a stat grid — Audit ID (copyable), Timestamp, Response Time, AI Source, and Execution Mode (shown only when recorded) — followed by these sections:
Model — how the message was routed and which models answered it:
Stat
Description
Routing Source
How the model was chosen. Reads Not configured when a source was recorded but nothing routed the query, and Not recorded when the audit carries no routing metadata at all — two different diagnoses
Summarization
The model used for the summarization stage — the model the request actually ran on, otherwise the configured model, else Not recorded
Matched Rule
The routing rule that matched; labelled Primary Rule when more than one rule contributed to the decision
Extra Details
A collapsible panel — rendered only when there is something to show — listing the per-stage contributing rules, the Refinement model, the Guardrail model, and the Complexity tier. When a decision model classified the question, Classifier Confidence and Classified By (the versioned model that answered) follow it, and a confidence below the threshold says the tier fell back to Moderate
AI Confidence — the confidence score as a percentage with a color-coded progress bar. If the response also has a vector confidence score (the similarity of the best match retrieval found), it is displayed separately. A Degraded chip appears beneath the bars when the answer's low score measures no answer rather than a knowledge gap, and says why: the knowledge base could not be searched at all, the query failed, or the query was cancelled before its answer was scored, because the caller left or the service restarted. No escalation rule runs on such an answer. Treat a search or query failure as a platform fault to investigate, not as missing content to author.
Nearest Knowledge Base Match — when the confidence score is below the medium threshold, this section shows the question and stored answer of the Q&A entry that scored highest in retrieval, as Matched Question and Matched Answer. It shows what the knowledge base holds, not the assistant's wording, through the same Output guardrails set to Redact as the answer, so what they mask in an answer is masked here too.
An answer drawn from documents has no stored question or answer, so the section does not appear.
A stored question or answer too long for retrieval to pass on whole is left out of its line.
When that masking cannot finish, the section does not appear.
Conversations recorded before this behaviour may show the assistant's own wording under Matched Answer.
Governance — compliance status (Compliant, Not compliant, or Not checked), checked timestamp, reasoning, and per-guardrail results. Each guardrail result shows its compliance status, guardrail ID, and reasoning.
Escalation — the confidence band (High, Medium, or Low), whether the conversation was escalated, the escalation reason, and — when a ticket was created — the ticket ID as a copyable value (a truncated monospace string with a Copy button). The ticket ID itself is not a link; a separate View ticket button below it closes the drawer and opens the Tickets page with the ticket ID pre-filled in the search box, which resolves to that single ticket.
Click any message in the conversation thread to switch the Audit tab to that message's audit record. By default, the tab shows the most recent message.
When a guardrail evaluation produces an incorrect result — for example, flagging safe content as non-compliant — you can mark it as a false positive. Flagging records a review annotation on that single guardrail result (who flagged it, when, and an optional reason) and feeds the per-guardrail false-positive-rate metric on the Guardrails page. Only Platform Admins and holders of Manage policies, guardrails and egress can flag or unflag one: anyone else sees the guardrail's result without the flag button.
Flagging a false positive is an annotation, not a correction. It does not change the audit's compliance status, and it does not lower the Block Rate on the Dashboard — the block rate counts audits whose compliance is false and is blind to the flag. It also cannot undo an escalation or close a ticket that was already created: escalation rules are evaluated once, when the audit event is ingested, and they match on the response's confidence band — a guardrail result never triggers an escalation in the first place. To stop a guardrail producing bad results, edit the guardrail itself.
Open the Conversation Details
Click a conversation card to open the details drawer, then switch to the Audit tab.
Find the Guardrail Result
In the Governance section, locate the guardrail result you want to flag. Each guardrail row shows its compliance status and a flag icon.
Flag as False Positive
Click the flag icon next to the guardrail result. A confirmation dialog appears where you can optionally enter a reason for the flag.
Confirm
Click Flag as false positive to save. An orange "False Positive" chip appears next to the guardrail result to indicate it has been flagged.
To remove a false positive flag, click the orange flag icon on a flagged guardrail and confirm the removal.
False positive flags are per-guardrail, per-message. Flagging one guardrail result does not affect other guardrails in the same conversation or other conversations.
View and manage escalated support tickets with status tracking, severity classification, and conversation details
The Tickets page displays support tickets created when conversations are escalated by your configured escalation rules. You can search, filter, and update tickets to track resolution progress, review the original conversation, and assign tickets to team members. Tickets are listed newest-updated-first by default, and Table view lets you re-sort them by creation or update time. A Refresh button beside the filters re-runs the current query — the page loads once and does not poll, so this is how you pick up tickets raised since you opened it. Each new ticket also sends a notification to the holders of Manage escalation rules, Platform Admins among them, which opens this page.
The Tickets page displays all escalated conversations as actionable support tickets.
Ticket — a record created when an AI conversation triggers an escalation rule. Each ticket captures the original question, the AI response, and metadata about the interaction.
Status — tracks where a ticket is in the resolution workflow: Open, In Progress, Resolved, or Closed.
Severity — indicates urgency: Critical, High, Medium, or Low.
Confidence score — the AI's self-assessed confidence in its response, expressed as a percentage. Lower confidence often triggers escalation. Not every ticket carries one — see Conversation Tab.
Tickets appear as cards in list view by default. Each card shows the ticket ID (truncated to its first 8 characters, with a copy button), an Escalation badge, the title and description, the assignee, the creator, status, severity, and the creation date. A confidence badge is shown only when the ticket carries an AI confidence score. Toggle between List and Table view using the buttons in the top-right corner.
The list shows 10 tickets per page. When there is more than one page, a pager appears below the list; it is hidden when all results fit on a single page. The current page is kept in the URL alongside the active filters — the page parameter is zero-based and omitted on the first page (page 2 is ?page=1) — so a filtered, paged view can be shared as a link. Changing a filter returns you to the first page, but opening a ?page=N link takes you straight to that page.
Tickets load newest-updated-first (updated_at descending) by default. To change the order, switch to Table view and click the Created or Updated column header — the two sortable columns. Clicking a column sorts by it; clicking the active column again flips the direction between descending and ascending, shown by the arrow on the header. Those are the only two sortable fields, and the card (List) view has no sort control, so the order can only be changed from Table view.
Use the search bar and filter dropdowns above the ticket list to narrow results:
Filter
Options
Description
Search
Free text
Case-insensitive substring match on the user's display name, the question, and the answer. A ticket ID matches only when you enter the complete ID
Status
All, Open, In Progress, Resolved, Closed
Filter by resolution status
Severity
All, Critical, High, Medium, Low
Filter by urgency level
The truncated 8-character ID shown on a ticket card will not match a ticket by ID — it is still substring-matched against the name, question, and answer text, so it may incidentally hit an unrelated ticket. Use the copy button on the card or in the details drawer to get the full ID, then paste it into the search box.
Active filters appear as dismissible chips below the filter bar. Click the X on any chip to remove that filter.
A Created by Escalation Rule banner is pinned at the top of the tab for tickets tagged escalation — which is every ticket the platform creates, since escalation rules are the only ticket-creation path.
Below the banner, the tab displays the ticket metadata:
Field
Description
Ticket ID
Unique identifier, with a copy button
Created
Timestamp when the ticket was created
Assigned To
The team member responsible for resolution (shown as — while the ticket is unassigned)
Channel
The communication channel where the conversation occurred, copied from the source conversation when the ticket is created. Blank (shown as —) on tickets created before this was added
Chat ID
Session identifier linking to the original conversation, with a copy button
Priority
The ticket's severity level
Description
The rule that escalated the conversation, as Escalated by rule: <rule name>
User
The person who asked the question — display name next to a circle containing their first initial
Channel is populated on new tickets only. Escalation now copies the channel of the originating conversation onto each ticket it creates, so the Channel field in the drawer — and the Channel column in Table view — shows where the conversation took place (Teams, Web Chat, API, and so on). Tickets created before this was added were not backfilled, so their Channel stays blank and renders as an em dash (—). To confirm where any conversation took place, open it in the Conversation Logs.
Shows the original interaction that triggered the escalation:
This is the exchange that triggered the ticket, captured as it was answered — editing the knowledge base afterwards does not change what is shown here.
Original Question — what the user asked
Answer — the response that was provided
AI Response (Raw) — appears only on older tickets: the model's own response text as recorded on the source conversation, shown where it differed from the answer that was delivered. New tickets do not carry it
AI Confidence — a labeled score with a progress bar showing how confident the AI was in its answer. Shown only when the ticket carries a confidence score
If the escalation rule that created the ticket has Include AI context cleared, the ticket is stored with no confidence score: the card shows no confidence badge, and this tab shows only the question and the answer, with no AI Confidence bar. The same is true when the source conversation recorded no confidence score. See Escalation Rules for the toggle.
Shows governance and tracking information: the audit ID (with a copy button), the last update timestamp, and the ticket's status. When the ticket carries a chat/session ID, a View conversation in Log button appears and navigates to the full conversation in the Conversation Logs page.
Click directly on a ticket card's Status chip, Severity chip, or Assigned To value to edit it in place. Select the new value from the dropdown, or type a new assignee name and press Enter — or clear the field entirely and commit to remove the current assignee (press Escape to cancel; clicking away also commits what you typed). Changes save automatically. Inline editing is available on the cards in List view only — in Table view, use the edit (pencil) action on a row to open the edit dialog.
Clicking the Assigned To value on a card turns it into a text field you can type a new assignee into.
Click the Edit button on any ticket card to open the edit dialog. The dialog lets you update Status and Severity from dropdown menus, and set Assigned To in a free-text field (placeholder "Unassigned"); clearing that field and saving removes the assignee. Save changes stays disabled until at least one of the three fields differs from its saved value; Cancel prompts you to confirm before discarding unsaved changes.
Clearing the Assigned To field unassigns the ticket. Empty the field and commit — inline on a card, or in the edit dialog — and the current assignee is removed; the field then reads —. You can also replace one assignee with another at any time. (An unchanged, already-empty field is left alone, so editing only a ticket's status never disturbs its assignee.)
When you change a ticket's status to Resolved, the system automatically records the resolution timestamp. Changing it back to another status clears the resolution record.
The first 100 characters of the user's question (or Low confidence query when no question was recorded)
No
Description
The escalating rule, recorded as Escalated by rule: <rule name>
No
Status
Open, In Progress, Resolved, Closed
Yes
Severity
Critical, High, Medium, Low
Yes
Assigned To
Free text — name or email of the responsible team member. Can be set, replaced, or cleared to unassign
Yes
Confidence Score
AI confidence percentage (0–100%). Absent on tickets stored without AI context or without a recorded score
No
Channel
Communication channel (e.g., Teams), copied from the source conversation when the ticket is created. Blank (—) on tickets created before this was added
No
Created At
Timestamp of ticket creation
No
Updated At
Timestamp of last modification
No
User
Display name of the person who asked the question
No
Question
The original user question
No
Answer
The response provided to the user
No
Escalation Tag
Indicates the ticket was created by an escalation rule
No
Tickets are created automatically by escalation rules — that is the only path that creates a ticket. You cannot create a ticket manually from the Tickets page, and a ticket cannot be deleted from the console. Configure Escalation Rules to control when tickets are generated, and which severity and assignee they are created with.
Create, search, and curate the Q&A pairs and document chunks that power your AI assistant's responses
The Knowledge Base is the central content store that powers your AI assistant's responses. It holds two types of items — Q&A pairs, which you author in the console or which the platform imports or generates from a file uploaded to a Q&A-type content pack, and document chunks that the platform extracts from uploaded files — and gives curators a unified workspace to search, filter, edit, rate, and govern every entry across the entire tenant.
The Knowledge Base page in Text Search mode, with the seeded Employee Handbook entries visible.
Q&A pairs — questions and answers. Each pair has a question (what the user might ask) and an answer (what the assistant should respond with). Pairs reach the Knowledge Base by three routes: authored manually with Add Q&A, imported row-by-row from a CSV or XLSX file uploaded to a Q&A-type content pack, or generated by the platform from a PDF uploaded to a Q&A-type pack. Imported and generated pairs are created as Draft.
Document chunks — when you upload a PDF to a document-type content pack, the system splits it into chunks. Each chunk contains a portion of the document together with the page numbers it came from. The same file uploaded to a Q&A-type pack produces Q&A pairs instead.
Content packs — containers that group Q&A pairs or document chunks together. Every item belongs to a pack, and the pack decides which callers it can answer.
Status workflow — items move through statuses that control visibility: Draft (hidden from users), Approved (live), Needs Attention (flagged for review), and Discarded (soft-deleted). Only Approved items are retrievable, so a new Q&A — which starts as Draft — is invisible to the assistant until you approve it.
Vector index — Q&A pairs and document chunks are embedded as they are written, so there is nothing to rebuild and no reindex to schedule: a curator's change is searchable as soon as it saves. Every search is scoped to your tenant.
The toolbar exposes two search modes via a toggle on the left of the search field. Switch between them by clicking the magnifying-glass icon (Text Search) or the sparkles icon (AI Search).
The search-mode toggle sits to the left of the search field, with Filters and Add Q&A to its right.
Text Search is the default mode. As you type in the search field, results filter in real time across the question, answer, title, section heading, chunk content and tag fields — typing part of a tag finds every item whose tag contains it. Combine it with the Filters popover to narrow by tag, item type, status, sensitivity, and rating, and to change the sort order.
Each active filter appears as a chip beneath the toolbar, where you can clear it individually. Clear All, inside the Filters popover, resets every filter at once.
The search text, the filters, the sort order and the current page are kept in the page's URL, so reloading reopens the list you were looking at, and a filtered view can be shared as a link. Whoever opens the link sees the search text it carries. An AI Search query is not kept in the URL.
AI Search runs a vector similarity search across the entire tenant knowledge base: your query is embedded and the nearest items are returned. Use it when you cannot remember the exact wording of an item, want to find paraphrased duplicates, or need to discover items by intent rather than by keyword.
It matches on meaning only — there is no keyword matching underneath it. An exact string such as a policy code, a part number or a person's name is what Text Search is for; a short identifier carries almost no meaning to embed, so AI Search is the wrong tool to look one up with.
AI Search returns ranked semantic matches with confidence labels, highlighting the full query phrase wherever it appears in a title or preview.
Each result card shows:
A type badge (QnA or Document) with an icon
A confidence chip combining the qualitative label (Low / Medium / High) and the normalized score percentage
The current status of the underlying item
For document chunks, the chunk position within the source file (Chunk 3/12)
The title and content preview, with the full query phrase highlighted wherever it appears verbatim
The result list is sorted by score. The score is a cosine similarity between your query and the item, expressed as a percentage: it is a measure of closeness in meaning, not a percentage of correctness, and unrelated text still scores around 50%. The colored bar on the left of every card mirrors the confidence level so you can scan a busy result set quickly.
AI Search finds items in every status — Draft, Needs Attention and Discarded as well as Approved — so you can use it to review unapproved content by meaning. Each card's status badge says which it is. Only Approved items answer questions, so a match here is not necessarily one the assistant can use.
Click the sparkles icon in the search-mode toggle. The query field updates to the AI Search variant with a "Search semantically across the entire knowledge base" placeholder.
Type a natural-language query
Enter a question, paraphrase, or topic — anything from a single keyword to a full sentence. Queries are limited to 500 characters: the field does not stop you typing past that, but a longer one is refused when you run it.
Run the search
Press Enter or click the arrow button on the right of the field. A loading indicator replaces the arrow while the search runs; the response usually arrives within a couple of seconds.
Open a result
Click any Q&A card to open it in the details modal where you can edit, change status, or review history.
Document chunk hits are read-only in the result list. Each says Preview only, and clicking one opens nothing. To edit the underlying chunk, switch to Text Search and find the parent document.
Click Filters in the toolbar to open the filter panel. The panel opens in both search modes, and in AI Search it offers only the filters AI Search applies — see the note below.
The panel in Text Search. In AI Search it offers only Type, Status and Sensitivity.
Filter
Options
Tags
Multi-select from the tags your Q&A pairs carry. Matches items carrying any of the selected tags, whatever their letter case. Q&A pairs only
Type
All, QnA, Document
Status
All, Approved, Needs Attention, Draft, Discarded
Sensitivity
All, Public, Standard, Sensitive, Secret. Q&A pairs only
Rating
All, 5 stars through 1 star. Matches items rated exactly that number of stars — a "4★" filter does not include 5★ items. Q&A pairs only
Sort
Relevance, Newest, Oldest. "Relevance" sorts by most-recently-updated, identical to "Newest"
AI Search applies Type, Status and Sensitivity. In AI Search the Filters popover offers only those three. Tags, Rating and Sort, and their chips, are hidden there, and apply again when you switch back to Text Search; Clear All in AI Search resets only the three it shows. Changing Type, Status or Sensitivity after a query has run runs it again under the new filter.
Status narrows AI Search to the status you pick: filter by Draft, for instance, to find unapproved Q&As by meaning.
Sensitivity is a Q&A pair's alone, so any Sensitivity leaves document chunks out of AI Search as it does in Text Search. It is applied to the closest matches AI Search found, so a narrow one can return fewer results, or none, while matching items of that sensitivity rank further down.
Tags, Sensitivity and Rating apply to Q&A pairs only. In Text Search, selecting any of them narrows the result set to Q&As — every document chunk is excluded, even when Item Type is set to All, because chunks carry no tags, sensitivity or rating, and their cards show none. Combining one of them with Item Type = Document therefore always returns an empty result set.
"Relevance" is not a relevance ranking. In Text Search it sorts by most-recently-updated, exactly like "Newest": text results are ordered by date and never scored for relevance. Only AI Search ranks results by semantic relevance, which is why it offers no Sort.
The tags offered are the ones your Q&A pairs carry, read again each time the Filters popover opens, so a tag you add to a Q&A is offered as soon as you save it. A tag no longer on any Q&A stops being offered.
Click Add Q&A in the top-right corner of the Knowledge Base page.
A pair saved here starts as Draft and is invisible to the assistant until you approve it. Create stays disabled until the question, the answer and a content pack are all given.
Enter the Question and Answer
Type the question your users might ask in the Question field and the response the assistant should provide in the Answer field. Both fields are required.
Select a Content Pack
Choose a content pack from the Content Pack dropdown. Only Q&A-type packs appear in this list, and one is required: a Q&A answers only the callers with access to its pack. If your tenant has no Q&A-type pack yet, click Create a Q&A pack under the dropdown: it opens Add Knowledge Pack with Q&A selected, and the pack you create there is chosen for this pair, with the question and answer you typed kept. A pair's details offer the same link while your tenant has no Q&A-type pack.
Create the Item
Click Create. The item is saved with Draft status. A success notification appears and the dialog closes automatically.
The item does not answer questions yet. The assistant uses only Approved items, so it cannot use a draft. Open the new item, click Approve, then click Save changes to publish it. In the details modal the quick-action buttons only stage the status change (the footer shows "You have unsaved changes"); closing the modal before you save asks whether to keep editing or discard it. To publish in one click instead, use the card's three-dot menu — that writes the change immediately.
Write questions in natural language that matches how your users actually ask. For example, use "How do I request time off?" rather than "Time Off Request Procedure."
Click any card — a Q&A pair or a document chunk — to open the details modal. The modal exposes two tabs at the top:
Details — the editable view with status and sensitivity badges, quick-action buttons (Approve, Flag for Attention, Discard), inline-editable question and answer fields, a Q&A pair's Content Pack, rating, tags, and metadata. Choose another Q&A-type pack and click Save changes to move the pair. A pair moved out of the pack its file was uploaded to no longer belongs to that file: removing or re-processing the file leaves it in place. A pair saved before a pack was required has none and answers no one: its card says No content pack, and it saves again only once you choose one here. A pair's question and answer may not be left blank: either one cleared says it is required and holds Save changes.
History — a chronological list of every prior version. The Compare button (enabled once two or more versions exist) opens a side-by-side diff view where you can pick a base version and a comparison target to inspect exactly what changed and who changed it.
For document chunks, the modal includes chunk navigation buttons (Previous / Next) to step through all chunks from the same source file, with a "Chunk N of Total" indicator.
Save your changes before navigating between chunks: the Previous / Next buttons are disabled while you have unsaved edits. Switching tabs is not blocked, so it is possible to move from Details to History with unsaved edits still pending — save first.
There are two ways to move an item through the workflow:
From the card — open the three-dot menu on any card (Q&A pairs and document chunks both have one) and choose Approve, Discard, or Flag as Needs Attention. The change saves immediately. A pair in no content pack offers none of these until it is put in one.
From the details modal — open the item and use the quick-action buttons (Approve, Flag for Attention, Discard). These buttons only stage the new status in the open modal; you must click Save changes to persist it. If you close the modal without saving, you are asked first: Keep editing keeps the staged status change, and Discard changes drops it.
Approving is what publishes an item: the assistant answers only from Approved items, so it cannot retrieve a draft until the item is approved and the change is saved.
Open the item's details modal, click Delete at the bottom-left, and confirm. The item stops being retrieved at once and cannot be restored. This is a hard delete, distinct from the Discarded status, which only hides the item from users and can be reversed.
Edits you make here take effect when you save them — there is nothing to rebuild afterwards. To see what the platform ingested from an uploaded file, and how much knowledge came out of it, click Processing History in the toolbar; the page is described under Knowledge Packs.
A file uploaded to a Q&A-type pack becomes Q&A pairs, not document chunks. There are two paths:
CSV or XLSX — imported directly, row by row, into question/answer pairs. Document parsing is skipped entirely. Both formats are accepted by Q&A-type packs only. A row missing its question, its answer or its second column is left out and the rest imported; the file's row in the pack says how many were left out, and why for the first five. A file none of whose rows can be imported fails, naming its first such row and why.
PDF — parsed and chunked like a document, after which the platform generates Q&A pairs from the chunks.
Both paths create the pairs with Draft status, so nothing they produce is retrievable until you review and approve it.
There is a size ceiling of 100 MB per file, refused before the transfer starts. A second ceiling applies after parsing: a source that yields more than 10,000 items — chunks or Q&A pairs — fails at that point, so a large, text-dense PDF can upload successfully and then fail during processing. A CSV or XLSX file is held to it as it is read: it fails at its first row past 10,000 that holds a question or an answer, a header row aside, or once its pairs hold more than about 32 MB of text, less when the text holds emoji. An XLSX file also fails when reading it takes more than 30 seconds of processing time, or far more memory than 10,000 rows of text need. Document-type packs accept PDF only; Q&A-type packs accept PDF, CSV and XLSX.
Which collection this item belongs to, and so which callers it can answer. Changed from the item's details
Yes
Status
Controls visibility: Approved (live), Draft (hidden), Needs Attention (flagged), Discarded (removed). New Q&As start as Draft and answer nothing until approved
Set on create
Sensitivity
A classification label: Public, Standard, Sensitive, or Secret. Text Search and AI Search can filter by it. It does not restrict who is answered from the item
No (defaults to Public)
Rating
Curator quality assessment from 1 to 5 stars
No (defaults to 0)
Tags
Categorization labels. The item's editor offers every tag your Q&A pairs already carry and accepts a new one typed in; once saved, the new tag is offered on every Q&A and in the Filters popover
No
Sensitivity is a label, not access control. Marking an item Sensitive or Secret does not change who is answered from it: once approved, it can answer every caller with access to its knowledge pack. To keep an item from some callers, put it in a knowledge pack they have no access to — see How access control works.
Position within the source document (e.g., Chunk 3 of 12)
No
Status
Same status workflow as Q&A items. Chunks are created Approved
Yes
Page numbers are captured during parsing and kept on the record, but the console does not display them today. Chunks carry no section heading: text extraction yields the page's text, not the document's structure.
Knowledge Packs — create content pack containers and upload documents
Guardrails — set safety policies that evaluate user input
Conversation Logs — see how the assistant uses knowledge items in responses
Confidence Thresholds — tune the minimum scores the runtime accepts before answering from a knowledge item
Knowledge Packs
Organize knowledge base content into collections with file uploads, content type selection, the organizations whose agents may search them, processing history, and bulk status management
Knowledge packs let you organize your knowledge base content into logical collections. Each pack groups related question-and-answer pairs or documents, making it easier to manage, upload, and maintain the content that powers your AI assistant's responses.
The Knowledge Packs page displays all packs as cards with content type badges, source counts, and action buttons.
Before working with knowledge packs, understand these core concepts:
Content type — each pack is either QnA (question-answer pairs for direct lookup) or Document (whole documents for agent search without creating QnAs). You choose the type when creating a pack and it cannot be changed later. The console spells the content typeQnAand an individual pairQ&A— this page follows the same convention.
Sources — files you upload to a pack. Each source is first transferred from your browser (Uploading), then goes through the processing pipeline (Queued → Parsing → Chunking → Generating QnA → Indexing) before its content becomes searchable. Per-source progress and failures are shown inside the pack's details modal.
Status — packs display an overall status derived from their sources: Syncing while any source is Queued, Parsing, Chunking, Generating QnA or Indexing; Error if a source failed and no source is in flight (in-flight work outranks a failure, so a source that is being retried reads Syncing, not Error); Active otherwise. A source that is still Uploading is deliberately not counted as in flight — the bytes are still with the browser — so on its own it does not make the pack Syncing: such a pack reads Active (or Error, if a sibling source failed). Stopped (cancelled) sources are likewise excluded from the in-flight set.
Bulk actions — you can approve or draft all QnAs or document chunks in a pack at once, controlling whether content is used to answer questions.
Searchable on write — there is nothing to sync. Processing embeds each chunk or Q&A as it stores it, so content is searchable the moment it lands. What decides whether the assistant may use an item is its status: only Approved items are retrievable, and approving one takes effect immediately. Past processing runs are listed on the read-only Processing History page.
The Knowledge Packs page displays all packs as cards in a responsive grid. Each card shows the pack name, description, content type badge (QnA or Document), source and file counts, a Last processed timestamp for that pack (see the field reference), and quick-action buttons. The quick actions are Delete and, for QnA and Document packs only, the ⋮ bulk-actions menu.
Use the Search knowledge packs field at the top of the page to find packs by name. For more precise filtering, click Filters to open the advanced filters popover, where you can filter by status — Active, Syncing, or Error (the three states a pack can be in; see the status reference).
Active filter selections appear as chips below the search bar. Click the x on any chip to remove that filter, or use Clear All Filters in the popover to reset all filters at once.
Click the Add Knowledge Pack button in the top-right corner of the page.
Select a Content Type
Choose between QnA and Document using the toggle buttons. QnA packs store or generate question-answer pairs for direct lookup. Document packs store whole documents for agent search without creating QnAs.
The content type is fixed at creation and decides which files the pack accepts: Document packs take PDF only, Q&A packs take PDF, CSV and XLSX.
Enter Name and Description
Provide a descriptive Name (up to 200 characters) and Description (up to 1,000 characters) for the pack. Both fields are required and marked with an asterisk: Create stays disabled until both are filled, and a field left blank says so.
Create the Pack
Click Create to save the new knowledge pack. The dialog closes automatically and the pack appears in the grid.
The content type cannot be changed after creation. If you need to switch between QnA and Document, create a new pack with the correct type.
Click any knowledge pack card to open its details modal. From here you can edit the pack's name and description, upload files, manage sources, and choose which organizations' agents may search the pack.
The drop zone names the formats this pack accepts, every source already uploaded to it is listed beneath with its processing state, and the Organizations section shows whose agents may search it.
To rename a pack, hover over (or tab to) the pack name in the modal header and click the pencil button that appears — clicking the name itself does nothing. The description is directly clickable. Make your changes and press Enter to confirm or Escape to cancel, then click Save changes to persist your edits to the server. Neither may be left blank: a field cleared says it is required, stays open on Enter, and holds Save changes.
Drag and drop files onto the upload area, or click Select Files to browse. You can upload multiple files at once, as many as you like: past the number your tenant processes at a time, the rest wait their turn and start on their own (below). The hint under the drop zone names the formats for the pack you opened, and they depend on its content type:
Document packs: PDF only
QnA packs: PDF, plus CSV and XLSX for importing question/answer pairs you have already written
PDF is the only document format, and it must carry a text layer. Word, PowerPoint and image files (.doc, .docx, .pptx, .png, .jpg, .tiff, .bmp) are refused, and so is a spreadsheet added to a Document pack — XLSX is accepted only by QnA packs, as a table of pairs to import. The console refuses them before anything is transferred: Select Files offers only the accepted extensions, and a file that gets in anyway — dropped onto the upload area, or chosen after switching the picker to "All Files" — is dropped from the selection with the toast <file> is not a supported file type. Supported: .pdf. It never reaches Selected Files, and no source row is created. Convert before you upload, not after.
There is no OCR. A scanned page or a photograph of a document uploads successfully and then fails during processing with "No extractable text layer was found in this file" — export a text-based PDF from the original instead. Convert Office documents to PDF before uploading.
Review Selected Files
Selected files appear in the Selected Files list below the drop zone. Remove any unwanted files by clicking the x button next to each file, or click Clear All to remove all pending files.
Upload and Process
Click Upload Files to start the upload. Each file goes directly from your browser to AskRAI's object storage over a short-lived signed URL — the bytes never pass through the AskRAI API — and processing begins automatically. You can track the processing status in the Uploaded Files list:
Uploading / Queued — file is being transferred or waiting to process
Waiting to process — file is stored, and starts processing on its own once one of the files processing now finishes
Parsing / Chunking / Generating QnA / Indexing — file is being processed through the pipeline
Completed — file has been fully processed and content is searchable. A CSV or XLSX file that left rows out says under its name how many, for example Imported 2 Q&A pairs; 1 row could not be imported, then lists the first five by row number with why, such as Row 3: Answer cannot be empty. A row with neither a question nor an answer is not counted
Error — processing failed. The row shows the whole reason under the file's name
If the pack already holds a file of the same name, you are asked what to do before anything is transferred, so the same passages are not indexed twice:
Replace — uploads the new file and, once it reads Completed, deletes the old one with every document chunk or Q&A made from it. Until then the old file keeps answering, and if the new one fails or never finishes uploading, the old one stays.
Keep both — uploads the new file beside the old one, and both are searched.
Skip — uploads nothing; closing the question does the same.
A file is matched by its name in this pack only: a renamed copy, or the same file in another pack, is uploaded without asking.
Some failures on AskRAI's side can clear on their own, such as a storage or database outage. A file that meets one is usually tried again automatically: it goes back to Queued and starts over, with nothing for you to do, and reads Error only if the last attempt fails too. A failure that would only happen again, or one that comes about an hour after the file was queued, reads Error straight away. In rare cases processing stops without reporting why: such a file reads Error within about an hour and a half of its last progress, and Retry processing is offered.
While the pack stays open, a file you upload or retry is toasted as it finishes: <file> processing complete!, <file> processing complete: followed by what a CSV or XLSX file imported and how many rows it left out, or <file> processing failed: followed by the reason, which stays until you dismiss it or retry the file. A file being tried again is not toasted until it finishes. A long reason is cut short in the toast; the file's row always shows it in full.
You can stop a source that has entered the processing pipeline (Queued, Parsing, Chunking, Generating QnA or Indexing) by clicking the stop button next to it. Stopped sources show a Stopped status and their content is not included in search results.
The transfer and the processing are two separate steps, and the second one can wait, or be refused, after the bytes have already landed. Either way the file stays safely in storage and leaves Selected Files: nothing has to be uploaded again, and uploading it again would only ask to replace it with itself.
Your tenant processes up to five files at a time by default, counted across every pack. A file stored past that reads Waiting to process, and the console starts it as soon as a slot frees, oldest first: when a file it is tracking finishes, and otherwise at least once a minute, for a slot freed in another pack or by another admin. Each person can also ask for processing ten times a minute, asks refused for a full tenant included, so a large batch of small files starts at most about ten files a minute even while slots are free, the rest waiting the same way. A file uploaded while one of the two passing refusals below holds also reads Waiting to process, and is started the same way. The pack can be closed meanwhile. Reload the page or close the tab, though, and a file still waiting stays in Uploading with Retry processing offered, which starts it, or puts it back in line while the limit holds.
When you press Retry processing yourself, a refusal is toasted with its reason, and the source stays in Uploading or Error with Retry processing still offered:
Message
What it means
What to do
The processing queue is not accepting work right now. Please retry shortly.
The bounded work queue refused the job, or did not confirm it in time. The source is put back exactly where it was, rather than left in a state that is neither retryable nor cancellable. If processing had already begun by then, nothing is put back and no message is shown: the file simply processes.
Retry processing. It is a transient refusal, not a rejection of the file.
Content pack is being modified concurrently. Please retry.
Another change to the same pack — an upload, a delete, a status change, or a running job reporting progress — won the race to write it. Nothing was changed.
Retry processing. Packs are edited as a whole, so two writes landing together is routine; the second one is asked to try again rather than silently overwriting the first.
A retry never processes a file twice. A job the queue was slow to confirm can still arrive after its source was put back, and if it has, Retry processing says Processing had already started for this file and the row moves on to where the file actually is.
Waiting and both refusals happen before any parsing, so nothing is half-ingested and no partial content becomes searchable. Retrying costs nothing beyond the retry itself.
A row stuck in Uploading has two causes — try Retry processing before you delete it. The source is registered before the signed URL is issued, so if the browser tab is closed or the transfer fails, the source stays in Uploading. There is no server-side work to stop, so no stop button is offered for it, and the automatic check that marks genuinely stuck sources Error deliberately leaves it alone. The Retry processing button (the circular arrow, offered for Uploading and Error sources) covers the case where the transfer did land and only the follow-up processing call failed: it re-queues the file already in storage, with nothing to transfer again — and a refusal from the table above is the most common reason that call failed. If the transfer never landed, retrying cannot help — use the trash icon, which stays available for this status, and upload the file again. An abandoned upload does not make the pack read Syncing — the pack reads Active (or Error, if another source failed).
Every row in the Uploaded Files list carries a Download button that retrieves the original file exactly as it was uploaded — useful for checking what was actually ingested, or for recovering a file whose local copy is gone. It is disabled only while the source is still Uploading, when there is nothing stored yet to fetch. Retry processing and Stop processing appear only for the statuses described above.
In the same list, click the trash icon next to a source to remove it, along with everything derived from it and the uploaded file itself. The trash icon is disabled only while the source is in the processing pipeline (Queued, Parsing, Chunking, Generating QnA or Indexing) — stop it first, then delete it. Completed, failed, stopped and abandoned Uploading sources can all be deleted directly.
The Organizations section of a pack's details decides which agents may search it: "Agents in these organizations may search this pack. People reach it through their groups." A pack starts granted to no organization, so no agent can use it until one is ticked. Once it is, it can be attached to the agents of that organization's projects, on each agent's Access & Data tab. People are not affected by this list at all: what a person can read is still decided by their groups.
Who can change it. Only someone allowed to manage users and groups, such as a Platform Admin, can tick or untick an organization and click Save organizations. Everyone else sees the same list read-only, with a line saying who can change it.
Used by. Beside the list, Used by N agents names every agent that holds the pack, with its project. An agent in a project not shared with you is counted and listed as An agent in a project not shared with you, without its name or its project's.
Revoking. Unticking an organization takes the pack off every agent in that organization's projects as soon as you save. If any of them holds the pack, Save organizations first asks you to confirm, naming the agents that will lose it, and Revoke and save stays disabled until that list has loaded.
Changed elsewhere. If another admin changed the list after you opened the pack, your save is not applied: the list shows theirs and says so, so you can make your change again.
A deleted organization. A grant to an organization that has since been deleted is dropped the next time the list is saved, and the section says so.
Bulk actions let you approve or draft all items in a knowledge pack at once. This is useful when you have uploaded new content and want it all to answer questions, or when you need to temporarily hide all content from users.
Open the Bulk Actions Menu
On the knowledge pack card, click the three-dot menu icon (⋮) to open the bulk actions menu. This option is only available for QnA and Document type packs.
Choose an Action
Select either:
Bulk Approve All QnAs (or All Chunks on a Document pack) — marks every item in the pack as approved, making it retrievable
Bulk Draft All QnAs (or All Chunks) — marks every item as draft, taking it back out of retrieval
Confirm the Action
A confirmation dialog explains the impact. Click Approve all or Mark all as draft to proceed, or Cancel to abort. The page then says how many items changed, until you leave it.
Approving all items makes them immediately visible in AI assistant responses. Review your content before bulk-approving to avoid surfacing incomplete or inaccurate information.
To delete a pack, click the trash icon on the pack card. A confirmation dialog warns that the action is permanent and will remove the pack, all Q&A entries, and all uploaded files, and names the agents that hold the pack, or says that none does. Delete knowledge pack stays disabled until that list has loaded; click it to confirm.
A deleted pack is granted nowhere: before its content is removed, it is taken off every agent that holds it and every group that grants it, so no group goes on listing a pack that no longer exists. A group's knowledge packs can only name packs that exist.
Deleting a knowledge pack is permanent and cannot be undone. All associated content — including Q&A entries, document chunks, and uploaded files — is permanently removed, and every group and agent loses the pack.
There is no index to rebuild and nothing to trigger: each chunk and each Q&A pair is embedded and written as it is processed, so it is searchable as soon as it lands, and changing an item's status to Approved makes it retrievable immediately. What the platform records instead is the ingestion itself — one run per file processed.
Click Processing History at the top of the Knowledge Packs page to open that record. It is read-only, and it shows:
Active run banner — while a file is being processed, a banner shows the run's status, when it started, who started it, and the file it is working on
History table — a paginated table of past runs: what was ingested, how long it took, and how much knowledge came out of it
The page checks for a run every 10 seconds while none is in progress and every 3 seconds while one is, so a run started elsewhere appears, and you can watch it complete, without reloading. Processing continues whether or not the page is open.
A run is recorded for each file that goes through the pipeline, whether it was uploaded to a Document pack, uploaded to a QnA pack for pair generation, or imported as a CSV or XLSX table of pairs. Bulk status changes and deletions are applied directly and are not runs, so they never appear here.
Brief summary of the pack's content (truncated to 2 lines on cards)
Content Type
QnA or Document — determines how uploaded files are processed
Status
Active, Syncing, or Error — derived from the state of the pack's sources. A source that is still Uploading does not count as in flight, so it does not make the pack Syncing
Files
Number of uploaded files in the pack
Sources
Number of sources connected to the pack
Last processed
When a file in this pack last finished processing successfully. A failed run does not move it, and neither does an edit, a status change or a deletion — it tracks ingestion, not content changes. Reads Never until the pack's first file completes
The card gives you the summary; the details modal gives you the detail. If a pack reads Error, open it — its list of files shows which source failed and why.
Q&A Import for a CSV or XLSX table of ready-made pairs; Document Upload for every other file, including a PDF uploaded to a QnA pack for pair generation
Triggered By
The user whose upload started the run, or system when the platform started it itself
Produced
What the run stored, as "N Q&A, N chunks". A run that stored nothing reads "Nothing stored from N parsed chunks", or "Nothing parsed" when no text could be extracted at all
Admin — configure confidence thresholds that affect how knowledge pack content is used
Sandbox — test your AI assistant's responses using knowledge pack content
Guardrails
Review how each guardrail is performing — fire rates, compliance trend and false positives — and set its name, category and priority
Guardrails are the safety and compliance checks AskRAI runs over an interaction. This page is where you review how they are performing — how often each one fired, against what, and how many of those were false positives — and where you set a guardrail's name, description, category and priority. Like every guardrail surface, it opens to the holders of View policies, guardrails and egress, read-only, and of Manage policies, guardrails and egress, who make those changes; Platform Admin holds both (Access). A Member does not see it in the console's navigation.
What a guardrail actually does is defined elsewhere. Its kind, the stage it reads, the action it takes and whether it is Active all live on the Admin → Guardrails page, which is also where guardrails are now created. Every editor here links there with Edit in Admin. See Guardrails (concept) for what those three decisions mean.
Each card carries the guardrail's category, its priority and a preview of its prompt — the fields this page owns.
A guardrail that nothing lists screens nothing, for anyone. Guardrails are attached to a subject, never applied tenant-wide: a person's guardrails come from their groups, an agent's from the agent. This page has no attachment control. To put one into effect, add it to a group under Admin → Users → Groups (see Users, Roles & Groups), to an agent on the project's Team pane, or to a policy attached to either.
Six kinds, five of them free. PII, regex deny, word deny, secret scan and link domain are evaluated in code and cost no model call. Only an LLM judge reaches a provider — and only a judge has a prompt.
Three stages. A guardrail reads the user's question (Input), the generated answer (Output), or the arguments an agent is about to send to a tool (Tool call). A rule about how answers should be worded belongs on Output.
Three actions.Block stops the turn, Warn lets it continue and leaves a record, Redact substitutes what it found and continues. One blocking guardrail is enough — there is no majority rule.
Priority is evaluation order. The deterministic kinds run one after another in priority order, and the first one to block is the one reported as the reason. Judges run afterwards, at most three at a time. Once something has blocked, only the judges that would also Block are skipped — a Warn judge still runs, so it keeps firing on exactly the turns it was attached to watch. (A judge cannot be set to Redact: it returns a verdict, not the position of what it objected to.)
Audit recording. Every evaluation, pass or fail, is recorded and counted in the analytics. No setting reduces this.
Only Active guardrails run. A draft is listed and attachable and evaluates nothing. The status badge is in the editor here; the status itself is set in Admin.
List view (default) — a card per guardrail with its name, category badge, priority chip, a preview of its prompt, and a fire badge.
Table view — columns for name, description, category, priority, reporting level, fire count, fire rate and a sparkline trend.
Analytics view — a compliance trend line, a category distribution breakdown, and a top-fired guardrails chart.
Table view sorts on Name, Category and Priority only — Description, Fires, Fire Rate and Trend carry no sort control. Note the pager: the list is ten guardrails to a page.
By default the list is in run order: lowest priority number first, so the guardrail that runs first heads it. Sorting, filtering and paging are all done by the server, so the sort applies to the whole set rather than to the page you are looking at.
The card (List) view relabels the category badge: compliance shows as Regulatory, quality as Behavioral, privacy as Legal, and custom as Procedural. The underlying names are what you see in the editor, the filter dropdown, and Table view.
Filter the list from the toolbar:
Search — case-insensitive substring match across the name, description and prompt fields.
Category — Safety, Compliance, Quality, Privacy, or Custom.
Priority — a range of priority numbers, From and To inclusive, each applied as you type it. Leave either blank for no bound: From40 alone lists every guardrail at 40 or more. The lowest number runs first.
Reporting level — None, Alerts or All. This is stored metadata that no longer has an editor control and does not affect what is audited (see below); the filter is here because the value is still recorded and still shown in Table view.
Active filters appear as removable chips below the toolbar. Clear All lives inside the Filters popover, not next to the chips.
Add Guardrail navigates to Admin → Guardrails, where authoring happens. That is the only surface carrying kind, stage, action and status — the four fields that decide whether a guardrail does anything at all — so a guardrail cannot be created from this page.
This page and Admin → Guardrails open to the same people, so everyone who can see this page can open Admin → Guardrails too. Add Guardrail needs Manage policies, guardrails and egress: for a holder of View alone it is held, saying so.
Once the guardrail exists, come back here to set its category and priority, and to watch it perform.
Click any guardrail card or table row to open the editor. Name and description are edited in place from the header; category, priority and — for an LLM judge — the prompt are below.
The strip at the top is what this guardrail does at runtime — status, kind, stage and action — none of which this editor can change. It is shown because the fields beneath it read as the whole of a guardrail without it.
The Prompt field appears only for an LLM judge, and Save changes is held until it has one: a judge with an empty prompt asks the model nothing. Every other kind is refused by the server for carrying a prompt at all, so no prompt is offered for them.
Priority takes any whole number from 0 up, and the lowest runs first; the guardrails that ship with AskRAI sit between 5 and 40. A priority you have not touched never holds Save changes, so renaming a guardrail leaves its priority as it was.
Saving applies from the next turn onward, including turns in conversations already under way, and is in force everywhere within five minutes at the outside.
Guardrails that ship with AskRAI are read-only on both pages — an edit or a delete is refused. Neither List nor Table view marks them: the Platform badge appears once you open one, alongside the notice that it cannot be changed.
Every control is disabled and Delete is absent — the editor says so rather than letting you reach a permission error. To change one, duplicate it under Admin → Guardrails to get an editable copy.
Switch to the Analytics view to see guardrail performance over a configurable date range. That view has its own date picker (with 30d/60d/90d presets) and a Channel filter, separate from the Analytics period picker used by List and Table view. The Analytics picker allows up to 90 days; the List/Table picker is limited to a 30-day span, the longest the fire badges can show. In both, a wider range, or a From after its To, is not applied: the reason appears under the date inputs, and the view keeps the last range it showed. A link to the Analytics view carrying such a range opens on the last 30 days. Each day of a range, and of the compliance trend, runs from midnight in your browser's time zone, as the conversation logs show their times.
Compliance trend — the share of blocking guardrail evaluations that passed. Warn and Redact results are left out: they found something and let the turn through, so how often those fire is what the fire count and the Top Triggered chart show instead. It counts evaluations rather than conversations, so a message screened by three guardrails contributes three results.
Category distribution — fires broken down by category.
Top Triggered Guardrails — guardrails ranked by fire count, not by priority. Each bar's label also carries that guardrail's fire rate and, where one exists, its false-positive rate — the share of its fires later marked as false positives in the conversation logs. There is no separate false-positive chart. Clicking a bar opens that guardrail's editor, wherever it sits in the list and whatever the list's filters hide. A bar for a guardrail deleted since it fired says the guardrail no longer exists.
In List view each card shows a fire badge with the total for the selected range, and beside it the fire rate as a percentage of conversations plus a sparkline. The badge colour reflects the rate: green below 15%, orange from 15% up to 50%, red at 50% or more. Table view shows the same numbers as plain columns.
Nothing lists it. Attach it to a group, an agent, or a policy — or its status is draft, which is set in Admin.
Save changes stays disabled
The name is empty, it is an LLM judge with no prompt, or Priority holds something other than a whole number from 0 up.
Guardrails is missing from the console's navigation
None of the account's roles grants View policies, guardrails and egress or its Manage, both of which Platform Admin includes. Guardrails are reserved for their holders wherever they appear.
Editing a platform guardrail is refused
Platform rows are read-only. Duplicate one under Admin → Guardrails.
Manage user accounts, define routing roles with mapping rules including caller and credential types, and organize access through groups
User Management is your central hub for access management. Users represent real people in your organization, routing roles define usage patterns with automatic mapping rules, and groups tie users and routing roles together with access to specific knowledge packs and guardrails. Find it under Admin → Users.
The Users tab displays all user accounts with their status, department, and group memberships.
User Management lives in Admin, so it opens to the holders of View users & groups or Manage users & groups, Platform Admins among them — see Access. The older /users link still works and redirects here.
Everything on this page — groups, routing roles, mapping rules — decides which knowledge and guardrails apply to an interaction. It does not decide who may administer AskRAI. That is a separate, tenant-level question answered on the Access page, which grants the Platform Admin and Member roles. Adding someone to an "Admin Access" group here does not let them into Admin.
The Users tab shows all user accounts provisioned through Directory Sync — whether your identity provider pushes them over SCIM 2.0 or AskRAI pulls them from Google Workspace. Each user card displays the person's name, job title, department, email address, status, and group memberships.
If your directory deletes an account and later creates a new one with the same email address, the Users tab lists that person once, as the new account. So does every place you pick a user: adding group members, granting an Access role, or adding someone to a project team. The old account still appears on the Directory tab, tagged Deprovisioned. Nothing moves to the new account. The old account keeps its groups, its Access role, its organization and project grants and its project teams, and none of them gives anyone access. A block on the old account does not carry over either. Give the new account the groups and roles it should have, share with it the organizations and projects it should see, and block it if it should be blocked.
AskRAI refuses every question the user asks, and everything they do in the admin console
To block a user, open their details drawer, choose Block user beside their account status, and confirm. Their questions are refused at once, and their use of the admin console within 30 seconds. A blocked user's drawer offers Unblock user instead, which gives them back the access their groups grant, on the same timing. You cannot block your own account.
Blocking or unblocking someone takes away or gives back every role they hold, so it needs every permission their roles grant, and only a Platform Admin blocks or unblocks a Platform Admin. The tenant's last Platform Admin assigned directly to a user who can sign in cannot be blocked: one already blocked, or deprovisioned by your directory, does not count. When one of these rules stops you, AskRAI says why.
A user your directory has deprovisioned shows no status, only the Deprovisioned tag: AskRAI refuses their queries. If you blocked them, they still show Blocked beside the tag.
Click any user row to open the details drawer. Its header shows the user's ID, which you can copy, and it has these tabs:
Details — name, job title, department, account status with Block user or Unblock user, and email address
Groups — lists all groups the user belongs to, with member counts and knowledge pack access
Access — every role the user holds, assigned to them directly or through a group, and each permission those roles grant, by section, with the roles it comes from: "From Project leads; Tool keepers, via Finance analysts". A group a role comes through opens on the Groups tab. Below them, the user's grants: each organization and then each project shared with them, with its level, and whether it was shared with them, with a group they are in, which it names, or with everyone in the tenant. It lists only the organizations and projects you can see yourself, so it may hold fewer grants than the user has. Only someone who can view roles and assignments sees this tab
The Access tab says where each of a person's permissions comes from.
Use the search bar and the Status dropdown to narrow the list:
Filter
Options
Description
Search
Free text
Matches user names, display names, email addresses, and departments
Status
All, Active, Blocked
Filter by account status. Active leaves out deprovisioned users
The list cannot be filtered by group. A user's groups are shown on each user row and in the details drawer, and a group's members are listed when you open the group on the Groups tab.
Groups are permission containers that connect users and routing roles to knowledge packs and guardrails. A user's access to knowledge base content is determined by their group memberships.
Each group card shows its users, its routing roles, its roles, its knowledge packs and its guardrails.
A group card's Routing roles are the routing roles in the group, described under Routing roles tab. Its Roles are the roles the group is assigned on the Access page, which its members hold while the group is active. Only someone who can view roles and assignments sees them. Anyone else is told which permission reading them needs.
The Filters button narrows the list to the groups holding every routing role, knowledge pack and guardrail you pick.
Switch to the Groups tab and click Add Group in the top-right corner.
A native group created here can carry guardrails and knowledge packs exactly like a synced one — the difference is only where its membership comes from.
Enter Group Details
Type a group name (required) and an optional description. Click Create to save.
Configure the Group
After creation, the group details modal opens automatically. Use its six tabs to configure the group:
Members — add users and routing roles to the group. Toggle between Users, Routing roles, or Both views, search, and click the + icon to add them. A programmable-access credential created in this group is listed as a member with a key icon. It cannot be removed here, because its membership is what applies the group's knowledge packs and guardrails to it. It leaves the group when it is revoked or deleted on the Programmable Access page. A group's members hold the tenant roles assigned to it, so adding or removing one needs every permission those roles grant, and only a Platform Admin changes who is in a group holding Platform Admin. Its members also hold the group's organization and project grants, so changing them needs Admin on every organization and project the group is shared with.
Knowledge Packs — select which knowledge packs this group can access. Search and add packs from the available list.
Guardrails — assign the guardrails that apply to this group's members. An active Input or Output guardrail applies to every member's query. A Tool call guardrail checks an agent's tool calls, and a member's query makes none, so it does not apply here. Naming a group's guardrails and policies takes View policies, guardrails and egress, and changing them Manage policies, guardrails and egress.
Policies — attach governance policies to the group. On every member's query, a policy applies its status and its Input and Output guardrails, and its egress allowlist only as the list a Link domain guardrail checks links against. Its ceilings, its approval requirements and its Tool call guardrails govern an agent's beats, so they do not apply to the group's members. See A policy on a group.
Credentials — a read-only list of the programmable-access credentials mapped to this group, each with its type and an Active, Interface off, Expired or Revoked status. Credentials themselves are issued and managed on the Programmable Access page.
Directory — link this group to a directory group so its membership is provisioned from your identity provider. Search the directory groups by name: the list shows the first 50 that match, and says so when there are more. While linked, the tab names the directory group this group follows, members are synced from the directory and managed there, and unlinking returns the group to manual membership. If the tab says the link did not finish, the group names the directory group but has none of its members yet: click Link again to finish it. When the directory group is deleted in your identity provider or Google Workspace, AskRAI unlinks this group for you as soon as it learns of it, which for Google Workspace is the next sync. Everyone the directory group gave it leaves, including anyone you had also added by hand, the other members you added stay, and you manage the group here from then on. No notification is sent, and a directory group created again under the same name is a new one to link to. If the tab instead says the directory no longer holds the group this one follows, as it can for a directory group deleted before AskRAI unlinked groups on its own, nothing syncs its members until you unlink it. This requires directory groups provisioned through Directory Sync. Linking hands the group's membership to the directory, so it needs every permission the group's tenant roles grant, and Admin on every organization and project the group is shared with.
Open the group and click Delete, then confirm. You cannot delete a group while it governs an active programmable-access credential. The refusal names those credentials. Revoke or delete each one on the Programmable Access page, then delete the group. Without this rule, the credentials would go on working with none of the group's knowledge packs or guardrails.
Members are assigned automatically from user attributes. Not yet functional — the console creates only Manual groups, and automatic assignment is not evaluated at query time
Routing roles represent usage patterns rather than individual people. They are not the roles that open areas of Admin. Each role defines mapping rules that automatically classify incoming interactions — for example, so that requests arriving on a specific channel get the knowledge packs and guardrails meant for them.
Each role card displays its mapping rules, its access category, the date it was last updated, and its enabled/disabled status.
The Access filter narrows the list to the roles of one category.
Mapping rules define when a role applies based on interaction properties:
Rule Type
Description
Values
Channel
Communication channel
Teams, Web Chat, Mobile App, WhatsApp, SMS, Phone, Email, API, CLI, MCP
Authentication
Authentication method
Authenticated, Unauthenticated, API Key, Executive SSO, Service Credential
Caller Type
Who initiated the request
Human, Application, Agent
Credential Type
How the caller authenticated
Personal Token, Service Account, Agent Credential, Scoped API Key
All of a role's rules must match for the role to apply, and a user receives the combined access of every role that matches — there is no ordering between roles and no first-wins. A role with no rules matches no request.
The values above are each kind's complete list, and a rule is saved only with values from its kind's list: any other value is refused, and the refusal lists the values its kind accepts. A rule with no value, or an IN rule with nothing selected, is refused too.
A role saved before AskRAI checked these values can still hold one that no option names. The role opens as it was saved, and its editor shows such a value in an IN rule as Unrecognised, with a button to remove it. The role is refused on save while it holds one, so remove the value, then select Save changes.
A rule stored with the NOT IN operator, which the editor does not offer for a new rule, opens with its operator named.
A role can hold rules of a kind the editor does not offer, such as Device or Referrer. No caller reports a device or a referrer, so a rule of either kind can never be satisfied, and because every rule must match, a role holding one matches no request. Its groups grant none of their knowledge packs and apply none of their guardrails through it.
The console shows you such a role:
Its card is markedWithdrawn rules: matches no request.
Its editor lists them read-only under Withdrawn rules, apart from its other rules, and says that the role matches no request while it holds them.
Saving keeps them. Change the role's details or its other rules and select Save changes, and the role still holds them.
Removing them is a choice you make in the editor. Select Remove these rules when saving, then Save changes, and the role matches on its remaining rules.
Removing these rules can widen who the role reaches. A role holding a Channel rule beside a Device rule matches nothing; once the Device rule is gone, it matches every request on that channel, and the knowledge packs and guardrails of every group it belongs to start applying to those callers. Review the remaining rules, and the groups the role is in, before you remove them. If you no longer want the role at all, delete it instead.
Caller Type and Credential Type rules are designed for programmable traffic. Pair them with the Programmable Access page to declaratively route machine callers — for example, map every Agent credential to a read-only role, or give Service Accounts a higher-privilege role that Personal Tokens do not receive.
Routing roles are added to groups, not to users. To give a routing role access to knowledge packs or guardrails, add it to a group with the appropriate configuration.
Switch to the Routing roles tab and click Add Role. Enter a name, optionally add a description, and choose its Category and status. The category starts at Employee Access. After creation, open the role to configure mapping rules.
To change a role's category, open the role, choose another Category, and select Save changes. A routing rule on Role Category applies to every request that matches a role of that category, so moving a role to another category changes which of those rules apply to its requests.
You cannot delete a role that is assigned to any group. Remove the role from all groups first, then delete it.
The Directory tab is a read-only view of the identities provisioned through Directory Sync, shown separately from the native groups and routing roles you manage in AskRAI. Use it to confirm that a sync took effect and that the right people and groups arrived.
The Directory tab lists the synced users and groups, each tagged Synced from directory.
The tab is split into two sections:
Directory Users — the synced people, with their name, email, and a Synced from directory badge. A user suspended or removed in the source directory is tagged Deprovisioned.
Directory Groups — the synced groups, with their member count and source badge.
Each heading counts every user or group the search matches. Each list shows the first 50 of them, and says so when there are more.
Use the Search directory box to find users by name, email or department, and groups by name. If no source is enabled yet, the tab prompts you to configure Directory Sync; if a source is enabled but the first sync hasn't completed, it shows an "awaiting first sync" state.
The Directory tab reflects exactly what your identity provider sent. To change who appears here, manage users in your IdP or Google Workspace — not in AskRAI. Native Groups and Routing roles (the other tabs) remain yours to configure and can be linked to synced identities.
Users are real people synced from your identity provider
Routing roles classify interactions automatically via mapping rules
Groups bundle users and routing roles together
Groups grant access to knowledge packs and guardrails
A user's effective access is the union of all knowledge packs and guardrails from every group they belong to. A group either grants a knowledge pack or it does not: a pack granted by any one of a user's groups is theirs to search, and nothing on another group takes it away. Nor does an item's Sensitivity, which is a classification label: a Secret item in a granted pack is found for the same callers as a Public one.
Administrative access runs on a separate track: a user's tenant roles — Platform Admin, Auditor, Member or one you build — are granted on the Access page and decide which areas of Admin they can open, with Organizations also open to an organization's Admins. The two are independent, so a Member can still hold rich content access through their groups, and a Platform Admin has no extra knowledge access just for being an admin.
Programmable Access — issue credentials whose Caller Type and Credential Type are matched by the role rules described above
Sandbox — test how a credential resolves to a role and group before pointing live traffic at it
Admin — configure system-wide settings and escalation rules
Directory Sync
Provision users and groups into AskRAI from your identity provider via SCIM 2.0, or pull them from Google Workspace with the Admin SDK Directory API
Directory Sync keeps AskRAI's users and groups in step with your identity provider so access management always reflects your real org. Open it under Admin → Directory Sync. AskRAI supports two directory sources — pick the one your identity provider uses.
Directory Sync presents both sources on one page: generic SCIM 2.0 at the top and Google Workspace below. A tenant uses one source at a time.
Directory Sync lives in the Admin area, and opens to the holders of View directory sync, read-only, or Manage directory sync, Platform Admins among them. Anyone else who opens Admin → Directory Sync is returned to the Projects workspace. Roles are assigned under Admin → Access.
Microsoft Entra ID, Okta, or any SCIM 2.0 identity provider
Google Workspace
AskRAI pulls your directory from Google
Google Workspace tenants (Google does not support outbound SCIM 2.0)
A tenant uses one directory source at a time. Enabling Google Workspace sync is blocked while generic SCIM is enabled, and vice-versa — the inactive source shows a reminder to disable the other one first. Switch sources deliberately.
With SCIM provisioning, your identity provider pushes user and group changes to AskRAI in near real time. Enable it, generate a bearer token, and paste the endpoint URL and token into your IdP's provisioning settings.
Enable SCIM provisioning. Turn on the SCIM Provisioning switch. The Connection details card then exposes the endpoint URL and token controls.
Generate the bearer token. Click Generate token. AskRAI shows the SCIM endpoint URL and the token together — once. Whoever holds the token decides who is in every group linked to the directory, so generating it, like switching SCIM on, needs every permission the tenant roles of those groups grant, and Admin on every organization and project they are shared with.
The bearer token is revealed only at generation time. Copy it before closing — you cannot view it again.
Configure your identity provider. Paste the SCIM endpoint URL and bearer token into your IdP's SCIM provisioning settings (for example, Entra ID's Provisioning blade or Okta's Provisioning tab). Your IdP then pushes users and groups to AskRAI.
To replace a token, click Rotate token — this immediately invalidates the previous one, so update your IdP right away. Revoke removes the token entirely and stops inbound provisioning.
Google Workspace can't push SCIM 2.0 to third-party apps, so AskRAI reads your directory through the Google Admin SDK Directory API using a service account with domain-wide delegation. There is no service-account key to download, upload, store, rotate, or leak — AskRAI authenticates with keyless Workload Identity Federation (WIF). AskRAI acts as its own OpenID Connect identity provider, mints a short-lived token, and federates it into your GCP project, which you configure to trust AskRAI. You connect AskRAI with six non-secret identifiers — your workspace domain, an admin email, the service-account email, your GCP project number, and the workload identity pool and provider IDs. No credential ever leaves Google.
The issuer, subject and JWKS URI are values you paste into GCP, not values you enter here — they are what your project trusts, which is why no key ever changes hands.
Create a service account. In the Google Cloud console, create (or reuse) a project, enable the Admin SDK API, then create a service account. Note its email — you do not create or download a key.
Grant domain-wide delegation. In the Google Admin console, go to Security → Access and data control → API controls → Manage Domain-Wide Delegation and add a new client using the service account's client ID and the three read-only scopes below. AskRAI shows you the exact scopes to paste.
Create a workload identity pool and provider. In your GCP project, create a workload identity pool and add an OIDC provider to it. Configure the provider to trust AskRAI as the identity provider:
Issuer (URL) — the RAI federation issuer shown on the Google Workspace card (for example https://api.be.askrai.ai/oidc/federation).
JWKS — AskRAI publishes its public signing keys at the JWKS URI shown on the card (the issuer's discovery document points to it). Google fetches these keys to verify the federation tokens AskRAI presents.
Allowed audiences — keep GCP's default, which is the provider's own full resource name. AskRAI binds every federation token it mints to exactly that resource.
Grant the service account to the federated identity. On the service account, grant the roles/iam.serviceAccountTokenCreator role — notroles/iam.workloadIdentityUser — to the federation principal built from the federation subject AskRAI shows on the card:
The federation subject is your organization's own: AskRAI presents it only when it reads your organization's directory, so another AskRAI organization cannot use your service account, even one that knows every connection field. Grant the role to this one principal, never to every identity in the pool (principalSet://…).
The serviceAccountTokenCreator role lets AskRAI's federated identity call iamcredentials signJwt to build the domain-wide-delegation assertion — there is no key for it to use instead.
Configure AskRAI. Enter your workspace domain, an admin email for the service account to impersonate, the service-account email, your GCP project number, the workload identity pool ID, and the workload identity provider ID. Click Save connection. A workload identity provider and a service account each connect one AskRAI organization: if another organization is connected through yours, the save is refused.
Test and enable. Click Test connection to confirm federation and the delegation work, then turn on the Google Workspace switch. AskRAI runs an initial sync and then keeps the directory current. Saving the connection and turning it on each need every permission the tenant roles of the groups linked to the directory grant, and Admin on every organization and project those groups are shared with, since the directory decides who is in them.
The Google Workspace domain to sync (e.g. acme-corp.com)
Yes
Admin email to impersonate
A Workspace admin the service account acts as when reading the directory
Yes
Service-account email
The email of the service account you created in your GCP project (e.g. directory-sync@acme.iam.gserviceaccount.com)
Yes
GCP project number
The numeric ID of the project that holds your service account and workload identity pool
Yes
Workload identity pool ID
The ID of the workload identity pool you created
Yes
Workload identity provider ID
The ID of the OIDC provider you added to the pool
Yes
Real-time user sync
Registers a Google users.watch channel so user changes (including offboarding) propagate within seconds. Groups are always reconciled on the scheduled pull
No
AskRAI also displays, read-only, the federation issuer, federation subject, and JWKS URI you authorize in GCP (steps 3 and 4). These are AskRAI-side values — copy them into your pool and IAM binding; you never enter them. The federation subject is your organization's alone, for as long as your organization exists.
A connection made while every AskRAI organization shared the federation subject askrai-directory-sync stops syncing until you grant roles/iam.serviceAccountTokenCreator to the subject now shown on the card (step 4). Everyone who can manage directory sync receives a notification saying so at the next scheduled sync. Then remove the grant to askrai-directory-sync: AskRAI no longer presents it.
Verifies the federation and domain-wide delegation and reports how many users are visible, without enabling sync
Sync now
Runs an on-demand reconciliation instead of waiting for the next scheduled pull. While it runs, the card says so and holds Sync now; when it ends, the card shows Last sync OK or Last sync failed with its error, without a reload, and a notification says how it ended wherever you are in the console. A sync that has not ended after five minutes shows its result the next time the page opens
Disconnect
Removes the Google Workspace connection and disables Google sync. No key is stored, so nothing is left behind on the AskRAI side
AskRAI reconciles your Google directory into the same directory store as SCIM, so synced users and groups appear under Admin → Users and can back native groups — the rest of the platform doesn't care which source provisioned them.
Scheduled pull — users, groups, and group members are polled on an interval. Use Sync now to run an on-demand sync.
Near-real-time user changes — when Real-time user sync is on, AskRAI registers a Google users.watch channel so user changes (including offboarding) propagate within seconds. Groups and members are always reconciled on the scheduled pull (Google offers no group watch channel).
Deprovisioning — a user suspended or removed in Google Workspace is marked inactive in AskRAI on the next sync, revoking their access. Identities map by Google's stable user id, so a synced user lines up with the same person who signs in via Google. A sync never removes anyone on an answer it cannot trust. When Google lists no users while synced users are still active, the sync takes no one offline and fails, naming what to check. When Google lists no groups while synced groups remain, or more groups or group members than a sync reads, the sync keeps those groups as they were and still succeeds, with a warning on the card saying what it kept. A directory with more users than a sync reads (100,000) fails on every run until AskRAI raises that limit, and meanwhile no one the sync could not read is taken offline.
Failure notifications — when a Google Workspace sync fails, every holder of Manage directory sync, Platform Admins among them, receives a notification carrying the error, which opens this page. A failure you can fix names what Google refused. A failure on AskRAI's side says only "The sync failed on our side", and the next scheduled sync runs again. Further failures of the same kind add none until a sync succeeds again, the connection is disconnected, or one of the six connection fields above is saved with a new value. Changing only Real-time user sync does not count. A failure of the other kind notifies you, so a refusal that follows a failure on AskRAI's side always reaches you.
Grant the service account only the three read-only scopes above, and impersonate a dedicated admin rather than a personal account. With keyless federation there is no long-lived credential to store, rotate, or leak — AskRAI mints a short-lived token per sync and federates it into your project. AskRAI never writes back to your directory — it reads it.
Provisioned users and groups land in the directory store and show up on the Users, Roles & Groups page. The Directory tab there lists every synced identity with a Synced from directory badge, so you can confirm a sync took effect.
Admin → Directory Sync is missing, or opening it redirects to Projects
None of your roles holds View directory sync or Manage directory sync
Ask someone who manages roles and assignments for a role holding the one you need, under Admin → Access
Can't enable a source
The other source is still enabled
Disable the active source first — a tenant uses one directory at a time
Test connection fails
Federation not trusted, or domain-wide delegation not authorized
Confirm the pool's issuer matches the federation issuer and serves AskRAI's keys at the JWKS URI, the provider's allowed audience is its own resource name (GCP's default), the IAM binding grants roles/iam.serviceAccountTokenCreator (not workloadIdentityUser) to the federation subject, and the three read-only scopes are authorized in the Google Admin console
Save connection is refused because another organization is connected
Another AskRAI organization's connection uses this workload identity provider or service account
Connect through a provider and a service account of your own. If they are yours and you did not connect them elsewhere, contact AskRAI support
Last sync failed badge
Revoked delegation, a wrong admin email, or a changed pool/provider — or, when the error says "The sync failed on our side", a failure on AskRAI's side
Open the error shown on the card. If it names what Google refused, fix the connection, then click Sync now. If it says the sync failed on our side, there is nothing to fix on your side: the next scheduled sync runs again
Offboarded user still active
Real-time user sync is off, or the change is awaiting the scheduled pull
Enable Real-time user sync, or click Sync now to reconcile immediately
Lost the SCIM token
The token is shown only once
Click Rotate token to issue a new one and update your identity provider
Group your projects under tenant-scoped organizations, switch the active organization to scope the Projects workspace, share an organization at Read, Write or Admin, and manage each organization's name and slug
Organizations are tenant-scoped containers that group your projects. The active organization scopes the Projects workspace, so switching organizations switches which projects you see and work in. Manage them under Admin → Organizations, in the Platform section of the Admin sidebar.
Each row shows an organization's name and slug, with the active organization marked. The header switcher (top) reflects the same active organization.
Admin → Organizations opens to anyone who holds View every organization and project or Create organizations, or who is Admin on at least one organization, so whoever creates an organization can always reach it. Anyone else who opens it is returned to Projects. On the page, creating an organization needs Create organizations, and renaming, deleting and sharing one need Admin access to it: a row you don't administer is read-only. Anyone can still switch between the organizations they can see from the header org switcher. Permissions come from the roles assigned under Admin → Access.
A tenant can hold many organizations, and each organization groups its own projects. Exactly one organization is active at a time. It scopes the Projects plane and also the Skills library and tool-server grants, so switching organization changes what the Admin plane shows you as well as which projects you see. The choice is remembered across sessions.
Tenant → organizations → projects — organizations sit between your tenant and your projects. Creating projects requires an organization to put them in.
Active organization — the organization currently in context. It carries a Current badge in the list and its name appears in the header org switcher.
Identity — every organization has a name and a slug, each unique within the tenant. Two names are told apart by more than case, symbols or extra spaces.
Only what is shared with you — the org switcher, the Projects plane and this page list an organization you hold a level on, or one holding a project shared with you, which then shows only the projects you can read in it. Platform Admins, and the holders of View every organization and project or Administer every organization, see every one.
Organizations live entirely within your tenant — they are an internal way to structure projects, not a billing boundary or a separate login. Switching the active organization never changes your tenant or your sign-in.
The active organization is shown in the org switcher in the top header — the button labelled with the active organization's name. Open it to move between organizations without leaving the page.
The org switcher lists every organization you can see and marks the active one with a check; the New organization item jumps to the Organizations page with the create dialog open.
You can switch the active organization two ways:
From the header switcher — open it and choose an organization.
From the Organizations page — click any organization's name to make it active.
Switching the active organization reloads the Projects workspace, and the Skills library with it — both are org-scoped, so the Admin plane changes under you as well as the Projects plane. The switcher appears only once you can see at least one organization.
Creating an organization needs Create organizations, which Administer every organization includes. Whoever creates one is its Admin. Click New organization — the button on the Organizations page or the shortcut at the bottom of the header org switcher — or, on the Admin plane, choose Create → Organization at the right of the top header, to open the create dialog. The switcher and the Create menu show their entries to every holder of Create organizations, and to nobody else.
The slug is derived from the name as you type; you can override it before creating.
Open the create dialog. Click New organization. The dialog explains that an organization groups your projects.
Enter a name. Type the organization's display Name (for example, Acme Partners). It must differ from the name of every other organization in your tenant by more than case, symbols or extra spaces, so acme partners is refused where Acme Partners exists. As you type, AskRAI derives a URL-safe Slug automatically.
Adjust the slug (optional). Edit the Slug if you want a specific value. It may contain only lowercase letters, numbers, dashes, and underscores. Leave it as derived, or blank, to let AskRAI generate one from the name and guarantee it is unique.
Create. Click Create. The new organization is added, becomes the active organization, and a confirmation appears. The header switcher updates to show it.
The organization's display name, shown in the list and the header switcher. Unique within the tenant, whatever its case, symbols or extra spaces
Yes
Slug
A URL-safe identifier, unique within the tenant. Lowercase letters, numbers, dashes, and underscores only. Auto-derived from the name; unless you type one on create, AskRAI generates and de-duplicates it
No (auto-generated)
Slugs must be unique within your tenant, and an organization keeps its slug when renamed. If you type a slug that's already taken, the Slug field reads Organization slug '…' already exists for this tenant — pick another. When you leave the derived slug as it is, or blank, AskRAI appends a numeric suffix (-2, -3, …) if needed to keep it unique, so the slug created may differ from the one shown.
Each organization row has an actions menu (the ⋮ button) with Share, Edit and Delete. Editing and deleting an organization need Admin access to it: for anyone else Edit and Delete are held, saying they need Admin access to this organization.
Delete asks for confirmation, and is held while the organization still holds projects — delete those first.
Choose Edit to open the edit dialog, where you can update the Name and Slug. A new name is held to the same rule as on create, while the organization's own name always saves, in another case too, as does a name two organizations already shared. The slug is required when editing and must stay unique within the tenant. Click Save changes to apply. Only the field you changed is saved, so another admin's change to the other field stands; if you changed nothing, the dialog closes without saving.
Choose Delete to open a confirmation dialog titled Delete organization?. It first checks whether the organization still holds projects. When it holds none, the dialog warns that the deletion is permanent and cannot be undone; click Delete to confirm.
You can't delete an organization that still has projects. The dialog says how many it holds, and Delete stays unavailable until you delete them. If a project is created in the organization while the dialog is open, AskRAI refuses the deletion with Organization has projects and cannot be deleted, and the dialog then shows the count.
Deleting an organization deletes the grants that shared it.
An organization is shared the way a project is: its Admins grant a person, a group or everyone in your tenant Read, Write or Admin. Each level includes everything the one before it allows.
Level
Adds
Read
See the organization, its row on this page and who it is shared with, in its Share dialog. Its projects only as each is shared with you
Rename, delete and share the organization, and change or remove its grants. Admin on every project in it
Read and Write on an organization reach none of its projects: each of those is shared on its own, from its own Share dialog. Only Admin on the organization carries down to every project in it, including projects created after the grant.
An organization you hold no level on is hidden from you, unless it holds a project shared with you: then it shows with only the projects you can read in it. Without Write on an organization, New project in it is held, saying creating a project needs Write access to this organization.
Platform Admin. A Platform Admin holds Admin on every organization.
Administer every organization. A role holding this permission gives Admin on every organization, and so on every project. View every organization and project gives Read on each. Both are assigned through roles on Access.
A grant to you.
A grant to a group you are in. A group that is inactive grants nothing, and deleting a group removes its grants. Because a group's members hold its grants, changing who is in a group shared with an organization needs Admin on that organization.
General access. The level the organization gives everyone in your tenant, if any.
A few rules follow:
Whoever creates an organization is its Admin. Creating it grants them Admin, a grant like any other that an Admin can change or remove.
Organizations from before sharing have no grant. None was given to anyone, so until a Platform Admin or a holder of Administer every organization shares one, only they can rename, delete or share it, nobody else creates a project in it, and anyone else sees it only to reach a project shared with them. Share each organization at Write with the people who should create projects in it before they sign in, and see projects from before sharing for the projects already in it.
One grant each. A person or group holds at most one grant on an organization. Giving them another level changes the one they have.
A change holds at once. AskRAI checks the level on every change anyone makes, so a grant you lower or remove stops working on that person's next action.
Who opens Admin → Organizations is a wider set than who can change each organization on it: the holders of View every organization and project and Create organizations, and the Admins of any one organization. The page lists only the organizations you can see, and each row follows your level on that organization. A row you don't administer is read-only: its Edit and Delete are held, saying they need Admin access to this organization, and its Share dialog shows who the organization is shared with, read-only, when you hold Read or above on it. New organization is held for anyone without Create organizations, saying it needs that permission.
Choose Share in an organization's actions menu (the ⋮ button) to open its dialog. Only the organization's Admins can change anything in it: below Admin, it shows who the organization is shared with, read-only.
Admin on an organization is Admin on every project in it; Read and Write reach none of its projects.
Review who has access. The dialog lists each person and group the organization is shared with, each with its level, then General access, then Also has access: the holders of Administer every organization and of View every organization and project, and the tenant's Platform Admins. Their access comes from their roles, so this dialog does not change it.
Add people or groups. Search in Add people or groups, pick a person or group from your directory, choose Read, Write or Admin, and add them.
Change or remove a grant. Pick another level in a grant's level select, or remove the grant with its remove control. A removal asks you to confirm first, naming who loses which level, since getting it back means adding them again.
Set General access. Under General access, choose what everyone in your tenant holds: No access, Read, Write or Admin. Anyone who holds more through a grant of their own keeps the higher level. Choosing No access asks you to confirm first.
Granting Admin on an organization gives Admin on every project in it: its grantee can share, reset and delete any of them and decide their proposals. Give Write to someone who should create projects in it, and Read to someone who should only see it.
An organization with no Admin grant can still be shared by the holders of Administer every organization and the Platform Admins. Each grant made, changed or removed is recorded in the Change Log under Access, naming the organization, who it was given to and the level.
Test AI responses with configurable guardrails and credentials, and inspect search, audit, identity, and guardrail results
The Sandbox lets you test AI responses in a safe environment before deploying configuration changes. Send messages, select which guardrails and knowledge packs to apply, and inspect every detail of the response pipeline — including guardrail evaluations, search results, audit records, and model information.
Nothing you send here reaches an end user, and nothing is written to your audit trail — the Audit tab shows a preview of the record this query would have produced. It is still a real model call, so it costs tokens.
Choose one of two modes at the top of the configuration panel:
Mode
Description
Custom
Toggle individual guardrails and knowledge packs on as chips
Group
Select a pre-configured group — guardrails and knowledge packs are resolved from the group settings
When you switch modes, selections from the previous mode are cleared automatically.
Guardrails are offered only to the holders of View policies, guardrails and egress or its Manage, Platform Admins among them: for anyone else, Custom mode lists no Guardrails and Group mode names none of the group's, and a test chat runs under none they choose.
In Custom mode, two chip lists appear — each a scrollable bordered box, not a dropdown:
Guardrails — click a chip to toggle that guardrail on or off for the next message
Knowledge Packs — click a chip to toggle that knowledge pack into the search scope
Selected chips are highlighted. If nothing is configured yet, the list shows None available.
You can test only the knowledge packs a group you belong to grants. Every other pack is listed with a lock and cannot be selected, and a note under the list says why. A pack you have just created is locked until you grant it to one of your groups in Users, Roles & Groups. Group mode is not limited this way: it tests whichever packs the selected group grants.
In Group mode, a single dropdown lets you select a group. After selection, the panel displays the knowledge packs resolved from that group's configuration, and the guardrails the group applies to its members' conversations: the active guardrails attached to the group directly or carried by its active policies. A draft guardrail is neither listed nor run here, as it governs none of the group's conversations until you activate it; to try one first, pick it in Custom mode, which runs drafts too.
Expand the Context Overrides section to simulate different user contexts and, for programmable access work, impersonate a specific credential:
Override
Options
Purpose
Channel
None, Teams, WhatsApp, Web, API, CLI, MCP
Simulate the channel the request arrives on. None leaves the channel unset, and the request is recorded as Web Chat
Auth Status
None, Authenticated, Anonymous
Simulate how the caller authenticated. Anonymous is currently broken — the value the console sends is not one the server accepts, so the request is rejected. Use None or Authenticated
Execution Mode
None, Interactive User, Agent Augmentation
Choose whether responses are rendered for a human or structured for an agent
Test as Credential
Active credentials only (first 100), listed as <name> (<credential type>)
Run the sandbox query as if it came from the selected credential, inheriting its caller type, its channel, and — conditionally — its group
Caller Name
Free text
Label the test request with a friendly caller name (for example finance-bot) for audit preview clarity
The Channel selector offers only those six channels (plus None). SMS, Phone, Email and Mobile App exist in the platform-wide channel list but cannot be simulated from the Sandbox.
Channel — taken from the credential, unless you set the Channel override to something other than Web yourself.
Group — taken from the credential only when you have not selected a group and have not selected any guardrails in Custom mode.
Impersonation covers identity resolution only. The credential's rate limits are never evaluated in the Sandbox — a sandbox query is not counted against its request budgets or concurrency limit, or against the tenant's, and its Max prompt characters is not applied, so this control cannot be used to check that a limit behaves as configured.
The picker lists only credentials whose status is active, capped at the first 100. A revoked credential does not appear — it must be re-issued on the Programmable Access page before it can be tested here. Credential status is independent of expiry, so a credential that is past its expires_at date but has not been revoked still appears in the list.
The Test as Credential selector appears only to the holders of View credentials or Manage credentials, Platform Admins among them. Anyone else sees the other four overrides — Channel, Auth Status, Execution Mode and Caller Name — but no credential picker.
Click New Conversation to abort any in-flight request and clear the messages, the thread ID and the open Results Inspector.
New Conversation does not keep your whole configuration. It also resets three Context Overrides — Execution Mode, Caller Name and Test as Credential. The mode (Custom or Group), the selected guardrails, knowledge packs and group, and the Channel and Auth Status overrides are preserved. Re-select the credential before re-running an identity test.
Type a message in the text field at the bottom of the chat panel and press Enter or click the send button. The Sandbox runs your message through the full pipeline under the configuration you selected.
Your messages appear in a bubble on the right and assistant responses on the left, each with a timestamp. A response shows the model's formatting, such as bold text, lists and code, and any HTML it writes shows as text.
Messages within the same conversation share a thread ID, and history is carried across them, so follow-up questions have full context.
The Sandbox always evaluates your draft routing configuration — there is no toggle. When your tenant has a draft model-routing configuration, the Sandbox evaluates the draft; if there is no draft, it falls back to the published configuration. There is nothing beneath that — a stage your configuration never assigns a model to has no platform model to fall back on. This is what lets you exercise unpublished routing rules before publishing them, but it also means the Routing Decision shown on the Model Info tab reflects the draft, not necessarily what live traffic is using.
A rule on Group ID is exercised here, against whichever group is actually governing the turn — the one you selected, or the credential's own group when you simulate a credential and override neither the group nor the guardrails. Choose explicit guardrails alongside a credential and no group governs the turn, so a Group ID rule matches nothing. A rule on Role Category is never exercised: the Sandbox names a group outright instead of matching the caller against your roles, so it has no matched role to report a category for, whatever that rule does in production.
When a message gets no answer, it is marked Not answered and the reason stays under it, worded to name what to change — for example, No model is configured for the summarization stage. Choose one under Admin → Routing → Default Models. when your routing assigns no model to a stage the question needs. An error notice shows the same reason until you dismiss it, and the text you sent returns to the message box so you can send it again.
Click the eye icon on any assistant message to open the Results Inspector panel below the chat. The inspector has five tabs, in this order — Guardrails (the default active tab), Audit Preview, Identity & Access, Search Debug, and Model Info.
Shows the evaluation results for each guardrail applied to the message, whichever stage it reads — the question or the answer.
Summary bar — displays how many guardrails passed (for example, "2/3 guardrails passed")
Per-guardrail cards — each card shows the guardrail name, category, pass/fail status, and expandable reasoning
Not run — each guardrail the message was sent with that has no result, named with its stage and why: its stage never ran (an Output guardrail does not run when an Input guardrail has already blocked the question), or it was skipped because another guardrail at its stage had already blocked.
If a tripwire triggered, an error alert appears at the top listing the blocking guardrails. A message sent with no guardrails reads No guardrails selected.
Displays the audit record that would be created in production. The panel renders these sections, in order:
Section
Details
Governance
Compliance status (compliant/non-compliant), a Reason when the guardrail engine returns one, and how many guardrails were evaluated
Channel
Channel Type (always shown), plus Caller Type, Caller Name and Credential ID when they are set — the fields that prove a Test as Credential impersonation reached the audit record
AI Response
Confidence score with color-coded indicator, response source
Escalation
Matched escalation rule (if any), action type, confidence band
Execution Mode
The mode the request ran under — the second field, beside Channel, proving a Test as Credential impersonation reached the audit record
Below the sections, the tab shows the Processing Time in milliseconds and ends with an expandable Raw Audit JSON viewer (with copy-to-clipboard) containing the full preview payload.
The audit preview also evaluates the response against your tenant's escalation rules in real time.
The Identity & Access tab shows how AskRAI resolved the caller for this request — essential when debugging Programmable Access credentials, role mapping rules, or agent pipelines. The tab is organised into up to four sections:
Section
Fields
Identity
Credential Name, Credential Type, Caller Type
Access
Group (or No group assigned)
Context
Channel, Execution Mode
Agent Augmentation
Suggested Action (proceed, retry_with_context, or abort), Answer Format, Knowledge Grounded flag, Source Type, and an optional blocked-reason alert
This tab is populated only when the message was sent with a credential selected in Test as Credential. Without one, it shows the empty state "Select a credential in the config panel to see identity and access details" — even though the request still ran with your Channel, Auth Status and Execution Mode overrides applied.
The Agent Augmentation section requires both conditions: the request must have been executed in Agent Augmentation mode and run against a credential, since the section renders inside this tab. Its fields mirror the structured context that the runtime returns to downstream agents, letting you verify the exact payload your agent will receive before shipping.
If the Group field shows No group assigned for a credential you expected to inherit access, check the credential's Group setting in Programmable Access — Personal Tokens inherit from the user's groups instead of carrying a group directly.
The Routing Decision section is always shown — including when no routing rule applied, in which case the source reads Not configured. Because the Sandbox evaluates your draft routing configuration, this section tells you what a draft rule would do before you publish it.
Field
Description
Source
Where the model choice came from — Tenant Default, Routing Rule, Merged Rules, Auto-Route, or Not configured when nothing assigned this stage a model. Always shown
Generation Model
The model that generated the response — the routing decision's configured model, falling back to the summarization model. Always shown
Matched Rule
The routing rule that matched. Shown as Primary Rule when more than one rule contributed. Only appears when a rule matched
Complexity
The complexity tier assigned by the classifier — simple, moderate, or complex. Only appears when the classifier ran
When more than one distinct rule contributed, an Extra Details (N rules contributed) expander appears. Expanded, it lists the non-summarization contributing rules by stage (for example Tool Call Rule or Guardrail Rule) and then shows the Refinement and Guardrail model chips.
Users, Roles & Groups — configure groups used in Group mode and Caller Type or Credential Type role rules
Programmable Access — issue the credentials impersonated by the Test as Credential selector
Admin — set confidence thresholds and escalation rules that affect audit previews
Model Routing
Configure which AI models handle different pipeline stages and define rules to route requests based on context
Model Routing controls which AI models process each stage of the response pipeline. Configure default models, enable automatic complexity-based routing, and create rules that match requests by channel, authentication status, or user group. Changes follow a draft-and-publish workflow with full version history and rollback support.
To open it, switch to the Admin plane from the top navigation bar and select Routing in the Admin sidebar.
Routing opens to the holders of View routing or Manage routing, Platform Admins among them, and to View alone read-only. Anyone else who opens it is redirected away — see Access.
Everything below the publish bar is a draft. Nothing on this page affects a live query until you publish it.
Before configuring routing, understand the three layers that determine which model handles a request. They are evaluated in order of precedence:
Layer
Description
Precedence
Routing Rules
Match requests by context (channel, auth status, group, role, complexity) and assign specific models
Highest
Auto-Route
Classify query complexity as simple, moderate, or complex, then map each tier to a model
Medium
Defaults
Tenant-level fallback models for each pipeline stage
Lowest
There is no fourth layer beneath these. Every model AskRAI runs is one your tenant registered under Model Providers, so a stage that no layer assigns has nothing to fall back on — and what happens then depends on the stage. Summarization has nowhere to go without one, so the request fails; guardrail evaluation fails the same way, but only for a tenant whose guardrails include an LLM judge — the deterministic kinds need no model. Query refinement is the only stage that degrades quietly — it answers on the unrefined question. Confidence assessment fails closed: every answer it scores comes back 0.0, so the answer bands Low for the user, 0.0 is what the audit record keeps, and any Escalation Rule on the Low band fires on that conversation. It scores every generated answer — a curated answer served straight from the knowledge base is banded from its own score and is unaffected. The retrieval relevance score is recorded alongside it but is not what bands the answer. Set a tenant default for every stage you rely on.
Routing configuration uses a draft-and-publish workflow. Changes you make on the page are local edits until you save them as a draft. The draft must then be published to take effect in production.
The publish bar at the top of the page shows:
Control
Description
Validate
Checks the configuration for errors — for example a rule that sets no model at all. A rule with no target model is valid provided it overrides at least one stage. A configuration that leaves some queries without a Summarization Model is valid, with a warning that names the stage and sends you to Default Models; you can still publish it. A configuration with neither says Configuration is valid
Save draft
Persists your edits as a draft without affecting production
Discard
Reverts all unsaved local edits back to the last saved draft
History
Opens the version history drawer to compare or rollback versions
Publish
Promotes the saved draft to production (disabled until a valid draft is saved)
Another admin may save or publish the routing config while you have the page open. Save draft and Publish then refuse your change rather than write over theirs, and the page says so with a Reload button. Reload to see their version, then make your change again: reloading discards your unsaved edits.
Publishing a routing configuration takes effect immediately for all new requests in your tenant. Test changes in the Sandbox before publishing to production.
The Default Models section sets tenant-level fallback models for each pipeline stage. If no routing rule or auto-route tier assigns a model for a stage, the default is used.
Select a model from the Summarization Model dropdown to set the primary default. Expand the Advanced section to override the Query Refinement, Guardrail and Confidence Assessment models separately.
The Assistant Model is the chat model a project's assistant gets when it is added. Left on None, an assistant gets the Summarization Model instead. An assistant keeps the model it got, so changing this later moves only the assistants added after; one added while neither model was set answers on whichever is set when it's asked, and can't be asked while both are on None.
Leave a dropdown on None and that stage has no tenant default at all. No pipeline stage falls through to the Summarization Model — it is the summarization stage's own default and no other stage's; only assistants, which are no stage of a query, take it. The single exception among the stages is Confidence Assessment, which reuses the Query Refinement Model when its own is left on None. Routing rules and auto-route tiers fall through to these defaults, which is why their dropdowns offer No override; nothing falls through beneath the defaults, which is the state the note above describes.
Summarization is the stage a question cannot pass without a model, so its empty choice reads None — queries that reach this stage fail. Routing and the Admin overview both warn that some queries cannot be answered while nothing is published, or while the published routing sets no Summarization Model and auto-route is off, has no Classifier Model, or leaves a tier without a model. The Guardrail Model's empty choice names the one question it fails: one governed by an LLM judge with no judge model of its own.
Every stage's model dropdown lists every enabled chat model from your tenant's Model Providers, tagged with the provider each came from. A chat model is not tied to a stage, so any of them can serve any stage. The Classifier Model and Confidence Assessment Model dropdowns list decision models as well (A decision model as the classifier, as the confidence assessment model). A dropdown is disabled with nothing in it only while your tenant has no enabled model it can offer — register a provider, or enable a model on one you already have.
The Confidence Assessment Model can be a decision model connected under Model Providers, such as TypeSafe's Jev. It then scores every generated answer, streamed or not, as it is delivered: after your Output guardrails have run on it, so an answer one of them blocks is never sent to it. It reads the question, the knowledge the answer was written from and the answer, and gives the probability of two things:
The answer addresses the question.
The sources state every factual claim in the answer.
The answer's confidence score is the product of the two, banded against your confidence thresholds.
A streamed answer is scored by it in place of a chat model's assessment. If it fails, the answer scores 0.0 and bands Low, as it does when a chat model's assessment fails.
An answer that is not streamed takes its score in place of the one the Summarization Model gives its own answer. If it fails, the answer keeps the Summarization Model's score.
The audit record keeps the score, the thresholds it was measured against and the versioned model that answered, such as jev-1.14.0.
A curated answer served straight from the knowledge base is banded from its own score, as before. Each question, its sources and its answer are processed under your own agreement with TypeSafe.
Choosing a decision model moves which band your answers fall in, and so the escalation tickets your rules open. Its score measures something other than a chat model's, so the same answer can land in another band. Review your confidence thresholds and Escalation Rules when you switch, and watch the dashboard for a day or two.
Auto-route automatically classifies each incoming query by complexity and routes it to the most appropriate model. This optimizes cost and performance by sending simple queries to faster models and reserving powerful models for complex requests.
The classifier is itself a model call on every query, so it is worth pointing at a cheap, fast model — its only job is to decide which tier the question belongs to.
Toggle Enable auto-route classification to activate this feature. When enabled, two additional configuration areas appear:
Classifier Model — the model that evaluates query complexity: a chat model, or a decision model such as TypeSafe's Jev. Every query pays its latency, so a small, quick model is the right choice.
Tier Mapping — assign a summarization model (and optionally query refinement and guardrail models) for each complexity tier.
Straightforward factual queries that require minimal reasoning
Moderate
Multi-step questions that need some analysis or comparison
Complex
Queries requiring deep reasoning, multi-document synthesis, or specialized knowledge
For each tier, select a primary model from the dropdown. Expand Advanced under each tier to set stage-specific overrides for query refinement and guardrail models.
Whenever the classifier fails — a timeout, a refused key, an error from its provider — the question is routed as Moderate rather than failed.
The Classifier Model can be a decision model connected under Model Providers, such as TypeSafe's Jev. It writes no text. It scores the question as simple, moderate or complex, with a probability for each and a confidence in the result.
The tier is the one with the highest probability.
Below a confidence of 0.5, the tier is Moderate, as it is on any failure. Routing is there to save cost, and a question the classifier is unsure about goes to the middle tier.
The audit record keeps the tier, its confidence and the versioned model that answered, such as jev-1.14.0.
When the classifier is a TypeSafe model, each question it reads is processed under your own agreement with TypeSafe. A question written to steer the classifier can move its tier, so a decision model is no defence against an attacker.
The classifier reads the question before any guardrail. Its tier picks the guardrail model, so it has to run first. An Input guardrail that Redacts therefore never covers what the classifier reads: the question reaches the classifier's provider as it was asked. That holds for a chat classifier as well as a decision one.
Routing rules let you assign models based on request context. Rules are evaluated by priority — lower numbers run first. Multiple matching rules can contribute different stages (one rule might set the summarization model while another sets the guardrail model).
Click Add Rule in the top-right corner of the Routing Rules section.
The rule editor, filled in — a rule that routes Teams requests to one model. The Target Model list offers only the models you registered under Model Providers.
Set the Rule Name and Priority
Enter a descriptive name for the rule. Set the Priority number — rules with lower priority values are evaluated first. Toggle Enabled to activate or deactivate the rule without deleting it.
Choose the Target Model
Select a Target Model (Summarization) from the dropdown. This is the primary model assignment for matching requests. The dropdown offers No override plus every enabled chat model your tenant registered — there is no platform-supplied entry to pick, and the control is disabled outright while your tenant has no enabled chat model.
Expand Stage Overrides to optionally set different models for query refinement and guardrail stages.
Define Conditions
Add one or more conditions that a request must match for this rule to apply. All conditions must match (AND logic).
Give every condition a value. While one has none, Add rule (or Update rule) stays disabled and the editor's footer reads Give every condition a value to save the rule. A draft that already holds such a condition is refused by Save draft and Validate, with Condition must have a value on that condition.
Save the Rule
Click Add rule to add the rule to your configuration. The rule appears in the list sorted by priority.
Each condition matches a request attribute against a value:
Each field below (except Group ID) is a fixed dropdown — these are the complete option lists, not examples:
Field
Description
Values
Channel
The communication channel the request arrived on
Teams, Web Chat, WhatsApp, SMS, Phone, Email, Mobile App, API, CLI, MCP
Auth Status
How the caller authenticated
Authenticated, Unauthenticated, API Key, Executive SSO, Service Credential
Group ID
The groups the caller resolved into
Free-text group ID
Role Category
The categories of the roles the request matched
Public Access, Employee Access, Admin Access, API Access, System Access
Complexity Tier
The auto-route complexity classification (requires auto-route enabled)
Simple, Moderate, Complex
Group ID matches against every group the caller resolved into — those assigned to them directly, and those reached through a role whose mapping rules matched the request. Automatic groups are not among them: nothing supplies the user attributes those rules read, so an automatic group never contributes to routing. Role Category matches the categories of the roles the request matched, whether or not those roles lead to a group. A caller who resolves into no groups at all is a real answer, not a blank: a not_in rule is satisfied by it.
Device Type is no longer a condition field. No caller ever reported a device type, so a condition on it matched no request, and a rule holding one never routed anything.
A rule saved while the field was offered still holds its Device Type condition, and it still matches no request. Removing the condition silently would let the rule start matching on its other conditions and route traffic to a model nobody chose for it, so the condition stays until you remove it:
In the rules list, the rule is marked Withdrawn conditions: matches no request.
The rule editor lists them under Withdrawn conditions, as they were saved. They cannot be edited.
Saving other changes to the rule keeps them, and so do publishing and rolling back to a version that holds them.
To make the rule match again, open it, tick Remove these conditions when saving, click Update rule, then Save draft and Publish. From then on the rule matches on its remaining conditions, so check that those describe the requests you mean it to route. A rule that holds no other condition needs one before it can be saved: a rule with no condition would match every request.
Rules override auto-route and defaults. If a rule assigns a summarization model, it takes precedence over the auto-route tier mapping and the default model for that stage.
The Test Rules section at the bottom of the page lets you simulate a request and see which rules match and which models are resolved for each stage.
Select values for the context fields (channel, auth status, group ID, role category, and complexity tier if auto-route is enabled), then click Evaluate. The result shows:
Source — where the final model selection came from (Tenant Default, Routing Rule, Auto-Route, Merged Rules, or Not configured when nothing assigned the stage a model)
Resolved Models — which model handles each pipeline stage (summarization, refinement, guardrail) and the source of each assignment
Matched Rules — which rules matched the test inputs, sorted by priority
Rules With Withdrawn Conditions — the enabled rules that match no request because they hold a withdrawn condition, whatever the inputs
The rule tester evaluates against your current unsaved configuration, so you can try changes before saving or publishing. It is a separate implementation from the runtime, and one difference is worth knowing. Leaving a field blank means "not supplied" in both, so a blank never matches — but the tester has no way to say "resolved into no groups", which in production does satisfy a not_in rule.
Click History in the publish bar to open the version history drawer. Each published configuration is stored as a numbered version. Publishing a draft that matches the published configuration adds no version: the draft is cleared, and the published version keeps its number.
For each version, you can:
Compare an archived version with the current published version to see what changed
Rollback to restore an archived version as the active configuration
Rolling back to an earlier version permanently deletes every routing version newer than the rollback target. This action cannot be undone. Other versioned areas behave differently — rolling a skill back keeps its history and republishes the older content as a new version.
Configure a tenant — identity and access, model providers and routing, agent capabilities, the governance plane, confidence and escalation, and organizations
Admin is where a tenant is configured: who administers it, which models it may call, what its agents can do, what governs them, and how AskRAI handles an answer it is not confident in. Open Admin with the Admin control in the top navigation bar — this switches the console to the Admin plane, where each area below appears in the left Admin sidebar, grouped exactly as it is here. Select Console or Projects in the same top bar to leave it.
Each Admin area opens to the people whose roles grant its permission: a Platform Admin holds them all, an Auditor only the Change Log, and a role you build the areas you chose for it. Organizations also opens to anyone who is Admin on at least one organization. Someone holding none and administering no organization, a Member, does not see the Admin control at all, and an Admin link they open sends them back to Projects. Build and grant roles on the Access page.
The Admin overview page opens with a row of figures, each a link to the page it counts: Users and Policies for the whole tenant, Projects and Skills for the organization named above the row. Projects leaves out archived projects, and Skills counts that organization's Library. A figure shows only to someone holding that area's View permission, which for Projects is View every organization and project, and the row hides when none is left. A count that cannot be read says so in its place, with a Retry.
The overview and the sidebar are built from one list, so an area appears in both or in neither.
Switch tenant in the sidebar is an AskRAI support control rather than a tenant setting. It is shown only to AskRAI staff, and because it is an action rather than a page it has no card on this overview.
Access
Build roles from permissions, assign them and the built-in Platform Admin, Auditor and Member roles to directory users or groups, and control who can reach each area of Admin
Access is where you decide who administers your tenant. Everyone who signs in is a Member by default: they see and work in the organizations and projects shared with them, at the level each is shared at, and use every console page but Guardrails. What else a person can do comes from the roles they hold. A role is a bundle of permissions, each opening one area of Admin. AskRAI ships three built-in roles, and you build your own from the permissions you choose. Manage both under Admin → Access, which has two tabs: Roles and Assignments.
The Roles tab lists the built-in roles first, then the ones your tenant built, each with how many people and groups hold it.
A person holds every role assigned to them directly, and every role assigned to an active group they are in. What they can do is the union of those roles' permissions: holding a permission through any one role is enough, and no role takes away what another grants. To see where each of a person's permissions comes from, and the organizations and projects shared with them, open them under Admin → Users and choose the Access tab (User details drawer). The user menu at the bottom of the sidebar names the one role you hold, or how many you hold.
Role
What it grants
Who should hold it
Platform Admin
Every permission, including any added later: the full Admin surface, and guardrails wherever they appear
The small group who configure the tenant
Auditor
View change log: reading the Change Log, the record of who changed what in Admin. Otherwise what a Member has
Whoever reviews how the tenant is configured without changing it, such as compliance or internal audit
Member
The organizations and projects shared with them, at the level each is shared at, and every console page but Guardrails. No permissions
Everyone else: the default for any signed-in user
A role you build
The permissions you chose for it
Whoever does that job, such as the people who look after your tools
The built-in roles are locked: you can't edit or delete them. To start a role from one, Duplicate it and change the copy.
Members are not locked out of the product. A Member keeps full use of the console (Dashboard, Log, Tickets, Knowledge Packs, Knowledge Base, Sandbox), and works in each project shared with them as far as its level allows. What a Member cannot do is reach Admin or work with guardrails. Neither the Admin control nor the console's Guardrails page appears in their navigation, and either address opened directly returns them to Projects. The one part of Admin a Member can reach is Organizations, once they are Admin on an organization. The Sandbox offers them no guardrails to test with, the Log no false-positive flag, and they cannot attach or detach an agent's guardrails, even in their own projects. The one exception is an agent template: an agent a Member creates from one still gets the guardrails a template admin published in it, since a template only ever adds controls.
You never have to assign the Member role. A user with no assignment at all is already a Member. Assigning Member explicitly is only useful as documentation: a visible record that you considered this person and deliberately left them without administrative access.
Most permissions open one area of Admin, and a person holding any of them sees the Admin control with only those areas in it. Administer every project opens none by itself: it acts on projects wherever they appear. Admin → Organizations also opens to someone who holds no permission but is Admin on at least one organization, such as one shared with them at Admin. Most areas come as a pair: View opens the area's pages read-only, and Manage changes them and includes View, so a role needs only one of the two. The role editor lists them in these sections:
Section
Permission
What it lets its holder do
Organizations & projects
Create organizations
Create organizations, each one its creator's to administer, from Admin → Organizations or the header org switcher
View every organization and project
Read every organization and project as if each were shared with them at Read, and open Admin → Organizations read-only
Administer every organization
Admin on every organization, and so on every project in each: rename, delete and share them. Includes View every organization and project and Create organizations
Administer every project
Admin on every project: share, reset and delete them, and decide their proposals
Edit users and native groups, and who is in each group
View roles & assignments
Read every role on this page, what it grants and who holds it
Manage roles & assignments ⚠
Build roles and assign them on this page, within the permissions they hold
View directory sync
Read how SCIM and Google Workspace provisioning are set up, the directory they provision and which groups follow it
Manage directory sync ⚠
Connect SCIM or Google Workspace provisioning, link directory groups to native ones, and be notified when a sync fails
AI models
View model providers
Read the connected model providers, their models and usage, but not their stored keys
Manage model providers
Connect the tenant's own model providers and models, reveal their stored keys, and test a model
View routing
Read which model answers which query, under Routing, and every published version
Manage routing
Choose which model answers which query, and publish or roll back a version
View confidence
Read the score bands that classify an answer's confidence
Manage confidence
Set the score bands
Governance
View policies, guardrails and egress
Read every policy, guardrail and egress allowlist in full, what governs each agent, the console's Guardrails page, and choose guardrails to try in the Sandbox
Manage policies, guardrails and egress
Author them, test a guardrail, attach them to agents and groups, and flag a guardrail's result as a false positive
Set the rules, and be notified of the tickets they raise
Agent building blocks
View skills
Read the skill library, each skill's versions and the agents that use it, and pick skills for an agent
Manage skills
Add skills and publish their versions, add them to organizations, and move an organization's agents onto a new version
View tools
Read tool servers and builtins, their tools, releases and test runs, the calls agents made from projects shared with you, and the agents that use them
Manage tools
Register tool servers and builtins, grant them to organizations, and be notified when a hosted server is held or moved onto a platform update
View agent templates
Read agent templates, their versions and readiness, and suggested ones
Manage agent templates
Publish agent templates, grant them to organizations, export and import them, and review suggested ones, of which they are notified
Programmable access
View credentials
Read the API, CLI and MCP credentials of Programmable Access, their limits and usage, and which interfaces are on, never a secret
Manage credentials
Create, rotate and revoke credentials, and turn each interface on or off
Oversight
View change log
Read the Change Log: who changed what in Admin, and when
⚠ marks a sensitive permission, one that decides who holds the others. Manage users & groups changes who is in the groups that roles are given to, and Manage directory sync links a group to your directory and provisions who is in it, so the holder of either can hand a group's roles to anyone, Platform Admin included. Manage roles & assignments hands out roles. Give these three to as few people as you can.
Administer every organization was called Manage organizations, and a role that held it holds it still. It now also gives Admin on every organization and every project, so its holders can share, reset and delete any project and decide its proposals. Check who holds it, and give Create organizations instead to someone who should only create organizations.
A person holding an area's View but not its Manage opens its pages and reads everything on them, and changes nothing. A View only note at the top of the page names the permission a change needs. Buttons that would change something, such as Add Group or New role, stay in place but greyed out, and say which permission they need when you point at them or move to them with the keyboard. Actions on a single row, such as removing an assignment, are not shown, and anything you open, a group, a role or a guardrail, opens read-only, with its fields greyed out and no save button. On an agent's Guardrails tab, a holder of View policies, guardrails and egress sees what is attached and what governs the agent, and changes none of it.
Testing a model or a guardrail needs the area's Manage, since a test is part of setting one up. A model provider's stored keys are never shown to a holder of View alone.
Notifications meant for an area's admins, such as a failed directory sync or a new escalation ticket, go only to the holders of its Manage permission.
Nobody can give out more than they have. A holder of Manage roles & assignments:
saves a role only if they hold every permission in it, and edits one only if they also hold every permission it held before, since taking a permission away from its holders is like removing their role;
assigns, removes or deletes a role only if they hold every permission it grants.
The same holds for the groups roles are given to, since a group's members hold its roles and its organization and project grants. Whoever adds or removes a member, makes the group active or inactive, deletes it, or links it to a directory group holds every permission its roles grant, and Admin on every organization and project the group is shared with. So does whoever chooses what feeds the directory, which decides who is in every group linked to it: generating the SCIM token, switching SCIM on, and setting up or switching on Google directory sync. The refusal names the permissions, organizations or projects missing.
Blocking or unblocking a person takes away or gives back every role they hold, so it too needs every permission their roles grant.
Only a Platform Admin assigns or removes Platform Admin, changes who is in a group that holds it, or blocks or unblocks someone who holds it. When one of these rules stops a change, AskRAI names the permissions you are missing.
What a person may see and do in a project is held to its access levels rather than to a role. Someone with no level on a project does not see it, and Read opens it and shows everything in it, changing nothing. Only someone with Write access to the project or above can:
None of these is a permission. A project's Admins give each level from its Share dialog, to a person, a group or everyone in the tenant. A Member creates projects in an organization they hold Write on, is Admin on each one they create, and holds whatever level each other project is shared with them at. Admin on a project also comes from Admin on its organization, and from Administer every organization or Administer every project, the only permissions on this page that reach these decisions. A Platform Admin holds Admin on every project. Everyone on a project's team when access levels arrived was made its Admin, and nobody else was given anything: a project whose team had no people then has no Admin grant, and its organization's Admins, the holders of those two permissions or a Platform Admin share it. Share your organizations and projects before your members sign in, or they see none of them.
An agent's skills and governance are attached only by the holders of those permissions, whatever their level on the project. For a limit on autonomy that holds whoever edits an agent, attach a policy whose Maximum autonomy is Manual.
You do not have to bootstrap access by hand. The first genuine user to sign in to a tenant is promoted to Platform Admin automatically, so the tenant is never left with nobody who can administer it. Every user who signs in after that is a Member until an admin says otherwise. A tenant whose only Platform Admin assignment is to an inactive or empty group counts as having none, so the next person to sign in who holds no role is promoted the same way.
Open the editor. On Admin → Access, in the Roles tab, click New role. To start from an existing role, a built-in one included, click its Duplicate button instead: the editor opens as a new role named "Copy of …" with that role's permissions.
Each section's checkbox is clear, mixed or checked as none, some or all of its permissions are selected.
Name it. Give the role a Name of up to 80 characters, unique in your tenant whatever its capitals, and not the name of a built-in role. A Description of up to 500 characters says what the role is for.
Choose its permissions. Tick single permissions, or a section's checkbox to select every permission in it. Type in Search permissions to narrow the list by name or description. A permission you don't hold yourself is shown greyed out, since you can't give it away; when you duplicate a role, those are left out of the copy, and the editor says how many.
Check the summary and save. The summary lists what the role grants, by section, and for an existing role how many people and groups hold it. Click Save role.
A role can hold no permissions at all, which makes it a label: its holders are Members like everyone else.
Click Edit on a role you built to change its name, description or permissions. The change reaches everyone who holds it on their next request: a person who loses a permission can no longer use that area, though a page they already have open shows it until they reload. If someone else changed the same role's permissions since you opened it, saving is refused, so you can reopen it and see their change before making yours.
Click Delete to remove a role. The confirmation names how many people and groups hold it, and deleting it takes it away from all of them. You can't edit or delete a built-in role.
The Assignments tab lists each person and group once, with every role assigned to them.
Each person and group appears once, with all of their roles.
Open the dialog. On Admin → Access, in the Assignments tab, click Add assignment.
Choose whether you are granting roles to a user or a group, pick the principal, and check the roles.
Choose what you are assigning to. Set Assign to to User or Group. Switching between them clears the picker, so you cannot accidentally submit a user you selected as a group.
Pick the principal. Type in the picker to search your directory. The list searches the server as you type, so you are never limited to a first page of results: anyone in the directory can be found by name or email.
Choose the roles. The Roles list starts with none checked and offers the built-in roles, then the ones your tenant built, each saying what it grants. Check every role to assign, then click Assign, which waits until a principal and at least one role are chosen. The new assignments appear immediately in the table.
Each role is assigned on its own. If some can't be assigned, for example because one grants a permission you don't hold, the dialog stays open with only those roles still checked, and names each of them with the reason. The others are assigned.
Assigning is idempotent: granting a role a principal already holds changes nothing and reports no error, so it is safe to re-run.
Granting a role to a group is the better choice for anything but a one-off. Everyone in the group holds the role, and membership is managed where it belongs, in your identity provider through Directory Sync, rather than in a list you have to remember to update when someone joins or leaves.
Grant a role to a group and every member of that group holds it, with membership managed in your identity provider.
A group passes on its roles only while it is active: the moment a group is made inactive, its members lose its roles on their next request, while its assignments stay listed here for when it is active again. Deleting a group removes its assignments with it.
You can only assign a role to a user or group that exists in your directory. If someone is missing from the picker, provision them through Directory Sync first: AskRAI will not grant a role to an identity it does not know.
Click the × on a role in the Assignments tab to revoke that one grant. The user, or every member of that group, drops back to whatever their remaining roles give them, usually Member.
The tenant always keeps at least one admin. Removing or blocking the last Platform Admin who is assigned directly to a user and can sign in is refused, so a tenant can never lock itself out. An admin who is blocked, or whom your directory has deprovisioned, cannot sign in, so does not count. A group assignment does not satisfy this: a group can be emptied in your identity provider, which would strip the tenant's last admin. Grant Platform Admin to at least one individual user, and assign the second admin before removing the first.
A change to who holds what takes effect on the person's next request. A user whose role you just changed may need to reload the console to see Admin areas appear or disappear.
The role's name; a built-in role is marked Built-in
Permissions
How many permissions it grants: Every permission for Platform Admin, None for a role with none
Held by
How many people and groups are assigned it directly; Everyone signed in for Member
Actions
Duplicate on every role; Edit and Delete on the roles you built. A holder of View roles & assignments alone has an eye button in their place, View, which opens the role read-only
Configure the score boundaries that classify AI responses into high, medium, and low confidence bands
Confidence thresholds determine how the platform categorizes each AI response into high, medium, or low confidence bands. These bands drive escalation rules, dashboard metrics, and the confidence labels shown in conversation logs — tuning them is one of the fastest ways to change how the AI assistant behaves without touching any content. The page also shows a Minimum Relevance Threshold slider, which decides how close a knowledge base match must be before the assistant will answer from it at all — see Minimum Relevance Threshold below.
The two controls act at different moments: the relevance threshold decides whether an answer is generated at all, and the bands classify an answer that already exists.
Confidence Thresholds opens to the holders of View confidence, read-only, and of Manage confidence, who save them; Platform Admin holds both. Both are assigned to users or groups through roles under Admin → Access. Anyone else does not see the Confidence Thresholds item in the Admin navigation and cannot open the page.
The upper panel displays a dual-handle slider. Its rail is labelled 0% and 100%, but the two handles travel only between 1% and 99%, and they can never meet: the API rejects 0 and 1 as threshold values and additionally requires Medium to stay strictly below High, so the slider clamps to the reachable window (step 1%, minimum one step between the handles) rather than producing a pair the save would reject.
Drag the handles to set two boundaries that split every scored response into three bands:
High confidence — responses scoring at or above the upper threshold (default: 90% and up)
Medium confidence — responses scoring at or above the lower threshold but below the upper one (default: 60% up to, but not including, 90%)
The score these bands split comes from your chat models unless you choose otherwise: a streamed answer is scored by the Confidence Assessment model under Routing, and an answer that is not streamed by the model that wrote it.
When the Confidence Assessment model is a decision model such as TypeSafe's Jev, it scores every answer instead: the probability that the answer addresses the question, times the probability that its sources state every factual claim in it. The same thresholds band that score.
Choosing a decision model moves which band your answers fall in, and so the escalation tickets your rules open. Its score measures something other than a chat model's. Answers scored before the switch keep their old scores, so the impact preview below mixes the two until 30 days have passed. Revisit your thresholds once your dashboard shows a few days of answers scored the new way.
When you adjust either threshold, a reclassification preview appears below the slider. The preview analyzes the last 30 days of conversation data, up to now, with each day running from midnight in your browser's time zone, as the conversation logs show their times. It shows:
Current vs. proposed counts — how many conversations fall into each band under the current and proposed thresholds
Reclassification impact — conversations that would move to or from the Medium band (High → Medium, Medium → Low, Low → Medium, Medium → High)
This helps you understand the effect of a change before you save it.
The reclassification list is not a complete account of the change. It only reports moves that touch the Medium band — a conversation that jumps straight from High to Low (or Low to High) is discarded before it reaches the preview. If your proposed bands cause only such jumps, the reclassification section does not render at all, even though the Current vs. Proposed band counts visibly shift. Trust the Current vs. Proposed counts, not the reclassification total, as the measure of how much a change moves.
The preview uses 30 days of historical data. If your tenant is new or has low conversation volume, the preview may show limited results — make small threshold changes and watch the dashboard for a day or two before tightening them further.
The second panel on the page holds a single slider labelled Minimum Relevance Threshold, which defaults to 0.65. It is a floor on retrieval: when the best knowledge base match for a question does not reach it, the assistant declines to answer rather than answering from weak material. Your tenant's saved value is what the assistant applies.
The number is a similarity score in the range 0–1, not a percentage of correctness. Text with nothing to do with the question still scores around 0.5 on that scale, which is why the default sits above it — a threshold at or below roughly 0.5 admits everything and switches the gate off. Raise it to answer only on strong matches; lower it to answer more often from weaker ones.
Both directions have a cost, and neither reports an error. Set it too high and answerable questions turn into the canned low-confidence reply for every user. Set it near or below 0.5 and the assistant will summarise whatever came back nearest, however unrelated. Do not expect that to quieten your escalation queue: Escalation Rules are keyed on the confidence band of the answer that was generated, never on this floor. An answer synthesised from weak material still bands Low when it scores below your Medium threshold, and still fires the same rule — except the ticket now cites a wrong answer that reached a user instead of a clean decline. If instead the assessment rates a fluent but unfounded answer Medium or High, the rule stops firing and you lose the signal entirely. This slider is a lever on answer quality, not on escalation volume. Move it a step at a time and watch the dashboard.
0.65 is a deliberately permissive starting point rather than a tuned value. Tune it from your own traffic, and note that a value saved before the slider was recalibrated was not carried forward — every tenant starts from the default until it is set again.
The gate itself runs after knowledge base retrieval and before answer generation — earlier in the pipeline than the confidence bands, which classify answers that have already been generated. AskRAI compares the highest relevance score from the retrieval step against your saved threshold:
If the best match reaches the threshold — an answer is generated and scored for confidence as usual
If every result scores below it — generation is skipped entirely and a fixed low-confidence reply is returned ("I couldn't find sufficient information to answer your question…") instead of a generated answer
The same floor is applied on the streaming and non-streaming paths — on the streaming path it is evaluated before the first token is sent, so a declined answer never starts rendering. A curated Q&A answer returned verbatim from the knowledge base is held to a stricter bar instead: a fixed 0.85, or your threshold if you have raised it above that. Anywhere at or below 0.85 — the default 0.65 included — this slider therefore changes nothing about which questions get a verbatim curated answer. A saved change applies to new queries as soon as the assistant picks the settings up, which is within five minutes at the outside.
Drag the band slider to change the High and Medium boundaries, and the Minimum Relevance Threshold slider to change the retrieval floor. Both are applied once saved.
Review the Preview
Check the impact preview under the sliders to confirm the effect of your proposed bands. Read the Current vs. Proposed band counts — the reclassification list below them omits any conversation that moves directly between High and Low.
Save changes
Click Save changes at the bottom of the page. The button is disabled until you make a change. To undo your edits without saving, click Discard.
A confidence band is not stored on a conversation — it is derived from the stored score against the current thresholds every time it is read. Saving new thresholds therefore re-bands your history immediately: dashboard band counts and success rate for periods that have already elapsed will shift, which is exactly what the impact preview is showing you. The stored confidence scores themselves are never rewritten, and escalation rules that already ran against past conversations are not re-evaluated.
Define automated actions that fire when AI response confidence falls into specific bands
Escalation rules define automated actions that fire when a conversation's confidence score falls into a specific band. Rules are evaluated in order — the first matching enabled rule wins.
With no enabled rule, no turn triggers an action. Each rule you add appears as a row, evaluated top to bottom.
Escalation runs after the answer has already been delivered. AskRAI answers the user first, and your rules are then evaluated against the record of that turn. Escalation is therefore a follow-up mechanism — it can open a ticket for a human to pick up, but it cannot intercept, alter, or withhold a response the user has already received. To stop an answer, use a guardrail: one on the Input stage refuses the question before an answer is generated, and one on the Output stage can withhold or rewrite the answer before anyone reads it.
Escalation Rules opens to the holders of View escalation rules and Manage escalation rules, Platform Admins among them. View reads the rules read-only and keeps Test Rule, which changes nothing; Manage changes them. Anyone else does not see Escalation Rules in the Admin sidebar. Rules are still evaluated for every user's queries — only authoring them is restricted. Two exceptions are worth knowing: the Sandbox only previews which rule would match and never runs its action, and a turn whose retrieval failed is skipped by rule evaluation entirely, so no ticket opens for it. See Access for the role model.
Which band triggers this rule — High, Medium, or Low
Yes
Action Type
What happens when the rule matches (see below)
Yes
Enabled
Toggle to activate or deactivate the rule without deleting it
Yes
Order
Priority position — drag a row, or use its Move up and Move down arrows
Auto
Each rule row also carries Move up and Move down arrows, which move the rule one place and work from the keyboard, and a trash icon (Remove rule) that deletes the rule from the list. Like every other change on this page, the removal is staged in the browser and only takes effect when you click Save changes.
Priority (Default/Low/Medium/High/Critical), Assigned To, Include AI Context
Auto Respond
Takes no follow-up action: the answer has been delivered, and nothing else happens
None
Expand a rule row to configure action-specific settings. Only Create Ticket has any, so an Auto Respond row has nothing to expand.
An Auto Respond rule still claims its band. Only the first enabled rule in a band fires, so an Auto Respond rule placed above a Create Ticket rule in the same band stops that ticket from ever opening. Use one deliberately to say that a band needs no follow-up, and check the order of your cards when a band you expect to escalate opens no tickets. A rule stored under an action this page does not offer shows as Auto Respond and acts as one, band included.
Every ticket a Create Ticket rule opens also sends a notification to everyone who holds Manage escalation rules, Platform Admins among them, whatever its Assigned To.
For Create Ticket, all three settings are honoured. Priority left at Default stores the ticket as Medium, and Assigned To takes a free-text user or group ID (it is copied onto the ticket verbatim and is not validated). Include AI Context is much narrower than its name suggests. It gates only the ticket's AI context, which on a new ticket holds the confidence score alone. It is on by default, and rules created before the setting existed keep including the AI context, so clearing it is an explicit opt-out.
Include AI Context is not a privacy control for the answer. The assistant's answer is copied onto every escalation ticket regardless of the toggle, and is always shown under Answer in the ticket drawer. Clearing the toggle removes only the confidence score, so the AI Confidence badge disappears from the ticket card and drawer. There is no setting that keeps a model-generated answer out of a ticket queue.
Older tickets may also carry a copy of the model's raw response, which the drawer shows as AI Response (Raw) where it differed from the delivered answer. A rule with the toggle cleared kept that copy off the ticket too. New tickets carry no such copy, whatever the toggle.
Apart from the confidence score, a ticket created with Include AI Context cleared is unchanged: it still carries the question, the answer text, the reporting user, the chat (session) id, the priority, the assignee and the originating Audit ID, and renders normally. A rule-created ticket also records the Channel of the conversation that triggered it, so the Channel field in the ticket drawer shows where the conversation took place.
Open the Admin plane from the top navigation bar, then select Escalation Rules in the Admin sidebar.
Add a Rule
Click Add Rule. A new rule row appears at the bottom of the list with default values (Low confidence, Create Ticket action).
A new rule row appears with default settings ready to configure.
Configure the Rule
Enter a name, select the confidence band and action type, then expand the row to set action-specific options. Every rule needs a name: while any row's name is blank, Save changes stays disabled and says why, and the blank name is marked on its row once you move on from it. A name the server refuses is marked on its row the same way, and your edits stay on the page to finish.
Reorder if Needed
Drag rule rows, or press a row's Move up or Move down arrow, to change evaluation order. A screen reader announces the rule's new position after each move. The first matching enabled rule is the one that fires — disabled rules are skipped entirely.
Save changes
Click Save changes to persist all rule modifications. Saving replaces the tenant's entire rule set with what is currently on screen — rules you removed are deleted, and reordered rows are stored in their new order.
Discard, next to Save changes, reverts every staged edit — additions, removals, reorders and field changes — back to the last saved state. Both buttons stay disabled until there is something unsaved.
Edits on this page are staged in the browser until you save. With unsaved changes, leaving for another page of the console, whether through a link, a button or your browser's Back button, first opens a Discard Changes? dialog: Keep editing stays on the page, and Discard changes drops the edits and leaves. Reloading or closing the browser tab asks through the browser's own prompt. Click Save changes before you leave.
Click Test Rule to open a dialog where you can set a confidence score (0–100%) and see which rule would match. The test result shows the confidence band the score falls into and, if a rule matches, its name and action type — otherwise it reports that no rule matches. Testing evaluates the last saved rule set, so while the page holds unsaved changes Test Rule is disabled and the page says why: Test Rule checks the saved rules — save or discard your changes to test them.
Rules are evaluated in the order shown. If multiple rules match the same confidence band, only the first enabled rule fires. Drag rows, or use their Move up and Move down arrows, to set the right priority.
Connect the AI model providers AskRAI runs on — every model routing can choose from is one you register here
The Model Providers section is where you connect the AI providers AskRAI runs on. Every model the platform can use is one you register here — AskRAI ships none of its own — so this page is a prerequisite for answering queries at all, not an optional extension. Once connected, these models appear in Model Routing configuration, where they can be assigned to routing rules. You can also check any connected model on its own — directly from its provider card — using Test Model.
Each connected provider is listed with its type, status, and the models you enabled on it, each with a button to test it.
Until one provider is active with at least one enabled chat model, nothing that needs a model works. A decision model answers no query on its own. Queries cannot be answered, and the Sandbox replaces its chat with a Configure a model provider empty state. Set this up first.
Model Providers opens to the holders of View model providers and Manage model providers, Platform Admins among them. View reads every provider, its models and usage read-only, never a stored key; Manage connects providers and models, reveals their stored keys and tests a model. Anyone else does not see Model Providers in the Admin sidebar, and one who follows a direct link to it is sent back to the Projects workspace. Roles are assigned under Admin → Access.
Every model has a kind, chat or decision. It follows from the provider's type, as the table shows, and cannot be set on the model.
A chat model writes text. It answers questions, refines them, judges guardrails, assesses confidence and runs agents.
A decision model writes no text. It answers yes/no and score questions about a text, each with a probability. TypeSafe's Jev models are decision models.
A decision model is offered only where AskRAI makes a decision: the auto-route Classifier Model, the Confidence Assessment Model, a guardrail's Judge model and an agent's Decision model. Every other model picker offers chat models only, and AskRAI refuses a decision model in any of them: each routing stage and rule, an agent's model and a guardrail's review model.
Use Custom (OpenAI-compatible) for any endpoint that speaks the OpenAI Chat Completions API, such as a LiteLLM proxy, a vLLM server, a hosted gateway like OpenRouter, or a gateway you run yourself. Set Base URL to the endpoint's OpenAI-compatible root, which usually ends in /v1 (for example, https://your-gateway.example.com/v1), enter the endpoint's API key, and enter each Model ID exactly as the endpoint names the model.
The Base URL must be an https address that resolves to a public IP. AskRAI refuses one on a private, loopback or reserved address, so a gateway inside your own network has to be published before AskRAI can reach it.
AskRAI does not test any particular gateway. Answering queries, evaluating guardrails and running agents rely on structured output (OpenAI's JSON-schema response_format), and agents also rely on tool calling. Whether those work through an OpenAI-compatible endpoint depends on the model and the host it routes to. Test Model sends one plain prompt, so it confirms the endpoint answers but checks neither.
On an AWS Bedrock provider, enter each Model ID as a foundation model ID (for example, anthropic.claude-3-5-sonnet-20241022-v2:0) or a cross-region inference profile ID (for example, us.anthropic.claude-sonnet-4-5-20250929-v1:0). OpenAI's models on Bedrock are entered the same way: a GPT model through its inference profile (for example, us.openai.gpt-6.1-sol), and the open-weight gpt-oss by its model ID (for example, openai.gpt-oss-120b-1:0). A cross-region inference profile runs its model in more than one region, so your IAM role needs access to the model in each of them: see the permissions policy.
A model named by an ARN is not supported, and AskRAI refuses one when you add it. That rules out a model that has only an ARN: an application inference profile, a provisioned throughput or an imported model.
In Service Account JSON, paste the JSON key file Google issued for the service account, as you downloaded it. AskRAI refuses a key that is not a service account key, and a key whose token_uri or universe_domain names a host other than Google Cloud's. A key from another universe, such as a sovereign cloud, is not supported.
Use TypeSafe to connect TypeSafe's Jev decision models with your own TypeSafe account. Enter your TypeSafe API key. Leave Base URL blank to reach TypeSafe's own API at https://api.typesafe.ai. A Base URL you do set must be an https address that resolves to a public IP, as on a Custom provider.
Enter each Model ID as a versioned id, ending in a full version number such as jev-1.14.0. AskRAI refuses any other name, an alias such as jev-latest or a partial version such as jev-1.14 among them. An alias moves to each new version TypeSafe releases, so the same question could start getting different answers with nothing changed on your side. To move to a new version, edit the model and change its Model ID: the classifier, the confidence assessment model, and every guardrail and agent that name it move with it.
A new TypeSafe model's Input $ / 1K tokens and Output $ / 1K tokens are filled in at TypeSafe's list price: 0.000042 for input and 0 for output, which TypeSafe does not charge for. Change them if your contract with TypeSafe says otherwise. Project budgets meter agents' beats, so the decision calls a beat makes, its agent's decision model checks and its decision judges, count toward its project's budget at these prices. A person's question is metered by no budget, whichever decision model it reaches.
What AskRAI sends to a TypeSafe model is processed under your own agreement with TypeSafe. For auto-route, that is the question; for the confidence assessment, the question, its sources and the answer; for a guardrail's judge, the text it judges; and for an agent's checks, its name and role, its inbox and task titles. TypeSafe does not train on customer data, and offers zero data retention only to its enterprise customers. TypeSafe's Data Processing Agreement sets out the terms.
Text written to steer a decision model can move its answers. Whoever writes the text it reads can push it toward an answer. For auto-route, that is the person asking the question, who could word it to land in another tier. For an agent's checks, it is whoever messages the agent or names a task. Do not rely on a decision model as a defence against an attacker.
Open the Admin plane from the top navigation bar, then select Model Providers in the Admin sidebar.
Click Add Provider
Click Add Provider in the top-right corner. The Add Model Provider dialog opens.
The dialog adapts its credential and configuration fields based on the selected provider type.
Enter Provider Details
Fill in the required fields:
Provider Name — a display label for this provider, at most 120 characters (for example, "Production OpenAI" or "Internal Azure GPT-4"). A name another of your providers holds is refused under the field, on create and on a rename
Provider Type — select from the dropdown (OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, GCP Vertex AI, Custom (OpenAI-compatible), or TypeSafe)
Credentials — enter the required credentials for the selected provider type. Credentials are encrypted at rest and are never included in the provider list or detail responses (those return only which fields have been set, never the values). An AWS Bedrock provider first asks how AskRAI authenticates: through an IAM role, which stores no credentials and is recommended, or with access keys.
If your provider type requires additional configuration (such as a Base URL for Azure OpenAI or a Region for AWS Bedrock), those fields appear automatically.
Add Models
Click Add Model in the Models section. For each model, enter:
Model ID — the provider's model identifier (for example, gpt-4-turbo or claude-3-5-sonnet-20241022, or a versioned id such as jev-1.14.0 on TypeSafe)
Display Name — a human-readable label shown, followed by the provider's name in parentheses, in routing configuration, every model picker and wherever the console names an agent's model. Each model on a provider needs a display name of its own, compared regardless of capitals. Two providers may each offer a model of the same name: the provider's name tells them apart
Input $ / 1K tokens and Output $ / 1K tokens — what this model costs you, in US dollars per 1,000 tokens. Both are optional; see Token pricing
Click Add to save the model. You can add multiple models to a single provider.
A chat model is not tied to a stage of the pipeline. Every enabled chat model is offered in every stage's select on Model Routing, and you decide there which model serves each stage. A decision model is offered only as the auto-route classifier and the confidence assessment model (Chat and decision models).
Create the Provider
Click Create provider to save. The provider appears as a card in the Model Providers section with its status and model count.
An AWS Bedrock provider can reach your models through an IAM role in your AWS account that AskRAI assumes, instead of through access keys. This is the recommended way to connect Bedrock: AskRAI stores no keys or secrets for the provider, so there is no long-lived credential to rotate or leak. Access keys remain supported (Connecting with access keys).
Choose IAM role in the provider form. In the Add Model Provider dialog, set Provider Type to AWS Bedrock, then choose IAM role as its authentication. The form shows two values to copy into your AWS account:
AskRAI's assumer role ARN — the AWS role AskRAI assumes your role from.
Your external ID — unique to your tenant. AskRAI generates it, and it cannot be chosen or changed.
Create a role with a permissions policy. In your AWS account, create an IAM role, with any name. Give it a permissions policy that allows bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on the foundation models AskRAI will use. For a cross-region inference profile (a model ID such as us.anthropic.claude-…), allow them on the inference profile's ARN as well, and on the foundation model's ARN in each region the profile routes to:
The first resource covers Anthropic's Claude foundation models in every region, so it includes each region an inference profile routes to; narrow it to the models you use. In the second, <region> is the region you set on the provider and <account-id> is your AWS account ID. For OpenAI's models, add the same two resources with openai.gpt-* and us.openai.gpt-* in place of the Claude patterns.
Model access must also be enabled for the account in the Amazon Bedrock console. The permissions policy lets the role call a model; it does not enable the model. For Anthropic's models, first submit Anthropic's use-case form. Then have an administrator open each model once in the Bedrock console's playground: that first call subscribes the account through AWS Marketplace, which the role cannot do.
Add the trust policy. Give the role a trust policy whose principal is AskRAI's assumer role. It admits the assumer only with your external ID, and lets it tag the session with your tenant ID:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "<assumer role ARN from the form>" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "<your external ID>" } } }, { "Effect": "Allow", "Principal": { "AWS": "<assumer role ARN from the form>" }, "Action": "sts:TagSession", "Condition": { "ForAllValues:StringEquals": { "aws:TagKeys": ["askrai-tenant-id"] } } } ]}
The external ID is what keeps the role yours: it stops another AskRAI customer from using your role, even one who learns its ARN. Match it exactly, with StringEquals: a pattern such as askrai-* would admit every customer's ID, and the save refuses such a role. Tagging a session assumes nothing on its own, so the second statement needs no external ID.
Enter the role in AskRAI and save. Back in the form, paste your role's ARN, set Region, add your models and click Create provider. When you save, AskRAI checks the trust: it assumes your role with your external ID, and confirms that the role refuses a different external ID. If either check fails, the save is refused with the reason, for example a trust policy without the sts:ExternalId condition.
Test a model. The save checks the trust, not model access. Test a model on the provider to confirm AskRAI can call it: the test makes one small Bedrock call.
Every session AskRAI opens with your role is named askrai-<your tenant ID> and carries the session tag askrai-tenant-id, so AskRAI's calls are visible in CloudTrail under that name. You may use the session name and the tag in conditions of your own policies.
To connect with access keys instead, choose them as the provider's authentication in place of IAM role, and enter an AWS Access Key ID and AWS Secret Access Key allowed the same Bedrock actions as the permissions policy above. They are encrypted at rest, as every provider credential is.
Click the edit icon on a provider card to open the edit dialog. You can update:
Provider Name — change the display label
Status — toggle between Active and Inactive using the switch. Switching a provider inactive stops every agent, routing entry and guardrail that runs on its models until it is active again, so the dialog lists them under the switch, and Save changes waits until it has. It stays allowed, as an emergency stop after a leaked key, for example
Credentials — leave blank to keep current values, or enter new credentials to replace them. Click the eye icon to reveal a stored credential value on demand.
Configuration — update Base URL, API Version, Region, or Project as applicable
Models — add new models, edit or remove existing ones, and put them in order
Click the pencil icon beside a model in the edit dialog to change its Model ID, Display Name, Input $ / 1K tokens, Output $ / 1K tokens and whether it is Enabled. Click Done, then Save changes. The model keeps its place on the provider, and a change of its display name, prices or Enabled takes effect on its next use.
Correcting a model ID — for a typo, say, or a provider renaming a model — changes the ID every agent, routing entry and LLM-judge guardrail on the model refers to. When anything runs on it, the row lists what does once you click Done, and Save changes moves them all to the corrected ID. An agent turn or a query already under way as you save can fail once on the old ID; the next one runs on the corrected model.
A provider's models are listed in the order you give them, in its edit dialog and on its card, and every model picker in the console lists them in that order too: an agent's model and decision model, a new team member's, an agent made from a template, a template's model, a guardrail's judge and review models, and every stage of Model Routing. A disabled model keeps its place on the provider but is not offered in any picker. A model you add goes last, and the models of a new provider can be put in order the same way in the Add Model Provider dialog before you create it.
To move a model, drag it to its new place in the edit dialog, or press its Move up or Move down button, then click Save changes. The new order is saved with the provider's other changes and recorded in the Change Log. If another admin added or removed one of the provider's models while your dialog was open, the order is not saved: the dialog says so and opens again on the provider as it now is, so you can put its models in order again.
Each provider's models stay together in a picker. The order of the providers themselves is not set here.
A model that an agent, a routing entry (in the published routing configuration or its draft) or a guardrail runs on cannot be removed or disabled: each of them would fail on its next use. Clicking Remove, or switching Enabled off and clicking Done, shows what runs on the model instead. Point each of them at another model, or delete it, and then remove or disable the model. A provider whose models are in use cannot be deleted either, and its delete confirmation lists what uses them.
The provider type cannot be changed after creation. To switch provider types, delete the existing provider and create a new one.
Click the play icon next to any model in a provider card to open the test drawer. Enter a prompt and click Send Test to verify the model responds correctly. The result shows:
Success — the model's response text and latency in milliseconds
Failed — the error message from the provider
A decision model writes no response text, so its test drawer asks for a yes/no question and a text to ask it about. A success shows the probability that the answer is yes, the versioned model that answered, and the latency.
Credentials are encrypted at rest and are never included in the provider list or detail responses — those carry only which fields have been set, never the values. When editing a provider, existing credentials appear as masked dots; a Model Providers administrator can reveal a stored value on demand by clicking the eye icon, which fetches it through a dedicated, permission-gated endpoint.
When you bring your own model, AskRAI does not know what your contract with the provider costs. Input $ / 1K tokens and Output $ / 1K tokens are where you tell it — and they are what makes project budgets accurate.
Token prices sit alongside the model's identifier in the Add Model form. Both are optional — leave them blank and the model bills at the platform's fallback rate.
Both fields take US dollars per 1,000 tokens — so a model billed at $2.00 per million input tokens is entered as 0.002. They are available on every provider type.
Field
Description
Required
Input $ / 1K tokens
What you pay for 1,000 prompt tokens
No — leave blank and beats are costed at the flat fallback rate
Output $ / 1K tokens
What you pay for 1,000 completion tokens
No — leave blank and beats are costed at the flat fallback rate
Leave a price blank and that side of the model bills at the platform's fallback rate. The two sides fall back independently, so you can price only the one that matters.
Zero is a valid price. Enter 0 for a model that genuinely costs you nothing — a self-hosted deployment, for example. A negative number is rejected with Token prices must be zero or a positive number.
A TypeSafe model starts at TypeSafe's list price, which you can change. See TypeSafe providers.
Once a model is saved, its row summarizes the rates as · in $0.002 / out $0.008 per 1K, and shows platform rate for whichever side you left blank.
Prices are used for budget accounting, and only for that — they do not influence routing or which model handles a query. Getting them wrong does not break anything, but it does make every project budget wrong in the same direction: a model priced too low will overspend its allocation before the budget stops it.
Pricing is read fresh on every agent beat, so correcting a rate takes effect immediately — there is no cache to wait out and no need to restart a running team. To correct a saved model's price, edit the model.
Model Routing — configure which models handle different query types using your connected providers, and which model classifies each question for auto-route
Confidence Thresholds — set the score boundaries that band an answer and drive escalation. They do not feed routing, whose conditions are the request-context fields listed on that page
Sandbox — test AI responses with different model configurations
Programmable Access
Issue and govern API, CLI, MCP and A2A credentials that let external applications and AI agents query AskRAI, or hand work to a project's agent, with enterprise-grade controls
Programmable Access turns AskRAI into a governed data plane for your external applications, CLI workflows, and AI agents. From this page you decide which machine-to-machine interfaces are enabled for your tenant, cap how many queries the tenant sends each minute and each day and how many it runs at once, and issue named credentials that authenticate every request with full audit context.
The interface toggles are the outer gate, and they fail closed: turning one off refuses every credential carrying that Channel, however the credential itself is configured.
Programmable Access opens to the holders of View credentials and Manage credentials. View reads every credential's settings, limits and usage, and which interfaces are on, read-only: it never shows a secret, and offers no rotate, revoke or delete. Manage creates, rotates and revokes credentials and turns the interfaces on and off. A Member does not see Programmable Access in the Admin sidebar — they cannot open the Admin plane at all — and a Member who follows a direct link to it is sent back to the Projects workspace. Roles are assigned under Admin → Access.
Before issuing credentials, understand the three layers that govern programmable traffic:
Layer
Scope
What it controls
Interface toggles
Tenant
Which credentials are accepted, by the Channel each was created with (API, CLI, MCP, A2A)
Rate limits
Tenant and per credential
How many queries may be sent each minute and each day, and how many may run at once. A credential also caps how long a prompt may be
Credentials
Per credential
Identity, scoping, IP allowlist, expiry, and lifecycle state
Every request to a programmable interface must present a credential. The credential determines the caller identity and what group access its queries are evaluated against.
The Interfaces panel turns each programmable interface on or off for the entire tenant. Each toggle governs the credentials created with its Channel, wherever they are used: turning one off refuses every later request those credentials send, in a conversation or an MCP session already open too, while a query already admitted runs to its end. The public API refuses them from the next request. Through the MCP server, a tool call fails from the next call, and connecting or listing tools within a minute.
Interface
Protocol
Typical caller
Accepts
Runtime API
REST over HTTPS
Backend services, internal applications, server-side jobs
A credential of any Channel but A2A, while that Channel's interface is on
CLI
REST over HTTPS (via askrai command)
Power users, operators, scripts in terminals
A credential of any Channel but A2A, while that Channel's interface is on
MCP
Model Context Protocol over HTTP
AI agents (Claude, Copilot, Cursor, custom agents)
Only a credential with Channel MCP, while MCP is on
A2A
A2A 1.0 over JSON-RPC (HTTPS)
Agents outside AskRAI handing work to a project's agent
A credential with Channel A2A or API that the agent lists under External access, while that Channel's interface is on
The askrai CLI is not generally available yet, and there is nowhere to install it from. Its interface and its Channel are on this page already, and what the page says of the CLI describes how it behaves. Until it is available, call the public API directly, or connect an AI agent to the MCP server.
The CLI calls the public API as any other caller does and sends nothing that names it, so AskRAI cannot tell it from the Runtime API. Turning CLI off refuses the credentials created with Channel CLI, from the CLI and from any other caller alike. It does not stop the CLI, which goes on working with a credential created with Channel API while Runtime API is on, or with Channel MCP while MCP is on.
Turning all four interfaces off refuses every credential the tenant holds: together the toggles are the tenant-wide kill switch for programmable access, and credential-level controls sit inside this boundary. To stop one caller, revoke its credentials instead.
The askrai command verifies AskRAI's certificate against the trust store of the operating system it runs on: the keychain on macOS, the certificate store on Windows, and the system CA certificates on Linux. It carries no certificate bundle of its own.
A root certificate your organization installed in that store is trusted, so the CLI works behind a proxy that inspects TLS once the proxy's root is installed there.
A certificate authority the operating system does not list is not trusted, including one found only in a bundle that a Python package such as certifi ships.
When the CLI refuses a certificate it reports API error: Cannot connect to API, the same message it gives for a host it cannot reach.
The askrai command is governed by the AskRAI customer agreement, and askrai --help says so. The open-source packages installed with it are each provided under their own license: the CLI's package carries their license texts in THIRD_PARTY_NOTICES.txt, beside its own LICENSE.
The Rate Limits panel holds the tenant-wide limits on programmable traffic. Every credential the tenant holds counts toward them together:
Limit
What it caps
Default
Requests per minute
Queries the tenant's credentials may send in each minute
300
Requests per day
Queries the tenant's credentials may send in each day
50,000
Max concurrent streams
Queries the tenant's credentials may have in flight at once
50
Type new values and click Save to apply them. The Save button is disabled until you have made a change. A new value normally applies within a few seconds of the save, and always within five minutes.
Each value must be a whole number of at least 1. Any other value is refused under its box, and Save stays disabled until it is corrected; the server refuses the same values too. A limit of 0 would reject every query of every credential the tenant holds, so it is not how programmable access is turned off: use the interface toggles above.
Requests per minute can be at most Requests per day, since a per-minute limit above the day's could never be reached. A higher one is refused under its box, and Save stays disabled until one of the two is changed. Limits saved before this check stay in force as saved until you save new ones.
Every limit applies, and none is unlimited. A request budget or prompt length saved before those limits were enforced applies as it was saved. A credential created with only a Max concurrent streams override holds the defaults for its other three limits, and those apply. A tenant or credential with no value of its own for a limit takes that limit's default.
Each request budget and concurrency limit is checked at two independent levels, and both must have headroom: the credential's own limit — its override, or the default — and the tenant's. The tenant's limits are a hard cap, not a floor: a credential never sends more queries in a minute or a day, or runs more at once, than the tenant allows, whatever its own limits say, so its effective limit is the smaller of the two.
Queries and A2A handoffs count: POST /v1/query and POST /v1/query/stream, whether the API, the CLI or MCP sent them, and an outside agent's SendMessage to a project's agent over A2A. Other calls, such as reading sessions or audit records, an A2A GetTask or CancelTask, or reading an agent's card, are neither counted nor refused by a budget.
A query counts once, when it is admitted — after its key, its prompt length, its execution mode, every request budget and both concurrency limits have accepted it. A streamed query counts once, as its stream starts, not per part of the answer. A SendMessage counts once its key, its address and its message pass their checks, one its agent then rejects included, and a repeat of one already answered, with the same messageId, is not counted again. It takes no concurrency slot, as it is answered at once.
A refused query counts against nothing. Whichever of those checks refuses it, no budget is spent, so a credential that spends its own budget does not go on spending its tenant's. An admitted query stays counted whatever its answer, a blocked or failed one included.
Request budgets are counted in fixed UTC windows: a per-minute budget in each whole minute of UTC, a per-day budget in each UTC day, starting at 00:00 UTC. The count does not slide, so a caller that spends its per-minute budget at the end of one minute can spend it again at the start of the next: up to twice the per-minute budget can arrive within 60 seconds.
Concurrency bounds how many queries run at once, not how many arrive over time. A query counts as a stream from the moment it is admitted until its answer is complete, whether or not the caller asked for a streamed response.
A query refused by a spent request budget is answered 429 with the code RATE_LIMITED and a Retry-After header holding the whole seconds until the window that refused it renews. Its detail says whose budget was spent, how large it is and when it renews, for example:
This credential's budget of 60 requests per minute is spent. It renews in 23 seconds.The tenant's budget of 50000 requests per day is spent. It renews at 00:00 UTC, in 3600 seconds.
On POST /v1/query/stream the refusal arrives before the stream starts, as the same 429, and an A2A SendMessage is refused with the same 429 too. The CLI and the MCP tools show the detail as it is written. A query refused because a concurrency limit is full is answered 429 with the code RATE_LIMITED too.
A credential whose budget is 0 is answered the same 429 with no Retry-After, because no window renews it, and a detail such as This credential's budget of 0 requests per minute refuses every query.
A prompt longer than the credential's Max prompt characters is answered 400 with the code INVALID_REQUEST and a detail such as The prompt is 812 characters, over this credential's limit of 500. A prompt longer than 10,000 characters, the platform's ceiling, is refused whatever the credential allows, with 422. Neither counts against any budget.
A caller whose keys keep being refused is held back, separately from these limits. Once around ten keys from one address have been refused within a minute, every key sent from that address is rejected with 429 and a Retry-After header until the minute is up, a working one included. The limit is the platform's and cannot be changed per tenant. An integration whose key was rotated or revoked should move to its new key rather than retry the old one. AI agents that connect through the hosted MCP server are counted by their own address, not by the server's. Agents that share an address are not all stopped by one of them: the server verifies a working key again once a minute, and until a key is next due it goes on being accepted while its address is held back. A key that comes due in that time, or one the server has not yet verified, waits until the address is released.
The Credentials table lists every credential issued for this tenant, regardless of status. Each row summarises identity, interface, lifecycle, and usage in a compact form:
Column
Description
Name
Human-friendly identifier chosen when the credential was created
Type
One of Personal Token, Service Account, Agent Credential, or Scoped API Key
Channel
Interface this credential was created for (API, CLI, MCP, or A2A), whose toggle it depends on
Status
Active, Interface off (its Channel's interface is turned off, so it cannot sign in until that interface is on), Expired (past its expiry, so it can no longer sign in), or Revoked
Last Used
Relative timestamp of the most recent successful authentication
Choose the type that best reflects who or what will hold the secret. The type drives how the credential is displayed and how its traffic is attributed in the audit trail and on the dashboard.
Type
Intended holder
Typical lifetime
Notes
Personal Token
A named human, tied to their identity
Short (days to weeks)
Revoke it by hand when the user is offboarded — see the warning below
Service Account
An unattended backend service
Medium (months)
The most common choice for server-side integrations
Agent Credential
An AI agent acting on behalf of a user
Medium (months)
Carries an agent-specific audit tag. It does not by itself enable agent_augmentation — execution modes are set separately and are available to every type
Scoped API Key
A narrowly-scoped integration
Varies
Used when you want an IP allowlist and tight rate limits
The credential type is a label, not a control. It changes how the credential is displayed and audited — it does not change what the credential is allowed to do. In particular, deleting or deprovisioning a user does not revoke their Personal Tokens: nothing in the offboarding or directory-sync path touches credentials. When someone leaves, revoke their credentials on this page by hand.
Click Create Credential in the top-right of the page. A modal opens with the full credential form.
The Create Credential dialog collects identity, scoping, and per-credential override settings in a single form.
Enter Identity Fields
Fill in the required identity fields:
Field
Required
Description
Name
Yes
Alphanumeric identifier (max 128 chars). Must start with a letter or digit and may contain hyphens and underscores. Used in logs and the credentials table
Description
No
Free-text explanation of what the credential is for (max 500 chars). Appears in the details drawer
Credential Type
Yes
One of the four types described above
Scope the Credential
Choose which interface and audience this credential belongs to:
Field
Description
Channel
Which programmable interface the credential is for — API, CLI, MCP, or A2A. The credential works only while that interface is on, and its queries are recorded under that Channel. While it is off, the dialog says so under Channel, with a Go to Interfaces link to its switch, and the credential is still created. The MCP server admits only a credential with Channel MCP; the Runtime API and the CLI admit any Channel but A2A (see below). An A2A credential cannot be a Personal Token
Kind
With Channel A2A only: an API key, an OAuth client, whose Client ID and Client secret an outside agent exchanges for short-lived tokens, or a Signing key, the Public key of a key an outside agent signs its own tokens with, and the Issuer and Audience those tokens carry. Which kind an agent takes is its External access method. A signing key holds no secret, so it is never rotated: register its replacement instead
Group
Optional. When set, the credential is added as a member of that group, so its queries are evaluated against the group's knowledge pack and guardrail assignments. The credential works only while that group governs it (see below), so only active groups are listed. With None, the credential belongs to no group and no group's knowledge packs or guardrails apply to it. Personal Tokens inherit from the user's groups instead
Caller Type
Human, Application, or Agent. Drives role mapping rules of the Caller Type rule type — a rule's type is what it reads, its operator is how it compares (equals, contains, in, not_in, between)
Execution Modes
Select one or both of Interactive User (a human is in the loop) and Agent Augmentation (an agent synthesises the response). Leaving this empty allows either mode
Only the MCP server holds a credential to its Channel. An AI agent connecting through the MCP server needs a credential created with Channel MCP, and one created with Channel API is refused with This key is for the API channel; create a key with Channel MCP. (a CLI one is told the same, naming CLI). The CLI sends nothing that tells it from the Runtime API, so a request from either is checked against the interface of the credential's own Channel: a credential created with Channel API works from the CLI while Runtime API is on. When the credential's interface is off, the request fails with 401 and the code UNAUTHORIZED, not 403, and its detail names the interface, such as The API interface is turned off for this organization. The CLI and the MCP server show the same reason.
An A2A credential calls only the agents that list it, over A2A. It is the credential an agent outside AskRAI holds, made from an agent's External access tab with Create key, or here with Channel A2A. Any other request it sends, a query, a session or audit read, or the CLI's sign-in check, is refused with 403, the code CHANNEL_DENIED and An A2A key calls only the A2A endpoint of an agent that lists it. An agent connecting through the MCP server with one is refused with 401 instead, with the same reason, and the Sandbox does not offer it to test as. An agent may also list a credential with Channel API, which goes on answering queries too: every credential made before A2A credentials existed keeps the Channel it was made with, so an agent that already lists one keeps answering it. A2A is off until it is turned on here, as every interface is, and while it is off the External access tab marks each A2A credential it lists Interface off.
A credential with a group works only while that group governs it. Every request checks that the group still exists, is active and still lists the credential. If it does not, the request is rejected with 403 and the code CREDENTIAL_UNGOVERNED, and nothing is revoked. An agent connecting through the MCP server is refused with 401 instead, with the same reason. The credential works again as soon as the group is reactivated or its membership is restored, and rotating the key puts the credential back in its group if the group still exists. The console keeps the membership in place: a group cannot be deleted while it governs an active credential, and a credential is removed from its group only by revoking or deleting it.
A credential is not created in an inactive group. Pick a group that was deactivated while the dialog was open, and Create is refused with The group this key was to join is inactive, and a key in an inactive group cannot sign in, so the key was not created. The dialog keeps your entries and marks the group This group is inactive. Choose another group. Rotating a credential whose group has gone inactive is still allowed, and the new secret signs in once the group is active again.
When a credential has execution modes set and a request does not name one, the least-augmenting mode the credential allows is applied — Interactive User whenever it is one of them, whatever order you ticked the boxes in. A request that names a mode outside the credential's list is rejected with 403.
Agent Augmentation is additive, not a replacement. A caller in agent mode still receives the rendered answer; it simply arrives alongside an extra agent_context block (suggested next action, blocked reason, whether the answer was knowledge-grounded, and the source type). The mode also reshapes the summarisation prompt. It never suppresses the answer, so do not use it to withhold prose from a downstream agent.
Add Security Boundaries
Two optional fields further constrain the credential:
Field
Description
IP Allowlist
Comma-separated list of IPv4 addresses or CIDR ranges. An entry that is neither is marked on the field, and no credential is created. Requests from other addresses are rejected with 403. Leave empty to allow any source. Through the MCP server, the address checked is the one that server reaches AskRAI from, not the agent's, so an allowlist of the agent's addresses refuses it, with 401 and This key's IP allowlist does not include the address the MCP server reaches AskRAI from. rather than 403
Expires At
Optional absolute expiration, which must be in the future: a time already past is refused on the field and no credential is created. After this timestamp the credential is treated as expired and rejects new requests with 403 and Credential has expired, or with 401 and the same reason for an agent connecting through the MCP server. Leave empty for a non-expiring credential
The allowlist is evaluated after the API key itself is verified, not before it — it narrows where a valid key may be used, and is not a pre-authentication network filter.
(Optional) Override the Rate Limits
Expand Per-credential rate limit overrides to set this credential's own limits. A box left blank gives the credential that limit's default:
Field
What it caps
Default
Allowed values
Requests per minute
Queries this credential may send in each minute
60
A whole number, 0 or more
Requests per day
Queries this credential may send in each day
10,000
A whole number, 0 or more
Max concurrent streams
Queries this credential may have in flight at once
5
A whole number, 0 or more
Max prompt characters
The longest prompt this credential may send
10,000
A whole number from 1 to 10,000
A value of 0 in any of the first three rejects every query the credential sends. A value outside these bounds is refused, by the dialog and by the server. Requests per minute can be at most Requests per day, a blank box counting as its default, so a credential blocked with 0 requests per day needs 0 requests per minute too. 10,000 characters is the platform's ceiling for a prompt, and no credential can raise it.
You can change a credential's limits later from its details drawer, without moving the integration to a new key: see Changing a credential's limits. Rotating its key keeps them.
The request budgets and the concurrency limit are not validated against the tenant's when you save — a credential can be saved with a number larger than its tenant's, and nothing clamps it. The larger number buys nothing: the tenant's limit and the credential's are both checked on every query, and the stricter one wins.
Create and Copy the Secret
Click Create. The server generates the API key and returns it exactly once in a modal:
The API key is shown only at creation time. Copy it to a secret manager immediately — there is no way to retrieve it again. If the secret is lost, rotate the credential to issue a new one.
Use the copy button, paste the key into your secret store, check I have copied this API key, and click Done to dismiss the modal. The new credential appears in the table with Active status, or Interface off while its Channel's interface is off, and a usage count of zero.
Click any credential row to open the details drawer on the right. The drawer is organised into three sections that mirror the create form:
The secret itself is never shown again after creation. Rotate Key issues a new one, which works at once, and invalidates the old one within a few seconds (always within five minutes), keeping the credential's ID, groups, rate limits and usage history.
Requests Per Minute, Requests Per Day, Max Concurrent Streams and Max Prompt Characters, each as it applies, marked (default) when the credential has no value of its own (for example 60 (default)). Whatever they say, the credential is held inside the tenant's limits too. Edit Limits changes them for a credential that is not revoked
Lifecycle
Created timestamp, Created By, Expires At, Last Used (relative), Last Rotated, Usage Count
The footer exposes three lifecycle actions. Which actions are available depends on the current status of the credential:
Action
Available when
Effect
Revoke
Status is Active, Interface off or Expired
Marks the credential Revoked. Requests using it are rejected within a few seconds, and always within five minutes. The credential remains in the table for audit purposes
Rotate Key
Status is Active or Interface off
Generates a new secret for the same credential ID and shows it in the secret modal. The new secret works at once, and the old one stops working within a few seconds, and always within five minutes. Usage counts, groups, and the rate limits are preserved
Delete
Always
Removes the credential permanently. Requests using it are rejected within a few seconds, and always within five minutes. Use Revoke instead if you want to keep an audit trail
Rotating an active credential invalidates the previous secret within a few seconds, so callers still holding it start failing almost at once. Schedule rotations for windows where callers can pick up the new secret, or rotate credential pairs if you need zero-downtime handover.
Revoking, rotating or deleting takes effect on every server of the public API within a few seconds, and always within five minutes. Five minutes is the longest a server keeps a credential it has already checked, if the notice of the change does not reach it. A query admitted before then also runs to its end. Treat a leaked secret as usable for that long after you revoke it.
An integration that needs a larger budget, or one you want to hold back, keeps its key: you change the limits of the credential it already uses.
Open the Edit
Click the credential's row to open its details drawer, then click Edit Limits beside Rate Limits. The edit is offered for any credential that is not revoked.
Type the New Limits
The four boxes open on the limits the credential holds now, or blank when it holds none of its own. They take the same values as when the credential is created, and a box left blank gives the credential that limit's default, which its placeholder shows. A value outside the allowed range is refused under its box, and Save stays disabled until it is corrected.
Each box opens on the limit as it applies now; the tenant's limits still hold the credential whatever you save.
Save
Click Save. The drawer shows the new limits, and they apply to the credential's next query within a few seconds, and always within five minutes. Cancel leaves the limits as they were.
What the credential has already sent in the current minute and day still counts. A credential refused at a budget of 2 requests per minute that you raise to 3 is admitted again within the same minute, for one more query; a budget you lower below what it has already sent refuses its queries until the window renews.
Only the rate limits can be changed. A credential's name, description, group, IP allowlist and expiry stay as they were set when it was created.
Click the credential row or choose Revoke from the actions menu (⋮) on the row.
Confirm the Revocation
A confirmation dialog asks you to confirm. Revoking is a soft-delete: the credential stays visible in the table with Revoked status so auditors can still see who issued it and when, but API calls using the secret return 401 Unauthorized within a few seconds, and always within five minutes.
The Usage Overview panel at the bottom of the page summarises programmable traffic at a glance. Its figures cover every credential your tenant holds, whatever the credentials table above it is filtered to or paged to:
Metric
What it shows
Total Requests
Sum of Usage Count across every credential, revoked ones included
Active Credentials
Count of credentials in Active status, so neither expired nor revoked, and on an interface that is on
Enabled Interfaces
How many of the four interfaces (API, CLI, MCP, A2A) are turned on, out of four
Below the metric cards:
Requests by Interface — bar chart grouping total requests by channel, useful for spotting interface-level surges
Top Credentials by Usage — a two-column table (Name, Requests) ranking the five busiest credentials, of any status. A quick way to find noisy callers
Filtering or paging the credentials table does not change the Usage Overview. The figures are read when the page opens and again after you create, revoke or delete a credential; reload the page to see requests made since. To compare one credential type's load, filter the table by type and read each credential's Usage Count.
Programmable Access sits alongside the human channel — Teams, the only one delivering traffic today — in the runtime pipeline. A request from a programmable credential is handled the same way as a human request — it is evaluated by guardrails, routed through auto-route or routing rules, and audited into the same conversation log — with two key differences:
Identity comes from the credential, not from an end-user SSO session. The caller type, channel, caller name, credential ID and credential type travel with the request and surface in the Conversation Logs, Dashboard, and Sandbox panels. The group is not sent with the request — instead, the credential is enrolled as a member of the group when you create it, so group-scoped knowledge and guardrails resolve from that membership. A credential whose group no longer governs it is refused rather than answered without the group's controls.
Execution modes let you opt into agent-friendly response shapes. agent_augmentation adds a structured agent_context block (suggested next action, blocked reason, grounding, source type) alongside the rendered answer.
Credentials also participate in the role system. When you create a role under Users, Roles & Groups, you can match on Caller Type or Credential Type in addition to Channel and Authentication — giving you the same declarative access model for machine traffic that you use for human traffic.
Connect an AI agent (MCP) — the MCP server's address, an example client configuration, and the tools it offers
External Access (A2A) — open a project's agent to agents outside AskRAI, which call it with a key issued here
Users, Roles & Groups — define Caller Type and Credential Type rules that map programmable traffic to roles
Sandbox — test credential behaviour, including group resolution and execution modes, before pointing live traffic at the credential
Dashboard — monitor programmable traffic volume and top callers across your tenant
Conversation Logs — filter by API, CLI, or MCP channel and by caller type to investigate specific credential activity
Model Routing — set tenant-level fallback models for the pipeline stages exercised by programmable traffic
Skills
Author, validate, publish and version the SKILL.md instruction packs an agent can be pinned to, and adopt the ones the platform ships
A skill is a SKILL.md file — instructions an agent loads when it needs them, rather than guidance you paste into every system prompt. Admin → Skills is where an organization's skills live: the platform catalog you can adopt from, the custom skills you write, and the version history an agent is pinned to. Open it with the Admin control in the top navigation bar, then choose Skills under Capabilities.
Authoring skills takes Manage skills; View skills opens this page read-only. The Skills card on an agent's Skills & Tools tab needs either one — anyone else sees a note there instead of a picker. The Tools card beside it needs no permission: the people with Write access to the agent's project choose which connected servers it may call. Pinning a skill also needs that Write access.
Each card carries the skill's validation verdict, its scope, its category and its tags — everything the library is browsed by.
Unlike the governance areas, which are tenant-wide, this page is scoped to an organization. The library you are looking at is the library of the organization named in the header switcher, and adopting, authoring and pinning all happen inside it. Switch organizations in the header and the grid, the badge counts and the version banner all re-read for the new one. Since the switcher lists only the organizations shared with you, the page also offers an Organization select of every organization in your tenant, so you can manage one whose projects you cannot open.
That matters when you have more than one organization: the same platform skill can be adopted by several, and removing it from one leaves the others untouched.
Everything this organization may attach — the platform skills it has adopted plus the skills it wrote itself.
Discover
Platform skills this organization has not adopted yet. A skill leaves this tab the moment you adopt it.
Custom
Only the skills this organization authored.
Library holds both kinds, and the control on each card says which: a skill this organization wrote is Deleted, an adopted platform skill is Removed from org.
The badge on each tab counts the whole tab, not the filtered view, so the grid under a badge can legitimately show fewer cards than the number claims once you type in the search box or pick a category.
Library also says how many of its skills are validated and how many are flagged, over the whole Library in the same way: validated counts the cards reading All checks passed, and flagged those reading Safety flagged.
Search matches name, description and tags. The category chips — Documents, Engineering, Operations, Support, Data, Compliance and Customer — are the product's closed list; a skill always has exactly one.
The platform ships six skills into every tenant — five attributed to the RAI platform library, and one, the deliberately unsafe slack-integration, to a Community catalog. All six go through the same nine automatic checks, and the safety panel shows the date of the stored verdict. They are read-only: you can open one and read it, but the name, the body, the category and the tags are all disabled, and there is no version to roll back.
A platform skill opens with View rather than Edit — every field is disabled and the safety rail shows the same nine checks.
One catalog entry, slack-integration, is deliberately unsafe: its body fetches an external URL, the validator flags it, and adoption is refused. It is there to demonstrate that the safety gate works. Its Add to org button is disabled, and so is the button on any skill that has never been published.
The skill moves into Library, and the tab counts move with it.
Adoption publishes nothing and moves no agent. It widens what this organization may attach — you still have to pin the skill to an agent for anything to change.
To reverse it, use Remove from org on the card. That drops the skill from this organization's library and detaches it from every agent in this organization; the platform skill itself is untouched and other organizations keep it.
The editor is a two-state document: Structured shows the parsed fields and sections, Raw shows the SKILL.md file itself. Both edit the same content, and the safety rail on the right shows the server's verdict on whichever version is on screen.
The three levels are a progressive-disclosure model: the metadata is always in the agent's prompt, the sections are fetched only when the agent reaches for the skill.
Open the Custom tab and choose Create skill.
Fill in name and description under Level 1 · Metadata, or switch to Raw and write the file directly. The name must be lowercase letters, numbers and hyphens, at most 64 characters, and the field says so as you type.
Write the body under Level 2. The description is what the agent reads to decide whether to reach for the skill, so write it as a trigger — "Use when…".
Pick a Category and add Tags beside the view tabs. Tags are free text; press Enter or comma to commit one.
Choose Save skill. It stays disabled while the name is blank or breaks the format, with the reason under name. The server parses and scans the document as it stores it, and the rail updates to the stored verdict; a name it cannot read is marked under name too.
Optionally write a Change note, then choose Publish.
Validate safety runs the same scan without saving, so you can see what a change would do before committing it. The rail says "Unsaved preview — the stored verdict changes when you save" while you are looking at one.
A skill is a single SKILL.md. Bundled files are not stored or loaded, so links to a scripts/ directory are ordinary markdown text — write what the agent needs into the sections themselves.
Skills are instructions an agent follows, so a skill that reaches outside its own document can change behaviour after it was published. That is the threat the scan is built around. The checks run automatically and match formats and patterns in the text; no person reviews a skill. Each check is a pass, a warning or a failure:
Check
Fails or warns when
Required name field
The frontmatter has no name. Fails.
Required description field
The frontmatter has no description. Fails.
Name format
The name is not lowercase letters, numbers and hyphens, is over 64 characters, or is a reserved word. Fails.
No XML tags in metadata
The name or description contains <…>. Fails.
Description includes when to use the skill
The description is under 20 characters or carries no trigger phrase. Warns.
No external network requests
The document contains a URL or a fetch-shaped pattern. Fails.
No dynamic code execution patterns
The document mentions eval, exec, subprocess, os.system or shell=True. Warns.
No data exfiltration indicators
The document carries encoding or exfiltration language. Fails.
Instructions body present
Every section is empty. Warns.
Those checks resolve to one of four statuses:
All checks passed — every check passed. Only this status can be published.
Has warnings — the three required checks passed, but something warned. Nothing is waiting on a person: fix what warned and save again.
Safety flagged — a safety check failed: XML tags in the metadata, an external request or an exfiltration indicator. A flagged platform skill cannot be adopted.
Draft — a required check failed: the name or description is missing, or the name breaks its format. A skill the checks have not run on yet is a draft too.
There is no second copy of this scan in the browser. The verdict you see always came from the server, so what the editor shows and what the publish gate enforces cannot disagree. The name field's format error, shown as you type, is a hint: the server's Name format check still decides.
Saving and publishing are different acts, and the difference is the whole versioning model.
Saving updates the draft. Publishing snapshots the saved draft as a numbered version — and moves nobody. An agent runs the version it was pinned to until someone deliberately moves it, so publishing a new version never changes what a configured agent does.
Every publish is listed with its author, its change note and the time — and every earlier version stays listed and resolvable.
Publish is offered only when the stored verdict is All checks passedand there are no unsaved edits, because publishing snapshots the saved draft rather than what is on screen. The Unpublished changes badge in the header says when the draft has moved ahead of the published version.
Roll back on an older version re-publishes that version's content as a new version. The checks do not run again: it goes live exactly as it was published. Nothing is deleted or renumbered — an agent pinned to any earlier number must still be able to resolve it — and agents already pinned do not move. Your unpublished draft is left alone. Roll back is disabled while the editor holds unsaved edits, because a rollback reloads the editor from the server's copy of the draft.
Rolling back is not available on a platform skill: your organization owns the pins but not the skill.
When agents in this organization are pinned to something older than the published version, the Versions tab shows a banner naming the count and a Force update control. Confirming moves every one of those agents onto the published version from its next beat, and the tab then says how many it moved. Agents in other organizations are not affected.
Re-pinning an agent to a different version is what changes what it runs. A rollback does not: it moves the library's current version, while every agent stays on the version it was pinned to.
Skills are authored here and attached on the project Team pane — open an agent and use its Skills & Tools tab.
Each pin carries the version it was attached at. v2 and v1 here are two different snapshots of two different skills, not a sequence.
The picker offers only skills in this organization's library that have a published version — an unpublished skill cannot be attached. An agent may hold at most 50 pins.
When the library moves ahead of a pin, the row offers a control to move that one agent onto the published version; Force update in the Versions tab does the same thing for every agent at once.
Skills reach an agent's beats, not console or channel chat turns. The beat's prompt lists each pinned skill's name and description, and the agent calls an inline LoadSkill read to pull a body when it decides the skill applies — at most two bodies per beat by default, and loading one costs no action budget.
Delete sits in the editor header and on the card in the grid. Before you can confirm, the dialog reads how many agents in this organization are pinned to the skill and says so — that number is the whole question. The skill is then detached from every agent in this organization.
The version history is kept, so an agent that is still pinned goes on resolving the version it was pinned to. It cannot be attached again, though: the attach picker offers only skills that are not deleted, and there is no restore.
A platform skill has no Delete, only Remove from org.
The stored verdict is not All checks passed, or the draft has unsaved edits. Save first, then read the safety rail.
Add to org is disabled
The skill is safety-flagged, or it has never been published.
The Structured tab is read-only on a skill you own
The frontmatter could not be parsed, and a banner says why. Editing it there would overwrite metadata the server read correctly — fix the file on the Raw tab.
A skill is missing from an agent's picker
It has no published version, or it is not in the active organization's library.
Saving an agent's skills fails, naming a skill
A pinned skill has left the library — deleted, or removed from this organization. Remove that row on the agent's Skills & Tools tab and save again.
The grid is empty after switching organizations
The library is per organization. A skill adopted by one organization is not adopted by another.
Connect MCP tool servers or write hosted ones, review every tool a server offers before an agent can call it, and grant servers to the organizations that may use them
A tool is something an agent can call in another system — search a corpus, look up a ticket, post a message. Admin → Tools is where an administrator connects the servers that offer those tools and decides, one tool at a time, which of them an agent is allowed to call. Open it with the Admin control in the top navigation bar, then choose Tools under Capabilities.
Connecting and reviewing tool servers takes Manage tools; View tools opens this page read-only, with every server's tools, releases and calls, and Sync, Test, edits and deletes held. Granting a connected server to an agent needs no permission: administrators connect servers and decide which organizations may use them, and the people with Write access to an agent's project choose which of those it may call.
A new tenant has no tool servers. Nothing is connected until an administrator connects it.
Tool servers this tenant connects by URL and credential. Every tool one offers is held for review before an agent can bind it.
Builtin
Tools the platform authors, such as SQL connections and Mailboxes, added as many times as you need, each with its own settings. Their tools arrive already approved, because there is no third-party text for an administrator to read.
Hosted
Servers whose code you write here and the platform builds and runs for this tenant: see Hosted servers.
Each tab reads its servers afresh when you open it, so a tab always shows that kind's current list.
The Builtin tab shows a card for each kind of platform tool, with the connections you added listed beneath it. Today those are SQL database, see SQL connections, and Mailbox archives, see Mailboxes.
Each card lists its connections; Add connection adds another.
Header name (required), an optional prefix such as Bearer , and the Token.
OAuth client credentials
A token fetched with a client ID and secret.
Client ID (required), the Client secret, optional Scopes, and where the credentials are sent at the token endpoint.
One server, one credential, shared by everyone. Every agent, in every organization granted this server, calls it as this one connected account — there are no per-agent credentials. Granting a server to an agent is granting that agent the right to act as that account.
For OAuth, where the client ID and secret are sent is asked rather than negotiated. A server that accepts only the request body answers a correctly-formed Basic header with invalid_client — the same error it returns for a wrong secret — so no status code can tell the two apart. Set it to match what your server expects.
An OAuth server's authorization server must publish its metadata (RFC 8414, or an OpenID discovery document), naming the token endpoint the secret is sent to. Without it the secret is sent nowhere — never to a /token guessed on the server's own host — agents' calls to the server fail, and Sync tools and Test connection fail with no OAuth authorization-server metadata could be read for this server.
A credential is write-only: the stored value never comes back, and the form shows only whether one is set. Sending a new value rotates it, one field at a time.
A connected server's card is a summary of everything that decides whether its tools are reachable: its status, when it last synced, how many organizations hold it, and how it authenticates.
This is the property the whole feature is built around. A tool's title, description and schemas are text a third party wrote, and an agent follows them. So nothing a server offers is callable until an administrator has read it and accepted it under their own name.
Three tools discovered, none of them approvable yet — the page approval counts only rows whose text has been on screen.
A row joins the page approval only after its schemas have been opened. That is not a formality: the input schemas are not on the row, so a bulk approval that promoted them unread would put an administrator's name on text nobody saw. There is deliberately no control that marks rows read without showing them.
Opening one row's schemas admits that row and no other. Show what approving all N accepts opens the rest — a shortcut through the gate, never around it.
Open the server and go to its Tools tab.
Read each tool. Use Show the schemas on a row, or Show what approving all N accepts to open every held-back row at once.
Choose Approve N on this page.
Approval is per page of the listing, and the button's label carries the count — Approve 0 on this page and Approve 3 on this page are the same control. If tools on another page are still waiting, the tab says so.
Approving accepts a tool. It does not switch it on — those are two decisions.
Each row carries three things, and all three must line up before an agent can call the tool:
Control
Meaning
Approval
An administrator has read this version of the tool and accepted it.
Enable
This tool is offered to agents at all. Approving an MCP server's tool never switches it on.
Effect
Read only or Side effecting. A side-effecting tool changes something in the outside world, so a beat spends an action budget slot on it and an agent at manual autonomy may not call it at all.
A tool binds to an agent only when it is approved, enabled, and still offered by the server.
The effect is an administrator's decision — nothing is inferred from the tool's name. The default it starts from does come from the server, though: a tool declaring readOnlyHint arrives marked Read only, which costs no action budget and is exempt from the manual-approval gate. Check it rather than accept it, since the server is a third party. It is what the runtime reads when it decides whether a call costs an action and whether approval is required — see Policies.
Sync tools re-reads what the server offers. Anything that changed lands as pending, and the row is pulled back into review: the tool keeps running for agents at the text that was approved, while the new text waits for someone to read it.
A rewritten description is shown in plain sight, labelled as not yet accepted, and the approval gate is closed again.
The rewritten text is on the row rather than hidden behind the disclosure, because that is what an administrator has to read before deciding. Approving replaces the approved title and description with the pending ones; the disclosure holds the comparison, so you can see exactly what you are accepting and what you are discarding.
Until then, agents keep binding the approved snapshot. A description rewritten upstream does not reach an agent on its own.
Test connection runs the same handshake and writes nothing — use it to check a URL or a credential without touching the catalog.
Moving a connected server to a different URL deletes every tool it has offered and drops the server back to inactive and not synced, so each tool has to be discovered and approved again — including the decisions about what each one is allowed to do. The form asks you to confirm before it does that.
Switched on is the administrator's own decision about whether the server should run, separate from the status the last handshake reported. A server that is switched off binds to no agent, whatever organizations it is granted to.
A server can only be switched on once a sync has succeeded against it — until then it is offered to no agent, and the control says so rather than failing silently.
Switch on Simulated system when a server stands in for a real one, such as a demo's stub. Its card is marked Simulated, and so is each call an agent makes to it while it is marked, on its project's Activity tab. Calls made before you switch it on stay unmarked, and those made while it was on keep the mark. It is a label only: the server binds, runs and is governed as any other.
An MCP server is connected once for the tenant and then granted to the organizations that may use it. Agents in those organizations' projects can be given the server; an organization removed here loses it immediately.
The checklist is the complete set. Saving with nothing ticked revokes the server everywhere, and the confirmation says so.
The Agents tab answers the other half of that question — which agents currently hold a grant to this server, and therefore what a revoke or a delete would take away. It is a read, so it has a tab of its own rather than only appearing when you start to destroy something.
A hosted server is a tool server whose code the platform builds and runs, rather than one you connect by URL. Its code runs in an isolated sandbox that belongs to that one server, and one project's calls never share a running environment with another project's.
You write a hosted server's code here and publish it, the platform builds and checks each release, and an administrator reviews and approves it before any agent can call its tools. Its tools are approved with the release that carries them, so its tool list has no approve control.
There is nothing to install: a hosted server is written, published and run from the console.
On the Hosted tab, choose New hosted server. Give it a Name, pick its Runtime, Node.js 24 or Python 3.14, and a Template to start from, then choose Create.
The server opens on its Source tab. Edit its files, its dependencies, its Memory (MB) and its Timeout (seconds), and choose Save. The entry file, server.mjs or server.py, is an ordinary MCP server written with the official SDK, which the platform installs for you.
Each file opens in a code editor that highlights Python and JavaScript, numbers its lines, indents as you type and closes brackets. Completions appear as you type, or when you press Ctrl+Space: the language's keywords, the names the file defines, and the platform's askrai helpers, each with a line on what it does. Ctrl+F (⌘F on a Mac) searches the file. Tab indents; press Escape and then Tab to move on from the editor.
Choose Publish. The platform builds the saved source into a new release, and the Releases tab shows it move: Building, Built, Staging, then Staged, with the tools it offers listed as Pending approval.
Choose Review release, read what the release changes, and choose Approve release: see Review and approve a release.
A hosted server starts from a template on one runtime.
The Source tab holds everything a release is built from.
Each template is a small working server you can publish as it is:
Template
What its tool does
Dependencies
Word count
Counts the words in a block of text
none
Spreadsheet to CSV
Turns one sheet of an .xlsx file, sent as base64, into CSV text
openpyxl (Python), exceljs (Node.js)
Spreadsheet summary (Python only)
Reads an .xlsx file from the calling project's Workspace tab and summarizes each sheet in Markdown: its size and first rows
openpyxl, reading the file as Reading files describes
Chart
Draws a bar chart of labelled values as a PNG image
matplotlib (Python), sharp (Node.js)
REST call with a secret
Calls an HTTP API with a token from the server's secrets
none
Web screenshot (Node.js only)
Opens a public web page in Chromium and saves a PNG of it to the calling project's Workspace tab
Every Node.js template also declares zod, which its tools' input schemas are written in. A tool receives what it works on as its arguments, and reads a file of the project's Workspace tab the agent passes it (see Reading files). An image it returns is not shown to the model.
link = askrai.file(ctx, png, "image/png", "chart.png")return [TextContent(type="text", text="Chart drawn"), link]
A call saves up to 5 files of at most 25 MB each, within the time the call has left. Python's askrai.file() waits for its upload, so an async tool calls it through asyncio.to_thread.
A file appears under tool-outputs › the server's slug once the agent's beat completes, and the agent is told its name, type and size. A name already taken there gets the call's id added.
Only a file the tool returns is kept; one it uploads but leaves out of its result is deleted within about nine days, and counts against your tenant's file storage allowance until its kept copy expires 30 days after that. Once the allowance is used up, askrai.file() fails and the tool's error says so, and the agent is told the call saved no file even if the tool hides that error.
A test run saves its files apart from every project, for a day.
An agent names a file of its project's Workspace tab by its askrai-workspace: link, which it reads from the files it lists or a tool's earlier result. When it passes that link among a hosted tool's arguments, the tool reads the file's bytes with askrai.read():
const bytes = await askrai.read(ctx, file)
data = askrai.read(ctx, file)
A call reads up to 5 files, each as its current version stood when the call began, and only files the agent itself may read: its workspace access decides, as it does for the agent's own reads. A link to any other file, or a sixth one, gets nothing, and the agent is told which links the tool could not read and why. A file a tool saves can be passed on from the agent's next heartbeat, once it has landed in the Workspace tab.
askrai.read() fails for a link the call was given nothing for, and when the file does not arrive within the time the call has left. Reading a file twice is fine. askrai.downloads(ctx) lists the files a call may read, each with its link, name, type and size. Python's askrai.read() waits for the file, so an async tool calls it through asyncio.to_thread.
A link anywhere among the arguments counts, in a list or inside a sentence. A server you connect over MCP is never given a file: a link reaches it as text.
A release reaches askrai.read() once it runs on helpers that have it: a release published before needs publishing again, or a platform update.
A Node.js server can drive a web browser. Tick Browser layer under Layers on its Source tab, declare puppeteer-core among its dependencies, and start Chromium with askrai.browser.launch():
Its pages reach public addresses only. A request, redirect, embedded resource or WebSocket to a private, loopback or link-local address is refused, and so is any scheme but http and https, such as file:, besides a page's own data: and blob: URLs.
Open every page in the browser's default context, with browser.newPage(). Chromium runs as a single process here, and a second browser context, browser.createBrowserContext(), ends it.
Nothing outlasts the call. The browser is closed and its profile removed when the call ends, whatever the code left open.
It brings fonts for Chinese, Japanese and Korean text and for emoji, and gives the server 2 GB of temporary storage.
A release keeps the browser it was built with. Each release uses the browser layer's version that was current when its build started, and its review shows that version.
The Web screenshot template is a working example. It waits for the page to load until 3 seconds before the call runs out of time, then captures what has rendered, and its result says when the page had not finished loading. A page that fails to load, or that has not begun to arrive by then, is an error the agent is told the reason for, and nothing is saved.
At most 100 text files, 512 KB together. A path stays inside the server and may not be a file a package manager reads, such as package.json, .npmrc, pyproject.toml or requirements.txt
Dependencies
At most 50 packages from npm or PyPI, each at an exact version, such as 3.1.5. No ranges, git or URL dependencies
Packages
Installed with install scripts off and from prebuilt binaries only, for Linux on arm64. A version published less than two days ago is not installed yet
Size
The built server, with what it installs and the browser layer if it uses it, at most 250 MB
None between calls: each call may run in a fresh environment
The MCP SDK and the platform's own helpers are provided, so a server may not declare them, nor any package in the @askrai/ or askrai- namespaces. A tenant holds at most 25 hosted servers, unless AskRAI has raised its limit.
The Source tab's Egress sets what the server's code can reach, and each release keeps the choice it was published with. Two modes are available today:
Egress
The server's code reaches
Internet
Any host on the internet, as the code itself chooses
No network access
Nothing on the internet: it can neither connect to a host nor look up a name. The files a call saves with askrai.file() still reach the project's Workspace tab
A third mode, Allowlisted hosts only, is coming soon. Egress lists it, marked Coming soon, but it cannot be chosen yet.
Choose No network access for a server that only works on what its call carries, such as Word count, Spreadsheet to CSV or Chart. Changing it is a source change like any other: it takes effect when you publish and approve a release, and the release review shows it under Settings. A server with no network access that no agent has called for 14 days can answer its next call as unavailable, at no cost, while it reconnects; the calls after it go through.
The Secrets tab holds the server's secrets, each under a name you choose, such as API_TOKEN. Add one, rotate its value or remove it, one at a time; a value is never shown again once saved. Every call carries all of them, and the code reads one by its name: askrai.secrets(ctx)["API_TOKEN"].
Whoever can publish this server can use its secrets: publishing runs code with them. Secrets are removed from everything the platform keeps or shows, but the server's own code holds them during a call.
Each Publish builds the saved source in an environment of its own:
Packages are checked before anything runs. A dependency that a security advisory marks as malicious fails the release. Any other advisory is shown on the release as a warning.
The platform checks what it built against your source before it stages it.
A newer publish replaces an earlier one that is not yet live, which shows as Superseded.
Builds wait their turn. A tenant builds one release at a time, so a release can stay Building while another is built. A tenant publishes at most 20 times an hour.
A release that fails says whose the failure is. Your source means the build or the server itself refused it: a dependency that does not exist at that version or has no prebuilt binary, a malicious package, a size over the limit, or code that fails as it starts or cannot list its tools. Platform means it failed on our side, and publishing again later is safe. The release shows its build log either way.
A staged release lists the tools it offers, which no agent can call until the release is approved.
A release is approved as one unit: its code, its dependencies and every tool it offers. On the Releases tab, a Staged release has Review release, which sets it beside the release live now, so you read what approving it would change. For a server's first release, everything is new.
Section
What it shows
Tools
Every tool either release lists, marked Added, Removed, Changed or Unchanged, with a changed description or input schema shown against the live one. Each tool the release lists has an Effect choice, Read only or Side effecting, and Test run (see Test-run a tool).
Test runs
The release's own test runs, newest first.
Settings
The runtime, memory, timeout and egress, with what each was if it changed.
Dependencies
The packages added, removed or moved to another version.
Lockfile
The changed lines of the exact package versions the release installs.
Warnings
The security advisories against those packages.
Source
Each changed file, line by line.
Back to releases leaves the review without approving.
A release is reviewed beside the live one, and each tool's effect is set before it is approved.
Each tool's effect starts from what its code declares: a tool annotated readOnlyHint starts as Read only, any other as Side effecting. On a server with internet access every tool starts as Side effecting whatever it declares, because a request to an address the model chose can carry the project's data out. On a server with no network access each tool starts from what it declares. Check each one: the effect you approve is what the agent's autonomy and action budget read (see Approve, enable, effect), and you can change it later on the server's Tools tab, as for any tool.
Approve release puts the release live in one step. Agents call its tools from their next beat, and a beat already running finishes on the release it started with. A tool the live release already offered keeps whether it was switched on; a new tool arrives switched on, because approving the release was the decision. The release shows as Live, and the one it replaced as Retired. A server an administrator switched off stays off.
If someone publishes, approves or reverts this server's releases while you are reviewing, the approval is refused and the review reads the release again. Check what it holds now, then approve again.
Anyone who can manage tools can approve a release, including the person who published it. When you approve a release you published, the review says so before you choose Approve release, and the approval is recorded as a self-approval: the release is marked Self-approved, and so is the server while that release is live, on its card and as Approval on its Connection tab, and so is the audit record of every call to its tools. It is a record, not a block: no setting requires a second approver.
When the live release replaced an earlier one, the Releases tab shows Revert to previous release. Confirm with Revert, and the release the live one replaced goes live again in one step: its code and its tools as they were approved, from each agent's next beat. Each tool keeps whether it is switched on now, so a tool you switched off stays off. The reverted release shows as Retired, and the restored one as Live again.
A revert goes back one step only, and afterwards there is nothing further to revert to until the next release is approved. The release a live one replaced is the only earlier release kept to return to.
AskRAI keeps what a hosted server runs on patched: the platform layers, such as the browser layer, and the MCP SDK and helpers it provides. To move a live release onto a newer version of one, AskRAI makes a new release of the same code, files and installed packages, checks them again, and lists its tools. A newer MCP SDK replaces the one the release installed, and every other package it still needs stays at its version. The release shows as a Platform rebase, and nothing about it counts toward your hourly publish limit.
Its tools and installed packages are unchanged: AskRAI puts it live, and the release says so beside Approved. Each tool keeps its effect and whether it is switched on, and a self-approved release stays marked Self-approved. You can revert it as any release.
Its tools changed, or a newer MCP SDK changed its installed packages: it waits as Staged for your review, and the release asks you to approve it by a date. Review and approve it as any release: the review shows what changed in the lockfile.
The update is not yet tried on live servers: it waits as Staged for your review even with its tools and installed packages unchanged, and the release asks you to approve it by a date.
Its code no longer builds or lists its tools on the update: it shows as Failed, with the reason or the server's output in its build log, and asks you to publish and approve a release by a date. A newer MCP SDK that needs another version of a package the release installed is one such reason: publishing again installs them together.
Either way, everyone who can manage tools is notified, and reminded three days before the date, unless it asked you within those three days. An update to the browser layer, which carries Chromium's security fixes, is due 14 days after AskRAI published the first one your live release lacks, and any other 30 days after it asks you. Until you act, your agents keep calling the live release, past the date too: nothing changes on its own, and AskRAI follows up with you, since that release goes without the update. A server held for a malicious package is never moved, and neither is one with a release of its own being built or awaiting review.
AskRAI moves servers onto an update a few at a time, and can withdraw the update. A Platform rebase it put live is then reverted to the release before it, which lists the same tools (unless that release can no longer be restored, as one held for a malicious package cannot), and one waiting for your review shows as Superseded, asking nothing more of you. A platform rebase you approved stays live.
A test run calls one tool of a release yourself, without an agent: try it before you approve the release, or find out why a live one fails. Choose Test run beside the tool, in a Staged release's review or under Show details of a Staged or Live release on the Releases tab.
The dialog has a field for each argument the tool takes, marked (required) where the tool needs it. When an argument is a list or an object the form cannot show, switch on Edit as JSON and write the arguments as one JSON object. A test run's arguments come to at most 1,048,576 bytes (1 MiB) as JSON.
Choose Run. A run takes at most the server's timeout, and a little longer when the server has not been called for a few minutes.
The Result says whether the tool answered or failed, and shows how long it took, its billed duration and memory, and its estimated cost. Output is what an agent would read, and Log tail is the last 64 KB the code printed.
A test run shows what the tool answered and what its code printed.
A test run is a real call to the release's code:
It runs with the server's secrets. They are removed from everything the run shows, as on an agent's call. The run is kept apart from every project's calls.
It is recorded. Each run appears on the server's Calls tab marked Test run, with who ran it, and a release's review lists its own under Test runs. The record keeps a failed run's log tail; the whole 64 KB is shown only in the dialog, once.
The files it saves are kept for a day. A file the code saves with askrai.file() is listed in the Result and on the run's record, ready to open, and lands in no project's Workspace tab. A day later it is deleted.
It reads no workspace file. A test run belongs to no project, so a link in its arguments reaches the code as text, and askrai.read() fails.
It costs what an agent's call costs. Its compute counts toward the tenant's 250,000 GB-seconds a month, and it takes one of the 5 hosted calls the tenant may run at once.
A tenant test-runs at most 30 times an hour, unless AskRAI has raised its limit. A run past any of these limits, or while AskRAI has suspended or paused hosted tools, is refused in the dialog with the reason: it runs nothing and costs nothing.
An agent calls a hosted server's tools as it calls any other tool's, and the same controls govern it: organizations, grants, each tool's effect, the agent's autonomy, approval requirements, the per-beat call and action budgets, egress allowlists and the audit trail. On top of those:
The approved code is the code that runs. Each call goes to the exact release whose tools the agent was offered, never to code published after it.
Secrets stay out of everything kept or shown. The server's secrets travel with each call. Before anything is stored, shown to a model or shown to you, they are removed from the result, the audit trail and the call's log, encoded copies included.
A call that cannot run is refused before it costs anything. A tenant runs at most 5 hosted calls at once and 250,000 GB-seconds of hosted compute a month, unless AskRAI has raised its limits, and a call that starts a new environment for its server counts that environment's charge too. A call past either limit, or one the beat no longer has time to finish, is refused before it counts against the agent's budgets, and the agent is told why. A server that cannot take the call at all is reported to the agent as unavailable, also at no cost.
An egress allowlist admits a hosted server by name. A server with internet access is admitted only when every allowlist in force names its pseudo-host, <slug>.hosted.invalid. Its code reaches the internet itself, so admitting it admits traffic that no allowlist restricts downstream, and Egress allowlists labels such an entry downstream traffic unrestricted. A server with no network access is admitted under every allowlist, needs no entry, and carries no such label. An agent's Skills & Tools tab shows each hosted server's network access, and warns This agent’s egress allowlists refuse its calls, naming the pseudo-host to add, when not every allowlist in force for that agent admits it.
AskRAI can suspend a tenant's hosted tools. If a tenant's hosted code puts the platform or other tenants at risk, AskRAI suspends its hosted tools: every agent's call to one is refused at no cost, nothing can be published, and releases already building wait. The Hosted tab says so while it lasts, and only AskRAI lifts it. AskRAI can also pause every tenant's hosted tools at once while it deals with a platform-wide problem.
A live release found malicious is held. Every night AskRAI checks each live release's packages again. A package newly marked malicious holds that one server:
every agent's call to its tools is refused at no cost, and its live release never runs again;
the administrators who manage tools are notified;
the server shows the hold and the packages behind it, and the release is marked Held.
You can still publish, test-run and approve a new release. Approving a release without the package, published after the hold, lifts it, and the held release can no longer be restored. A release published before the hold can be neither approved nor test-run: publish again. Any other new advisory shows on the live release as a warning. If the advisory is later withdrawn, AskRAI can publish the held release again for you to approve, but cannot release a package that is still marked malicious.
The audit trail records each hosted call's billed duration and memory, the charge for a new environment it started, the redacted log of a call that failed, and whether the release it ran was self-approved.
A server's Calls tab lists the calls made to its tools, newest first: its test runs, and the calls agents and assistants made from the projects shared with you. A call from a project you cannot open is neither listed nor counted. Each shows when it was made, the agent or assistant and project that made it or Test run with who ran it, the tool, whether it succeeded or which step stopped it, and how long it took. The arguments a call sent and what came back are not shown here; an agent's call shows them on its project's Activity tab, to the people who can open the project.
A hosted server's calls also show their billed duration, the memory they used, an estimated cost, the files each was handed to read and the files it saved, which open from here: an agent's from its project's Workspace tab, a test run's for a day. A failed call has Show log tail: the last of what its code printed, with the server's secrets removed. The estimated cost prices the call's billed GB-seconds, with the charge for a new environment it started, at $0.0000133334 a GB-second, plus $0.0000002 for the call itself. It is a guide for comparing calls, not a bill.
Every call to a server, an agent's or a test run, newest first.
Open the agent on the project's Team pane and use its Skills & Tools tab. The picker offers the servers granted to that project's organization; an agent may hold up to 100.
An agent granted a whole server may call every approved, enabled tool on it — or, if you choose Only selected tools when granting the server on the agent's Skills & Tools tab, just the ones you name. Narrowing there is the least-privilege control: the agent is offered nothing else. Each tool reaches the model under a namespaced name — the server's slug, then __, then the tool's own name — so two servers offering a search tool never collide.
Delete is in the sheet header. Before you can confirm, the dialog reads how many agents hold the server and states the count.
Deleting removes the server, its stored credentials, every tool it has discovered, and every agent's grant to it — across the whole tenant, not only the organizations it was granted to. If a delete fails, running it again is safe and finishes what it started.
Deleting a hosted server also stops its releases, including one still building, and deletes the code it runs: every release's build and every version the platform staged. Agents lose its tools from their next beat. If the platform cannot remove all of the code at once, the server is still deleted for you, and what is left can no longer be called by any agent.
AskRAI keeps a short record of each deleted hosted server for a year, also after your tenant is erased: the name its code ran under, your tenant's id and when the server existed. It holds none of the server's code, secrets or results, and lets AskRAI answer an abuse report about the server that arrives later.
MCP Server (connected by URL), Builtin (added from the Builtin tab's catalog) or Hosted (code you write on the Hosted tab, which the platform runs). Cannot be changed after connecting.
Name
Required. At most 120 characters.
Description
Optional. At most 500 characters.
URL
The MCP endpoint. Required for an MCP server, at most 2048 characters.
Authentication
No authentication, Header token, or OAuth client credentials.
Header name / prefix
Header token only. At most 128 and 64 characters.
Client ID / Scopes
OAuth only. At most 256 characters; up to 64 scopes.
Organizations
Up to 100 organizations may be granted one server.
Simulated system
Off unless you switch it on. Marks the server and its calls as a stand-in for a real system.
Effect
Per tool: Read only or Side effecting. A hosted server's tools are given theirs when their release is approved.
Enable
Per tool. Off until you switch it on for an MCP server. A hosted server's new tool arrives on when its release is approved. A builtin connection's tools arrive approved and on, and a tool you switch off stays off.
No row on this page has had its schemas opened. Open one, or use Show what approving all N accepts.
A tool is approved and enabled but an agent cannot call it
The server may be switched off, not granted to that agent's organization, or not granted to the agent. All three are required.
Granting tools to an agent is refused with Tools cannot be granted on tool server …
The refusal names each tool that cannot be granted, grouped by why: not approved, disabled, or no longer offered by the server. An approved tool must also be enabled, and still offered by its server, to be granted. A Platform Admin can approve or enable it here; otherwise leave it out of the grant.
The connection fails with a credential error, and the secret is right
A required detail is missing — Header name for a header token, Client ID for OAuth. The call fails closed rather than going out unauthenticated.
OAuth fails with invalid_client for a correct secret
The server expects the credentials in the request body, not the Basic header. Change where they are sent on the Connection tab.
OAuth fails with no OAuth authorization-server metadata could be read
The authorization server publishes no metadata, or answered for it with a server error. Ask the server's operator to publish metadata naming its token endpoint; the secret is not sent until it does.
The connection fails with the server's TLS certificate did not verify
AskRAI does not trust the certificate the server presented, and says why in parentheses. A self-signed certificate, or one AskRAI cannot trace to a public certificate authority (unable to get local issuer certificate), needs a certificate from a public authority, served with its intermediates. An expired one needs renewing.
The connection fails with the server's TLS certificate is not for this host
The certificate does not name the host in the server's URL. Enter the name it was issued for.
An approval comes back as stale
The row moved since you read it — a sync replaced it. Re-read the row and approve again.
An approval comes back as unmatched
The server no longer offers a tool by that name.
An MCP server will not switch on
No sync has succeeded against it yet. Run Sync tools first.
Tools disappeared after an edit
The URL was changed. Moving the endpoint deletes the catalog by design — re-sync and approve again.
An agent is told a hosted tool is unavailable
The server's code could not take the call just then. Nothing ran and nothing was charged, so the agent can try again on a later beat.
Every hosted call is refused for the rest of the month
The tenant has used its hosted compute for this month.
A hosted release fails with a dependency error
That version does not exist, is less than two days old, or has no prebuilt binary for Linux on arm64. Pick another exact version.
A hosted release stays Building
Another of the tenant's releases is being built, and this one waits its turn.
A browser tool fails with Target closed or Protocol error after opening a page
Its code opened a second browser context, which ends Chromium here. Open every page with browser.newPage(): see The browser layer.
Publish says the hourly limit is reached
The tenant has published as often as its hourly limit allows, 20 times unless AskRAI raised it. Publish again later.
The Hosted tab says RAI has suspended this tenant’s hosted tools
Every agent's call to a hosted tool is refused, and nothing can be published, until AskRAI lifts the suspension. Contact AskRAI support.
Publish says hosted tools are paused across the platform
AskRAI has paused every tenant's hosted tools for a while. Publish again later.
A hosted server says RAI holds this server
The nightly check found a package in its live release that is now marked malicious, so its calls are refused. Remove or replace the package, publish, and approve the new release: the approval lifts the hold.
Save says someone else saved this server
The source changed since you opened it. Reload it, then make your change again.
Approve release is refused because the release, or the live one, changed
Someone published, approved or reverted this server's releases while you were reviewing. The review has read the release again: check what it holds now and approve again. A release a newer publish replaced shows as Superseded and can no longer be approved.
A Platform rebase release asks you to approve it, or publish, by a date
AskRAI moved the server's code onto a platform update, and its tools or installed packages changed, the update was not yet tried on live servers, or it no longer built or listed its tools. Review and approve the release, or fix the code and publish: see Platform updates.
Revert to previous release is not shown
No release is live, or the live one replaced none: a server's first release, and a release just restored by a revert, have nothing to go back to.
An agent's Skills & Tools tab warns This agent’s egress allowlists refuse its calls
Not every egress allowlist in force for that agent names the hosted server's pseudo-host, so each call to its tools is refused. Add the <slug>.hosted.invalid host the warning names to each of them.
Connect your PostgreSQL, MySQL, MariaDB, Oracle, Snowflake, SQL Server and Azure SQL databases, as many as you need, and let the agents you grant one list, describe, query and explain its tables, export a query's rows from PostgreSQL, MySQL, MariaDB, Oracle or Snowflake, and on a read-write connection change its rows within a limit you set
A SQL connection lets an agent read a database your teams already run: list its tables, describe one, run a query, see a query's plan and export a query's rows as a CSV file into the project's workspace. A connection you set to read and write also lets an agent change rows, one statement at a time, within a row limit you set: see Let agents change rows. You add as many connections as you need, each with its own server, login, organizations and limits, so a finance warehouse can be granted to one organization and a CRM database to two others, each under a different login.
Adding and changing SQL connections takes Manage tools, as connecting any tool server does, and View tools reads them read-only. Granting a connection to an agent is open to the people with Write access to its project, under the same rules as any other tool server: see Tools.
Five engines connect today: PostgreSQL, MySQL, which connects MariaDB too (see MySQL and MariaDB), Oracle, Autonomous Database included, Snowflake, which connects by its account rather than a host and signs in with a key pair or External OAuth, and SQL Server, which connects both SQL Server and Azure SQL Database. Oracle and Snowflake have differences of their own, and where SQL Server differs, this page says so.
A login that can only read. The database's own permissions are the boundary: AskRAI checks every statement and rolls back every read, but what the login is allowed to do is what an agent can ever reach. Create a login with read access to the tables your agents need and nothing more. For a connection that writes, grant it changes to only the tables agents should change. On SQL Server, which has no read-only transaction, the login's grants are what stop a write: make it a member of db_datareader, or grant it SELECT on each schema agents read, as in GRANT SELECT ON SCHEMA::sales TO [askrai-reader].
Your firewall allows AskRAI. AskRAI reaches your database from a fixed set of addresses, which the connection form lists under Allow these addresses through your firewall. On Azure SQL, add them to the server's firewall rules. Azure SQL serves a client outside Azure, as AskRAI is, through its gateway on port 1433 under the Proxy connection policy, the default for such a client, so a connection needs port 1433 alone, not the redirect ports 11000 to 11999. AskRAI connects Azure SQL in Azure's public cloud: Azure Government and Azure China (usgovcloudapi.net, chinacloudapi.cn) are not supported.
TLS with a certificate for the host name. AskRAI never connects without encryption. It verifies the server's certificate against the system's trusted authorities, or against a certificate authority you provide, and checks that the certificate is valid for the host you enter. Azure SQL's certificates come from public authorities, so the system's trusted authorities verify it.
Strict encryption, on SQL Server. AskRAI connects to SQL Server with strict encryption, where TLS starts before any of the database's own protocol is sent. That needs SQL Server 2022 or later on Windows, SQL Server 2025 on Linux, or Azure SQL Database: SQL Server 2022 on Linux refuses strict encryption, and so does every earlier release.
A port AskRAI opens. The database must listen on 5432, 1433, 3306, 1521, 1522 or 2484. Snowflake is reached over HTTPS, on 443: see Snowflake.
A public address. The host must resolve to an address on the public internet. A private network is not reachable.
Give the connection a Name agents will read, such as Finance DB, a Description, and tick the Organizations that may use it.
Under Database server, choose the Engine, which fills in its default Port, then enter the Host and Database, or for Oracle the Service name, or for Snowflake the Account and Database, and the Warehouse and Role if you need them. For Azure SQL Database, choose SQL Server and enter the server's name as Azure shows it, such as contoso.database.windows.net. Choose how TLS is verified, and paste the CA certificate if you chose a certificate authority you provide.
Under Login, enter the Username and Password of the read-only login. On Snowflake, Sign in with offers Key pair, the user's name and its Private key, or External OAuth client credentials: see Sign in with a key pair and Sign in with External OAuth client credentials. On SQL Server and MySQL, Sign in with offers SQL login or Microsoft Entra service principal, which signs in with its Directory (tenant) ID, Application (client) ID and Client secret, and on MySQL the Username of the MySQL user created for it: see Sign in as a Microsoft Entra service principal. Once the connection exists, how it signs in is fixed.
Under Access, keep Read only, or choose Read and write to let agents change rows. Then list the Schemas the tools show. Leave the list empty to show every schema the login can see.
Adjust the Limits if you need to, and add Notes for agents: what the tables hold and how to read them, such as "Amounts are in cents; the fiscal year starts in April."
Choose Add connection. AskRAI tests the connection as it adds it. When the test passes, the connection is on and its tools are ready to grant. When it fails, the connection is kept, switched off, with the reason under The connection test failed, so you can correct it and test again.
Each kind of platform tool has a card, with the connections you added listed beneath it.
The Connection tab shows each setting and the outbound addresses to allow. Read and write adds Max rows changed.
On SQL Server and MySQL, a connection can sign in as a Microsoft Entra service principal in place of a SQL login, on a server that accepts Entra sign-ins, as Azure SQL and Azure Database for MySQL do. The service principal is an app you register in your own Entra tenant: AskRAI registers no multi-tenant app, so there is nothing of AskRAI's to consent to.
In the Microsoft Entra admin center, register an application in your tenant. From its Overview, copy the Directory (tenant) ID and the Application (client) ID.
Under Certificates & secrets, create a client secret and copy its value.
Signed in as a Microsoft Entra admin of the server, create a user for the app and grant it read access. On SQL Server, in the database the connection reads, the user is named as the app is:
CREATE USER [askrai-reader] FROM EXTERNAL PROVIDER;ALTER ROLE db_datareader ADD MEMBER [askrai-reader];
On Azure Database for MySQL, you name the user, and identify the app by its Application (client) ID:
CREATE AADUSER 'askrai-reader' IDENTIFIED BY '<application (client) id>';GRANT SELECT ON finance.* TO 'askrai-reader'@'%';
Under the connection's Login, choose Microsoft Entra service principal under Sign in with, and enter the Directory (tenant) ID, the Application (client) ID and the Client secret. On MySQL, enter the user's name too, as the Username.
As it connects, AskRAI asks Microsoft Entra for a token from https://login.microsoftonline.com/<directory id>/oauth2/v2.0/token, for the scope https://database.windows.net/.default on SQL Server and https://ossrdbms-aad.database.windows.net/.default on MySQL, and hands it to the database: on MySQL as the user's password, which the server asks for over the connection's TLS. AskRAI never writes the token down: it is held in memory, and only until shortly before it expires.
Windows authentication is not available on SQL Server, and on neither engine is signing in as each person with their own Entra account: every call signs in as the connection's one login or service principal.
Every SQL connection offers these tools, all read-only toward your database. export_query is offered on PostgreSQL, MySQL, MariaDB, Oracle and Snowflake connections, and a connection set to Read and write adds execute (see Let agents change rows):
Tool
What it does
list_tables
Lists the tables and views the login can see, inside the connection's schemas, with each one's kind, approximate row count and comment, a page at a time
describe_table
Describes a table: its columns with their types, defaults and comments, its primary and foreign keys, and a few sample rows when asked
query
Runs one read statement and answers its rows as a table, up to the connection's Max rows
explain
Shows the database's estimated plan for a read statement, without running it
export_query
Runs one read statement and saves every row it answers as a CSV file in the agent's workspace: see Export a query's rows
An agent sees each tool under the connection's own name, so one granted Finance DB and CRM DB calls finance-db__query and crm-db__query and never confuses the two. Each tool's description opens with the connection's name and ends with your notes.
A query's answer holds whole rows only. When a result is longer than one answer can carry, the agent is told how many rows it was shown and that more exist, so it can narrow its query. A value longer than 2,000 characters is cut there, and marked as cut.
A query answers at most 100 columns. A wider result is refused before any of its rows is read, and so is one whose column names and types leave no room for a row; either way, the agent is told to select fewer columns.
A value longer than 2,000 characters is cut, with a marker, and a value of a large type is cut by the database server itself, so it never crosses the connection whole. On SQL Server, a result column of a type the server does not cut is refused before any row is read: xml, and CLR types such as geometry and geography, and the agent is told to select it as CAST(column AS nvarchar(max)), which is cut. A json value, which SQL Server describes as text it cuts, is read and cut by AskRAI up to 64 KiB; past that the connection ends, with the same advice.
On SQL Server, two tools need more than read access. explain compiles the statement and runs none of it, which needs the SHOWPLAN permission: GRANT SHOWPLAN TO [askrai-reader]. describe_table shows a column's default only to a login granted VIEW DEFINITION on its schema, as in GRANT VIEW DEFINITION ON SCHEMA::sales TO [askrai-reader].
export_query runs a read statement as query does, read-only, and saves every row it answers as a CSV file in the project's workspace, where people open and download it from the Workspace tab. The agent names the file, ending in .csv, and it lands in the agent's default folder, or at the workspace root for an agent that may write anywhere and has no default folder.
Up to 25 MiB. A larger result ends at a whole row, and the agent is told the statement answered more, so it can export the rest with fewer columns or a narrower WHERE. On Oracle and Snowflake an export also ends once it has read 50 MiB of the database's answers, which a result reaches before 25 MiB of CSV only when much of it is long values, cut in the file, and on Snowflake binary values, written as their length, or NULLs. On MySQL and MariaDB a row longer than 1 MiB refuses the export, and the agent is told how to cut its long value. An export also ends at a whole row once it has read for the connection's Statement timeout, or if the connection drops, keeping the rows read so far, and the agent is told which.
An agent's write. The file is saved as any file an agent writes is: inside the agent's workspace access, counted against your organization's workspace storage, and spending one of the agent's actions for the beat. At Manual autonomy it is a proposal a person approves before it is saved. When the agent may not write the file, the export does not run; when storage is full, it runs but nothing is saved. Either way the agent is told why.
Values as a query shows them. A value longer than 2,000 characters is cut, ending in …<cut at 2000 characters>, and a binary value is written as its length, such as <binary 4096 bytes>. The connection's password, private key or client secret, and the access token it signed in with, wherever a value holds one, is written as [redacted]. An empty value and a NULL differ: a NULL is the one empty, unquoted cell.
Safe to open in a spreadsheet. A value a spreadsheet would run as a formula, one starting with =, +, - or @ (after any spaces), or with a tab or a carriage return, is written with a ' in front of it, so it opens as text. A number such as -12.5 is left as it is. Outside a spreadsheet, such a value shows the '.
Your output guardrails read the file. A guardrail that blocks or redacts what agents write checks every row, and when it finds what it objects to, the whole export is refused rather than saved altered, and the agent is told to export without that content. A guardrail that only warns is recorded, and the file is saved.
An agent whose output stage holds a blocking LLM judge cannot export. A judge reads what an agent writes with a model, and no model can read an export whole, so every export is refused before it runs. A judge that only warns is not asked, and the beat's trail says so.
A connection added before export_query was available gains it when you choose Sync tools on its Connection tab.
AskRAI protects a read-only connection in layers, and the login's permissions stay the boundary:
Every statement is checked before it reaches your database. A query runs only if it is exactly one read: a SELECT, a set operation such as UNION, VALUES, or a WITH query ending in one. A statement that writes, changes the schema, sets the session or locks rows is refused, and so is SELECT … INTO. On SQL Server, so are a table hint that takes or holds locks (UPDLOCK, HOLDLOCK, XLOCK, TABLOCK and their kin), with or without WITH, NEXT VALUE FOR, since a sequence's advance survives a rollback, and FOR BROWSE, and so is a linked server, whatever the schemas: OPENQUERY, OPENROWSET, OPENDATASOURCE and a name of four parts, since what they run on another server no rollback undoes. A statement AskRAI cannot read is refused too, never passed through.
Every read runs in a read-only transaction where the database has one, which the database itself enforces. On Oracle, a sequence's NEXTVAL is refused before it runs, since Oracle advances a sequence even inside a read-only transaction. SQL Server has no read-only transaction, so there the login's permissions are what stop a write. Snowflake has none either, so there the check and the role's grants are what keep a read a read: see The role is the boundary.
Every read is rolled back, whether it succeeds or fails.
Every read is bounded: by the connection's Statement timeout, by a lock timeout of a quarter of it, so it never waits out its time on someone else's lock, and by Max rows. Oracle's reads never wait on locks. SQL Server has no statement timeout of its own, so there AskRAI ends a statement that runs too long from its side.
What a check cannot see, it does not claim to catch. A function a SELECT calls can try to write, and the read-only transaction and the login's permissions are what stop it. On SQL Server, the login's permissions alone stop it.
Schemas limit what the tools show, not what the login can read.list_tables and describe_table show only the schemas you list, and a query may name only tables in those schemas, never one in another schema or in the database's own catalog (a name starting pg_ on PostgreSQL, the sys and INFORMATION_SCHEMA schemas on SQL Server). On Oracle a query names each table as schema.name, since an unqualified name could reach the login's own schema or a public synonym, and a call to a package such as DBMS_XMLGEN is refused. Oracle also reads c.name as a call to a function of schema c, or of a package, where c is a table joined by JOIN or APPLY that has no column name, so such a table's columns are qualified only in the ON that joins it. Elsewhere, join with a comma and a WHERE condition, marking an outer join with (+) as in WHERE i.id = c.id(+), or name the column alone. A view, or a function the database already holds, built in or your own, can still read beyond them, and some run a query given to them as text. The login's permissions are the boundary: grant it access only to what agents may read.
SQL Server has no search path either, so with schemas listed, a query names each table and table-valued function with its schema, as in sales.orders. Only the names a WITH query defines and the built-in OPENJSON, STRING_SPLIT, GENERATE_SERIES, REGEXP_MATCHES and REGEXP_SPLIT_TO_TABLE go without one, and each of those only where the database's compatibility level makes it built in: 130 for OPENJSON and STRING_SPLIT, 160 for GENERATE_SERIES and 170 for the other two. Below that level, SQL Server would run a function of the same name in the login's default schema or in dbo instead, so a query calling one there is refused. A schema matches only as it is written in the list, case included. A column's method, such as value() on an xml column or STDistance() on a geometry one, is called on the column named with its table's name or alias, as in d.doc.value('(/a)[1]', 'int'), since doc.value(…) alone can also name a function value in a schema doc, which SQL Server calls where the query reads no column doc. In a CROSS APPLY or OUTER APPLY, only nodes() runs, with the columns it returns named after its alias: CROSS APPLY d.doc.nodes('/a') AS x(n). A function that reads the catalog by an object's, a schema's or a database's name, such as OBJECT_DEFINITION, OBJECT_ID, SCHEMA_NAME or DB_NAME, is refused while schemas are listed.
With no schemas listed, a query can also name a table in another database on the same server, as in otherdb.sales.orders, wherever the login can open that database. Grant the login access only to the databases agents may read.
Set Access to Read and write, and an agent granted the connection can call execute: one INSERT, UPDATE, DELETE or MERGE on one table, which AskRAI commits and answers with how many rows it changed. Switching the connection back to Read only takes execute away from every agent at once.
Each change is bounded by Max rows changed. A statement runs in a transaction of its own. When it changes more rows than Max rows changed, 100 by default, it is rolled back, nothing changes, and the agent is told how many rows it would have changed. On MySQL and MariaDB a row an UPDATE matched counts whether or not its values changed.
Changing rows is a side effect, and autonomy governs it. An agent at Manual autonomy is refused, as it is for every tool that changes something. At Full autonomy, each call is made at once and spends one of the agent's actions for its run. A policy that requires approval for side effects holds the call. See Autonomy levels.
Every statement is checked before it reaches your database. AskRAI refuses:
an UPDATE or DELETE without a WHERE clause, or with one that names no column, such as WHERE 1=1, since it picks every row or none. A condition that is always true of a column, such as WHERE id = id, is not caught: Max rows changed is what bounds it;
a WITH clause, RETURNING, OUTPUT, INTO, a locking clause, an optimizer hint written in a comment (/*+ … */), and any variable or parameter;
more than one table to change: MySQL's multi-table UPDATE and DELETE, its DELETE … USING, SQL Server's DELETE … FROM with a FROM of its own, and a join, subquery or function in the table's place. A PostgreSQL UPDATE … FROM or DELETE … USING, and an Oracle or SQL Server UPDATE … FROM, may read other tables; on SQL Server, a DELETE reads them in a subquery of its WHERE;
any function but a built-in one that only computes a value: text, number, date and time, conditional and conversion functions, and aggregates. A function of your database's own, a sequence's next value, dblink and a call to a package are refused;
on Oracle, a column qualified with anything but a table the statement reads, since pkg.fn calls a package's function. A MERGE joins its source to its target, and an UPDATE … FROM may join tables with JOIN or APPLY, where Oracle reads a name the table lacks as a call, so their columns are qualified only in the ON that joins them. Elsewhere name the column alone, renaming a source's column in a subquery where the target has one of its name: MERGE INTO finance.ledger t USING (SELECT id sid, amount new_amount FROM finance.staged) s ON (t.id = s.sid) WHEN MATCHED THEN UPDATE SET amount = new_amount;
on PostgreSQL, what can run a function of your database's own without a call: an OPERATOR(…), a cast to a type other than the common built-in ones, a name after a table or alias that is not one of its columns, such as t.fn, which PostgreSQL reads as fn(t), and a name after a value in parentheses, such as (t).fn;
on SQL Server, TOP on the statement itself, any table hint, even one a read may take, such as WITH (NOLOCK) or TABLOCKX, a linked server as for a read, and what can run a type of your database's own without a call: a cast to any type but SQL Server's own, json among those refused since SQL Server 2022 has none, a property after ::, a property of a value in parentheses, such as (shape).STX, and a name after a column, such as shape.STX, which reads a property of the column's type. So a column is qualified only with the name or alias of a table the statement reads, as in o.status, never with a schema;
every other statement: schema changes, GRANT, CALL, EXEC, COPY, TRUNCATE, MySQL's REPLACE and Oracle's INSERT ALL.
Every table a statement changes or reads is held to the connection's Schemas, in a subquery, a FROM, a USING or a MERGE's source.
What the checks cannot see. A trigger, a cascading foreign key, a view or a function your database holds can change more than the statement names, and only the login's permissions stop that. On PostgreSQL so can an operator or function your database defines under a built-in one's name, and the type or domain of a column the statement writes to. Those changes are not counted toward the limit. On a table that can roll back, they are rolled back with the statement, but not what a trigger writes to a table that cannot, such as MyISAM, nor what it commits in an Oracle autonomous transaction.
MySQL and MariaDB. A table whose storage engine has no transactions, such as MyISAM, cannot be rolled back past the limit, so AskRAI never writes to one, nor through a view. MySQL's statement timeout covers reads alone, so a long write ends uncommitted when the call's time runs out.
SQL Server and Azure SQL.Max rows changed counts the rows the statement itself changed, never the rows its triggers report, whether or not a trigger sets NOCOUNT. An error a trigger raises stops the change, and nothing commits. A statement still running at the connection's Statement timeout, or waiting past the lock timeout on a row another session holds, ends with nothing changed. A trigger that commits or rolls back the transaction itself ends it before the limit can be held, so the agent is told the change may stand.
Snowflake commits each statement as it runs, so a change past Max rows changed cannot be rolled back. AskRAI reads how many rows the statement changed once it has run, and when that is past the limit, the agent is told so and the change stands. Connect as a role that may change only what agents should, and set Max rows changed as a warning rather than a guarantee. INSERT OVERWRITE, which empties a table first, is refused.
Writes are available on every engine: PostgreSQL, MySQL, MariaDB, Oracle, Snowflake, SQL Server and Azure SQL.
Choose Test connection on the Connection tab at any time. A passing test shows the server's version and confirms that a read-only transaction opened, for example Connected to PostgreSQL 18.6 · read-only transaction opened, Connected to Oracle 23.26.3.0.0 · read-only transaction opened, or Connected to MySQL 11.8.9-MariaDB-ubu2404 · read-only transaction opened for a MariaDB server. SQL Server has no read-only transaction, so its test shows the server's version and edition, and that reads are rolled back, for example Connected to SQL Server 17.0.1000.7 Enterprise Edition (64-bit) · reads run in a transaction that is rolled back.
Edit any field on the Connection tab and choose Save changes. AskRAI tests the connection again as it saves.
Renaming. A new name alone saves without a test, and the tools' descriptions open with it at once. Their names, such as finance-db__query, keep the name the connection was added with.
Moving to another database. Changing the engine, host, port, database or service name, or a Snowflake connection's account, moves the connection, so AskRAI asks you to confirm. Its tools are rebuilt, and it stays off until a test against the new database passes.
The password, a Snowflake connection's private key, or a client's Client secret, is never shown. A connection with one stored says A value is stored; choose Replace value to set a new one.
Someone else saved first. If another administrator changed the connection after you opened it, your save is not applied. Choose Reload to see their change, then make yours again.
An Oracle connection names the database's Service name in place of a database, and connects over TCPS, Oracle's TLS:
The listener serves TCPS. Port 2484 is the default, and 1521 or 1522 work when the listener serves TCPS on them. A listener that serves only plain TCP refuses the connection.
No redirect. AskRAI connects only to the address it checked, so it does not follow a listener that redirects the connection to another one. Connect to the listener of the instance that serves the service: for Real Application Clusters, a node's listener rather than SCAN, and not through shared server dispatchers.
A login. Oracle connections sign in with a username and password. Signing in with an OCI IAM or Microsoft Entra service principal is not available yet, and neither is a wallet's mutual TLS.
Schemas in capitals. Name each schema as Oracle's catalog does, in capitals unless it was created quoted, such as FINANCE.
Explain writes a plan, and keeps none. Oracle writes an estimated plan into your session's own plan table, so explain runs in a transaction that is rolled back rather than a read-only one. The statement itself is never run.
Autonomous Database. Connect with its TLS connection string, not mutual TLS: in the database's Network settings, turn off Require mutual TLS (mTLS) authentication and add the addresses on the Connection tab to its access control list. Enter the host and port of the connection string (port 1522) and its service name, such as abc123_finance_high.adb.oraclecloud.com. AskRAI has not yet been confirmed against a live Autonomous Database. If Test connection says the listener redirected the connection, run an Oracle Connection Manager that your database trusts, reachable from AskRAI over TCPS, and connect to it instead.
Choose MySQL as the engine for either: MariaDB speaks MySQL's protocol, and AskRAI tells them apart when it connects. AskRAI needs MySQL 8.0 or later, or MariaDB 10.2 or later. It connects on 3306 by default.
A schema is a database. On MySQL and MariaDB the Schemas you list are databases. A table named without its database is read in the connection's Database, so when you list schemas, list that database among them. Leave the list empty to show every database the login can see, apart from the server's own: information_schema, mysql, performance_schema and sys.
Names are read as written. MySQL does not fold a name to lower case, so Orders and orders are two tables on a server that tells case apart, and an agent names a database exactly as it is listed.
The checks are MySQL's. Statements are read as MySQL writes them, backquoted names included. An optimizer hint (/*+ … */) is refused, since one can lift the statement timeout, and so are SELECT … INTO, FOR UPDATE and LOCK IN SHARE MODE. A comment is dropped before the statement runs, so a versioned comment (/*! … */) never reaches your server.
Each read is a read-only transaction (START TRANSACTION READ ONLY), held to the statement timeout and a lock timeout, and never committed.
A login, or on Azure a Microsoft Entra service principal. An Azure Database for MySQL connection can sign in as an app you register in Entra, as the MySQL user created for it: see Sign in as a Microsoft Entra service principal.
No person context. MySQL and MariaDB hold no session value a row-level policy can read, so every call reads as the connection's login.
A Snowflake connection names your Account in place of a host and port, and signs in as a Snowflake user with a key pair, or with a token your own identity provider issues through Snowflake's External OAuth, rather than a password. AskRAI reaches your account through Snowflake's SQL API over HTTPS, on port 443, from the addresses the form lists under Allow these addresses through your firewall, so a Snowflake network policy can allow them.
Account is your account identifier: the part of your Snowflake address before .snowflakecomputing.com, such as myorg-myaccount.
Database is required.
Warehouse and Role are optional. Without them, the user's default warehouse and role apply, or with External OAuth the role the token names.
Names as Snowflake stores them. The database, warehouse, role and each schema are matched exactly as Snowflake stores them: in capitals, such as FINANCE, unless the object was created in double quotes.
Enter the Snowflake user's name as the Username, and its Private key in place of a password: an unencrypted RSA private key of 2048 to 4096 bits in PKCS#8 form, a .p8 file.
Generate an unencrypted private key in PKCS#8 form:
In Snowflake, as an administrator who may alter the user, set the public key on it. Paste the body of rsa_key.pub, without its -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines:
ALTER USER <user> SET RSA_PUBLIC_KEY='<key body>';
Paste the whole of rsa_key.p8 into Private key, or load the file there.
An encrypted private key is refused when you save the connection, and AskRAI says why. The key is stored encrypted and never shown again. To rotate it, set a new public key on the user and replace the private key here: setting it as RSA_PUBLIC_KEY_2 keeps the old key working until you do.
A Snowflake connection can sign in with an access token from your own identity provider, such as Okta or Microsoft Entra ID, which a Snowflake External OAuth security integration trusts. The client application is yours: AskRAI registers none.
In your identity provider, create a client application that may use the client credentials grant, and copy its client ID, a client secret and the provider's token endpoint. Have its tokens name the Snowflake role the connection runs as: on Okta, a scope such as session:role:ASKRAI_READER, which you list under Scopes; on Microsoft Entra ID, an app role of that value on your Snowflake resource's application, granted to the client, whose /.default scope you list instead.
In Snowflake, create an External OAuth security integration for that provider, mapping the token's subject to a Snowflake user, and grant that user the role: see The role is the boundary.
Under the connection's Login, choose External OAuth client credentials under Sign in with, and enter the Token endpoint, an https:// address, the Client ID, the Scopes, separated by spaces, and the Client secret.
As it connects, AskRAI posts the client ID and secret to the token endpoint in a Basic authentication header, asks for the scopes you listed, and sends the token to Snowflake as its OAuth bearer. AskRAI never writes the token down: it is held in memory, and only until shortly before it expires.
Snowflake runs the session in the role the token names. Leave the connection's Role empty, or name that same role: Snowflake refuses a request naming another, and the connection's test fails. Signing in as each person with their own Snowflake OAuth is not available: every call signs in as the connection's one client.
Snowflake has no read-only transaction, so the role the connection runs as is what keeps it read-only. AskRAI's own check still lets only one read statement through: a SELECT, a set operation such as UNION, or a WITH query ending in one. It refuses a statement that writes or changes the schema, a SHOW written by an agent, CALL and EXECUTE IMMEDIATE, a SYSTEM$ function and a sequence's NEXTVAL.
Connect as a user whose role is granted only what agents may read: USAGE on the warehouse, the database and the schemas, and SELECT on the tables. For example:
CREATE ROLE askrai_reader;GRANT USAGE ON WAREHOUSE analytics_wh TO ROLE askrai_reader;GRANT USAGE ON DATABASE finance TO ROLE askrai_reader;GRANT USAGE ON SCHEMA finance.reporting TO ROLE askrai_reader;GRANT SELECT ON ALL TABLES IN SCHEMA finance.reporting TO ROLE askrai_reader;GRANT ROLE askrai_reader TO USER askrai;
Name that role as the connection's Role, or make it the user's default.
With schemas listed, a query names each table as schema.table, with one of those schemas; only the names a WITH query defines for itself go without one. Snowflake would otherwise look an unqualified name up in its search path, which includes PUBLIC. A query is refused too when it names a database in front of a schema (db.schema.table), reads a stage (@stage), or reads INFORMATION_SCHEMA or the shared SNOWFLAKE database. A table function of another schema, or one Snowflake looks up by name, is refused, and so is GET_DDL(); FLATTEN reads only what the query already reads. IDENTIFIER() and TO_QUERY() are refused whatever the schemas: they name an object or a query by text.
With no schemas listed, the role decides what an agent sees.
The five read tools work as on every engine. describe_table shows the primary and foreign keys a table declares, which Snowflake records but does not enforce, and explain shows Snowflake's estimated plan without running the statement.
The statement timeout is applied by Snowflake itself.
A row or an answer too large to read is refused, and the agent is told to select fewer or narrower columns, or to cut long values with LEFT().
Warehouse time each query uses is billed by Snowflake to your account.
No person context. Snowflake holds no session value a row access policy can read, so every call reads as the connection's user.
A SQL connection is granted like any other tool server: on the agent's Skills & Tools tab, by a Member of a project in an organization the connection is granted to. See Team. An egress allowlist in force for the agent admits a SQL connection by its host, and a Snowflake connection by its account's, such as myorg-myaccount.snowflakecomputing.com.
An agent template that grants a SQL connection finds it by the connection's name in each organization. When it holds no name that matches, it uses the organization's SQL connection if the organization is granted exactly one, and otherwise lists the grant as one it could not apply.
The Calls tab lists the calls agents made to the connection from the projects shared with you, with a Summary of each, such as SELECT · 3 rows · 12 ms or SELECT · export · 50000 rows · 840 ms. A summary never holds your data. An export refused before it ran, because the agent may not save its file, shows as Refused: the agent may not save that file there.
On your database's side, AskRAI's sessions sign in as the connection's login and are named askrai-agent, so a DBA tells them apart: PostgreSQL's application name, MySQL's program_name connection attribute, Oracle's module, SQL Server's program name.
Calls per minute caps the calls every agent together makes to the connection in each minute, counted from the start of the minute (UTC), so a busy team cannot overload your database. Once the minute's calls are used up, further calls are refused without reaching the database, and the agent is told the connection is busy and to try again later. The Calls tab shows each one as Refused: the connection’s calls per minute were used up or could not be counted: when a call cannot be counted, it is refused too rather than risk going past your limit. A refused call does not count against the agent's own call budget.
The database engine: PostgreSQL, MySQL for a MySQL or MariaDB server, Oracle, Snowflake, or SQL Server for SQL Server and Azure SQL Database
Host
The database server's host name or IP address, alone: no scheme, port or path. For Azure SQL Database, the server's name, such as contoso.database.windows.net. Not on Snowflake
Port
The port the server listens on: 5432, 1433, 3306, 1521, 1522 or 2484. Choosing the engine fills in its default: 5432 for PostgreSQL, 3306 for MySQL, 2484 for Oracle, 1433 for SQL Server. Not on Snowflake
Database
The database to connect to. Not on Oracle
Service name
Oracle only: the service the listener registers for the database
Account
Snowflake only: the account identifier, the part of its address before .snowflakecomputing.com
Warehouse
Snowflake only, optional: the warehouse queries run on. Empty uses the user's default
Role
Snowflake only, optional: the role queries run as. Empty uses the user's default, or with External OAuth the role the token names
TLS
Verify the server against the system's trusted authorities, or against a certificate authority you provide
CA certificate
The certificate authority's certificate, in PEM form, when you provide one
Sign in with
On SQL Server and MySQL, SQL login or Microsoft Entra service principal. On Snowflake, Key pair or External OAuth client credentials. Fixed once the connection exists
Username, Password, Private key
The login. On Snowflake, the user's name and its unencrypted PKCS#8 Private key in place of a password
On SQL Server and MySQL, a Microsoft Entra service principal in place of a password: the IDs from the app's overview in Entra, and a client secret created for it. On MySQL, the Username is the MySQL user created for the app
Token endpoint, Client ID, Scopes, Client secret
On Snowflake, External OAuth client credentials in place of a user and key: your identity provider's token endpoint, the client's ID and secret, and the scopes its token is asked for, separated by spaces
Access
Read only, or Read and write to let agents change rows with execute
Schemas
The schemas the tools show and a query may name. Empty shows every schema the login sees. On MySQL and MariaDB, databases, the connection's own among them. On Snowflake, named as Snowflake stores them: in capitals unless created in double quotes
Max rows
The most rows a query answers, up to 1,000. 200 by default
Max rows changed
Read and write only: the most rows one statement may change, up to 10,000. 100 by default. A statement changing more is rolled back, except on Snowflake
Statement timeout
How long a statement may run, in seconds, up to 27. 15 by default
Calls per minute
How many calls agents may make to the connection each minute, up to 600. 60 by default
Notes for agents
What agents should know to read the data, up to 2,000 characters
The username or password is wrong, or the login may not connect. On SQL Server, the login may also be refused the database you entered. On MySQL with a Microsoft Entra service principal, the Username must be the user created for this app's Application (client) ID. Check them, then Test connection
the login may not connect to this database
On SQL Server, the login signed in but may not open the database: it has no user there, or no database of that name exists. Check the Database, and that the login has a user in it
Could not get an access token
Microsoft Entra refused the service principal's sign-in. Check the Directory (tenant) ID, the Application (client) ID and the Client secret, and that the secret has not expired
the server's TLS certificate is not for this host
The certificate does not name the host you entered. Enter the name the certificate was issued for
the server's TLS certificate did not verify
AskRAI does not trust the certificate, and says why in parentheses. unable to get local issuer certificate or a self-signed certificate: it was not issued by an authority AskRAI trusts. Choose to verify against a certificate authority you provide, and paste its certificate, not the server's own. certificate has expired: renew it
the database redirected the connection to another server
On Azure SQL, the server's connection policy is Redirect, which sends a connection to another address that AskRAI does not follow. Set the policy to Default or Proxy, which carries a connection from outside Azure through the gateway on port 1433
The connection ended before the database had answered
The database sent more than AskRAI reads of one answer or one value, or something it does not read, or the call ran out of time, and AskRAI closed the connection rather than hold it. Select fewer or narrower columns. On SQL Server, select a json column as CAST(column AS nvarchar(max)), which the server cuts
the TLS handshake with the server failed: strict encryption needs SQL Server 2022 or later, or Azure SQL
The server cannot take strict encryption: it is older than SQL Server 2022, or it is SQL Server 2022 on Linux. Connect to SQL Server 2022 or later on Windows, SQL Server 2025 on Linux, or Azure SQL Database
the server does not offer TLS
The database does not accept encrypted connections. Turn TLS on at the server
the connection timed out or the server refused the connection
AskRAI could not reach the server. Check the host and port, and that your firewall allows the addresses on the Connection tab
the host resolves to a non-public address
The host leads to a private network, which AskRAI does not reach
the database does not exist
No database of that name is on the server
the listener does not know this service name
Oracle's listener has no service of that name. Check the service name, such as the one in your connection string
the listener redirected the connection to another listener
Oracle's listener sent the connection on, which AskRAI does not follow. Connect to the listener of the instance itself: see Oracle
the TLS handshake with the server failed
The port is not served over TLS. On Oracle, connect to the listener's TCPS port
the database account is locked or the login's password has expired
The login cannot sign in until a database administrator unlocks it or sets a new password
the database's answer was larger than one call may read
A statement's answer went past what one call reads. Select fewer or narrower columns, or fewer rows
the login may not connect to this database
The login holds no access to the database, or, on MySQL and MariaDB, no database of that name is on the server
On MySQL and MariaDB a schema is a database …
The schemas you listed leave out the connection's database. Add it to the list
An agent's export did not run
The agent may not write to the workspace or to its default folder, the folder is gone, the file name does not end in .csv, or a blocking LLM judge reads what it writes. The agent is told which
An agent's export ran but saved no file
An output guardrail blocks or redacts something in the rows, or your organization's workspace storage is full. The agent is told which
Port … isn't open from RAI
The port is not one AskRAI connects on. Use one of 5432, 1433, 3306, 1521, 1522 or 2484
RAI's outbound addresses are not configured in this environment
This environment has no fixed outbound address to allow
An agent's query is refused with Only a read runs here
The statement was not a single read. The agent is told why, and can rewrite it
An agent's change is refused with The statement changed … rows, more than this connection's limit
The statement would have changed more rows than Max rows changed, so it was rolled back. Raise the limit, or let the agent change the rows in smaller calls
An agent's change is refused with That table's storage engine (MyISAM) has no transactions
On MySQL and MariaDB, AskRAI writes only to a table that can be rolled back. Convert the table to InnoDB, or keep the connection read-only
… connections can't write yet
The engine does not support Read and write yet. Keep the connection read-only
Let the agents you grant a mailbox connection list the folders of an Outlook archive uploaded to their project, search its messages by sender, recipient, subject, date and attachments, read a message one section at a time, and save its attachments into the workspace when you allow it
A mailbox connection lets an agent read the Outlook archives, .pst and .ost files, uploaded to its project's workspace: list an archive's folders, search its messages, and read a message one section at a time, such as only its body or only its recipients. It can also follow a message's thread, and, where you allow it, save a message's attachment into the workspace to read it like any other file. Every mail tool is read-only: an agent reads the archive, and never sends, moves or deletes mail.
Adding and changing mailbox connections takes Manage tools, as connecting any tool server does, and View tools reads them read-only. Granting a connection to an agent is open to the people with Write access to its project, under the same rules as any other tool server: see Tools.
An agent reads an archive once it is indexed. Upload the archive to the project's Workspace tab, up to 20 GB, and wait for its row to read Indexed: see Workspace tab. An agent reads what the index holds of each message, never the archive file itself.
A connection reaches nothing outside AskRAI, so it has no server, login or firewall rule to set up.
On the Mailbox archives card, choose Add connection.
Give the connection a Name agents will read, such as Claims mailboxes, a Description, and tick the Organizations that may use it.
Under What agents may read, choose whether to Let agents read transport headers and Let agents save attachments: see Transport headers and Save an attachment.
Adjust the Limits if you need to, and add Notes for agents: whose mail the archives hold and what they are for, such as "The claims team's archives, 2019 to 2023."
Choose Add connection. The connection is on at once, and its tools are ready to grant.
A mailbox connection has no server or login: only what agents may read, its limits and your notes.
Each connection is listed beneath its card, on as soon as it is added.
Every mailbox connection offers these tools, all read-only, and save_attachment too when it lets agents save attachments:
Tool
What it does
list_folders
Lists an archive's folders as a tree, each with its key, how many items it holds, and why it could not be read when it could not
search_messages
Finds messages, newest first, by folder, sender, recipient, subject, date and whether they have attachments, or by words in the subject, the sender, the first recipients or the first lines of the body. Each match is summarized: its key, date, sender, first three recipients and how many more, subject and number of attachments
read_message
Reads only the sections of one message the agent asks for: headers (subject, sender, dates and message IDs), recipients, body, attachments (each one's name, type and size), and transport headers when the connection allows them
read_thread
Lists the messages of one message's conversation in the order they were sent, summarized as a search summarizes them
save_attachment
Saves one attachment of a message, named by its number as read_message lists it, as a file in the agent's workspace, read out of the archive after the agent's run. Only when the connection lets agents save attachments
An agent names an archive by its path in the workspace, such as archives/claims-2021.pst, or by its link, and reads only an archive inside the folders it may read. An archive in another project's workspace reads as no file at all.
An agent sees each tool under the connection's own name, so one granted Claims mailboxes calls claims-mailboxes__search_messages. Each tool's description opens with the connection's name and ends with your notes.
A search looks at a message's headers and the first lines of its body, not the whole body: an agent finds a message by what it is about, then reads the body of the one it chose. Sender, recipient and subject match any part of what they name, ignoring case, so allen finds phillip.allen@enron.com. A recipient is looked for among the first 50 of each of a message's To, Cc and Bcc.
Some archives hold folders or messages that could not be read when they were indexed, and the archive's Indexed line in the project's workspace counts them. Every search and every thread of such an archive ends by saying how many, such as 4 messages of this archive could not be read when it was indexed, so an agent never takes a search that found nothing for one that could not look.
read_message answers only the sections asked for, so an agent that needs a message's body reads its body alone, without its recipient list. A long body is read a page at a time: each page says where it ended, and the agent asks for the next page from there. Searches and threads list Messages per search page at a time, and each page says how to ask for the next.
A message's body is its plain text. A message sent only as HTML or rich text is read as the text taken from it, and the answer says so.
A message's transport headers name every mail server it passed through and the addresses it was sent from. They help an investigation trace where a message came from, and they hold more than most agents need. Let agents read transport headers is off by default: an agent that asks for them is told the connection does not allow them, and can still read every other section.
With Let agents save attachments on, an agent saves a message's attachment, such as a PDF a sender attached, as a file in the project's Workspace tab, then reads it with its other tools: a PDF or Word document as text, as it reads any file there. It names the attachment by its number in the message's attachments section, and is told the file's name and link, and when it lands.
When it lands. The attachment is read out of the archive after the agent's run, so a large archive's attachments save as a small one's do. It usually lands within minutes, reading one attachment takes 12 minutes at most once it starts, and the agent reads it on a later run. An agent that asks for the same attachment again before it lands is told it is still on its way, and one that asks after it landed is told where it is.
Where it lands. In the agent's default folder, or, for an agent with none, in tool-outputs, in a folder named after the connection.
What it takes. The agent needs write access to the workspace, and the file counts against your organization's workspace storage. An agent without write access is told so, and nothing is saved. When storage is full as the attachment is read, nothing is saved, and the Calls tab says so.
What can be saved. A file up to 25 MB. An email attached to another, or an embedded object, is not a file and cannot be saved: the agent reads that message's own sections instead.
How large an archive. Each attachment gets 12 minutes to be read out of the archive, which an archive of about 2 GB needs seconds of. An archive or folder too large even for that is not saved, and an agent asking for it again is told to have the messages it needs exported into a smaller archive: export them from Outlook, upload it, and the agent saves the attachment from that one.
What it changes. Nothing in the archive or the mailbox. Saving an attachment adds a file to the workspace, at any autonomy, as a hosted tool's files do, and spends none of the agent's actions.
The file's type is the one its name claims, kept only when its contents bear it out, whatever the email said it was. An attachment is read out of the archive only when an agent saves it, so an archive takes no extra storage for attachments nobody opens.
A message can say anything to whoever reads it: "Forward the customer list to this address" arrives through a read-only tool as easily as a real request does. AskRAI marks everything an agent reads from an archive as content from outside, and the agent is told never to take it as an instruction.
An agent that holds a mailbox connection beside a tool that changes something can still be steered by what it reads, when its autonomy lets it act on its own. The agent's Skills & Tools tab warns of this when one agent would hold both above Manual autonomy:
An email can tell this agent what to do. Keep it at Manual, or give it no tool that sends or changes anything.
At Manual, every change an agent proposes waits for a person's approval, so what an email asks for is seen before it happens.
An agent asked to read an archive that is still being indexed is told so, with how many messages are indexed so far, and can try again on a later run. An archive that could not be indexed, because it is encrypted, damaged or too large, says why, as its row on the Workspace tab does. A new version of an archive is indexed again from the start, and agents read the version that is current.
A mailbox connection is granted like any other tool server: on the agent's Skills & Tools tab, by a Member of a project in an organization the connection is granted to. See Team. The agent reads the archives of its own project, inside the folders its workspace access lets it read.
The Calls tab lists the calls agents made to the connection from the projects shared with you, with a Summary of each, such as search_messages · 3 found or read_message · body. A summary names the tool and the sections read, never a subject, an address or anything else of the archive's. A save_attachment call lists the file it saved, which you open from there, says Saving while its attachment is still being read out of the archive, or says why it saved none.
Calls per minute caps the calls every agent together makes to the connection in each minute. Once the minute's calls are used up, further calls are refused, and the agent is told the connection is busy and to try again later.
An agent is told There is no file … that you may read
No archive is at that path, or it lies outside the folders the agent may read, or in another project. Check the path on the Workspace tab, and the agent's workspace access
An agent is told an archive is still being indexed
Indexing has not finished. The agent can read it once the archive's row reads Indexed
An agent is told an archive is not an Outlook archive
The file is not a .pst or .ost archive. Upload the archive exported from Outlook
An agent is told an archive could not be indexed
Indexing kept failing. Upload it again as a new version; if that fails too, contact AskRAI
An agent is told This connection does not let you read transport_headers
Let agents read transport headers is off. Turn it on if agents need them
An agent is told There is no message with key …
No message of that archive has that key. An agent finds a message's key with search_messages
An agent is told This connection does not let you save attachments
Let agents save attachments is off. Turn it on if agents need the attachments themselves
An agent is told an attachment was not saved because it has no write access, or because workspace storage is full
Give the agent write access on its Access & Data tab, or free storage on the project's Workspace tab
An agent is told an attachment could not be read out of the archive in the 12 minutes a save is given
The archive, or the folder holding the message, is too large to read. Export the messages the agent needs from Outlook into a smaller archive, upload it, and have the agent find the message there and save its attachment. See Save an attachment
A save_attachment call on the Calls tab still says Saving
Its attachment is waiting for its turn or being read out of the archive, which takes 12 minutes at most, and it is tried again if it fails on our side. If it still says so an hour later, contact AskRAI support
Author reusable agent configurations, version them, grant them to organizations, save an existing agent as one, and review the agents projects suggest
An agent template is a complete agent configuration — its prompt and goals, its model and parameters, its skills, tools, governance, workspace access, knowledge packs, heartbeat and budget — kept once and reused. Admin → Agent templates is where your tenant's templates are written, versioned and granted to organizations. Open it with the Admin control in the top navigation bar, then choose Agent templates under Capabilities.
Agent templates are administered by the holders of Manage agent templates; View agent templates reads every template, its versions and readiness, and the suggestions, read-only. Editing a template's draft changes nothing anyone else sees: only a published version is what the organizations it is granted to will create agents from.
A project's members create agents from the published templates granted to its organization, on the project's Add agent → From template tab.
Each card carries the template's live version, whether its draft is ahead of it, the organizations that may use it, and how many agents were made from it; a platform template is offered to every organization. Tick cards to export them together.
A template is written once for the whole tenant and granted to the organizations that may use it, the way a tool server is. Each organization resolves the template against what it has: its own skills and the platform skills it adopted, the tool servers granted to it, and the governance that applies to it. A template written in one organization can therefore be ready in one organization and partial in another — the Readiness tab shows exactly how.
Choose New template, give it a Name and a Category, and choose Create.
The editor opens on the new draft. Fill in its tabs — Overview, Behavior, Skills & Tools, Guardrails, Heartbeat & Budget and Workspace — and choose Save draft. They are the same forms an agent has, so a template is configured exactly as an agent is.
On the Overview tab, tick the organizations that may use the template under Organizations and choose Save organizations.
Choose Publish, optionally with a change note.
Publish and Duplicate act on the saved draft, so they wait until your edits are saved. A template never published is in no organization's gallery.
An agent that is already configured well is the fastest start. In the agent's pane, choose Save as template. The agent's configuration becomes a new, unpublished draft, granted to the agent's organization, and you can open it in Admin to refine and publish it. The agent itself is not changed.
What carries over is configuration, never the agent's place in its project: its name in the project, who it reports to, its run history and spend stay behind. The workspace folders it may read and write are kept as paths from the workspace root, so the template can be used in any project.
The people with Write access to a project who cannot manage templates themselves can still put one of its well-configured agents forward: Suggest as template in the agent's pane sends its configuration, as it stands at that moment, with a note — see the Team page. Each agent has at most one suggestion waiting at a time.
Everyone who can manage agent templates hears of a new suggestion on the notifications bell, and the Suggestions tab of this page lists them, newest first, with a count of those waiting on the tab. Filter by Pending, Approved, Rejected or Withdrawn, or show All.
Each suggestion says who suggested which agent from which project, whether it would be a new template or a new version, and the note it came with.
Choose Review on a suggestion. It opens in the same editor as a template, with the same tabs: the note it came with, who suggested it and from which project are in its header.
Edit anything you want changed before it is published. Readiness shows what it would apply, with your edits, in the organizations it would be offered to.
Choose Approve & publish, optionally adding a note of your own — or Reject, with a reason the suggester is told.
A review is the template editor over the suggested snapshot: edit any tab, then approve or reject.
Approving publishes it at once, with a change note saying who suggested it and from which agent and project:
As a new template, granted to the organization of the project it came from. Grant it to more on its Overview tab once it is published.
As the next version of a template, when it was suggested as a new version of the template its agent was made from. That template keeps the organizations it is granted to, and its name, role, category, icon, description and tags as members see them, rather than the agent's; change them in the review if you mean to. If its draft held no unpublished changes, the draft moves to the new version too; unpublished work of yours in the draft is left alone. A suggestion whose template was deleted since is published as a new template.
A few things are worth knowing:
The suggestion is a snapshot. The agent may change after it was suggested, and the review says so when it has; what you approve is what was suggested, with your edits. A suggestion whose agent was deleted can still be reviewed.
Suggesting and deciding are separate permissions. Anyone who can manage agent templates can review any suggestion. Its version is marked Suggested, and marked again when its own suggester decided it.
A template belongs to no project, so its Workspace tab names folders by path — Reports/Q3 — rather than picking them from a tree. When an agent is made from the template in a project, each path is looked up there.
The same rules apply as on an agent: write access never reaches beyond read access, and a write scope limited to folders needs a default folder inside it.
The Knowledge card on the Workspace tab attaches knowledge packs to the template, each with a When to search it note, as on an agent. A template belongs to no project, so the picker offers every pack of your tenant. Save as template keeps an agent's packs and their notes.
When an agent is made from the template, each pack applies where the agent's organization is granted it, in the pack's Organizations section. Where the template's own pack is not granted, a granted pack of the same name stands in for it, shown as matched by name. Any other pack is not applied: not granted to this organization, deleted, or not in this tenant. Unlike a missing control, a pack that is not applied never holds the agent at Manual approval: a pack only adds what the agent can look up.
The Readiness tab resolves the saved draft against every organization the template is granted to, one card each, marked Ready or with how many items would not be applied. Every reference the template makes comes out as one of:
The same template is ready in the organization it was written in, and partial in one its tool server is not granted to.
Outcome
Meaning
Applied
The exact skill, tool server, control, knowledge pack or model the template names is available here.
Matched
The exact one is not, but an equivalent is: a skill or knowledge pack of the same name, a tool server with the same identifier, or the platform's own copy of a platform control. Shown with what it was matched by.
Not applied
Nothing here can stand in for it. The reason is shown: not granted to this organization, not adopted, unpublished, a draft, inactive, deleted, or not in this tenant.
A few rules are worth knowing:
A control is never matched by name. A guardrail, policy or egress allowlist applies only as the exact control the template names. A same-named control elsewhere may be weaker.
A missing control holds the agent at Manual. When a guardrail, policy or egress allowlist does not apply in an organization, an agent made there starts at Manual approval, whatever the template's autonomy, and Readiness says so.
A tool narrowed to some of its tools stays narrowed. When none of the tools a grant names are approved in an organization, the grant is left out entirely rather than widened to the whole server.
A model that does not apply is not a gap. An agent cannot run without one, so whoever creates the agent picks one of your models instead.
A skill shows the version it was authored on and the version an agent made now would run, when the two differ.
Beside an item that is not applied, someone who manages it sees how to fix it: Grant to the organization for a tool server, or for a knowledge pack to someone who manages users and access, Adopt for a platform skill, Activate for a draft guardrail, policy or allowlist. The project's From template tab shows the same fixes.
Publishing never waits on readiness: a template can be published while it is partial somewhere. The publish dialog lists what would not apply in each granted organization, so you can fix it first if you meant to.
Templates are versioned the way skills are. The draft is yours to edit; Publish turns it into an immutable, numbered version and makes that version the live one. The Versions tab lists every version, newest first, with its change note and author, and marks the live one Live.
To undo a publish, choose Roll back on an older version and confirm. Rollback never rewrites history: it publishes that version's content again as a new version — rolling back to v1 from v2 makes v3, with v1's content. Your draft is left as it was, and the editor shows Draft · unpublished changes whenever the draft differs from the live version.
Rolling back to v1 published v3 with v1's content; v1 and v2 stay in the history, each with the agents made from it.
Agents already made from a template are copies: publishing a new version, or rolling one back, never changes them. Each one's pane says a newer version is available and what it changed, and lets its project apply what the agent was made without once it applies there. See An agent made from a template.
Each card in the library says how many agents were made from the template, in every project of every organization. The Versions tab lists, under each version, the agents made from it, with their project and how many of that version's items each has not applied yet. Choose an agent's name to open its pane on its project's Team tab.
Tick the templates you want on their cards and choose Export selected. The download, askrai-agent-templates-<date>.zip, holds each template's published version, never its draft or its history, and the definitions of what it names that your tenant wrote for itself:
each organization skill it uses, as its SKILL.md, at the version the template was authored against;
each guardrail, policy and egress allowlist of your tenant it uses, with the guardrails and allowlist a policy names.
Each definition is in the file once, however many templates name it. A platform template, platform skill or platform control is named by reference only, since every tenant has its own. A template that has never been published cannot be exported, and the export names it.
No tool server, hosted tool source, model provider or credential. A tool server is named by its identifier and a model by its provider type and name: the tenant importing the file connects its own.
No knowledge pack's content. A pack is named by its name, with its note, and applies in the tenant importing the file only as a pack of its own of that name.
No version history, no agents, and nothing of a project.
Each file in a bundle carries a checksum, which catches a damaged file but not a forged one: bundles are not signed, so import only files you trust.
Choose Import, pick the zip as the Bundle file, and choose the Organization to import into. Organization skills the bundle carries are created there, and new templates are granted to it.
Review the preview. Each template is imported as a New template, as a New version of the template of yours it was exported from, or you Skip it. Each definition the bundle carries is one you Create, map to one of yours with Use existing, or Skip. Each template shows what it would apply in the organization once imported, and each definition what it would arrive without here: an LLM judge's model you do not offer, or a tool server a policy's approval clause names that you have not connected.
Choose Import. The dialog says how many templates it imported, and lists any it refused with the reason, until you choose Done.
Each template's preview shows what would not apply once imported: here the guardrail the bundle carries arrives as a draft, so an agent made from either template starts at Manual.
A definition arrives only with a template that arrives: skip every template that names it, and it is not created.
Use existing is only ever your choice. A guardrail, policy or allowlist of yours with the same name is offered, never picked for you: a control with the same name may be weaker.
Templates arrive as unpublished drafts. A new template's first publish is pre-filled with the change note Imported from and the file's name.
Skills arrive unpublished, and must pass the safety scan to be published like any other. One the scan flags can never be published as it stands.
Guardrails, policies and egress allowlists arrive as drafts, which govern nothing. An LLM judge whose model your tenant does not offer arrives without one.
Until each is published or activated, a template naming it shows it as not applied on Readiness, and an agent made from it starts at Manual approval.
A new version replaces a template's draft only when that draft has no unpublished changes. A template never published counts as all unpublished changes. Otherwise the template is refused with the reason, and its live version never changes.
What an imported template names by name or identifier alone, such as a skill, a platform control, a tool server, a model or a knowledge pack, is listed on its tab as held by its name, identifier or catalog key. It stays in the template through every save until you remove it, or pick your own in its place. A guardrail, policy or egress allowlist you skipped in the import is listed as Not in this tenant instead. Picking your own guardrail or policy does not replace a skipped one: it stays until you remove it, and until then an agent made from the template starts at Manual approval. Picking your own allowlist does replace a skipped one.
A bundle is at most 5 MiB, 500 files and 50 templates.
Every tenant has five platform templates, built only from what every tenant has: Document Analyst, Data Analyst, Code Reviewer, Support Triage and Corporate Writer. Each names the platform skills it needs and the safety preamble skill, and is governed by Baseline safety. None names a tool or a model: whoever creates an agent from one picks the model. Each starts at Manual approval with its heartbeat off and access to the whole workspace. Every organization is offered them; a platform skill an organization has not adopted shows as not adopted, with Adopt for someone who manages skills.
Platform templates are read-only: open one to read it, or choose Duplicate & edit to make a copy of your own, which starts unpublished. Any template can be duplicated the same way, and a tenant template can be deleted.
Policies
Bundle guardrails with the ceilings an agent runs under — autonomy, actions per beat, tool calls per beat and approval requirements — and attach the result to an agent, or to a group to guard its members' queries
A policy bundles the guardrails it carries with the ceilings it sets. Attached to an agent, all of it governs that agent's beats. Attached to a group, its guardrails on questions and answers govern the queries of the group's members, and its ceilings do not — see A policy on a group. Admin → Policies is where policies are written. Open it with the Admin control in the top navigation bar, then choose Policies under Governance in the Admin sidebar.
Policies, Guardrails and Egress Allowlists are one plane: View policies, guardrails and egress opens all three read-only, and Manage policies, guardrails and egress changes them. Platform Admin holds both. Manage is also required to attach governance to an agent or a group, even though attaching happens on the Team pane or the group — without that rule, anyone with Write access to a project could strip every control off its agents.
Each row summarises what the policy actually constrains, rather than leaving it to be inferred.
This is the single most important property of the model. A policy never grants anything. Every clause is an upper bound, and composing two policies takes the tighter of each:
Numeric ceilings take the minimum.
Autonomy can only move an agent down the list.
Approval requirements are unioned — if either policy requires approval, approval is required.
A host must be admitted by every egress allowlist in force.
Guardrails are added together.
Attaching a second policy can therefore only narrow what an agent may do, never widen it. That is what makes it safe to hand an agent a broad policy and a narrow one at the same time.
Any number of guardrails, up to 100. Every guardrail a policy carries is added to whatever else governs the subject.
Only Active guardrails take part. A draft can be listed in a policy and attached with it, and it checks nothing — the picker shows each guardrail's status badge so you can see that before you save.
At most one, or None. It names the hosts the agent's tools are allowed to reach. Because a host must be admitted by every allowlist in force, adding one to a second policy can only narrow the reach.
A Link domain guardrail has no hosts of its own and reads whatever allowlist is in force, so a policy that carries one must name an allowlist as well. Saving an Active policy that carries a Link domain guardrail and names none is refused — without an allowlist to compare against, that guardrail cannot be evaluated at all.
How much a beat may do on its own — Manual or Full.
Actions per beat
How many actions one beat may take. 1 to 20.
Tool calls per beat
How many tool calls one beat may make. 1 to 20.
Require approval for
Read-only tools, Tools that change something, or both.
Every ceiling bounds an agent's beat, so it governs only the agents the policy is attached to — never the members of a group that carries it.
Leave a ceiling blank and this policy sets none there. Blank is not zero — zero is a value the server refuses, and it would read like the tightest possible setting rather than the refusal it is.
There is no separate approval control on an agent. An approval requirement is a policy clause, so it is something a policy brings rather than a fourth thing to attach.
A policy is Draft or Active. Only an Active policy is in force; a draft can be attached and listed and governs nothing. The page states the count under the list when any policy on it is still a draft.
Select New policy, or, from anywhere on the Admin plane, Create → Policy at the right of the top header. The editor opens as a sheet on the right. The Create menu shows this entry only to holders of Manage policies, guardrails and egress.
Give it a Name and a Description. Name it after the population it governs — "Customer-facing agents" — rather than after the controls inside it, which will change.
Choose the Guardrails it carries. The picker is searchable and shows each guardrail's kind and status.
Choose an Egress allowlist, or leave it on None.
Set the Ceilings you want to impose, and leave the rest blank.
Each ceiling is an upper bound; where two policies both set one, the tighter wins.
Writing a policy governs nothing on its own. Attach it to a subject, and which subject you choose decides which traffic it governs:
An agent — open the agent on the project's Team pane and use its Guardrails tab. Everything the policy carries governs that agent's beats.
A group — attach it to a native group on the Users page. Part of the policy governs the queries of the people in that group, from the console, a channel, the API, the CLI or MCP; a caller's groups are resolved on every query and narrowed together into one effective set. The next section says which part.
A subject may carry up to 25 policies, plus guardrails and an allowlist attached directly. The agent's Guardrails tab shows an In force panel that asks the server what the current selection actually composes to, and re-asks it on every change. That panel is the only place the whole narrowing is visible before a beat runs — including narrowing you did not intend. The agent's Heartbeat tab says it too, beside each setting a ceiling holds lower.
Saving the Guardrails tab writes only what you changed: the policies, the guardrails, or the allowlist. A policy, guardrail or allowlist another admin attached while your tab was open stays attached. If you both changed the same list, the later save wins that list.
Detaching governance is a widening, and nothing about an empty selection is invalid, so it validates clean. Attachment is gated on the governance permission for exactly that reason: without it, stripping every control off an agent would be an ordinary edit.
A query asks a question and returns an answer; it calls no tool and runs no beat. So when a policy is attached to a group, only the parts of it that act on a question or an answer govern the group's members:
Part of the policy
On a group member's query
Status
Applies. An Active policy is in force; a Draft one governs nothing.
Input and Output guardrails
Apply, alongside the group's own guardrails.
Egress allowlist
Applies only as the list a Link domain guardrail compares the answer's links against.
Maximum autonomy, Actions per beat, Tool calls per beat
Do not apply. They bound an agent's beat.
Require approval for
Does not apply. It holds an agent's tool calls for approval.
Tool call guardrails
Do not apply. They inspect what an agent sends to a tool.
The parts that do not apply on a query do not reach an agent either: an agent's beats are governed by the policies attached to that agent, never by those on a group. To bound what an agent may do, attach the policy to the agent.
Every tenant is seeded with Baseline safety, a platform policy bundling the shipped deterministic controls: no credential leakage, masked contact details, blocked identifiers and denied words. It carries a Platform badge. The Add agent panel ticks it for every new agent, for someone with the governance permission.
A platform policy is inspectable but not editable — write your own alongside it.
Platform policies are read-only: the server refuses an edit or a delete. Unlike a guardrail, a policy has no duplicate action, so the editor says plainly that it cannot be changed rather than offering a Save that would fail. Write your own alongside it — composing a second policy can only narrow what an agent may do, so adding one never weakens the baseline.
Seeding a tenant changes no traffic. A policy governs a turn only once something attaches it.
Delete is on the left of the editor footer. Before you can confirm, the dialog reads how many agents and groups attach the policy and states the count, because that number is the whole question — deleting a policy nothing uses is housekeeping, and deleting one that governs a live team is not. If that lookup fails, the dialog says so rather than showing a reassuring zero.
Deleting is permanent, and the policy stops governing everything it is attached to.
A policy with no guardrails and no ceiling is legal, and the list flags it: "This policy carries no guardrails and sets no ceiling — attaching it changes nothing." It is worth writing one deliberately as a placeholder, but it is more often a policy someone emptied without noticing.
Author the checks that inspect what reaches an agent, what it says, and what it sends to a tool — their kind, stage, action, and whether they are in force
A guardrail is one check: what it reads, what it does about a violation, and whether it is in force at all. Admin → Guardrails is where guardrails are defined. Open it with the Admin control in the top navigation bar, then choose Guardrails under Governance in the Admin sidebar.
Guardrails, Policies and Egress Allowlists are one plane: View policies, guardrails and egress opens all three read-only, and Manage policies, guardrails and egress changes them, tests a guardrail and attaches governance to an agent or a group. Platform Admin holds both, and a Member sees none of the three. Grant either through a role on the Access page.
Each row carries the guardrail's status, its kind, the stage it runs at, and what it does about a violation.
The kind decides how the check is performed, and which configuration fields the form offers you.
Kind
What it does
PII
Finds personal identifiers — email, phone, US Social Security number, payment card, IBAN.
Regex deny
Refuses anything matching your patterns.
Word deny
Refuses specific terms.
Secret scan
Finds API keys, tokens and private keys.
Link domain
Refuses a link unless every egress allowlist in force admits its host.
LLM judge
Asks a model your prompt about the payload.
The five deterministic kinds cost no model call. LLM judge is the only kind that reaches a provider, which is why it is the only one that needs a model and a prompt.
What reaches the agent — the user's question, or another agent's message.
Output
What the agent is about to say or record.
Tool call
The arguments the agent is about to send to a tool.
Stage matters more than it looks. A guardrail named "mask contact details" that only ever reads the question fires on nothing and reports compliance — the shape this plane exists to remove. If the rule is about the answer, set the stage to Output.
Redact is offered only for the kinds that can return the spans to substitute — PII, Regex deny, Word deny and Secret scan. Link domain and LLM judge return a verdict, not spans, so the form hides Redact when one of those is selected, and steps a chosen Redact back to Block.
A guardrail is Draft or Active. Only an Active guardrail is evaluated: a draft can be authored, listed and attached to an agent while checking nothing. That is deliberate — it is how you stage a control before it governs anyone — but it also means a plane full of drafts reports coverage it does not have. The page states the count above the list when any guardrail on it is still a draft.
Select New guardrail. The editor opens as a sheet on the right.
Give it a Name and a Description. The name is how the guardrail is identified in the guardrail analytics and in this list, so name it after the rule rather than the mechanism.
Choose the Kind, then the Stage and the Action. Each control shows a one-line explanation of the current choice beneath it.
Fill in the configuration the kind needs — the form offers only the fields that kind actually reads.
Choosing PII replaces the configuration area with the entity checkboxes; choosing another kind replaces it again.
Leave Status on Active and select Create guardrail.
Switching kind mid-edit clears the fields the new kind does not read. The server refuses a field its kind does not use, so the form drops them rather than letting you submit a request that would be rejected for naming a control the form has stopped showing.
Entities to look for — any of Email address, Phone number, US Social Security number, Payment card, IBAN. An active PII guardrail needs at least one. Plus Replacement, when the action is Redact.
Regex deny
Patterns — Python regular expressions, at most 25, each at most 200 characters. Plus Replacement, when the action is Redact.
Word deny
Words — at most 500, each at most 100 characters. Match case exactly. Where a word may appear. Plus Replacement, when the action is Redact.
Secret scan
Replacement, when the action is Redact. Nothing else — the detectors are built in.
Link domain
None. It compares links against the egress allowlists in force on whatever it is attached to.
LLM judge
Judge model — a chat model or a decision model your tenant has connected — and Prompt. With a decision model, also Acts at, Review model and Review from (below).
Where a word may appear has two settings, and neither is free:
Whole words only (the default) does not match inflections. A list containing refund does not catch refunds or refunding. Add the forms you mean.
Anywhere inside a word catches inflections, and also matches inside unrelated words — a list containing class then refuses an answer that mentions classical or classify. Profanity lists are where this bites hardest, because so many short offensive words are substrings of ordinary ones.
Which error is cheaper depends on your own vocabulary.
Patterns are Python regular expressions, so Python's syntax works, such as (?i) for case-insensitive matching and (?P<name>…) for a named group. They are checked when you save: a pattern that does not compile, or that repeats a group without a bound (the shape that can stall a turn on a crafted input), is refused on the Patterns field with a reason naming the pattern, and nothing is saved: (?:all |any |your )* will not save.
A counted repeat is written out in full when a pattern runs, so x{2000000}, ten characters long, would build two million elements. A pattern may build at most 1,000. A repeat counts one for itself, and its body once more than it must repeat at the least, so x{998} builds exactly 1,000. Nested counts multiply, and repeats side by side add up. Under full case folding ((?fi)), a wide character class counts as the many strings it folds into. [A-Z0-9]{10,30} builds a few dozen, and x{1000}y{1000} will not save. Lower the count, or use + or *. The same check applies when you Test a guardrail or Duplicate & edit one.
A Link domain guardrail carries no hosts of its own. Attach it to a subject that also carries an egress allowlist. With no allowlist in force it cannot be evaluated at all, and it stops the turn under its own name rather than passing quietly.
An LLM judge with no Judge model falls back to your tenant's guardrail routing stage, and only a person's question is routed. An agent's beat is not, so there such a judge cannot be evaluated: every beat stops, or, at the Tool call stage, every tool call is refused. It therefore cannot be attached to an agent, directly on the agent's Guardrails tab or through a policy the agent carries. Adding one to a policy an agent carries, or leaving a guardrail an agent carries as a judge with no Judge model, is refused the same way, naming the agents. Choose a Judge model first.
An agent that already carries one keeps it, and the history of each of its runs names the guardrail. Choose that guardrail a Judge model here, or detach it from the agent.
A Judge model can be a decision model, such as TypeSafe's Jev. It writes no verdict or reasoning. It answers how likely it is that the payload breaks your Prompt, as a probability from 0 to 1, and that probability decides:
At or above Acts at (0.7 unless you set it), the guardrail acts: it blocks or warns.
From Review from up to Acts at (Review from is 0.3 unless you set it), the Review model judges the payload as a chat judge would, and its verdict decides. This band exists only when you choose a Review model.
Below that, the guardrail passes. Without a Review model, everything below Acts at passes.
The Review model is one of your chat models. It also judges a decision judge whose model gives no answer, whether from an error, a timeout or a payload too long for it. Without a Review model, or when it fails as well, the guardrail cannot be evaluated and stops the turn under its own name, as any judge does.
Every decision judge of one stage that names the same model is asked in one request, which keeps the check fast. A decision model answers each rule separately, so batching changes no answer.
Text written to steer a decision model can move its answer. A decision judge is not a defence against an attacker. For a judge that blocks, choose a Review model, so an uncertain answer is judged a second time by a chat model.
What a decision judge reads is processed under your own agreement with TypeSafe. The audit record of each verdict names the probability, the Acts at it was measured against, the versioned model that answered and, when one decided, the Review model. In an agent's run history, a decision judge that fired names its probability and model. Its calls in a beat are charged to the project's budget at the model's own rates.
Every row has a flask icon, and the editor has a Test button. Both open a drawer that runs a sample payload through that one guardrail exactly as a live turn would. The definition travels by value, so you can test a draft you have not saved yet.
The drawer reports the verdict, why it fired, and what the agent would actually see.
The result has three parts:
The verdict — Allowed or Blocked, the action taken, and how many spans were redacted.
Why — every span the detector matched, and every near miss: a candidate that had the right shape and failed the check behind it, such as a card-shaped number that fails its checksum. This is the only place that answers "I pasted something that looks like a card number and it says Allowed".
What the agent would see — the payload after redaction, the note that nothing changed, or the statement that the turn is refused.
For a judge on a decision model, Why also shows the probability, the thresholds, and which band decided: acted, passed, or handed to the Review model.
Nothing in the test drawer is stored or audited. The excerpts are sliced out of the sample you typed, and they locate exactly the content a Redact guardrail exists to keep out of the audit trail.
If the guardrail cannot be evaluated at all, the drawer says Could not be evaluated rather than reporting a pass. An unevaluable control is not a clean payload, and a live turn stops there too.
Every tenant is seeded with a catalog of platform guardrails, marked with a Platform badge. They are read-only here: the server refuses an edit or a delete, so the editor shows the fields for inspection and offers no Save.
A platform guardrail is inspectable but not editable — Duplicate & edit is how you change one.
To change a platform guardrail, select Duplicate & edit. The server clones it as an editable tenant copy, and the editor stays open on the copy. The copy is created as a Draft, so review it and set it Active to put it in force.
Seeding a tenant changes no traffic on its own. A platform guardrail governs a turn only once something attaches it — directly, or through a policy.
The list shows ten guardrails per page. The search box searches the whole tenant on the server, not just the page you are looking at, so a guardrail on page three is reachable by name. Use the pagination control beneath the list to move between pages.
Select any row to open it. Change what you need and select Save changes; the editor warns you before discarding unsaved edits.
Delete is on the left of the editor footer and asks for confirmation. Deleting is permanent, and the confirmation states the consequence plainly: the guardrail stops governing every agent and group it is attached to.
The editor checks a definition before the round trip and names the reason, rather than surfacing an error you have to re-read the form to interpret. Most of these are also refused by the server; the judge-model rule is the editor's own.
Refusal
Why
A non-judge guardrail with a prompt
Only LLM judge reads a prompt. Leave it empty, or change the kind.
Redact on Link domain or LLM judge
Those kinds return a verdict, not the spans to replace.
An active LLM judge with no prompt
The prompt is the whole of what the model is asked.
An active LLM judge with no Judge model
Choose one. The server would accept the row and fall back to your tenant's guardrail routing stage on a person's question, but no agent could carry it (why), and the editor asks you to be explicit. Connect a provider first on Model Providers if the list is empty.
An active PII guardrail with no entity
There is nothing for it to look for.
An active Regex deny or Word deny with an empty list
There is nothing for it to match.
A blank entry in a pattern or word list
A blank entry matches everything.
Acts at, Review model or Review from on a judge whose model is not a decision model
They decide nothing there. Changing the Judge model to a chat model clears them.
Acts at outside 0 to 1, or 0
A judge that acts at 0 acts on everything.
Review from above Acts at, or without a Review model
There would be no band for a Review model to judge.
An active judge whose Review model your tenant cannot reach
It would fail on the first uncertain answer.
An incomplete definition cannot be tested whatever its status: the Test button checks the definition as though it were Active, because a test of a control that could not run answers nothing. A draft may still be saved incomplete — that is what a draft is for.
A guardrail written before this plane existed carries none of these fields, so it keeps the original behaviour: an LLM judge running at the Input stage that Blocks, and is Active. Those rows appear in this list alongside the rest and can be opened and given a kind, a stage and an action like any other — with one extra step, because an active judge carries no Judge model either: choose one before Save changes will enable. Until it has one it cannot be attached to an agent, and an agent that already carries it cannot evaluate it on any beat (why).
Write down the hosts an agent's tools may be dialled at, check a host against the list before saving, and attach the result to an agent or a policy
An egress allowlist is the set of hosts an agent's granted tools are allowed to reach. Admin → Egress Allowlists is where allowlists are written; attaching one to an agent or a policy is what puts it in force. Open it with the Admin control in the top navigation bar, then choose Egress Allowlists under Governance.
Egress Allowlists, Policies and Guardrails are one plane: View policies, guardrails and egress opens all three read-only, and Manage policies, guardrails and egress changes them. Platform Admin holds both. Manage is also required to attach an allowlist, even though attaching happens on the Team pane.
A new tenant has none. The platform ships no allowlist, so every list on this page is one somebody in your tenant wrote.
This is the property everything else follows from. An allowlist cannot grant an agent reach it would not otherwise have — every outbound request already passes AskRAI's own network protections, and the allowlist is applied after them. What an allowlist does is take the "any public host" those protections leave and cut it down to the hosts you wrote down.
Because of that, composing is a conjunction: a host must be admitted by every allowlist in force. Attaching a second one can only narrow the reach, never widen it — which is what makes it safe to give an agent a broad allowlist and a narrow one at the same time.
An agent with no allowlist in force is not blocked. It may reach any public host AskRAI's own network protections permit.
A host is a hostname and nothing else. The form refuses an entry the server would refuse, so what you can type is what will be stored:
Entry
Accepted
api.example.com
Yes — an exact host.
*.example.com
Yes — admits api.example.com and files.example.com, but notexample.com itself.
https://api.example.com
No. Enter the host only — no scheme.
api.example.com:8443
No. A host carries no port.
api.example.com/v1
No. A host carries no path.
*
No. A bare * admits everything, which is the absence of an allowlist.
api.*.com
No. A wildcard is only allowed as a leading *..
API.Example.com
Yes — listed as api.example.com. Hosts are matched without regard to case, so a second spelling of a listed host is refused as already in the list.
münchen.de
Yes — listed as xn--mnchen-3ya.de, its punycode form. It admits a server at either https://münchen.de or https://xn--mnchen-3ya.de.
straße.de
No. Enter it in its xn-- form: a host holding ß, ς or a zero-width joiner is read as a different host by different clients.
A wildcard's dot is part of the suffix on purpose: *.acme.com matches api.acme.com and does not match evilacme.com, so a neighbouring registration cannot slip in. A list holds at most 100 hosts, and each is at most 253 characters.
A hosted tool server has no URL, so an allowlist admits it by its pseudo-host, <slug>.hosted.invalid, or admits every hosted server with *.hosted.invalid. The .invalid ending is reserved and never names a real host. A hosted server with internet access is admitted only when every allowlist in force names it, and the warning on an agent's Skills & Tools tab names the host to add. A hosted server with no network access is admitted under every allowlist and needs no entry.
Such an entry is labelled downstream traffic unrestricted, on the allowlist's row and in its editor. Admitting the server lets an agent's calls reach it, and the server's own code then reaches the internet without this allowlist restricting where that traffic goes.
The Check hosts against this list box takes one or more hosts, separated by spaces or commas, and asks the server which of them the current list would refuse. It reads the hosts as they are typed in the editor, so you can test a list you have not saved yet.
A clean answer reads "Every host you listed is admitted." Anything else is named: "Refused: pastebin.com".
An allowlist is Draft or Active, and only an Active one is in force. A draft constrains nothing — the same position as an agent with no allowlist at all.
An Active allowlist must have at least one host. An empty one would admit nothing and refuse every outbound tool call, so the server refuses to store that combination and Create allowlist stays disabled until you add a host or move the list back to Draft.
Each row shows up to six hosts inline; a longer list collapses the remainder into a +N.
An allowlist governs nothing until something attaches it. There are two ways, and they compose:
An agent — open the agent on the project's Team pane and use its Guardrails tab. The Egress allowlist card holds one allowlist, or None.
A policy — a policy carries at most one allowlist, and attaching that policy to an agent or a group brings the allowlist with it. This is the only way a group gets one: a group has no egress allowlist of its own. A group member's query calls no tool, so on a group the allowlist does one thing — it is the list a Link domain guardrail compares the answer's links against.
The In force panel asks the server what the current selection actually composes to, and re-asks on every change.
When an agent tries to call a granted tool on a server whose host any allowlist in force leaves out, the call is not made. A server that signs in with OAuth client credentials names where it signs in — its metadata, its authorization server and its token endpoint — and each of those hosts is held to the same allowlists before anything is sent there, so the client secret never reaches a host that any allowlist in force leaves out. The agent is told "The egress allowlist in force does not admit a host that call needs, the server's own or one it signs in at, so the call was not made. Do not retry it — say what you needed from it, or take a step that reaches somewhere you are allowed." The message names neither the host nor the URL, because the path of a tool call routinely carries arguments the model wrote. The refusal is recorded as an audit event, so a beat that lost a tool call this way is visible afterwards rather than only in the transcript.
A refused call costs no action slot and no tool-call budget. A server that asks for a sign-in only after it has accepted the connection can have the refusal counted instead as a failed call that may have run.
An allowlist constrains the tool server itself — its URL, or a hosted server's pseudo-host — and the sign-in hosts it names, and nothing else on the outbound path. It does not reach whatever that server dials downstream of your call, a hosted server's own code included, or your model providers' endpoints — those are covered by AskRAI's own network protections alone.
A Link domainguardrail carries no hosts of its own: it compares links in content against whatever allowlist is in force. With none, it cannot be evaluated, and it fails closed — stopping every turn under its own name.
Two guards cover the common ways in, but neither is complete — check the In force panel after any change:
An Active policy that carries a Link domain guardrail and names no allowlist is refused when you save it. A policy naming an allowlist that is a draft, or that has no hosts, is not refused, and neither is in force at runtime.
Deleting an allowlist, moving it to Draft, or emptying its hosts is refused when doing so would leave an agent or a group holding a Link domain guardrail directly with nothing to compare against. The message names those subjects rather than counting them.
That second guard does not look through policies. It reads only the guardrails attached directly to an agent or group, so an allowlist reachable only through a policy's Link domain guardrail can be deleted without warning — and every turn that guardrail governs then stops, because a Link domain check with no allowlist cannot be evaluated and fails closed. Groups are the exposed case: a group can only receive an allowlist through a policy. Before deleting an allowlist, check which policies name it.
Open an allowlist by clicking its row. Editing hosts on a list already in force takes effect on the next beat — there is nothing to redeploy, and the change is in force within five minutes at the outside.
Delete is on the left of the sheet footer. Before you can confirm, the dialog reads how many agents and policies name the allowlist and states the count; if that lookup fails it says so rather than showing a reassuring zero. Deleting detaches the allowlist from every policy and agent naming it, which widens what those agents can reach, and cannot be undone.
Deleting an allowlist is a widening, so it is not refused merely for being in use — otherwise you could not remove a list you no longer trust without hunting down every reference first. The one case it is refused is the Link domain dependency above, where removing it would stop an agent entirely.
An allowlist the platform ships would be read-only — the sheet says so and offers no Save. No platform allowlist ships today, so every row on this page is one your tenant can edit.
The name is empty, nothing has changed yet, or the status is Active with no hosts.
A tool call is refused and the host looks right
*.example.com does not admit example.com itself. Add the bare host as a second entry.
A tool call is refused though an allowlist names that host
A host must be admitted by every allowlist in force — the agent's own and every one its policies carry. Read the In force panel on the agent's Guardrails tab.
A tool on an OAuth server is refused though the server's host is admitted
The server signs in somewhere else. Add every host its sign-in goes through: where its OAuth metadata is served, its authorization server and its token endpoint.
Deleting or deactivating an allowlist is refused
An agent or group would be left holding a Link domain guardrail directly with no allowlist. The message names them; detach that guardrail or give them another active allowlist first.
Every turn suddenly stops on a Link domain guardrail
An allowlist that guardrail reached through a policy was deleted or drafted — the refusal above does not see policies. Re-point the policy at an active allowlist with hosts.
An agent still reaches a host after you removed it
Only Active allowlists are in force. Check that the list you edited is not a draft, and that no second allowlist is attached higher up.
Saving a policy is refused, mentioning url_domain
The policy is Active and carries a Link domain guardrail with no allowlist named. Add one to the policy.
A Link domain guardrail cannot be ticked on an agent's Guardrails tab or in Add agent
No allowlist is in force for the agent yet: choose an Active one with hosts under Egress allowlist, or tick an Active policy that carries one.
See who changed anything in Admin, from people and access to models, capabilities, governance and organizations, when, and what changed
The Change Log is your tenant's record of what was changed in Admin: who made each change, when, and what it changed. Open it with the Admin control in the top navigation bar, then choose Change Log under Platform.
The Change Log is read by the holders of View change log: Platform Admins, Auditors, and anyone holding a role built with it on Access. It changes nothing itself: reading it is all it offers. An Auditor sees Admin with only the Change Log in it, and can open no other Admin page or change anything there.
Each edit lists the settings it changed, old value to new.
These changes in Admin each appear as one entry, once the change has been saved. Each entry is filed under an Area of Admin, listed here in the order the Admin sidebar shows them.
Users: a person's status changed; a group created, edited or deleted, people added to it or removed from it, or its roles, knowledge packs, guardrails or automatic assignment rules changed; a role created, edited or deleted.
Access: a role built on Access created, edited or deleted; a role assigned to a person or a group, or an assignment removed. Also an organization or a project shared with a person, a group or everyone in the tenant from its Share dialog, the level of a grant changed, or a grant removed: granted Write on project 'Onboarding Automation' to user 'Nadia Rahman'.
Directory Sync: SCIM provisioning switched on or off, and its token generated, rotated or revoked; a group linked to a directory group or unlinked from one, on the group's Directory tab in Users; Google Workspace sync configured, disconnected, switched on or off, or a sync started with Sync now. A Test connection records nothing.
Programmable Access: an API credential created, edited, rotated, revoked or deleted; an interface switched on or off, or the tenant rate limits changed.
Skills: a skill created, edited, published, rolled back or deleted; its agents moved onto the published version with Force update; a platform skill adopted into the organization or removed from it.
Tools: a tool server connected, edited, synced or deleted (a sync says how many tools it added, changed or removed, and any change to the server's status); its tools approved, switched on or off, or marked read-only or side-effecting; the server granted to an organization or withdrawn from one. For a hosted tool server, also its source saved, a release published, approved or reverted, and a secret set or removed.
Agent templates: a template created, whether new, from an agent, by import or as a copy; one edited, published, rolled back or deleted; a template granted to an organization or withdrawn from one; a suggested template approved or rejected.
When the change was made. Hover the time to see the exact date and time.
Who made it, by the name and email their sign-in carried at the time, so an entry still names someone who has since left your directory. A change made by AskRAI support while helping your tenant is marked RAI staff.
What was changed, named as it was then: deleted guardrail 'PII filter', withdrew tool server 'GitHub' from organization 'Acme'. Something whose name could not be read is named by its kind, as a guardrail not found.
For an edit, each setting it changed, with its old and new value where both are short, such as status: draft → active. A role's permissions, and a choice such as a guardrail's kind, read as their editor names them: permissions: View users & groups → View users & groups, View routing. A longer value, such as a guardrail's prompt or a routing rule, is named without its contents, and so is an address such as a tool server's URL, which can carry a key. A secret is never shown, whether a credential, a token or a hosted tool server's secret: a new key reads as credentials changed.
An edit that changed nothing, and a change that was refused, leave no entry. Switching a tool on or off is recorded as it was set, even when it already was.
Entries are listed newest first. Choose an Area to see only the changes made there; the page remembers the area in its link, so you can share a filtered view with another Platform Admin or an Auditor.
Entries are kept with no expiry.
Guides
Task-ordered routes through the documentation — from connecting your first model to running a team of agents in production
Every procedure in this documentation lives on the page for the screen it belongs to. This page puts those procedures in the order you are likely to need them, so you can work through a task without knowing which screen owns it.
Route that model to each pipeline stage — summarization, query refinement, guardrail judging and confidence scoring can each use a different model. Nothing takes effect until you publish.
Grant Platform Admin to the small group who configure the tenant, and Auditor to anyone who reviews their changes without making any. Everyone else is a Member, which needs no assignment, and sees only the organizations and projects shared with them: until something is, they see none.
Issue a credential for the API or the MCP server. The secret is shown once.
Share the project at Write with the people who should work in it and approve its agents' proposals, and at Read with those who should only follow it — as its creator, you are its Admin, and nobody else sees it until you share it. Then add people and agents to the team, and set each agent's reporting line so the org chart and manager oversight are right. Only people with Write access or above can join the team.
Set each agent's cadence and autonomy — how often it acts, and how much it may do without you. Autonomy needs Admin access to the project, a level above the Write that approval needs. Review an agent's name, goals, prompt, model parameters, skills and tools before raising its autonomy above Manual approval: anyone with Write access to the project may have changed them.
Connect an AI agent to AskRAI's hosted MCP server with a credential of Channel MCP, so it can ask governed questions of your knowledge base
AskRAI hosts an MCP server that lets an AI agent, such as Claude, Copilot, Cursor or one you built, ask governed questions of your knowledge base. Every question an agent asks is answered from the knowledge packs and guardrails of the credential it connects with, counted against your rate limits, and recorded in your conversation logs like any other.
The server signs an agent in with its API key alone and offers no OAuth sign-in, so the agent's client must let you set a request header for a remote MCP server.
Open Admin → Programmable Access and turn on MCP in the Interfaces panel. While it is off, every credential with Channel MCP is refused, however it is configured, so turning it off is also how you disconnect every agent at once.
Create a credential with Channel MCP
Click Create Credential and fill in the form as Creating a credential describes, with these choices:
Channel: MCP. The MCP server admits no other Channel: a key created with Channel API is refused with This key is for the API channel; create a key with Channel MCP., a CLI one is told the same, naming CLI, and an A2A one is refused with An A2A key calls only the A2A endpoint of an agent that lists it.
Group: the group whose knowledge packs and guardrails the agent should answer from. With None, no group's knowledge packs or guardrails apply to the agent's questions.
Credential TypeAgent Credential and Caller TypeAgent, so the agent's questions are labelled as an agent's in the conversation logs and on the dashboard.
IP Allowlist: leave it empty. The address it is checked against is the one the MCP server reaches AskRAI from, not the agent's, so an allowlist of the agent's addresses refuses every request.
Click Create and copy the key: it is shown only once.
Add the server to the agent's client
Give the client the server URL and the key as a Bearer token, as the examples below show.
Check the connection
Ask the agent to list its AskRAI tools, then to use askrai_query on a question your knowledge base answers. The question appears in Conversation Logs with Channel MCP.
Other clients name these settings differently: give yours the server URL and an Authorization header holding Bearer and the key.
Anyone holding the key can ask questions as its credential until you revoke it. Keep it in a secret store or an environment variable, and never in a configuration file that is checked into version control.
The MCP server takes each message the agent's client sends to https://mcp.askrai.ai/mcp with a Content-Length header or chunked, as the official C# MCP SDK sends them on .NET 8 and later, up to 121,024 bytes. A longer message fails its tool call: a chunked one is answered 413 as soon as that much of it has arrived, and one whose Content-Length declares more is refused before it reaches the MCP server, with 403 and an HTML page. The public API's query endpoints take bodies the same way: see Request bodies.
Asks a governed question of your knowledge base. Returns the answer with its status, confidence, guardrail results and citations, a thread_id and an audit_ref
prompt (required), thread_id, execution_mode
askrai_chat
Asks a further question in an existing conversation, the one the thread_id of an earlier answer names
prompt and thread_id (both required), execution_mode
askrai_get_audit
Retrieves the audit record of an earlier question asked with the same credential: what was asked and answered, its confidence, and whether a guardrail fired. For up to two minutes after the answer, the record may not be there yet
audit_ref (required)
An answer's status is delivered, blocked or low_confidence. execution_mode is interactive_user or agent_augmentation. Left out, the least-augmenting mode the credential allows applies, and a mode the credential does not allow is refused. agent_augmentation adds an agent_context block beside the answer, with a suggested next action, the reason an answer was blocked, whether it was grounded in your knowledge, and its source type: see Execution Modes.
Each askrai_query and askrai_chat call is one query, held to the credential's and the tenant's rate limits. askrai_get_audit is not counted. A tool call that is refused fails with the reason AskRAI gave, for example API error (429): This credential's budget of 60 requests per minute is spent. It renews in 23 seconds.
A key the server does not admit is refused when the agent connects, with a reason the client may show:
Reason
What to do
AskRAI did not recognise this API key. Check that it was copied whole and has not been revoked or deleted.
Copy the key again, or rotate the credential to issue a new one
This key is for the API channel; create a key with Channel MCP.
Create a credential with Channel MCP
An A2A key calls only the A2A endpoint of an agent that lists it
Create a credential with Channel MCP: a key made for an agent's External access calls nothing else
The MCP interface is turned off for this organization
Turn on MCP in the Interfaces panel. A key of another Channel whose interface is off names that interface instead: create a credential with Channel MCP
This key's group no longer exists, is inactive, or does not list the key, so the key is refused until an administrator restores it.
Reactivate the credential's group or restore the credential to it. Rotating the key puts it back in its group if the group still exists
This key's IP allowlist does not include the address the MCP server reaches AskRAI from.
Create a credential with no IP allowlist
Credential has expired
Create a new credential
Too many API keys from this address were refused. Try again after the time Retry-After gives.
Fix the key the agent sends, then try again after a minute
AskRAI could not check this API key just now. Try again in a minute.
Try again in a minute
Turning MCP off reaches an agent that is already connected: its next tool call is refused, and connecting or listing tools within a minute. A revoked, rotated or deleted key stops working as Viewing credential details describes.
AskRAI is a Responsible AI solution that helps staff and citizens get the information they need quickly and accurately — without stretching budgets or adding complexity. It combines retrieval-augmented generation (RAG) with curated knowledge bases, configurable guardrails, and built-in governance controls.
What can AskRAI do?
AskRAI organizes what your assistant does into the RIESE model — five pillars:
Resolve — Directly answer the user's question with a definitive answer from the knowledge base
Inform — Provide the facts or context a user needs to make a decision
Engage — Hold a multi-turn conversation to clarify needs and guide the user through a process
Support — Give ongoing, step-by-step help with complex workflows that span multiple messages
Escalate — Hand off to a human by opening a support ticket when confidence is too low to answer
AskRAI is built for organizations that need responsible, auditable AI — including municipalities, education and school districts, healthcare and social services, state agencies, public utilities, and financial services.
AskRAI answers from pre-processed, curated data rather than from the model's own training data. Admins ingest and curate that data from FAQs, troubleshooting guides, policy documents, and legacy help desk tickets. Grounding every response in approved sources is the main defence against an invented answer, and every answer is recorded with the question that produced it and the checks that ran.
What is Active AI Guardrail (AAIG)?
AAIG is AskRAI's guardrail technology. A guardrail is configured per tenant and reads one of three payloads: the user's question, the generated answer, or the arguments an agent is about to send to a tool. When it fires it can block the turn, warn and leave a record, or redact what it found and continue. See Guardrails.
Which platforms does AskRAI integrate with?
People reach AskRAI through Microsoft Teams — today that is the only human channel that delivers traffic. For machines, AskRAI exposes a governed public API and an MCP server for AI agents, each authenticated with a credential you issue from Programmable Access. The askraiCLI is not generally available yet.
The channel lists you meet elsewhere in the console — in role mapping rules, conversation filters and the Sandbox — carry more values than that, including Web Chat and Mobile App. They are the vocabulary the platform records and filters on; an embeddable web chat widget is planned, not shipped.
AskRAI gives you configurable safety and compliance controls, an always-on audit trail, and transparent logic. Rules about tone, fairness or bias are yours to write as LLM-judge guardrails; the platform ships no bias detector of its own. Every interaction is recorded in a complete, tenant-scoped audit trail, so every response is accountable and traceable — auditing is always on. Guardrail enforcement, by contrast, is something you configure rather than a default: a guardrail screens a user's questions only once it is assigned to a group that user belongs to, so guardrails apply per group instead of automatically to everyone. See Guardrails.
Is tenant data isolated?
Yes. Configuration, knowledge bases, guardrails, users and caches are all scoped to one tenant and never shared. The isolation is enforced as a tenant_id filter on every query and every cache key rather than by separate databases — all tenants share one collection and one vector index, and that filter is what separates them. Data leakage between tenants is treated as a security vulnerability.