Skip to main content

​
Airia Agent not showing up for users

A user reports that they don’t see Airia Agent in their Chat sidebar after you’ve enabled it. Work through these checks in order:
Navigate to Settings → Airia Agent and check that the Enable Airia Agent toggle is on and that the page shows an active deployment (not a provisioning spinner or error state).If the toggle is on but the page still shows a provisioning state, see Provisioning stalls or fails below.
Navigate to Settings → Airia Agent → Access & Privacy.
  • If access is set to All users, every tenant member should see Airia Agent. Move to the next check.
  • If access is set to Specific users and groups, verify the affected user (or a group they belong to) is in the list. If not, add them and save.
The user needs the Settings > Airia Agent > Read permission assigned to their role, or the OmniAgent tenant permission granted explicitly. Go to Settings → Users, find the user, and confirm their role includes the Airia Agent access permission.If your tenant uses Custom Roles, check that the role’s permission set includes Airia Agent access.
Permission changes propagate immediately on the server, but the user’s browser may have cached their previous session state. Ask them to press Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux) to force a full reload, then check the Chat sidebar again.
If the user is seeing a different agent instead of Airia Agent, they may be routed to the fallback agent because their access was restricted. Confirm their name or group appears in the access list, then ask them to start a new Chat session (not reload an existing conversation).
If none of these resolve the issue, collect the user’s ID and role, the current access mode setting, and any browser console errors, then contact Airia support.

​
Provisioning stalls or fails

After toggling Airia Agent on, the settings page shows a spinner that doesn’t resolve, or an error message appears instead of the active configuration.
Provisioning typically completes within 10–15 seconds. If the spinner is still showing after 30 seconds, do a hard refresh of the page (Cmd+Shift+R / Ctrl+Shift+R). The page re-checks provisioning status on load.
If the page loads but shows inconsistent state — for example, the toggle appears on but no deployment or configuration tabs are visible — the provisioning process may have partially completed.Try toggling Airia Agent off (which triggers a cleanup) and then on again. This restarts a fresh provisioning cycle.
Toggling off and back on will clear any tool, sub-agent, or system prompt configuration you had already saved. If you have configuration worth preserving, note it before toggling off.
Provisioning requires the Admin or Platform Admin role with the Settings > Airia Agent > Manage permission. If you don’t have both, the toggle may appear to activate but provisioning will silently fail.Ask a Platform Admin to verify your role assignments and retry.
If the issue persists after the steps above, contact Airia support with:
  • Your tenant ID
  • The timestamp of when you attempted to enable Airia Agent
  • Any error message or code shown on the settings page
  • Your user role and permissions

​
Tools not being invoked

Airia Agent isn’t using a tool you’ve configured, even for requests that clearly match the tool’s purpose.
In Settings → Airia Agent → Tools, find the tool in the Configured Tools list and confirm the toggle next to it is on. Disabled tools are listed but ignored at runtime.
Airia Agent selects tools based on their metadata. If the tool’s name or description is vague or overlaps with other tools, the agent may consistently choose a different one. Go to the tool’s definition and make the name and description more specific and distinct.
If two tools overlap in scope, use the system prompt to make the routing explicit — for example: “When users ask about X, use the Y tool.” See System Prompts for examples.
Tools that require authentication will silently fail to invoke if the bound credential is missing, expired, or invalid. In the Tools tab, confirm the credential assigned to the tool is current. Rotate or reassign the credential in Credential Management if needed.

​
Sub-agent not appearing in the picker

A catalog agent you want to add as a sub-agent doesn’t show up in the Sub-agents tab picker. The agent must be published to the Airia Catalog before it appears here. Unpublished and draft agents are not shown. Go to the agent’s interface settings in Agent Studio, publish it to the catalog, and then return to the Sub-agents tab. The picker refreshes on each load.

​
Upgrade stuck on placeholder bindings

After initiating a version upgrade, the Tools tab shows an unresolved Placeholder Bindings warning and the upgrade won’t complete. Each binding must be mapped to a configured MCP server or tool before the upgrade can proceed. See MCP placeholder bindings for step-by-step instructions. If a required tool or MCP server isn’t yet configured, add it in the Tools tab first, then return to the bindings section.