> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/agent-builder-faqs-and-troubleshooting.md).

# 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

<details>

<summary>Who can build agents?</summary>

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](/ai-workbench-qore/control-center/admin/roles.md).

</details>

<details>

<summary>Where are an agent's settings?</summary>

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](/ai-workbench-qore/console/agent-builder/the-canvas.md).

</details>

<details>

<summary>What does Try Agent need?</summary>

The **Trigger Agent** capability, and a widget key on the agent. **Try Agent** opens the Agent Playground in a new tab. See [The Canvas](/ai-workbench-qore/console/agent-builder/the-canvas.md).

</details>

<details>

<summary>What can I import?</summary>

An agent package exported from Qore: a ZIP file up to 50 MB. See [Get Started](/ai-workbench-qore/console/agent-builder/get-started.md#start-an-agent).

</details>

<details>

<summary>What do agent triggers do?</summary>

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](/ai-workbench-qore/console/agent-builder/build/triggers.md).

</details>

### Runtime and versions

<details>

<summary>What's the difference between Executor Version and Draft Version?</summary>

**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](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning.md#draft-versions-and-executor-versions).

</details>

<details>

<summary>Do existing agents move to a new executor version automatically?</summary>

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](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning.md#executor-version).

</details>

<details>

<summary>Which features need a newer executor version?</summary>

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](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning.md#when-the-executor-version-matters).

</details>

### Skills, MCP, and knowledge

<details>

<summary>Where do I add skills?</summary>

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](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent.md).

</details>

<details>

<summary>Does each MCP tool run without asking?</summary>

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](/ai-workbench-qore/console/agent-builder/build/mcp-tools.md#connecting-an-mcp-server).

</details>

<details>

<summary>Which version of a knowledge file does the agent answer from?</summary>

The latest synced version. A new file version reaches the agent only once it shows **Synced**. See [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent.md#common-issues-and-troubleshooting).

</details>

### Access and integration

<details>

<summary>What's the difference between a widget key and an API key?</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/authentication.md#key-types).

</details>

<details>

<summary>Can I see an API secret again?</summary>

No. It's shown once, when the pair is generated. See [Key types](/ai-workbench-qore/console/agent-builder/deploy/authentication.md#key-types).

</details>

<details>

<summary>Can I rotate a key?</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/authentication.md#renaming-or-deactivating-a-key).

</details>

<details>

<summary>What's the difference between Access &#x26; Security and Authentication?</summary>

**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](/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md).

</details>

<details>

<summary>Does Authentication block requests without a token?</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md#request-outcomes-and-token-security).

</details>

<details>

<summary>More questions about exporting an agent</summary>

Package delivery, knowledge, secrets, MCP connections, and email recipients are answered in the [Export Agent FAQs](/ai-workbench-qore/console/agent-builder/deploy/export-agent.md#faqs).

</details>

## Troubleshooting

### Building

<details>

<summary>I don't see the canvas</summary>

You may still be in the planning view. Select **Build Agent**. See [Create an agent](/ai-workbench-qore/task-guides/create-an-agent.md#common-issues).

</details>

<details>

<summary>Agent Behaviour won't save</summary>

A selected model or mode isn't available. Choose one that isn't greyed out or marked **Not Supported**. See [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior.md).

</details>

<details>

<summary>The chat says it was made in an older version</summary>

Select **Migrate chat** to keep its history, or **Start new conversation**. See [Create an agent](/ai-workbench-qore/task-guides/create-an-agent.md#common-issues).

</details>

<details>

<summary>A builder section is unavailable</summary>

The feature may need a newer executor version. Check **Agent Config** › **Runtime & Versoning**, upgrade, and validate the agent. See [When the executor version matters](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning.md#when-the-executor-version-matters).

</details>

<details>

<summary>An action is disabled with "You don't have access to …"</summary>

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](/ai-workbench-qore/control-center/admin/roles.md).

</details>

### Skills and MCP

<details>

<summary>The agent doesn't use a skill</summary>

Make the skill description specific, and refine the instructions to say when to use it. See [Adding a skill: troubleshooting](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent.md#common-issues-and-troubleshooting).

</details>

<details>

<summary>A skill fails at runtime</summary>

Check its credentials and endpoint, then inspect the run in **Runs & Traces**. See [Adding a skill: troubleshooting](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent.md#common-issues-and-troubleshooting).

</details>

<details>

<summary>An MCP server won't connect, or its tools fail</summary>

* **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](/ai-workbench-qore/console/agent-builder/build/mcp-tools.md).

</details>

### Knowledge

<details>

<summary>The agent ignores attached knowledge</summary>

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](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent.md#common-issues-and-troubleshooting).

</details>

<details>

<summary>Done stays disabled when attaching knowledge</summary>

No file or external content is selected yet. Upload a file or import content from a connected source. See [Attaching knowledge: troubleshooting](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent.md#common-issues-and-troubleshooting).

</details>

### Integration and authentication

<details>

<summary>The widget doesn't appear</summary>

Import the stylesheet, provide both `config` and `user`, and check that the widget key is correct and active. See [Integrate Agent: troubleshooting](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md#troubleshooting).

</details>

<details>

<summary>The widget returns "Unauthorized"</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/authentication.md#allowed-domains).

</details>

<details>

<summary>API calls return 401</summary>

Check the `x-api-key` and `x-api-key-secret` values. If you lost the secret, generate a new pair. See [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent.md#common-issues).

</details>

<details>

<summary>A request with variables is rejected</summary>

Every key in `variables` must already be declared in the agent's **Agent Variables**. See [Passing variables and a business ID](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md#passing-variables-and-a-business-id).

</details>

<details>

<summary>No webhook arrives</summary>

Webhooks need executor version 1.2 or later. See [Webhooks](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md#webhooks).

</details>

<details>

<summary>Requests fail with AGENT_AUTHENTICATION_FAILED or TOKEN_EXPIRED</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md#request-outcomes-and-token-security).

</details>

<details>

<summary>Developer Mode doesn't appear in the widget</summary>

Setup Identity Token is available on request, switched on only for clients who have asked for it. See [Setup Identity Token](/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md#setup-identity-token).

</details>

### Export and import

<details>

<summary>The Export Agent icon is disabled</summary>

Exporting needs the **Export Agent** capability. See [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent.md).

</details>

<details>

<summary>An export email hasn't arrived, or its link doesn't work</summary>

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](/ai-workbench-qore/console/agent-builder/deploy/export-agent.md#troubleshooting).

</details>

### Related

* [Get Started](/ai-workbench-qore/console/agent-builder/get-started.md), [The Canvas](/ai-workbench-qore/console/agent-builder/the-canvas.md), [Build](/ai-workbench-qore/console/agent-builder/build.md), [Deploy](/ai-workbench-qore/console/agent-builder/deploy.md), and [Monitor](/ai-workbench-qore/console/agent-builder/monitor.md)
* [Create an agent](/ai-workbench-qore/task-guides/create-an-agent.md) and [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent.md): every Agent Builder task

***

{% columns %}
{% column width="83.33333333333334%" %}

<p align="right"><em>Maintained by</em> <mark style="color:green;">Abhishek Paul</mark><br><code>AI-assisted, human-approved</code></p>
{% endcolumn %}

{% column width="16.666666666666664%" %}

<div align="left"><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-d034645b4f8f8ee661985f5306b60ded3289653c%2Fmaintainer-abhishek-paul.png?alt=media" alt="" width="60"></div>
{% endcolumn %}
{% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/ai-workbench-qore/console/agent-builder/agent-builder-faqs-and-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.