Agent Builder: FAQs & Troubleshooting
Answers to common Agent Builder questions, and fixes for skills, MCP servers, knowledge, integration, authentication, and export.
This page answers common questions about building, versioning, securing, and integrating agents. Use the troubleshooting entries when an agent doesn't use a skill or its knowledge, an integration call is refused, or an export or import doesn't go as expected.
FAQs
Building
Who can build agents?
Every standard role can view and trigger agents. Building, importing, exporting, publishing, sharing, versions, and attaching a governed graph need Developer, Account Admin, or Organisation Admin. See Roles.
Where are an agent's settings?
In Agent Config, opened from the canvas header. It holds the agent's details, behaviour, runtime, skills, connectors, triggers, secrets, access, and authentication. See The Canvas.
What does Try Agent need?
The Trigger Agent capability, and a widget key on the agent. Try Agent opens the Agent Playground in a new tab. See The Canvas.
What can I import?
An agent package exported from Qore: a ZIP file up to 50 MB. See Get Started.
What do agent triggers do?
They're the events that cause the agent to run. Each has a Trigger Source, a unique Trigger Name, and a Description that the planner reads at runtime to decide whether an event matches. Agent triggers aren't flow triggers. See Triggers.
Runtime and versions
What's the difference between Executor Version and Draft Version?
Executor Version selects the runtime that runs the agent, one per agent. Draft Version saves a snapshot of the agent's configuration, many per agent. They're independent. See Draft versions and executor versions.
Do existing agents move to a new executor version automatically?
No. New agents use the latest version available to your tenant; existing agents stay on their current version until you migrate them. An upgrade can change agent behaviour, so validate the agent first. See Runtime & Versioning.
Which features need a newer executor version?
For example, webhooks need 1.2 or later, and the Agents tab in Observe › Analytics needs 1.4 or later. If a builder section is unavailable, check the executor version. See When the executor version matters.
Skills, MCP, and knowledge
Where do I add skills?
In Add Skill: Skill Library skills, the MCP Marketplace, flows, other agents, custom skills, and pre-attached skills. Connecting an integration or an MCP server registers its skills too. See Adding a Skill to the Agent.
Does each MCP tool run without asking?
Not by default. Each tool of an MCP connection starts as Always Ask Permissions; set Allow Unsupervised per tool in Tools and Settings or Manage Tools. See MCP Tools.
Which version of a knowledge file does the agent answer from?
The latest synced version. A new file version reaches the agent only once it shows Synced. See Attaching Knowledge to an Agent.
Access and integration
What's the difference between a widget key and an API key?
A widget key is safe in browser code, because it works only from the platform and the agent's Allowed Domains. An API key is a key and secret pair for server-to-server calls; keep both server-side. See Key types.
Can I see an API secret again?
No. It's shown once, when the pair is generated. See Key types.
Can I rotate a key?
There's no rotate action. Add a new key, move your integrations to it, then deactivate the old one. Deactivation can't be undone. See Renaming or deactivating a key.
What's the difference between Access & Security and Authentication?
Access & Security authorizes the calling application, with keys and allowed domains. Authentication identifies the person, by verifying a Microsoft Entra ID or Google token. See Authentication.
Does Authentication block requests without a token?
No. A request without a token still runs, without $auth.token. A request with an invalid token is rejected. See Request outcomes and token security.
More questions about exporting an agent
Package delivery, knowledge, secrets, MCP connections, and email recipients are answered in the Export Agent FAQs.
Troubleshooting
Building
I don't see the canvas
You may still be in the planning view. Select Build Agent. See Create an agent.
Agent Behaviour won't save
A selected model or mode isn't available. Choose one that isn't greyed out or marked Not Supported. See Agent Behavior.
The chat says it was made in an older version
Select Migrate chat to keep its history, or Start new conversation. See Create an agent.
A builder section is unavailable
The feature may need a newer executor version. Check Agent Config › Runtime & Versoning, upgrade, and validate the agent. See When the executor version matters.
An action is disabled with "You don't have access to …"
The tooltip names the missing capability, for example You don't have access to build agents, … to export agents, or … to run agents. See Roles.
Skills and MCP
The agent doesn't use a skill
Make the skill description specific, and refine the instructions to say when to use it. See Adding a skill: troubleshooting.
A skill fails at runtime
Check its credentials and endpoint, then inspect the run in Runs & Traces. See Adding a skill: troubleshooting.
An MCP server won't connect, or its tools fail
It fails at Next on an OAuth server: enter the OAuth Client ID from the server's OAuth app under Advanced Settings.
Every tool call fails as unauthorised: turn on Authenticate M2M (OAuth client credentials) and reconnect.
It shows Initialize: it was imported without its credentials. Select Initialize and enter them.
See MCP Tools.
Knowledge
The agent ignores attached knowledge
Check that Knowledge Search is active, that the instructions tell the agent to consult its sources, and that new files show Synced. See Attaching knowledge: troubleshooting.
Done stays disabled when attaching knowledge
No file or external content is selected yet. Upload a file or import content from a connected source. See Attaching knowledge: troubleshooting.
Integration and authentication
The widget doesn't appear
Import the stylesheet, provide both config and user, and check that the widget key is correct and active. See Integrate Agent: troubleshooting.
The widget returns "Unauthorized"
The page's domain isn't on Allowed Domains exactly as the browser sends it, including protocol, subdomain, and port. With the list empty, the widget runs nowhere outside the platform. See Allowed Domains.
API calls return 401
Check the x-api-key and x-api-key-secret values. If you lost the secret, generate a new pair. See Integrate an agent.
A request with variables is rejected
Every key in variables must already be declared in the agent's Agent Variables. See Passing variables and a business ID.
No webhook arrives
Webhooks need executor version 1.2 or later. See Webhooks.
Requests fail with AGENT_AUTHENTICATION_FAILED or TOKEN_EXPIRED
The caller's token is invalid, issued for another application or client, or expired. An expired Microsoft Entra ID token gives TOKEN_EXPIRED; Google reports expired and invalid tokens the same way. AGENT_AUTHENTICATION_CONFIG_INVALID means the agent's provider details are incomplete. See Request outcomes and token security.
Developer Mode doesn't appear in the widget
Setup Identity Token is available on request, switched on only for clients who have asked for it. See Setup Identity Token.
Export and import
The Export Agent icon is disabled
Exporting needs the Export Agent capability. See Export Agent.
An export email hasn't arrived, or its link doesn't work
The email is sent only once the package is built, to the user who started the export, and its download link expires. These and other export and import problems are covered in Export Agent: troubleshooting.
Related
Get Started, The Canvas, Build, Deploy, and Monitor
Create an agent and Integrate an agent: every Agent Builder task
Maintained by Abhishek Paul
AI-assisted, human-approved
Last updated
Was this helpful?