> This is part 1 of 3 of the full documentation (pages 1–100 of 264).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.uptiq.ai/llms-full.txt/1
> Page index: https://docs.uptiq.ai/llms.txt

# 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
This site has an agentic ask interface you may use to query the documentation dynamically 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/index.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.

---

# UPTIQ Knowledgebase

Welcome to UPTIQ's centralised documentation for the Qore platform, UPTIQ Document AI, and UPTIQ Solutions.

UPTIQ Knowledgebase is the documentation hub for Qore, UPTIQ Document AI, and UPTIQ Solutions. It brings platform guidance, document intelligence, and solution documentation together in one place.

UPTIQ helps financial institutions turn complex workflows into intelligent, scalable experiences. Qore, Document AI, and UPTIQ Solutions combine to build, automate, and operate trusted AI workflows.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask a question</button> <a href="https://docs.uptiq.ai/ai-workbench-qore/help" class="button secondary" data-icon="life-ring">Get help</a>

### <i class="fa-layer-group">:layer-group:</i> The UPTIQ AI stack

{% columns %}
{% column width="33.33333333333333%" %}
\
**Qore** is the platform for building apps and agents.

**Document AI** is the document-processing layer behind UPTIQ Solutions. It classifies, extracts, validates, and delivers document intelligence.

**UPTIQ Solutions** are products built on Qore. Today they serve lending.
{% endcolumn %}

{% column width="66.66666666666667%" %}

<figure><img src="https://3314308225-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2HNakjnzmYueu3bgTBsv%2Fuploads%2Fgit-blob-a8a6d3bd3374eba8866e6c7091c17fefecca40f0%2Fuptiq-product-layers.png?alt=media" alt="Three layers: Qore platform at the base, Document AI above it, and UPTIQ Solutions on top, including Commercial Lending, Equipment Financing, Client Lending, and Wealth Review." width="563"><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

### <i class="fa-rocket">:rocket:</i> Qore Platform

Qore unifies Agentic AI and app creation, so you can build secure, production-ready apps and agents in one place. You build and run them in **Console**, and operate them across your account in **Control Center**.

<a href="https://docs.uptiq.ai/ai-workbench-qore" class="button primary" data-icon="book">Read Qore documentation</a>

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-rocket" style="color:$primary;">:rocket:</i></h4></td><td><strong>What is Qore</strong></td><td>Core concepts: what Qore is and how an agent works.</td><td><a href="https://docs.uptiq.ai/ai-workbench-qore/start-here/what-is-qore">https://docs.uptiq.ai/ai-workbench-qore/start-here/what-is-qore</a></td></tr><tr><td><h4><i class="fa-compass" style="color:$primary;">:compass:</i></h4></td><td><strong>Platform Guides</strong></td><td>Task guides for the people who use, run, review and administer Qore.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/platform-guides">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/platform-guides</a></td></tr><tr><td><h4><i class="fa-code" style="color:$primary;">:code:</i></h4></td><td><strong>API Reference</strong></td><td>Every service the platform exposes.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/api-reference">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/api-reference</a></td></tr><tr><td><h4><i class="fa-cubes" style="color:$primary;">:cubes:</i></h4></td><td><strong>Object Model</strong></td><td>The objects Qore stores, versions and relates to one another.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/qore-object-model">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/qore-object-model</a></td></tr><tr><td><h4><i class="fa-flask" style="color:$primary;">:flask:</i></h4></td><td><strong>Cookbooks</strong></td><td>API workflows for platform tasks.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/cookbooks">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/cookbooks</a></td></tr><tr><td><h4><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h4></td><td><strong>Implementation and Security</strong></td><td>Implementation and security documentation.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/qore-implementation-and-security">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/qore-implementation-and-security</a></td></tr></tbody></table>

### <i class="fa-file-lines">:file-lines:</i> Document AI

UPTIQ Document AI is the document-processing layer behind UPTIQ Solutions. It turns raw files into structured, reviewable, and actionable data.

Teams use it to classify incoming documents, extract fields, detect fraud signals, generate outputs, measure accuracy, and send results to downstream systems.

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-file-lines" style="color:$primary;">:file-lines:</i></h4></td><td><strong>Document AI overview</strong></td><td>Classifies, extracts, validates, and delivers document intelligence across UPTIQ Solutions.</td><td><a href="https://docs.uptiq.ai/document-ai">https://docs.uptiq.ai/document-ai</a></td></tr></tbody></table>

### <i class="fa-puzzle-piece">:puzzle-piece:</i> UPTIQ Solutions

UPTIQ Solutions are products built on Qore. Today they serve lending.

#### Lending

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-building-columns" style="color:$primary;">:building-columns:</i></h4></td><td><strong>Commercial Lending</strong></td><td>AI-powered commercial lending automation with human review at every stage.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/commercial-lending">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/commercial-lending</a></td></tr><tr><td><h4><i class="fa-truck" style="color:$primary;">:truck:</i></h4></td><td><strong>Equipment Financing</strong></td><td>Help customers apply for equipment financing and process applications efficiently.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/equipment-financing">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/equipment-financing</a></td></tr><tr><td><h4><i class="fa-compass" style="color:$primary;">:compass:</i></h4></td><td><strong>Client Lending</strong></td><td>Platform guidance, lending workflows, client resources, and support.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/client-lending-advisor-knowledge-centre">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/client-lending-advisor-knowledge-centre</a></td></tr><tr><td><h4><i class="fa-window-maximize" style="color:$primary;">:window-maximize:</i></h4></td><td><strong>Wealth Review</strong></td><td>Compliance and NIGO reviews of account packets.</td><td><a href="https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/wealth-review">https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/wealth-review</a></td></tr></tbody></table>

### <i class="fa-compass">:compass:</i> Find docs for your role

| If you are                             | Start here                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Evaluating UPTIQ                       | [The UPTIQ AI stack](#the-uptiq-ai-stack), then [UPTIQ Solutions](#uptiq-solutions)                                                                                                                                                                                                                                                                                                                                           |
| An admin setting up your organization  | [Platform Guides](https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/platform-guides)                                                                                                                                                                                                           |
| A builder creating agents or apps      | [What is Qore](https://docs.uptiq.ai/ai-workbench-qore/start-here/what-is-qore), then [Core concepts](https://docs.uptiq.ai/ai-workbench-qore/start-here/core-concepts)                                                                                                                                                                                                                                                       |
| A developer integrating with UPTIQ     | [API Reference](https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/api-reference), then [Cookbooks](https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/cookbooks) |
| A technical architect                  | [Object Model](https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/qore-object-model), then [Deployment options](https://docs.uptiq.ai/ai-workbench-qore/start-here/deployment-options)                                                                                                          |
| An implementation or security reviewer | [Implementation and Security](https://integrations.gitbook.com/v1/integrations/VA-Azure/installations/e225e56ca772be2c3176b129f445a091bd373c04c414c8915cad8cbd482bde0b/sites/site_YkKEL/visitor-auth?location=/qore-implementation-and-security)                                                                                                                                                                              |

### <i class="fa-lock">:lock:</i> Documentation access

Sign in with your Microsoft account to open protected documentation. Public documentation opens without signing in.

<details>

<summary>View documentation access requirements</summary>

| Documentation               | Access           |
| --------------------------- | ---------------- |
| What is Qore                | Public           |
| Document AI overview        | Public           |
| Platform Guides             | Sign in required |
| API Reference               | Sign in required |
| Object Model                | Sign in required |
| Cookbooks                   | Sign in required |
| Implementation and Security | Sign in required |
| Commercial Lending          | Sign in required |
| Equipment Financing         | Sign in required |
| Client Lending              | Sign in required |
| Wealth Review               | Sign in required |

</details>

### <i class="fa-life-ring">:life-ring:</i> Get help and support

#### Ask AI

The assistant answers your questions from the Qore and Document AI documentation on this site, and links to the pages it uses.

{% hint style="info" %}
**Beta.** Ask AI may contain mistakes. Use the page feedback form when an answer doesn't match the documentation.
{% endhint %}

To open it, select **Ask** next to search. Ask in your own words, then select **Send**. Each answer links to the pages it used.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask a question…</button> <a href="https://docs.uptiq.ai/ai-workbench-qore/ask-assistant" class="button secondary" data-icon="sparkles">About Ask Assistant</a>

#### Giving feedback

Pages in the Qore docs include a feedback form. Use it to tell us what helped, what was missing, or what was unclear. The form starts with **Was this helpful?**

{% stepper %}
{% step %}

#### Choose a reaction

Under **Was this helpful?**, select a smiling face (yes), a neutral face (not sure), or a frowning face (no).
{% endstep %}

{% step %}

#### Add details

In **Anything you'd like to add?**, describe what helped, or what was missing or unclear.
{% endstep %}

{% step %}

#### Submit

Select **Submit**.
{% endstep %}
{% endstepper %}

We review feedback and update documentation when needed.

<a href="https://docs.uptiq.ai/ai-workbench-qore/feedback" class="button secondary" data-icon="comment-dots">About feedback</a>

#### More resources

* [Release notes](https://docs.uptiq.ai/ai-workbench-qore/release-notes/2026) — Qore, UPTIQ Document AI, and each UPTIQ Solution have separate changelogs for product-specific updates and improvements.

***

{% columns %}
{% column width="65%" %}
&#x20;
{% endcolumn %}

{% column width="26%" %}

<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="9%" %}

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


# Overview

Platform documentation for Qore. Move from vision to velocity. Build secure, production-ready apps and agents in one place.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FT8VXJtQxM9irwGGOjX7l%2Fimage-removebg-preview.png?alt=media&amp;token=de19a66b-31b8-4ad6-abd4-66c3edeab271" alt=""><figcaption></figcaption></figure>

## <i class="fa-gears">:gears:</i> **Built for production with governance**

Ideas in lending and banking need reliable execution. **Qore shortens the path to shipping.**

Qore unifies Agentic AI and app creation. It removes setup friction. It drives measurable outcomes.

Whether you automate mortgage workflows or scale client onboarding, Qore turns strategy into a high-performance production system.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask the Qore Knowledge Assistant</button> <a href="/ai-workbench-qore/help" class="button secondary" data-icon="life-ring">Get help</a>

<button type="button" class="button secondary" data-action="ask" data-query="How do I create an agent?" data-icon="robot">Create an agent</button><button type="button" class="button secondary" data-action="ask" data-query="How do I create an app?" data-icon="mobile">Create an app</button><button type="button" class="button secondary" data-action="ask" data-query="How do I connect an integration?" data-icon="plug">Connect an integration</button><button type="button" class="button secondary" data-action="ask" data-query="How do I invite users to my account?" data-icon="user-group">Invite your team</button>

***

{% hint style="success" icon="sparkles" %}
**New in the October 4 release: a unified AI Gateway for every agent and an Operator that runs on a schedule.** This release also brings stronger sign-in, evaluation, and knowledge management capabilities.

<a href="/ai-workbench-qore/release-notes/2026/october-4" class="button secondary" data-icon="calendar">See what's new</a>
{% endhint %}

## <i class="fa-compass">:compass:</i> Explore Qore

Choose the area that matches your next step.

### Get oriented

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-compass" style="color:$primary;">:compass:</i></h4></td><td><h4>Start Here</h4></td><td>Learn how Qore’s builders, agents, and skills fit together.</td><td><a href="/ai-workbench-qore/start-here/what-is-qore">What is Qore</a></td></tr><tr><td><h4><i class="fa-lightbulb" style="color:$primary;">:lightbulb:</i></h4></td><td><h4>Core Concepts</h4></td><td>Understand reasoning, knowledge, tools, and safety.</td><td><a href="/ai-workbench-qore/start-here/core-concepts">Agent Foundations</a></td></tr><tr><td><h4><i class="fa-people-group" style="color:$primary;">:people-group:</i></h4></td><td><h4>Console Operator</h4></td><td>Describe a goal and let the Operator build and run the work.</td><td><a href="/ai-workbench-qore/console/console-operator">Console Operator</a></td></tr><tr><td><h4><i class="fa-route" style="color:$primary;">:route:</i></h4></td><td><h4>Task Guides</h4></td><td>Step-by-step guides for the Operator, agents, flows, knowledge, design systems, and apps.</td><td><a href="/ai-workbench-qore/guides">Task Guides</a></td></tr><tr><td><h4><i class="fa-robot" style="color:$primary;">:robot:</i></h4></td><td><h4>Agent Builder</h4></td><td>Configure, test, deploy, and monitor production agents.</td><td><a href="/ai-workbench-qore/console/agent-builder">Agent Builder</a></td></tr><tr><td><h4><i class="fa-mobile" style="color:$primary;">:mobile:</i></h4></td><td><h4>App Builder</h4></td><td>Plan, generate, test, and publish applications.</td><td><a href="/ai-workbench-qore/console/app-builder">App Builder</a></td></tr></tbody></table>

### Extend and operate

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-plug" style="color:$primary;">:plug:</i></h4></td><td><h4>Integrations</h4></td><td>Connect models, services, and your existing technology stack.</td><td><a href="/ai-workbench-qore/console/integrations-hub">Integrations Hub</a></td></tr><tr><td><h4><i class="fa-database" style="color:$primary;">:database:</i></h4></td><td><h4>Knowledge</h4></td><td>Turn documents into versioned knowledge bases that agents query.</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td><h4><i class="fa-book" style="color:$primary;">:book:</i></h4></td><td><h4>Platform Resources</h4></td><td>Browse the <strong>Skill Library</strong>, models, and integrations.</td><td><a href="/ai-workbench-qore/platform-resources/skill-library">Skill Library</a></td></tr><tr><td><h4><i class="fa-scale-balanced" style="color:$primary;">:scale-balanced:</i></h4></td><td><h4>Governance</h4></td><td>Manage access, branding, releases, and operational controls.</td><td><a href="/ai-workbench-qore/control-center/governance">Overview</a></td></tr><tr><td><h4><i class="fa-shield" style="color:$primary;">:shield:</i></h4></td><td><h4>Security &#x26; Compliance</h4></td><td>Review Qore’s deployment model and security controls.</td><td><a href="/ai-workbench-qore/control-center/detailed-security-and-runtime-faq">Security FAQ</a></td></tr><tr><td><h4><i class="fa-calendar" style="color:$primary;">:calendar:</i></h4></td><td><h4>Release Notes</h4></td><td>Track platform updates and releases.</td><td><a href="/ai-workbench-qore/release-notes/2026">2026</a></td></tr></tbody></table>

## <i class="fa-list-check">:list-check:</i> Popular tasks

<table data-view="cards"><thead><tr><th></th><th data-type="content-ref"></th><th data-type="content-ref"></th><th data-type="content-ref"></th></tr></thead><tbody><tr><td><h4>For builders</h4></td><td><a href="/ai-workbench-qore/task-guides/create-an-agent">Create an agent</a></td><td><a href="/ai-workbench-qore/task-guides/create-an-app">Create an app</a></td><td><a href="/ai-workbench-qore/console/app-builder/plan">Plan</a></td></tr><tr><td><h4>For admins</h4></td><td><a href="/ai-workbench-qore/control-center/admin/users">Users</a></td><td><a href="/ai-workbench-qore/control-center/admin/roles">Roles</a></td><td><a href="/ai-workbench-qore/control-center/admin/single-sign-on">Single Sign-On</a></td></tr><tr><td><h4>For developers</h4></td><td><a href="/ai-workbench-qore/task-guides/integrate-an-agent">Integrate an agent</a></td><td><a href="/ai-workbench-qore/task-guides/how-to-connect-an-integration">Connect an integration</a></td><td><a href="/ai-workbench-qore/platform-resources/the-agent-development-sdk">Agent SDK</a></td></tr></tbody></table>

***

## <i class="fa-table-cells-large">:table-cells-large:</i> Build in Console, operate in Control Center

Qore has two connected platform surfaces:

* [**Console**](/ai-workbench-qore/start-here/console) is where you build and run apps and agents. Use it to create, configure, test, publish, and run your work.
* [**Control Center**](/ai-workbench-qore/start-here/control-center) is where you operate them across your account. Monitor usage and quality, manage access and billing, inspect logs, and apply guardrails.

Each space has an [**Operator**](/ai-workbench-qore/core-concepts/operator): a chat that plans the work and hands each part to the right agent.

{% columns %}
{% column %}

#### <i class="fa-hammer">:hammer:</i> In Console

* [**Console Operator**](/ai-workbench-qore/console/console-operator) — Build apps, agents, knowledge bases, and agentic applications from one conversation. Run it on a [schedule](/ai-workbench-qore/console/console-operator/schedules), and answer an agent's questions from [Gates](/ai-workbench-qore/console/console-operator/gates).
* [**Agent Builder**](/ai-workbench-qore/console/agent-builder) — Configure, test, deploy, and monitor agents. Verify callers through Microsoft Entra ID or Google with [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1), and connect MCP servers with [OAuth client credentials](/ai-workbench-qore/console/agent-builder/build/mcp-tools#connect-with-client-credentials).
* [**Knowledge**](/ai-workbench-qore/console/knowledge) — Build knowledge bases from files, drives, and websites. Each [sync](/ai-workbench-qore/console/knowledge/sync-and-versions) creates a new knowledge version, and datasets can auto sync.
* [**Design Systems**](/ai-workbench-qore/console/design-systems) — Describe a brand and the builder sets its visual style, logos, fonts, and colors. Every save creates a version you can restore.
* [**Flows**](/ai-workbench-qore/console/flows) — Build a fixed, multi-step process that an agent runs as a single skill.
  {% endcolumn %}

{% column %}

#### <i class="fa-sliders">:sliders:</i> In Control Center

* [**AI Gateway**](/ai-workbench-qore/control-center/ai-gateway) — Every model request an agent makes passes through it. Approve model families once, for the whole organization.
* [**Evals**](/ai-workbench-qore/control-center/evals) — Score live agent output with a single judge or a jury of models, using methods such as Faithfulness. Route low-confidence results to [Human Review](/ai-workbench-qore/control-center/evals/human-review).
* [**Govern**](/ai-workbench-qore/control-center/govern) — Stop any agent in an emergency with [Agent Controls](/ai-workbench-qore/control-center/govern/agent-controls), see what agents can reach in [Connectors](/ai-workbench-qore/control-center/govern/connectors), and load an institution's knowledge graph into [Governed Graph](/ai-workbench-qore/control-center/govern/governed-graph).
* [**Admin**](/ai-workbench-qore/control-center/admin) — Invite users, sign in with [Google or Microsoft, including Entra ID](/ai-workbench-qore/control-center/admin/single-sign-on), and grant capabilities through [roles](/ai-workbench-qore/control-center/admin/roles).
* [**Observe**](/ai-workbench-qore/control-center/observe) and [**Cost Control**](/ai-workbench-qore/control-center/cost-control) — Trace every LLM call and request, track credit usage, and set hard limits and alerts.
  {% endcolumn %}
  {% endcolumns %}

***

## <i class="fa-shield">:shield:</i> Your environment stays yours

Qore turns AI strategy into a high-performance production system. It does not compromise your security posture.

{% columns %}
{% column %}

#### <i class="fa-earth-americas">:earth-americas:</i> Total data residency

Qore and its databases run in your cloud infrastructure. Qore runs on Google Cloud and Microsoft Azure, with AWS coming soon. See [Deployment options](/ai-workbench-qore/start-here/deployment-options). Traffic and data never leave your network boundaries.
{% endcolumn %}

{% column %}

#### <i class="fa-scale-balanced">:scale-balanced:</i> Jurisdictional compliance

Components remain in your designated regional data centers. You meet local data sovereignty laws from day one.
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
Qore runs entirely within your bank’s VPC. Review the [Security FAQ](/ai-workbench-qore/control-center/detailed-security-and-runtime-faq) for the zero-leak architecture.
{% endhint %}

***

## <i class="fa-layer-group">:layer-group:</i> The power trio

Three layers work together to handle complex financial workflows:

<table data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><h4><i class="fa-mobile" style="color:$primary;">:mobile:</i></h4></td><td><h4>Apps — the face</h4></td><td>The user experience for your clients and teams.</td></tr><tr><td><h4><i class="fa-brain" style="color:$primary;">:brain:</i></h4></td><td><h4>Agents — the brain</h4></td><td>The reasoning core that manages specialized knowledge and makes decisions.</td></tr><tr><td><h4><i class="fa-dumbbell" style="color:$primary;">:dumbbell:</i></h4></td><td><h4>Skills — the muscle</h4></td><td>Reusable tools and APIs that agents execute. External API integration lets agents read legacy core banking data or update third-party fintech services.</td></tr></tbody></table>

Around them, [**Knowledge**](/ai-workbench-qore/console/knowledge) turns your documents into content agents can query, and [**Flows**](/ai-workbench-qore/console/flows) package a fixed multi-step process as a single skill. In each space, an [**Operator**](/ai-workbench-qore/core-concepts/operator) takes your request and hands each part to the right agent.

***

## <i class="fa-route">:route:</i> Choose your velocity

Choose the workflow that matches your starting point.

Both paths help you bring financial applications to production quickly.

{% columns %}
{% column %}

#### <i class="fa-mobile">:mobile:</i> App-first workflow

**Best for:** Teams that want to refine the vision before shipping. Discuss the borrower journey in **Plan Mode**, then use **Build Mode** to create it.

* **Starting Point:** An idea or a rough architectural sketch.
* **The Tool:** **Plan Mode** for shaping, then **App Builder** for execution.
* **The Collaboration Loop:** Use **Share** after generating the initial blueprint to add stakeholders as collaborators, so they can review the loan flow before production.
* **The Win:** A functional, enterprise-ready interface aligned with the team.

<a href="/ai-workbench-qore/task-guides/create-an-app" class="button secondary" data-icon="mobile">Create an app</a>
{% endcolumn %}

{% column %}

#### <i class="fa-robot">:robot:</i> Agent-first workflow

**Best for:** Teams solving complex logic or automation first. Build the brain that understands lending rules, then decide where it runs.

* **Starting Point:** A defined automation need (like a KYC logic flow).
* **The Tool:** **Agent Builder** and **Skill Library** for reasoning and custom logic.
* **The Win:** A production-ready intelligence layer.
* **Next Move:** Launch it in a new app or integrate it with your existing stack through APIs or SDKs.

<a href="/ai-workbench-qore/task-guides/create-an-agent" class="button secondary" data-icon="robot">Create an agent</a>
{% endcolumn %}
{% endcolumns %}

You can also start in the [**Console Operator**](/ai-workbench-qore/console/console-operator): describe your goal, and it builds the app, agent, or knowledge base in your selected project.

<a href="/ai-workbench-qore/console/console-operator" class="button primary" data-icon="people-group">Open the Console Operator guide</a>

***

{% 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 %}


# Platform Reference

Reference documentation for every Qore module, organized by where you work.

The reference describes every Qore screen and setting. It's organized by the two places you work: **Console**, where you build and run apps and agents in a project, and **Control Center**, where you operate them across the account.

For step-by-step tasks, see [Task Guides](/ai-workbench-qore/guides).

## Console

Build and run apps and agents in a project. See [Console](/ai-workbench-qore/start-here/console).

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-folder-open" style="color:$primary;">:folder-open:</i></h3></td><td><h4><strong>Projects</strong></h4></td><td>Create and switch the projects your work lives in.</td><td><a href="/ai-workbench-qore/console/projects">Projects</a></td></tr><tr><td><h3><i class="fa-people-group" style="color:$primary;">:people-group:</i></h3></td><td><h4><strong>Console Operator</strong></h4></td><td>Describe a goal; the Operator plans it and hands the work to agents.</td><td><a href="/ai-workbench-qore/console/console-operator">Console Operator</a></td></tr><tr><td><h3><i class="fa-robot" style="color:$primary;">:robot:</i></h3></td><td><h4><strong>Agent Builder</strong></h4></td><td>Configure, test, deploy, and monitor agents.</td><td><a href="/ai-workbench-qore/console/agent-builder">Agent Builder</a></td></tr><tr><td><h3><i class="fa-mobile" style="color:$primary;">:mobile:</i></h3></td><td><h4><strong>App Builder</strong></h4></td><td>Plan, build, test, publish, and operate apps.</td><td><a href="/ai-workbench-qore/console/app-builder">App Builder</a></td></tr><tr><td><h3><i class="fa-database" style="color:$primary;">:database:</i></h3></td><td><h4><strong>Knowledge</strong></h4></td><td>Turn documents into versioned knowledge bases that agents query.</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td><h3><i class="fa-diagram-project" style="color:$primary;">:diagram-project:</i></h3></td><td><h4><strong>Flows</strong></h4></td><td>Automations of connected tasks, usable as agent skills.</td><td><a href="/ai-workbench-qore/console/flows">Flows</a></td></tr><tr><td><h3><i class="fa-store" style="color:$primary;">:store:</i></h3></td><td><h4><strong>Store</strong></h4></td><td>Browse ready-made agents and apps, then launch one.</td><td><a href="/ai-workbench-qore/console/store">Store</a></td></tr><tr><td><h3><i class="fa-plug" style="color:$primary;">:plug:</i></h3></td><td><h4><strong>Integrations Hub</strong></h4></td><td>Connect external services and systems.</td><td><a href="/ai-workbench-qore/console/integrations-hub">Integrations Hub</a></td></tr><tr><td><h3><i class="fa-layer-group" style="color:$primary;">:layer-group:</i></h3></td><td><h4><strong>Design Systems</strong></h4></td><td>Reusable visual identities for the project's apps.</td><td><a href="/ai-workbench-qore/console/design-systems">Design Systems</a></td></tr></tbody></table>

## Control Center

Operate apps and agents across the account. See [Control Center](/ai-workbench-qore/start-here/control-center).

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-compass" style="color:$primary;">:compass:</i></h3></td><td><h4><strong>Overview</strong></h4></td><td>Govern, monitor, evaluate, and control your Qore account.</td><td><a href="/ai-workbench-qore/control-center/governance">Overview</a></td></tr><tr><td><h3><i class="fa-building" style="color:$primary;">:building:</i></h3></td><td><h4><strong>Accounts</strong></h4></td><td>The account boundary and where to manage it.</td><td><a href="/ai-workbench-qore/control-center/accounts">Accounts</a></td></tr><tr><td><h3><i class="fa-user-shield" style="color:$primary;">:user-shield:</i></h3></td><td><h4><strong>Governance Operator</strong></h4></td><td>Ask about the account, and approve what it proposes.</td><td><a href="/ai-workbench-qore/control-center/governance-operator">Governance Operator</a></td></tr><tr><td><h3><i class="fa-magnifying-glass-chart" style="color:$primary;">:magnifying-glass-chart:</i></h3></td><td><h4><strong>Observe</strong></h4></td><td>Monitor platform activity and investigate operational data.</td><td><a href="/ai-workbench-qore/control-center/observe">Observe</a></td></tr><tr><td><h3><i class="fa-coins" style="color:$primary;">:coins:</i></h3></td><td><h4><strong>Cost Control</strong></h4></td><td>Track credit consumption and set limits and alerts.</td><td><a href="/ai-workbench-qore/control-center/cost-control">Cost Control</a></td></tr><tr><td><h3><i class="fa-clipboard-check" style="color:$primary;">:clipboard-check:</i></h3></td><td><h4><strong>Evals</strong></h4></td><td>Score agent outputs, monitor quality, and route reviews.</td><td><a href="/ai-workbench-qore/control-center/evals">Evals</a></td></tr><tr><td><h3><i class="fa-scale-balanced" style="color:$primary;">:scale-balanced:</i></h3></td><td><h4><strong>Govern</strong></h4></td><td>Stop active agent work and review what agents can reach.</td><td><a href="/ai-workbench-qore/control-center/govern">Govern</a></td></tr><tr><td><h3><i class="fa-route" style="color:$primary;">:route:</i></h3></td><td><h4><strong>AI Gateway</strong></h4></td><td>Route every agent's model calls, with a catalog and settings.</td><td><a href="/ai-workbench-qore/control-center/ai-gateway">AI Gateway</a></td></tr><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Admin</strong></h4></td><td>Manage users, sign-in, teams, roles, and API keys.</td><td><a href="/ai-workbench-qore/control-center/admin">Admin</a></td></tr><tr><td><h3><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h3></td><td><h4><strong>Security FAQ</strong></h4></td><td>Deployment, data, and runtime security.</td><td><a href="/ai-workbench-qore/control-center/detailed-security-and-runtime-faq">Security FAQ</a></td></tr></tbody></table>

## Platform Resources

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-puzzle-piece" style="color:$primary;">:puzzle-piece:</i></h3></td><td><h4><strong>Skill Library</strong></h4></td><td>Built-in and configurable skills for agents.</td><td><a href="/ai-workbench-qore/platform-resources/skill-library">Skill Library</a></td></tr><tr><td><h3><i class="fa-code" style="color:$primary;">:code:</i></h3></td><td><h4><strong>Agent SDK</strong></h4></td><td>A client for running Qore agents from your code.</td><td><a href="/ai-workbench-qore/platform-resources/the-agent-development-sdk">Agent SDK</a></td></tr></tbody></table>

***

{% 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 %}


# Task Guides

Step-by-step guides for every task in Qore, organized by what you want to do.

Task guides are organized by what you want to do. Each one opens with a list of tasks, then gives the steps for each, with links to the reference pages for detail.

***

## <i class="fa-hammer">:hammer:</i> Console

Build and run apps and agents in a project.

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Use the Console Operator</strong></h4></td><td>Ask, build, schedule, and answer gates from one chat.</td><td><a href="/ai-workbench-qore/task-guides/use-the-console-operator">Use the Console Operator</a></td></tr><tr><td><h3><i class="fa-robot" style="color:$primary;">:robot:</i></h3></td><td><h4><strong>Create an agent</strong></h4></td><td>Build, configure, test, export, and manage agents.</td><td><a href="/ai-workbench-qore/task-guides/create-an-agent">Create an agent</a></td></tr><tr><td><h3><i class="fa-diagram-project" style="color:$primary;">:diagram-project:</i></h3></td><td><h4><strong>Create a flow</strong></h4></td><td>Build, test, and publish automations, and use them from agents.</td><td><a href="/ai-workbench-qore/task-guides/create-a-flow">Create a flow</a></td></tr><tr><td><h3><i class="fa-database" style="color:$primary;">:database:</i></h3></td><td><h4><strong>Create a knowledge base</strong></h4></td><td>Add sources, sync files, and test the answers agents get.</td><td><a href="/ai-workbench-qore/task-guides/create-a-knowledge">Create a knowledge</a></td></tr><tr><td><h3><i class="fa-layer-group" style="color:$primary;">:layer-group:</i></h3></td><td><h4><strong>Create a design system</strong></h4></td><td>Set a brand's style, logos, fonts, and colors for apps.</td><td><a href="/ai-workbench-qore/task-guides/create-a-design-system">Create a design system</a></td></tr><tr><td><h3><i class="fa-mobile" style="color:$primary;">:mobile:</i></h3></td><td><h4><strong>Create an app</strong></h4></td><td>Build, preview, check, publish, and manage apps.</td><td><a href="/ai-workbench-qore/task-guides/create-an-app">Create an app</a></td></tr><tr><td><h3><i class="fa-link" style="color:$primary;">:link:</i></h3></td><td><h4><strong>Integrate an agent</strong></h4></td><td>Attach an agent to an app you built in Qore, or embed it in an external app.</td><td><a href="/ai-workbench-qore/task-guides/integrate-an-agent">Integrate an agent</a></td></tr><tr><td><h3><i class="fa-plug" style="color:$primary;">:plug:</i></h3></td><td><h4><strong>Connect an integration</strong></h4></td><td>Connect a third-party service to your account from Integrations.</td><td><a href="/ai-workbench-qore/task-guides/how-to-connect-an-integration">Connect an integration</a></td></tr></tbody></table>

***

## <i class="fa-shield-halved">:shield-halved:</i> Control Center

Operate and govern apps and agents across the account.

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-user-shield" style="color:$primary;">:user-shield:</i></h3></td><td><h4><strong>Use the Governance Operator</strong></h4></td><td>Ask about the account, approve staged changes, schedule runs, and answer gates.</td><td><a href="/ai-workbench-qore/task-guides/use-the-governance-operator">Use the Governance Operator</a></td></tr><tr><td><h3><i class="fa-chart-line" style="color:$primary;">:chart-line:</i></h3></td><td><h4><strong>Monitor activity</strong></h4></td><td>Trace runs, read analytics, audit changes, inspect logs, and export or report.</td><td><a href="/ai-workbench-qore/task-guides/monitor-activity">Monitor activity</a></td></tr><tr><td><h3><i class="fa-wallet" style="color:$primary;">:wallet:</i></h3></td><td><h4><strong>Manage costs and limits</strong></h4></td><td>Review credit usage and history, set hard limits, and get alerts.</td><td><a href="/ai-workbench-qore/task-guides/manage-costs-and-limits">Manage costs and limits</a></td></tr><tr><td><h3><i class="fa-clipboard-check" style="color:$primary;">:clipboard-check:</i></h3></td><td><h4><strong>Evaluate agent quality</strong></h4></td><td>Create evaluators, score live traffic, and review low-confidence results.</td><td><a href="/ai-workbench-qore/task-guides/evaluate-agent-quality">Evaluate agent quality</a></td></tr><tr><td><h3><i class="fa-scale-balanced" style="color:$primary;">:scale-balanced:</i></h3></td><td><h4><strong>Govern agents and models</strong></h4></td><td>Stop agents, review connectors, load a governed graph, and configure AI Gateway.</td><td><a href="/ai-workbench-qore/task-guides/govern-agents-and-models">Govern agents and models</a></td></tr><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Manage users and access</strong></h4></td><td>Invite people, set roles, organize teams, manage sign-in, and issue API keys.</td><td><a href="/ai-workbench-qore/task-guides/manage-users-and-access">Manage users and access</a></td></tr></tbody></table>

To see which roles can do each task, see [Roles and tasks](/ai-workbench-qore/roles-and-tasks). For what each screen and setting does, see [Platform Reference](/ai-workbench-qore/platform-reference). For answers to common questions, see the [Help Center](/ai-workbench-qore/help).

***

{% 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 %}


# Roles and tasks

Which roles can do each task in Qore, by module, mapped from the Roles capability matrix.

This page maps each task to the role capability it needs, and shows which of the eight standard roles have it. It also shows the Qore proficiency level needed for each role. Every check mark comes from the capability matrix on [Roles](/ai-workbench-qore/control-center/admin/roles). Where a task guide covers the task, the task links to it.

* A person can hold several roles in one account; their capabilities add up.
* Roles are held per account membership: a role in one account doesn't carry into another.
* A role applies across every project in its account. **Organisation Admin**'s tenant-level capabilities reach every account.
* Roles created in your organization appear under **Custom Roles** in **Admin** › **Roles** and aren't shown here.

## Qore roles

<details>

<summary>How Qore proficiency levels work</summary>

Stars show the Qore expertise needed for the role. They don't measure individual performance.

| Stars | Level             |
| :---: | ----------------- |
| ★☆☆☆☆ | Foundation        |
| ★★☆☆☆ | Working knowledge |
| ★★★☆☆ | Proficient        |
| ★★★★☆ | Advanced          |
| ★★★★★ | Expert            |

</details>

<table><thead><tr><th data-type="number">S. No</th><th>Role</th><th>Primary responsibility</th><th data-type="rating" data-max="5">Qore proficiency level</th></tr></thead><tbody><tr><td>1</td><td><strong>Viewer</strong></td><td>Use published apps, agents, knowledge bases, and flows in a project without building anything.</td><td>1</td></tr><tr><td>2</td><td><strong>Billing Manager</strong></td><td>Viewer, plus review credit usage and set credit limits.</td><td>2</td></tr><tr><td>3</td><td><strong>Approver</strong></td><td>Viewer, plus review and approve the publishing of agents, apps, knowledge, and knowledge graphs.</td><td>2</td></tr><tr><td>4</td><td><strong>Developer</strong></td><td>Build, publish, and version apps, agents, knowledge bases, flows, and design systems in projects.</td><td>3</td></tr><tr><td>5</td><td><strong>Governance Manager</strong></td><td>Oversee knowledge, observability, evaluations, govern graphs, and resource permissions for the account.</td><td>4</td></tr><tr><td>6</td><td><strong>Auditor</strong></td><td>Inspect traces, analytics, audit logs, reports, credit usage, and controls, without changing them.</td><td>3</td></tr><tr><td>7</td><td><strong>Account Admin</strong></td><td>Administer one account: its members, teams, API keys, AI Gateway, cost controls, and governance.</td><td>4</td></tr><tr><td>8</td><td><strong>Organisation Admin</strong></td><td>Account Admin, plus three tenant-level capabilities that reach every account: create accounts, and manage the organization's brand and roles.</td><td>5</td></tr><tr><td>9</td><td><strong>Custom Role</strong></td><td>Coming Soon</td><td>null</td></tr></tbody></table>

> **How to read the role matrix:** **Billing Mgr** means Billing Manager. **Dev** means Developer. **Gov Mgr** means Governance Manager. **Acct Admin** means Account Admin. **Org Admin** means Organisation Admin. ✓ means the role has the capability. — means it doesn't.

## Console

### Accounts and projects

Accounts and projects are chosen from the account and project switcher at the top of the Console sidebar.

| Task                                                                            | Capability        | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ------------------------------------------------------------------------------- | ----------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Choose an account](/ai-workbench-qore/control-center/accounts#switch-accounts) | Select an account |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Choose a project](/ai-workbench-qore/console/projects#find-projects)           | Select a project  |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create a project](/ai-workbench-qore/console/projects#create-a-project)        | Create a project  |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |

Creating, renaming, and deleting accounts happens in **Org Settings**, not Console. See [Organisation-wide](#organisation-wide).

### Apps

| Task                                                                                                         | Capability                    | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Open and use apps](/ai-workbench-qore/task-guides/create-an-app#open-an-app-to-keep-working-on-it)          | View apps                     |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create an app from a prompt](/ai-workbench-qore/task-guides/create-an-app#create-an-app-from-a-chat-prompt) | Build an app                  |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Build an app from your IDE](/ai-workbench-qore/task-guides/create-an-app#build-the-app-from-my-own-ide)     | Build an app headless         |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Import an app](/ai-workbench-qore/task-guides/create-an-app#import-an-app-i-already-have)                   | Import an app                 |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Export an app](/ai-workbench-qore/task-guides/create-an-app#export-the-app)                                 | Export an app                 |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Publish an app](/ai-workbench-qore/task-guides/create-an-app#publish-the-app)                               | Publish an app                |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Share an app](/ai-workbench-qore/task-guides/create-an-app#share-the-app)                                   | Share an app                  |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Connect your own domain](/ai-workbench-qore/task-guides/create-an-app#connect-my-own-domain)                | Manage an app's custom domain |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Connect the app's code to Git](/ai-workbench-qore/task-guides/create-an-app#view-or-edit-the-app-code)      | Connect an app to Git         |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Go back to an earlier version](/ai-workbench-qore/task-guides/create-an-app#go-back-to-an-earlier-version)  | Manage app versions           |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Attach an agent to an app](/ai-workbench-qore/task-guides/integrate-an-agent#attach-an-agent-to-a-qore-app) | Attach an agent to an app     |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |

### Agents

| Task                                                                                                                                | Capability                        | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Open and view agents](/ai-workbench-qore/task-guides/create-an-agent#find-one-of-my-agents)                                        | View agents                       |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create an agent from a prompt](/ai-workbench-qore/task-guides/create-an-agent#create-an-agent-from-a-chat-prompt)                  | Build an agent                    |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Build agents from your IDE](/ai-workbench-qore/task-guides/create-an-agent#build-agents-from-my-own-ide)                           | Build an agent headless           |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Import an agent](/ai-workbench-qore/task-guides/create-an-agent#import-an-agent-i-already-have)                                    | Import an agent                   |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Export an agent](/ai-workbench-qore/task-guides/create-an-agent#export-the-agent)                                                  | Export an agent                   |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| Publish an agent                                                                                                                    | Publish an agent                  |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Try or run an agent](/ai-workbench-qore/task-guides/create-an-agent#try-the-agent)                                                 | Trigger an agent                  |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| Share an agent                                                                                                                      | Share an agent                    |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Save or switch versions](/ai-workbench-qore/task-guides/create-an-agent#save-or-switch-versions)                                   | Manage agent versions             |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Attach a governed graph to an agent](/ai-workbench-qore/task-guides/create-an-agent#attach-existing-knowledge-or-a-governed-graph) | Attach a govern graph to an agent |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |

### Knowledge

| Task                                                                                                               | Capability                | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| View datasets                                                                                                      | View data sources         |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create a dataset](/ai-workbench-qore/task-guides/create-a-knowledge#create-a-dataset)                             | Build a data source       |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| [View knowledge bases](/ai-workbench-qore/task-guides/create-a-knowledge#find-one-of-my-knowledge-bases)           | View knowledge            |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create a knowledge base](/ai-workbench-qore/task-guides/create-a-knowledge#create-a-knowledge-base-from-a-prompt) | Build knowledge           |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| Import knowledge                                                                                                   | Import knowledge          |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| Export knowledge                                                                                                   | Export knowledge          |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| Publish knowledge                                                                                                  | Publish knowledge         |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| [See knowledge versions](/ai-workbench-qore/task-guides/create-a-knowledge#see-knowledge-versions)                 | Manage knowledge versions |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| [Ask a knowledge base questions](/ai-workbench-qore/task-guides/create-a-knowledge#test-the-knowledge-base)        | Query knowledge           |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Share a knowledge base](/ai-workbench-qore/task-guides/create-a-knowledge#share-a-knowledge-base)                 | Share knowledge           |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |

### Flows

| Task                                                                                                                        | Capability                | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [View flows](/ai-workbench-qore/task-guides/create-a-flow#find-one-of-my-flows)                                             | View flows                |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create a flow](/ai-workbench-qore/task-guides/create-a-flow#create-a-flow-from-a-chat-prompt)                              | Build a flow              |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Publish a flow](/ai-workbench-qore/task-guides/create-a-flow#publish-the-flow)                                             | Publish a flow            |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Review versions or undo draft changes](/ai-workbench-qore/task-guides/create-a-flow#review-versions-or-undo-draft-changes) | Manage flow versions      |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| Run a flow                                                                                                                  | Trigger a flow            |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Add an Agent task to a flow](/ai-workbench-qore/task-guides/create-a-flow#add-a-task)                                      | Attach an agent to a flow |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |

### Store, integrations, design systems, and Document AI

| Task                                                                                                                             | Capability                    | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| Browse the Store                                                                                                                 | View the store                |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| Use integrations                                                                                                                 | Use integrations              |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Connect an integration](/ai-workbench-qore/task-guides/how-to-connect-an-integration)                                           | Manage integrations           |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [View design systems](/ai-workbench-qore/task-guides/create-a-design-system#find-one-of-my-design-systems)                       | View design systems           |    ✓   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create or change a design system](/ai-workbench-qore/task-guides/create-a-design-system#create-a-design-system-from-a-prompt)   | Manage design systems         |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |
| [Work with documents through the Document AI Agent](/ai-workbench-qore/task-guides/use-the-console-operator#work-with-documents) | Trigger the Document AI Agent |    —   |      —      |     —    |  ✓  |    —    |    —    |      ✓     |     ✓     |

## Control Center

### Observe

| Task                                                                                                           | Capability      | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| -------------------------------------------------------------------------------------------------------------- | --------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Find and inspect runs](/ai-workbench-qore/task-guides/monitor-activity#find-an-agent-or-app-run)              | View traces     |    —   |      ✓      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Read analytics](/ai-workbench-qore/task-guides/monitor-activity#see-account-wide-build-activity)              | View analytics  |    —   |      —      |     —    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |
| [See who changed what](/ai-workbench-qore/task-guides/monitor-activity#see-who-changed-what-in-the-account)    | View audit logs |    —   |      —      |     —    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Create and change exports](/ai-workbench-qore/task-guides/monitor-activity#export-activity-data)              | Manage exports  |    —   |      —      |     —    |  —  |    ✓    |    —    |      ✓     |     ✓     |
| [Run exports](/ai-workbench-qore/task-guides/monitor-activity#track-and-update-exports)                        | Run exports     |    —   |      —      |     —    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Review and email reports](/ai-workbench-qore/task-guides/monitor-activity#review-a-usage-or-execution-report) | View reports    |    —   |      —      |     —    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |

### Cost Control

| Task                                                                                                      | Capability        | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| --------------------------------------------------------------------------------------------------------- | ----------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [See credit usage](/ai-workbench-qore/task-guides/manage-costs-and-limits#see-available-and-used-credits) | View credit usage |    —   |      ✓      |     —    |  —  |    —    |    ✓    |      ✓     |     ✓     |
| [Set limits and alerts](/ai-workbench-qore/task-guides/manage-costs-and-limits#cap-credit-consumption)    | Set credit limits |    —   |      ✓      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |

### Evals

| Task                                                                                                      | Capability        | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| --------------------------------------------------------------------------------------------------------- | ----------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Create and assign evaluators](/ai-workbench-qore/task-guides/evaluate-agent-quality#create-an-evaluator) | Build evals       |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| [Read Online Eval scores](/ai-workbench-qore/task-guides/evaluate-agent-quality#read-the-scores)          | View online evals |    —   |      —      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |

### Govern

| Task                                                                                                                 | Capability                    | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [See which agents are running](/ai-workbench-qore/task-guides/govern-agents-and-models#see-which-agents-are-running) | View agent controls           |    —   |      —      |     —    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Stop one agent or every agent](/ai-workbench-qore/task-guides/govern-agents-and-models#stop-one-agent)              | Stop agents                   |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| Resume agents                                                                                                        | Resume agents                 |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| [Upload and manage governed graphs](/ai-workbench-qore/task-guides/govern-agents-and-models#upload-a-governed-graph) | Manage govern graphs          |    —   |      —      |     —    |  —  |    ✓    |    —    |      ✓     |     ✓     |
| [View governed graphs](/ai-workbench-qore/task-guides/govern-agents-and-models#explore-a-graph-and-trace-a-fact)     | View govern graphs            |    —   |      —      |     ✓    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |
| Manage agent tool permissions                                                                                        | Manage agent tool permissions |    —   |      —      |     —    |  —  |    ✓    |    —    |      ✓     |     ✓     |

### AI Gateway

| Task                                                                                                                               | Capability               | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Call the AI Gateway](/ai-workbench-qore/task-guides/govern-agents-and-models#call-the-ai-gateway-from-my-own-code)                | Use the AI Gateway       |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |
| [Configure families, keys, and tiers](/ai-workbench-qore/task-guides/govern-agents-and-models#review-the-ai-gateway-configuration) | Configure the AI Gateway |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |

### Admin

| Task                                                                                                    | Capability                  | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ------------------------------------------------------------------------------------------------------- | --------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [See who has access](/ai-workbench-qore/task-guides/manage-users-and-access#see-who-has-access)         | View user                   |    —   |      —      |     —    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| [Invite a person](/ai-workbench-qore/task-guides/manage-users-and-access#invite-a-person)               | Create user                 |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| [Change a person's roles](/ai-workbench-qore/task-guides/manage-users-and-access#change-a-person-roles) | Manage user                 |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| Remove a person                                                                                         | Remove a user               |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| View teams                                                                                              | View teams                  |    —   |      —      |     —    |  —  |    ✓    |    —    |      ✓     |     ✓     |
| [Create and manage teams](/ai-workbench-qore/task-guides/manage-users-and-access#create-a-team)         | Manage teams                |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| [Create and revoke API keys](/ai-workbench-qore/task-guides/manage-users-and-access#create-an-api-key)  | Manage API keys             |    —   |      —      |     —    |  —  |    —    |    —    |      ✓     |     ✓     |
| View resource permissions                                                                               | View resource permissions   |    —   |      —      |     —    |  —  |    ✓    |    ✓    |      ✓     |     ✓     |
| Manage resource permissions                                                                             | Manage resource permissions |    —   |      —      |     —    |  ✓  |    ✓    |    —    |      ✓     |     ✓     |

### Publish Review (coming soon)

| Task                               | Capability                         | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ---------------------------------- | ---------------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| View publish reviews               | View publish reviews               |    —   |      —      |     ✓    |  ✓  |    ✓    |    ✓    |      ✓     |     ✓     |
| Approve agent publishing           | Approve agent publishing           |    —   |      —      |     ✓    |  —  |    —    |    —    |      ✓     |     ✓     |
| Approve app publishing             | Approve app publishing             |    —   |      —      |     ✓    |  —  |    —    |    —    |      ✓     |     ✓     |
| Approve knowledge graph publishing | Approve knowledge graph publishing |    —   |      —      |     ✓    |  —  |    —    |    —    |      ✓     |     ✓     |
| Approve knowledge publishing       | Approve knowledge publishing       |    —   |      —      |     ✓    |  —  |    —    |    —    |      ✓     |     ✓     |

## Tenant

### Organisation-wide

These tasks are in **Org Settings**: select your avatar at the top right, then **Org Settings**.

| Task                                                                                                          | Capability                            | Viewer | Billing Mgr | Approver | Dev | Gov Mgr | Auditor | Acct Admin | Org Admin |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------- | :----: | :---------: | :------: | :-: | :-----: | :-----: | :--------: | :-------: |
| [Create an account](/ai-workbench-qore/control-center/accounts#create-an-account)                             | Create an account                     |    —   |      —      |     —    |  —  |    —    |    —    |      —     |     ✓     |
| [Rename an account](/ai-workbench-qore/control-center/accounts#rename-an-account)                             | Create an account                     |    —   |      —      |     —    |  —  |    —    |    —    |      —     |     ✓     |
| [Delete an account](/ai-workbench-qore/control-center/accounts#delete-an-account)                             | Create an account                     |    —   |      —      |     —    |  —  |    —    |    —    |      —     |     ✓     |
| [Set usage limits for an account](/ai-workbench-qore/control-center/accounts#set-usage-limits-for-an-account) | Create an account + Set credit limits |    —   |      —      |     —    |  —  |    —    |    —    |      —     |     ✓     |
| Manage the organization brand                                                                                 | Manage organization brand             |    —   |      —      |     —    |  —  |    —    |    —    |      —     |     ✓     |
| Manage organization roles                                                                                     | Manage organization roles             |    —   |      —      |     —    |  —  |    —    |    —    |      —     |     ✓     |

## Related pages

* [Roles](/ai-workbench-qore/control-center/admin/roles), for each capability's full definition, role comparisons, and FAQs
* [Manage users and access](/ai-workbench-qore/task-guides/manage-users-and-access), to assign roles and teams
* [Task Guides](/ai-workbench-qore/guides)

***

{% 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.666666666666657%" %}

<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="64"></div>
{% endcolumn %}
{% endcolumns %}


# Help Center

Find answers, guides, and FAQs for Qore.

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

{% endcolumn %}

{% column width="66.66666666666667%" %}
{% hint style="success" icon="sparkles" %}
**Docs updated for the October 4 release.** [See what's new](/ai-workbench-qore/release-notes/2026/october-4)
{% endhint %}
{% endcolumn %}

{% column width="16.666666666666657%" %}

{% endcolumn %}
{% endcolumns %}

<h2 align="center">What can we help you find?</h2>

<p align="center">Browse the topics below or ask the Qore Knowledge Assistant anything about Qore.</p>

<p align="center"><button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask the Qore Knowledge Assistant</button><a href="/ai-workbench-qore/help/faqs" class="button secondary" data-icon="circle-question">Browse FAQs</a><a href="/ai-workbench-qore/help/troubleshooting" class="button secondary" data-icon="screwdriver-wrench">Troubleshooting</a></p>

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-leaf" style="color:$primary;">:leaf:</i></h3></td><td><h4><strong>Getting started</strong></h4></td><td>Learn the basics</td><td><a href="/ai-workbench-qore/start-here/what-is-qore">What is Qore</a></td></tr><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Admin</strong></h4></td><td>Manage users, teams, roles, and API keys</td><td><a href="/ai-workbench-qore/control-center/admin">Admin</a></td></tr><tr><td><h3><i class="fa-plug" style="color:$primary;">:plug:</i></h3></td><td><h4><strong>Integrations</strong></h4></td><td>Extend your workflow</td><td><a href="/ai-workbench-qore/console/integrations-hub">Integrations Hub</a></td></tr><tr><td><h3><i class="fa-coins" style="color:$primary;">:coins:</i></h3></td><td><h4><strong>Usage and cost</strong></h4></td><td>Track credit consumption and set limits</td><td><a href="/ai-workbench-qore/control-center/cost-control">Cost Control</a></td></tr><tr><td><h3><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h3></td><td><h4><strong>Security</strong></h4></td><td>Review deployment and security controls</td><td><a href="/ai-workbench-qore/control-center/detailed-security-and-runtime-faq">Security FAQ</a></td></tr><tr><td><h3><i class="fa-bullhorn" style="color:$primary;">:bullhorn:</i></h3></td><td><h4><strong>Product updates</strong></h4></td><td>See what’s new</td><td><a href="/ai-workbench-qore/release-notes/2026">2026</a></td></tr></tbody></table>

{% columns %}
{% column %}

### Featured

{% hint style="info" icon="compass" %}
New to Qore? Start with what Qore is and how an agent works.

<a href="/ai-workbench-qore/start-here/what-is-qore" class="button primary">What is Qore</a><br>

<a href="/ai-workbench-qore/start-here/how-an-agent-works" class="button secondary">How Agents Work</a>
{% endhint %}

{% content-ref url="/pages/UZ0I8WFQSmaFybHZZPHu" %}
[Create an agent](/ai-workbench-qore/task-guides/create-an-agent)
{% endcontent-ref %}

{% content-ref url="/pages/hiGz69Lerudswwr0DCJX" %}
[Create an app](/ai-workbench-qore/task-guides/create-an-app)
{% endcontent-ref %}

{% content-ref url="/pages/c9LqRJACw0U64C4Joa5F" %}
[Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized)
{% endcontent-ref %}
{% endcolumn %}

{% column %}

### Common tasks

{% content-ref url="/pages/9C6OEk3EkReA8YZCE8P0" %}
[Users](/ai-workbench-qore/control-center/admin/users)
{% endcontent-ref %}

{% content-ref url="/pages/uhimZ4T9Wkbu8aUdJOiq" %}
[Single Sign-On](/ai-workbench-qore/control-center/admin/single-sign-on)
{% endcontent-ref %}

{% content-ref url="/pages/pVV6YSoD6otYUPRSln3p" %}
[API Keys](/ai-workbench-qore/control-center/admin/api-keys)
{% endcontent-ref %}

{% content-ref url="/pages/wPELRh7S7bFQEBJcJZVb" %}
[Connect an integration](/ai-workbench-qore/task-guides/how-to-connect-an-integration)
{% endcontent-ref %}

{% content-ref url="/pages/5f7BN7oNJaYMtU9svTGg" %}
[Plan](/ai-workbench-qore/console/app-builder/plan)
{% endcontent-ref %}
{% endcolumn %}

{% column %}

### Updated for October 4

{% content-ref url="/pages/TcXH67sJVQWqdwljSeni" %}
[October 4](/ai-workbench-qore/release-notes/2026/october-4)
{% endcontent-ref %}

{% content-ref url="/pages/343aaa4879c5a104577605f40e609d50bd458c53" %}
[Gateway Settings](/ai-workbench-qore/control-center/ai-gateway/gateway-settings)
{% endcontent-ref %}

{% content-ref url="/pages/uCF75JM6zHZBMr9ai2RG" %}
[Deployment options](/ai-workbench-qore/start-here/deployment-options)
{% endcontent-ref %}

{% content-ref url="/pages/6CB3ux2H16RPihpNE3qg" %}
[Integrations Hub](/ai-workbench-qore/console/integrations-hub)
{% endcontent-ref %}

{% content-ref url="/pages/I59HzEvpXa0tjAaqrtTo" %}
[Glossary](/ai-workbench-qore/start-here/glossary)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}

## FAQs and troubleshooting

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-circle-question" style="color:$primary;">:circle-question:</i></h3></td><td><h4><strong>FAQs</strong></h4></td><td>Answers to common questions, by module.</td><td><a href="/ai-workbench-qore/help/faqs">FAQs</a></td></tr><tr><td><h3><i class="fa-screwdriver-wrench" style="color:$primary;">:screwdriver-wrench:</i></h3></td><td><h4><strong>Troubleshooting</strong></h4></td><td>Fixes for common problems, by module and by task.</td><td><a href="/ai-workbench-qore/help/troubleshooting">Troubleshooting</a></td></tr><tr><td><h3><i class="fa-lock" style="color:$primary;">:lock:</i></h3></td><td><h4><strong>Restricted developer resources</strong></h4></td><td>Request access to API Cookbooks, API Reference, Platform Guides, and the Object Model.</td><td><a href="/ai-workbench-qore/help/developer-access">Developer access</a></td></tr><tr><td><h3><i class="fa-route" style="color:$primary;">:route:</i></h3></td><td><h4><strong>Task Guides</strong></h4></td><td>Step-by-step guides for every task.</td><td><a href="/ai-workbench-qore/guides">Task Guides</a></td></tr></tbody></table>

***

{% 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.666666666666657%" %}

<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="64"></div>
{% endcolumn %}
{% endcolumns %}


# FAQs

Answers to common questions about Qore, by module.

Find answers to common questions, by module. For a problem you're seeing now, see [Troubleshooting](/ai-workbench-qore/help/troubleshooting).

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Admin</strong></h4></td><td>Users, sign-in, roles, teams, and API keys.</td><td><a href="/ai-workbench-qore/control-center/admin/admin-faqs-and-troubleshooting#faqs">Admin: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-id-badge" style="color:$primary;">:id-badge:</i></h3></td><td><h4><strong>Roles</strong></h4></td><td>What each role can do.</td><td><a href="/ai-workbench-qore/control-center/admin/roles#faqs">Roles</a></td></tr><tr><td><h3><i class="fa-database" style="color:$primary;">:database:</i></h3></td><td><h4><strong>Knowledge</strong></h4></td><td>Knowledge bases, datasets, sync, versions, and search.</td><td><a href="/ai-workbench-qore/console/knowledge/faqs">Knowledge: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-diagram-project" style="color:$primary;">:diagram-project:</i></h3></td><td><h4><strong>Flows</strong></h4></td><td>Building, starting, and publishing flows.</td><td><a href="/ai-workbench-qore/console/flows/flows-faqs-and-troubleshooting#faqs">Flows: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-file-export" style="color:$primary;">:file-export:</i></h3></td><td><h4><strong>Export Agent</strong></h4></td><td>What an agent package holds, and importing it.</td><td><a href="/ai-workbench-qore/console/agent-builder/deploy/export-agent#faqs">Export Agent</a></td></tr><tr><td><h3><i class="fa-diagram-nodes" style="color:$primary;">:diagram-nodes:</i></h3></td><td><h4><strong>Governed Graph</strong></h4></td><td>Obligation links and relationship counts in a loaded graph.</td><td><a href="/ai-workbench-qore/control-center/govern/governed-graph#faq">Governed Graph</a></td></tr><tr><td><h3><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h3></td><td><h4><strong>Security</strong></h4></td><td>Deployment, data, and runtime security.</td><td><a href="/ai-workbench-qore/control-center/detailed-security-and-runtime-faq#frequently-asked-questions">Security FAQ</a></td></tr><tr><td><h3><i class="fa-gauge-high" style="color:$primary;">:gauge-high:</i></h3></td><td><h4><strong>Usage limits</strong></h4></td><td>Credit spending caps and threshold alerts.</td><td><a href="/ai-workbench-qore/control-center/cost-control/usage-limits">Usage Limits</a></td></tr><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Console Operator</strong></h4></td><td>Conversations, agents and connections, schedules, and Gates.</td><td><a href="/ai-workbench-qore/console/console-operator/console-operator-faqs-and-troubleshooting#faqs">Console Operator: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-robot" style="color:$primary;">:robot:</i></h3></td><td><h4><strong>Agent Builder</strong></h4></td><td>Building, versions, skills, keys, and authentication.</td><td><a href="/ai-workbench-qore/console/agent-builder/agent-builder-faqs-and-troubleshooting#faqs">Agent Builder: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-window-maximize" style="color:$primary;">:window-maximize:</i></h3></td><td><h4><strong>App Builder</strong></h4></td><td>Modes, importing, versions, and publishing.</td><td><a href="/ai-workbench-qore/console/app-builder/app-builder-faqs-and-troubleshooting#faqs">App Builder: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-plug" style="color:$primary;">:plug:</i></h3></td><td><h4><strong>Integrations Hub</strong></h4></td><td>Connecting integrations and credential models.</td><td><a href="/ai-workbench-qore/console/integrations-hub/integrations-hub-faqs-and-troubleshooting#faqs">Integrations Hub: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-swatchbook" style="color:$primary;">:swatchbook:</i></h3></td><td><h4><strong>Design Systems</strong></h4></td><td>Scope, versions, fonts, and logos.</td><td><a href="/ai-workbench-qore/console/design-systems#faqs">Design Systems</a></td></tr><tr><td><h3><i class="fa-store" style="color:$primary;">:store:</i></h3></td><td><h4><strong>Store</strong></h4></td><td>Store agents and apps, and where they're available.</td><td><a href="/ai-workbench-qore/console/store/store-faqs-and-troubleshooting#faqs">Store: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-user-shield" style="color:$primary;">:user-shield:</i></h3></td><td><h4><strong>Governance Operator</strong></h4></td><td>Staged changes, scope, and schedules.</td><td><a href="/ai-workbench-qore/control-center/governance-operator#faqs">Governance Operator</a></td></tr><tr><td><h3><i class="fa-chart-line" style="color:$primary;">:chart-line:</i></h3></td><td><h4><strong>Observe</strong></h4></td><td>Traces, analytics, logs, exports, and reports.</td><td><a href="/ai-workbench-qore/control-center/observe/observe-faqs-and-troubleshooting#faqs">Observe: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-wallet" style="color:$primary;">:wallet:</i></h3></td><td><h4><strong>Cost Control</strong></h4></td><td>Credit usage, limits, and alerts.</td><td><a href="/ai-workbench-qore/control-center/cost-control/cost-control-faqs-and-troubleshooting#faqs">Cost Control: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-clipboard-check" style="color:$primary;">:clipboard-check:</i></h3></td><td><h4><strong>Evals</strong></h4></td><td>Evaluators, scores, routing, and Human Review.</td><td><a href="/ai-workbench-qore/control-center/evals/evals-faqs-and-troubleshooting#faqs">Evals: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h3></td><td><h4><strong>Govern</strong></h4></td><td>Agent Controls, Connectors, and Governed Graph.</td><td><a href="/ai-workbench-qore/control-center/govern/govern-faqs-and-troubleshooting#faqs">Govern: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-network-wired" style="color:$primary;">:network-wired:</i></h3></td><td><h4><strong>AI Gateway</strong></h4></td><td>Families, tiers, keys, and billing.</td><td><a href="/ai-workbench-qore/control-center/ai-gateway/ai-gateway-faqs-and-troubleshooting#faqs">AI Gateway: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-book" style="color:$primary;">:book:</i></h3></td><td><h4><strong>Glossary</strong></h4></td><td>Terms used across Qore.</td><td><a href="/ai-workbench-qore/start-here/glossary">Glossary</a></td></tr></tbody></table>

Can't find it? Ask the Qore Knowledge Assistant from the [Help Center](/ai-workbench-qore/help).

***

{% 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 %}


# Troubleshooting

Fixes for common problems in Qore, by module and by task.

Find the fix for a problem you're seeing. For general questions, see [FAQs](/ai-workbench-qore/help/faqs).

## By module

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Admin</strong></h4></td><td>Sign-in, teams, API keys, and roles.</td><td><a href="/ai-workbench-qore/control-center/admin/admin-faqs-and-troubleshooting#troubleshooting">Admin: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-database" style="color:$primary;">:database:</i></h3></td><td><h4><strong>Knowledge</strong></h4></td><td>Failed syncs, rate limits, and stuck files.</td><td><a href="/ai-workbench-qore/console/knowledge/faqs#troubleshooting">Knowledge: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-triangle-exclamation" style="color:$primary;">:triangle-exclamation:</i></h3></td><td><h4><strong>Knowledge processing</strong></h4></td><td>When a file fails to process, and retries.</td><td><a href="/ai-workbench-qore/console/knowledge#when-processing-fails">Knowledge</a></td></tr><tr><td><h3><i class="fa-diagram-project" style="color:$primary;">:diagram-project:</i></h3></td><td><h4><strong>Flows</strong></h4></td><td>Warnings, paused runs, and unexpected results.</td><td><a href="/ai-workbench-qore/console/flows/flows-faqs-and-troubleshooting#troubleshooting">Flows: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-file-export" style="color:$primary;">:file-export:</i></h3></td><td><h4><strong>Export Agent</strong></h4></td><td>Missing emails, expired links, and imports.</td><td><a href="/ai-workbench-qore/console/agent-builder/deploy/export-agent#troubleshooting">Export Agent</a></td></tr><tr><td><h3><i class="fa-code" style="color:$primary;">:code:</i></h3></td><td><h4><strong>Integrate Agent</strong></h4></td><td>A widget that doesn't appear, and Unauthorized errors.</td><td><a href="/ai-workbench-qore/console/agent-builder/deploy/agent-integration#troubleshooting">Integrate Agent</a></td></tr><tr><td><h3><i class="fa-puzzle-piece" style="color:$primary;">:puzzle-piece:</i></h3></td><td><h4><strong>Adding a skill</strong></h4></td><td>Skills the agent doesn't use, or that fail at runtime.</td><td><a href="/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent#common-issues-and-troubleshooting">Adding a skill to the agent</a></td></tr><tr><td><h3><i class="fa-book-open" style="color:$primary;">:book-open:</i></h3></td><td><h4><strong>Attaching knowledge</strong></h4></td><td>A Done button that stays disabled, and knowledge the agent doesn't use.</td><td><a href="/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent#common-issues-and-troubleshooting">Attaching Knowledge to an Agent</a></td></tr><tr><td><h3><i class="fa-rocket" style="color:$primary;">:rocket:</i></h3></td><td><h4><strong>Publishing an app</strong></h4></td><td>Publishing Failed, Fix with AI, and the deploy log.</td><td><a href="/ai-workbench-qore/console/app-builder/deploy#resolve-a-failed-publish">Deploy</a></td></tr><tr><td><h3><i class="fa-flask" style="color:$primary;">:flask:</i></h3></td><td><h4><strong>App tests</strong></h4></td><td>A build that fails its tests.</td><td><a href="/ai-workbench-qore/console/app-builder/testing#if-a-build-fails-its-tests">Testing</a></td></tr><tr><td><h3><i class="fa-diagram-nodes" style="color:$primary;">:diagram-nodes:</i></h3></td><td><h4><strong>Governed Graph</strong></h4></td><td>A graph upload that failed.</td><td><a href="/ai-workbench-qore/control-center/govern/governed-graph#troubleshooting">Governed Graph</a></td></tr><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Console Operator</strong></h4></td><td>Agents it won't use, missing connections, and schedules.</td><td><a href="/ai-workbench-qore/console/console-operator/console-operator-faqs-and-troubleshooting#troubleshooting">Console Operator: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-robot" style="color:$primary;">:robot:</i></h3></td><td><h4><strong>Agent Builder</strong></h4></td><td>Skills, MCP servers, knowledge, widget, API, and tokens.</td><td><a href="/ai-workbench-qore/console/agent-builder/agent-builder-faqs-and-troubleshooting#troubleshooting">Agent Builder: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-window-maximize" style="color:$primary;">:window-maximize:</i></h3></td><td><h4><strong>App Builder</strong></h4></td><td>Stalled builds, preview errors, failed tests, and publishes.</td><td><a href="/ai-workbench-qore/console/app-builder/app-builder-faqs-and-troubleshooting#troubleshooting">App Builder: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-plug" style="color:$primary;">:plug:</i></h3></td><td><h4><strong>Integrations Hub</strong></h4></td><td>Disabled Connect buttons, OAuth, and unusable connections.</td><td><a href="/ai-workbench-qore/console/integrations-hub/integrations-hub-faqs-and-troubleshooting#troubleshooting">Integrations Hub: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-swatchbook" style="color:$primary;">:swatchbook:</i></h3></td><td><h4><strong>Design Systems</strong></h4></td><td>Apps that don't change, fonts, and restores.</td><td><a href="/ai-workbench-qore/console/design-systems#troubleshooting">Design Systems</a></td></tr><tr><td><h3><i class="fa-store" style="color:$primary;">:store:</i></h3></td><td><h4><strong>Store</strong></h4></td><td>Listings you can't find.</td><td><a href="/ai-workbench-qore/console/store/store-faqs-and-troubleshooting#troubleshooting">Store: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-user-shield" style="color:$primary;">:user-shield:</i></h3></td><td><h4><strong>Governance Operator</strong></h4></td><td>Changes that don't happen, and schedules.</td><td><a href="/ai-workbench-qore/control-center/governance-operator#troubleshooting">Governance Operator</a></td></tr><tr><td><h3><i class="fa-chart-line" style="color:$primary;">:chart-line:</i></h3></td><td><h4><strong>Observe</strong></h4></td><td>Empty traces, waiting runs, and missing exports.</td><td><a href="/ai-workbench-qore/control-center/observe/observe-faqs-and-troubleshooting#troubleshooting">Observe: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-wallet" style="color:$primary;">:wallet:</i></h3></td><td><h4><strong>Cost Control</strong></h4></td><td>Blocked requests, missing alerts, and limits that won't save.</td><td><a href="/ai-workbench-qore/control-center/cost-control/cost-control-faqs-and-troubleshooting#troubleshooting">Cost Control: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-clipboard-check" style="color:$primary;">:clipboard-check:</i></h3></td><td><h4><strong>Evals</strong></h4></td><td>Missing scores, failed runs, and empty review queues.</td><td><a href="/ai-workbench-qore/control-center/evals/evals-faqs-and-troubleshooting#troubleshooting">Evals: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-shield-halved" style="color:$primary;">:shield-halved:</i></h3></td><td><h4><strong>Govern</strong></h4></td><td>Stopping agents, connector access, and graph uploads.</td><td><a href="/ai-workbench-qore/control-center/govern/govern-faqs-and-troubleshooting#troubleshooting">Govern: FAQs &amp; Troubleshooting</a></td></tr><tr><td><h3><i class="fa-network-wired" style="color:$primary;">:network-wired:</i></h3></td><td><h4><strong>AI Gateway</strong></h4></td><td>Unsaved changes, unavailable models, and failed calls.</td><td><a href="/ai-workbench-qore/control-center/ai-gateway/ai-gateway-faqs-and-troubleshooting#troubleshooting">AI Gateway: FAQs &amp; Troubleshooting</a></td></tr></tbody></table>

## By task

Each task guide ends with its common issues.

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-user-gear" style="color:$primary;">:user-gear:</i></h3></td><td><h4><strong>Use the Console Operator</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/use-the-console-operator#common-issues">Use the Console Operator</a></td></tr><tr><td><h3><i class="fa-robot" style="color:$primary;">:robot:</i></h3></td><td><h4><strong>Create an agent</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/create-an-agent#common-issues">Create an agent</a></td></tr><tr><td><h3><i class="fa-diagram-project" style="color:$primary;">:diagram-project:</i></h3></td><td><h4><strong>Create a flow</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/create-a-flow#common-issues">Create a flow</a></td></tr><tr><td><h3><i class="fa-database" style="color:$primary;">:database:</i></h3></td><td><h4><strong>Create a knowledge base</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/create-a-knowledge#common-issues">Create a knowledge</a></td></tr><tr><td><h3><i class="fa-layer-group" style="color:$primary;">:layer-group:</i></h3></td><td><h4><strong>Create a design system</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/create-a-design-system#common-issues">Create a design system</a></td></tr><tr><td><h3><i class="fa-mobile" style="color:$primary;">:mobile:</i></h3></td><td><h4><strong>Create an app</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/create-an-app#common-issues">Create an app</a></td></tr><tr><td><h3><i class="fa-link" style="color:$primary;">:link:</i></h3></td><td><h4><strong>Integrate an agent</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/integrate-an-agent#common-issues">Integrate an agent</a></td></tr><tr><td><h3><i class="fa-plug" style="color:$primary;">:plug:</i></h3></td><td><h4><strong>Connect an integration</strong></h4></td><td>Common issues, with fixes.</td><td><a href="/ai-workbench-qore/task-guides/how-to-connect-an-integration#common-issues">Connect an integration</a></td></tr></tbody></table>

Still stuck? From an agent or app builder, select **?** › **Need Help? Raise a Request**, or ask the Qore Knowledge Assistant from the [Help Center](/ai-workbench-qore/help).

***

{% 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 %}


# Developer access

Request portal access for API Cookbooks, API Reference, Platform Guides, and the Object Model.

Some developer resources are available only in the Qore documentation portal. They support secure, consistent integrations with the platform.

{% hint style="info" %}
**Access is available on request.** Request access to receive login details for the documentation portal.
{% endhint %}

### Available resources

| Resource            | What it covers                                                                | Why it matters                                               |
| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **API Cookbooks**   | Task-based examples for common API integrations.                              | Start with proven implementation patterns.                   |
| **API Reference**   | API endpoints, request and response formats, and authentication requirements. | Build requests that match the platform contract.             |
| **Platform Guides** | Implementation guidance for platform services, workflows, and integrations.   | Connect platform capabilities to your applications reliably. |
| **Object Model**    | The platform's core objects, fields, and relationships.                       | Map your data correctly across integrations.                 |

### Request access

Request access to the documentation portal. We provide login details after your request is approved.

{% hint style="warning" %}
You must sign in before you can access these resources.
{% endhint %}

***

{% 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 %}


# Feedback

Tell us whether a page helped you, and add details so we can improve it.

Every page in the Qore docs has a feedback form. Use it to tell us whether the page helped you, and what was missing or unclear. You can also use it to report an incorrect answer from [Ask Assistant](/ai-workbench-qore/ask-assistant).

### Where to find it

The feedback form is on the right side of every page, below **On this page**. It starts with the question **Was this helpful?**

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-330c4af0c5ab1f04300010f2e94f70f7682f3672%2F001_page_feedback.png?alt=media" alt="A Qore docs page with the right-hand panel highlighted: On this page lists the page sections, and below it Was this helpful? shows three reactions, with the smiling face selected and a comment box reading Anything you&#x27;d like to add? above a Submit button"><figcaption><p>The feedback form sits below On this page on every doc page.</p></figcaption></figure>

### Give feedback

{% stepper %}
{% step %}

### Choose a reaction

Under **Was this helpful?**, select the reaction that matches your experience.

| Reaction      | Meaning     |
| ------------- | ----------- |
| Smiling face  | Yes, it was |
| Neutral face  | Not sure    |
| Frowning face | No          |
| {% endstep %} |             |

{% step %}

### Add details

A comment box opens. In **Anything you'd like to add?**, describe what helped, or what was missing or unclear.
{% endstep %}

{% step %}

### Submit

Select **Submit**.
{% endstep %}
{% endstepper %}

### How we use your feedback

Your feedback is an important way for us to improve the Qore docs. We review the feedback we receive and evaluate it. When it shows that a page needs to change, we update the page.

***

{% 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 %}


# Ask Assistant

Ask questions about the Qore docs and get answers that link to the pages they come from.

The assistant answers your questions from the Qore and Document AI documentation on this site, and links to the pages it uses.

{% hint style="info" %}
**Beta.** The assistant is a Beta feature. AI responses may contain mistakes. If an answer is wrong or doesn't match the docs, tell us using the [feedback form](/ai-workbench-qore/feedback).
{% endhint %}

### Open the assistant

Select **Ask** at the top of the site, next to search. The assistant opens in a panel on the right side of the page you're reading.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-9b84cdbe8eae7fa0d380438adcd4d56563231cdf%2F001_assistant_panel.png?alt=media" alt="The GitBook Assistant panel open on the right of the Accounts, Projects, Spaces page: the greeting from the Qore Knowledge Assistant, five suggested questions starting with What is Qore?, and the Ask, search, or explain… input with Based on your context and Send below it"><figcaption><p>The assistant opens beside the page you're reading.</p></figcaption></figure>

### How it can help

* **Answers questions about the docs.** Ask in your own words, in the **Ask, search, or explain…** box, then select **Send**.
* **Links to its sources.** Each answer links to the pages it used, so you can read the full page.
* **Suggests where to start.** Select one of the suggested questions below the greeting to ask it.

### How it works

The assistant uses AI and your context to generate answers. To see what context it uses, hover over **Based on your context** below the input box. It uses:

* **The page you're on now.** You can ask about the page you're reading without naming it.
* **Info about you provided by the site.**
* **Messages in your conversation.** You can ask follow-up questions that build on earlier answers.

### Report an incorrect answer

The assistant is in Beta, and your feedback helps us improve it. If it gives an answer that's incorrect, or that doesn't match what the docs say, use the [feedback form](/ai-workbench-qore/feedback) to tell us. Describe the question you asked and what was wrong with the answer.

***

{% 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 %}


# What is Qore

High-Velocity Building with Enterprise Control

Qore provides a cloud-native launchpad that helps you move from an idea to a live application with minimal friction. Qore handles environment configuration and dependencies, and you keep full ownership of your security.

Your cloud-native launchpad is deployed within your bank’s network boundaries. No transactional data ever leaves your controlled VPC. See the [Security FAQ](/ai-workbench-qore/control-center/detailed-security-and-runtime-faq). For the cloud providers Qore runs on, see [Deployment options](/ai-workbench-qore/start-here/deployment-options).

> **Sign-in**: People sign in with **Google**, with **Microsoft** (including Microsoft Entra ID work and school accounts), or with email and password. Each single sign-on method is turned on per deployment. Access is invite-only: an administrator invites each person before they can sign in, whichever method they use. See [Single Sign-On](/ai-workbench-qore/control-center/admin/single-sign-on).

## Sharing & Collaboration

Qore makes it easy to bring the right people into the build at the right time.

* **Collaborator Invites**: Invite teammates directly by email. A collaborator joins the account and can open, edit and publish its apps — see [Plan](/ai-workbench-qore/console/app-builder/plan#collaboration) for what that covers before you invite someone.

## Meet the Builders: Your Intelligent Ecosystem

The power of Qore lies in how the three core pillars work together. Think of them as the components of a high-performance vehicle:

| **The Pillar**       | **Your Strategic Advantage**                                                                                                             | **The Analogy**                                                                                                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. App Builder**   | **The Interface:** Design the complete, user-facing experience where the human interaction happens.                                      | **The Car Body:** The sleek look and feel that users interact with.                                                                                                                      |
| **2. Agent Builder** | **The Intelligence:** Create the "brain"—the reasoning engine that manages knowledge and decides the next move.                          | **The Driver:** The smart core that knows where to go and how to get there.                                                                                                              |
| **3. Skill Library** | **The Capabilities:** Providing the individual, reusable actions (API calls, code, MCP servers, document processing) the Agent executes. | **The Toolbox:** Your direct line to the world. Whether it’s a built-in skill or a **custom-connected Third-Party API,** your agent has the muscle to interact with any external system. |

### Around the builders

| Area                                                                | What it does                                                                                                                                                                                             |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Knowledge**](/ai-workbench-qore/console/knowledge)               | Turns source documents into knowledge bases that agents query. A knowledge base changes only when you sync it, and each sync creates a new knowledge version.                                            |
| [**Flows**](/ai-workbench-qore/console/flows)                       | Builds a fixed, multi-step process that an agent can run as a single skill.                                                                                                                              |
| [**Design Systems**](/ai-workbench-qore/console/design-systems)     | Holds a project's shared visual identity, which the apps you build use.                                                                                                                                  |
| [**Console Operator**](/ai-workbench-qore/console/console-operator) | The chat surface in Console. Describe a goal, and it plans the work and hands each part to the right agent. It can also run on a schedule.                                                               |
| [**Control Center**](/ai-workbench-qore/start-here/control-center)  | Monitors and governs the whole account: AI Gateway, observability, evals, guardrails, cost, and access. Its **Governance Operator** answers account-wide questions and stages changes for your approval. |

## How It All Converges

### The Lending Example

In Qore, AI isn't a standalone tool; it’s a collaborative ecosystem. Here’s how a standard **Loan Origination** workflow comes to life:

{% stepper %}
{% step %}

#### The user interacts with the app

A Relationship Manager opens your custom Loan App to start a new file.
{% endstep %}

{% step %}

#### The app activates the agent

The interface sends a request to the Agent, such as *"Collect and verify docs for the Smith file"*.
{% endstep %}

{% step %}

#### The agent orchestrates the skills

The Agent maps the execution with its reasoning engine:

1. Use the **Classify Document** skill to identify each uploaded file.
2. Use an **Extract Document Data** skill to pull the fields it needs. With **Sensitive Data Masking** turned on, detected PII is replaced with tokens before it reaches a model.
3. Use an **API Call** skill to push verified data into your core banking system.
   {% endstep %}
   {% endstepper %}

**The Result:** You’ve transformed a fragmented, manual process into a unified, outcome-driven machine.

***

{% 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 %}


# How Agents Work

What an agent is, and the order you build one in.

An AI agent is a software-based digital worker that understands goals, makes decisions, and takes actions to complete tasks. Unlike a chatbot, which mainly generates responses, an agent reasons through problems, reads knowledge you give it, uses tools and integrations, and interacts with external systems — databases, APIs, enterprise applications — with minimal human intervention, while still allowing human oversight where you want it.

This page walks through building one, in the order you actually do it. Each step links to the concept behind it and the screen that configures it.

## 1. Describe what you want the agent to do

Start with a plain-language description of the task. Be specific about what the agent should accomplish — the more context you give, the less manual configuration you'll do afterwards. You don't need to know which settings to use yet.

{% hint style="info" %}
**What Qore does:** The Agent Builder analyses your prompt to pre-fill the agent's name, output format, and an initial skill set. Treat it as a first draft you'll review, not a finished agent.
{% endhint %}

## 2. Confirm how the agent identifies and responds

Review the suggested name and description, and choose the **Agent Output Format** that matches who — or what — receives the responses: `Markdown` for humans reading in a UI, `Json` when your application parses the output.

{% hint style="info" %}
**What Qore does:** Name and description are metadata for builders; they don't change how the agent behaves. Output format is a contract with whatever consumes the response.
{% endhint %}

→ [Basic Details](/ai-workbench-qore/console/agent-builder/build/basic-details)

## 3. Choose the runtime version

New agents are pinned to the latest executor version your tenant supports. Existing agents stay on the version they were created with unless you change it deliberately — the platform won't force an upgrade. Move to a newer version when you want a capability it introduces.

{% hint style="info" %}
**What Qore does:** The executor changes over time — new versions add capabilities, fix issues, and sometimes deprecate older behaviors. Switching versions can change agent behavior and the set of features available, so re-test after you do.
{% endhint %}

→ [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning)

## 4. Set how the agent thinks

Three levers, all on one screen, all with sensible defaults:

* **Agent Capability** (`Auto`, `Intelligent Planner`, `Next Best Step`, or `Fast`; default `Auto`) — how deeply the agent thinks about each request. `Auto` lets the platform decide per request. `Fast` leaves out persona memory, FAQ memory, and learning cases for lower latency.
* **Response Mode** (`Advanced`, `Balanced`, or `Flash`; default `Advanced`) — the speed-versus-quality trade-off.
* **Execution Model** and **Planning Model** — which model runs the agent, and which one plans its work. They can differ. Both are chosen in `Advanced` mode, from the models AI Gateway serves for your organization.

{% hint style="info" %}
**What Qore does:** Planning happens once per request; execution may run many tool calls. That's why the two models are separate — a common pattern is a heavier model for planning and a lighter one for execution.
{% endhint %}

→ [Steering & Reasoning](/ai-workbench-qore/core-concepts/steering-and-reasoning) · [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior)

## 5. Decide what the agent remembers

Both memory settings are under **Agent Config → Reinforcement Learning**, and both are off on a new agent.

**User persona memory** (**Enable User Persona**) lets the agent remember what an individual user has asked about, preferred, or corrected, across conversations.

**FAQ memory** (**Enable FAQ**) lets the agent reuse a stored answer when a question matches a known FAQ.

→ [Memory & Learning](/ai-workbench-qore/core-concepts/memory-and-learning) · [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings)

## 6. Remove capabilities the agent doesn't need

The platform attaches a set of skills to every agent by default. Read that list and disable anything your agent won't use — keeping unused skills active widens the range of things the agent can do wrong.

{% hint style="info" %}
**What Qore does:** Platform-supplied skills are attached automatically and can be individually disabled without affecting the ones that remain.
{% endhint %}

→ [Skills & Tools](/ai-workbench-qore/core-concepts/skills-and-tools) · [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities)

## 7. Connect the tools and data the agent needs

For each external system the agent must reach, attach the right kind of skill: an **API call** for REST endpoints and an **MCP server** for tool platforms. For document search, attach a **knowledge base**. Configure endpoints, authentication, and schemas for each.

→ [Adding a Skill to the Agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent) · [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools) · [Knowledge & Context](/ai-workbench-qore/core-concepts/knowledge-and-context)

## 8. Decide which guardrails the agent runs

Open **Agent Config → Guardrails** and choose the per-agent controls:

* **Sensitive Data Masking** replaces detected PII with tokens before it reaches a model.
* **Tool Execution Approval** pauses the agent before selected skills run, so the user can allow or deny each call.

{% hint style="info" %}
**What Qore does:** **Allowed LLM Families** and **Allowed LLM Providers** are always enforced. AI Gateway applies them to every model request, and your organization sets them, not the agent.
{% endhint %}

→ [Guardrails & Validation](/ai-workbench-qore/core-concepts/guardrails-and-validation) · [Guardrails (Beta)](/ai-workbench-qore/console/agent-builder/deploy/guardrails)

## 9. Test whether it behaves as intended

Use **Try Agent** to run sample inputs that represent real usage. Open the **execution trace** to see how the agent interpreted your instructions, which skills it called, and how long each step took. If something's off — wrong skill, unexpected output — adjust and re-test before moving on.

{% hint style="info" %}
**What Qore does:** The execution trace is for builders. End users see only the final response.
{% endhint %}

→ [Test](/ai-workbench-qore/console/agent-builder/test) · [Evals](/ai-workbench-qore/console/agent-builder/test/evals)

## 10. Go live, and keep it improving

Once the agent performs on your test cases, deploy it. Then review what it actually does in production: approve corrections that represent genuine improvements, reject anything incorrect or exploitable, and iterate as edge cases emerge.

{% hint style="warning" %}
**What Qore does:** Learning cases require manual approval before they enter agent memory. Auto-approval is intentionally disabled, so a malicious or mistaken input cannot quietly corrupt the agent's behavior.
{% endhint %}

→ [Deploy](/ai-workbench-qore/console/agent-builder/deploy) · [Monitor](/ai-workbench-qore/console/agent-builder/monitor) · [Human-in-the-Loop](/ai-workbench-qore/core-concepts/human-in-the-loop)

***

The loop closes: what you learn in step 10 becomes a change in steps 4 through 7. For the ideas behind each step, see [Agent Foundations](/ai-workbench-qore/start-here/core-concepts).

***

{% 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 Foundations

What an agent is, and the ideas the builder screens configure.

The [Agent Builder](/ai-workbench-qore/console/agent-builder) documents **what you do** — each screen, each field, each setting. This section documents **what an agent is**: the ideas those screens configure, and how they fit together.

Read a concept page when you want to understand *why* a setting exists and what it trades off. Read the builder page when you want to know what a specific control does and what its default is. Each concept links to the screens that configure it.

## The parts of an agent

An agent is a small number of things working together.

* [**Steering & Reasoning**](/ai-workbench-qore/core-concepts/steering-and-reasoning) — How the agent decides what to do. Instructions, autonomy, how deeply it thinks, and how the planner turns a request into a sequence of actions.
* [**Skills & Tools**](/ai-workbench-qore/core-concepts/skills-and-tools) — What the agent can *do*. The planner can only ever choose from this set.
* [**Knowledge & Context**](/ai-workbench-qore/core-concepts/knowledge-and-context) — What the agent can *read*. Retrieval from your documents, data, and governed graphs.
* [**Memory & Learning**](/ai-workbench-qore/core-concepts/memory-and-learning) — What the agent *carries forward*, across a conversation and across users.
* [**Guardrails & Validation**](/ai-workbench-qore/core-concepts/guardrails-and-validation) — The controls around a run: PII masking before model requests, approval before selected skills, and model policy.
* [**Human-in-the-Loop**](/ai-workbench-qore/core-concepts/human-in-the-loop) — The points where a person stays in the decision.
* [**Protocols**](/ai-workbench-qore/core-concepts/protocols) — How the agent talks to the outside world, and how your product talks to it.
* [**Evals**](/ai-workbench-qore/core-concepts/evals) — How the agent's output quality is scored, before release and on live traffic.

Beyond a single agent, an [**Operator**](/ai-workbench-qore/core-concepts/operator) coordinates a team of agents from one conversation, in Console and in Control Center.

## How they fit together

A request arrives. **Steering** decides how to approach it — the planner reads your instructions, uses **Memory** where it is turned on, and builds a plan. The plan calls **Skills**, which may retrieve from **Knowledge** or reach outside through **Protocols**. **Guardrails** mask PII before it reaches a model, and keep every model request within your organization's model policy. Where you've turned on Tool Execution Approval, a **person** allows or denies a skill call before it runs. **Evals** score the output, against test datasets before release and on live traffic after.

For the end-to-end workflow, see [How Agents Work](/ai-workbench-qore/start-here/how-an-agent-works).

{% hint style="info" %}
**Two catalogs, one idea.** Several concepts here appear in more than one place in the product — for example, an agent's connectors are configured per-agent in [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services), while the shared catalog lives in [Integrations](/ai-workbench-qore/console/integrations-hub). Same idea, different altitude. The concept pages say which is which.
{% endhint %}

***

{% 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 %}


# Accounts, Projects, Spaces

Accounts, projects, the two spaces, and what each Operator can reach.

Qore uses accounts, projects, and two spaces to separate daily creation from account-wide governance. Use this overview to choose the correct boundary and surface before you begin.

### At a glance

| Concept            | Use it for                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------ |
| **Tenant**         | The top-level boundary for accounts, org-wide roles, brands, and model policy.             |
| **Account**        | Cost Control, access to Console and Control Center, governance, and account-wide controls. |
| **Project**        | Apps, agents, knowledge bases, design systems, and shared context.                         |
| **Console**        | Building and running work in the selected project.                                         |
| **Control Center** | Monitoring and governing the full account.                                                 |

{% hint style="info" %}
**Key rule:** Console is project-scoped. Control Center is account-scoped. Control Center screens can still filter their data by project.
{% endhint %}

### How Qore is organized

A **tenant** is Qore's top-level boundary — one deployment for a customer. A tenant can have more than one **account**, and each account can have many projects. It holds org-wide roles, brands, the plan and model catalog. Org Settings manages the tenant's accounts and brands. Most customers see a single account and rarely need to think above that level.

An **account** is a business unit inside the tenant. **Cost Control** and credits, users (by membership), roles, teams, API keys, and governance controls belong to the account.

An account provides access to the **Console** and **Control Center** spaces.

Find **Account** in the left sidebar. Users with one account see that account. Users with multiple accounts can switch accounts from the account panel.

A **project** groups your apps, agents, knowledge bases, and design systems. Projects also define **context**. Every conversation in a project can use its artifacts.

Create a project for unrelated work. This keeps its context separate from other work.

Assets stay available within their project. For example, you can attach one knowledge base to multiple agents. You can also reuse a design system in a new app.

| Boundary | Owns                                              | Why it matters                             |
| -------- | ------------------------------------------------- | ------------------------------------------ |
| Account  | Cost Control, access, and governance              | These controls apply across every project. |
| Project  | Apps, agents, knowledge bases, and design systems | Artifacts and context remain isolated.     |

A new user receives a starter project named after them. It gives them an immediate place to build.

{% hint style="info" %}
**Terminology change:** Earlier releases used **workspace**. It now means **project**. Older screenshots and release notes may still use the earlier term.
{% endhint %}

### Spaces: Console and Control Center

A switcher beside the platform logo moves between **Console** and **Control Center**.

{% columns %}
{% column %}

#### Console

**Console** is your daily project workspace. Build apps and agents, create knowledge bases, and run what you built.

Console uses the project selected in its header. It also shows the active account.
{% endcolumn %}

{% column %}

#### Control Center

**Control Center** provides account-wide administration and monitoring. Use it for observability, quality, guardrails, audit, cost control, and access management.

It opens at the account level. Use each screen’s project filter to narrow its data.
{% endcolumn %}
{% endcolumns %}

| If you need to…                               | Use            | Scope                                    |
| --------------------------------------------- | -------------- | ---------------------------------------- |
| Build or run an app, agent, or knowledge base | Console        | Selected project                         |
| Check project artifacts                       | Console        | Selected project                         |
| Review activity, quality, cost, or access     | Control Center | Account, with optional project filtering |
| Manage users and roles                        | Control Center | Account                                  |

{% hint style="info" %}
Console combined the earlier **Build** and **Run** spaces. Both activities now happen in one project workspace.
{% endhint %}

{% hint style="warning" %}
Projects aren't available from **Control Center**. They live in **Console**, under **Accounts**.
{% endhint %}

Control Center does not have a global project selection. Analytics, Audit Trails, logs, Reports, and Credit Usage support project filters within the screen.

### Operators and artifact scope

Each space has an **Operator**. An Operator coordinates specialized agents with shared conversational context.

|                     | Console Operator                  | Governance Operator                    |
| ------------------- | --------------------------------- | -------------------------------------- |
| **Space**           | Console                           | Control Center                         |
| **Reach**           | Selected project                  | Whole account                          |
| **Focus**           | Apps, agents, and knowledge bases | Activity, cost, access, and guardrails |
| **Change handling** | Dispatches work immediately       | Stages changes for approval            |

The Console Operator can create a knowledge base, app, or agent. It creates the artifact in the current project. You can test it in the same chat.

The Console Operator can also search or crawl a URL. It can turn the result into a knowledge base or use it to create a design system.

The Governance Operator answers account-wide questions. Ask about published apps, recently created agents, or credit use. It can narrow a question to one project without changing Control Center’s account scope.

{% hint style="info" %}
Use the Governance Operator for oversight. It stages proposed changes and waits for your approval.
{% endhint %}

#### Module scope

| Module                            | Scoped to                  | Practical effect                                                                                                                                                      |
| --------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Design Systems**                | Project                    | Apps in the project inherit the design system.                                                                                                                        |
| **Flows**                         | Project                    | A flow and its versions belong to one project. Add it to an agent in that project as a skill.                                                                         |
| **Apps, agents, knowledge bases** | Project                    | They use the project context.                                                                                                                                         |
| **Store**                         | Account                    | Published solutions are visible across the account.                                                                                                                   |
| **Observe**                       | Account                    | Screens can filter results by project.                                                                                                                                |
| **Evaluators**                    | Account                    | An evaluator is attached to agents across the account, not created per project.                                                                                       |
| **Cost Control**                  | Tenant, account, and agent | Credit limits exist at all three levels — a tenant-wide cap, per-account caps and alerts, and a per-agent credit guardrail — and the strictest applicable limit wins. |
| **Admin**                         | Account                    | Roles apply across every project. Roles are held per account membership: one person can hold different roles in different accounts.                                   |
| **AI Gateway**                    | Account                    | Model policy applies to all account activity.                                                                                                                         |
| **Govern**                        | Account                    | Controls apply across the account.                                                                                                                                    |
| **Governed Graph**                | Account                    | An uploaded graph is created for the whole account, so every project can read it.                                                                                     |
| **Console Operator**              | Project                    | It works and builds in the selected project.                                                                                                                          |
| **Governance Operator**           | Account                    | It supports account-wide questions and project filtering.                                                                                                             |

{% hint style="warning" %}
The scope of **Integrations Hub** and **Custom Skills** is not confirmed. Do not treat either scope as documented until verified.
{% endhint %}

{% hint style="info" icon="readme" %}
**Good to remember**

* Control Center does not show an app or agent’s originating project.
* Switching accounts does not preserve the selected project.
  {% endhint %}

### Publishing and access

Who can publish depends on their role. **Developer**, **Account Admin**, and **Organisation Admin** can publish apps, agents, knowledge, and flows, and **Governance Manager** can publish knowledge. **Approver** and the two admin roles approve publishing when it needs review. See [Roles](/ai-workbench-qore/control-center/admin/roles).

Roles control what each person can do. Each role grants a set of capabilities, and a person holds roles per account membership. See [Roles](/ai-workbench-qore/control-center/admin/roles).

### Quick choice

{% tabs %}
{% tab title="I need to build" %}
Use **Console**. Select the project where the work belongs. Create and run apps, agents, and knowledge bases there.
{% endtab %}

{% tab title="I need to govern" %}
Use **Control Center**. Review account activity, quality, costs, access, and controls. Filter by project when available.
{% endtab %}
{% endtabs %}

### Related resources

{% content-ref url="/pages/6712483fe92d4497b985e3f00b6d0737aa398200" %}
[Console](/ai-workbench-qore/start-here/console)
{% endcontent-ref %}

{% content-ref url="/pages/807cab861e090edd0ce825909db3db1b28f73799" %}
[Control Center](/ai-workbench-qore/start-here/control-center)
{% endcontent-ref %}

***

{% 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 %}


# Console

Build and run apps and agents, manage your project, and open Console tools.

Console is where you build and run apps and agents. Start something new, review your project, and open every Console tool from one place.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-75f891939031c72910aab6ba475715a75cf62e2f%2Fqore_console_console-home-operator-prompt_rounded_shadow.png?alt=media" alt="The Console home screen, with the Operator chat prompt and a sidebar listing Operator, Apps, Agents, Knowledge, Flows, Store, Integrations, and Design Systems"><figcaption><p>The Console home screen.</p></figcaption></figure>

Open it at **Console → Dashboard**. Use **Control Center** to monitor and govern running apps and agents across your account.

{% hint style="info" %}
**Mobile** is a beta app target. **Flows** is a preview Console area.
{% endhint %}

## Start a build

Describe your intent in the Operator prompt. Operator coordinates the work needed to build an app, agent, knowledge base, or agentic app.

Operator can search or crawl a website when your request needs web context. For example, provide a URL to reuse its design system in an app or create a knowledge base from its content.

You can also select **Import an existing app** or **Build from your IDE** when you want to start from existing code.

<table data-view="cards"><thead><tr><th>Build in Console</th><th data-card-target data-type="content-ref">Learn more</th></tr></thead><tbody><tr><td>Start or import an app, then build and publish it.</td><td><a href="/ai-workbench-qore/console/app-builder">App Builder</a></td></tr><tr><td>Configure, test, deploy, and monitor an AI agent.</td><td><a href="/ai-workbench-qore/console/agent-builder/get-started">Get Started</a></td></tr><tr><td>Connect third-party services to your account.</td><td><a href="/ai-workbench-qore/console/integrations-hub">Integrations Hub</a></td></tr></tbody></table>

## Review your project

The Dashboard summarizes your current project:

* **Apps** and **Agents** show how many you have built.
* **Workflows** shows existing workflows. Select **Create Workflow** to open Flow Engine.
* **Knowledge Bases** shows available knowledge sources.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-5464e6d5382d95b0f66902ff3cafa07814af162c%2Fqore_app-builder_studio-dashboard-app-builder-credit-balance_rounded_shadow.png?alt=media" alt="The Console dashboard project summary, including the account&#x27;s credit balance"><figcaption><p>The Dashboard's project summary, including credit balance.</p></figcaption></figure>

Use **Recently worked on** to reopen items by name, type, or last updated time.

## Use dashboard shortcuts

* **Integrations** summarizes the connector catalog by category. Select **See all** to open the [Integrations Hub](/ai-workbench-qore/console/integrations-hub).
* **Quick Start** provides **Create Your App** and **Build an AI Agent**.

## Explore Console areas

The sidebar gives you direct access to each Console area:

* [App Builder](/ai-workbench-qore/console/app-builder) for creating, running, and publishing apps.
* [Agent Builder](/ai-workbench-qore/console/agent-builder) for building and deploying agents.
* [Knowledge](/ai-workbench-qore/console/knowledge) for building and querying knowledge bases.
* **Flows** (preview) for building workflows.
* [Store](/ai-workbench-qore/console/store) for browsing ready-made agents and apps.
* [Integrations](/ai-workbench-qore/console/integrations-hub) for the connector catalog.
* [Design Systems](/ai-workbench-qore/console/design-systems) for a project's shared visual identity.

## Manage running products

Use [Control Center](/ai-workbench-qore/start-here/control-center) for account-wide monitoring, governance, access, usage, billing, and audit.

***

{% 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 %}


# Control Center

Manage platform governance, monitoring, access, usage, quality, cost control, and audit.

Control Center is the account-wide administration and monitoring surface of the Qore platform. It's where you watch how your apps and agents are used, evaluate the quality of their output, enforce guardrails and kill switches, inspect logs, manage costs, and control who has access.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-f41f69b69ab19c707e31390646acecc935d0db35%2F006_control_center_governance_operator_home.png?alt=media" alt="Control Center open on the Governance Operator: the left navigation lists Operator, Observe, Cost Control, Evals, Govern, AI Gateway and Admin; Schedules and Gates sit in the top bar; the System agents panel is on the right"><figcaption><p>Control Center as an operator sees it, with the modules listed below in the left navigation.</p></figcaption></figure>

## At a glance

* **What it's for:** monitoring, quality control, governance, and administration across your whole Qore account — not building apps or agents (that happens in Console), but overseeing them.
* **Who uses it:** account admins and operators day-to-day; developers and integrators for API keys, logs, and permissions; anyone who needs to see usage, cost, or audit history.
* **How it's organized:** seven modules in the navigation: Operator, Observe, Cost Control, Evals, Govern, AI Gateway, and Admin.
* **Scope:** everything in Control Center is account-wide. There is no project selector for the space itself, though most screens can be narrowed to one project.

## Control Center modules

The Control Center navigation lists seven modules:

* [**Operator**](/ai-workbench-qore/control-center/governance-operator) — the Governance Operator: ask about the account, and approve what it proposes.
* [**Observe**](/ai-workbench-qore/control-center/observe) — who's using your apps and agents, with what outcomes, and every run, change, model call, request, and database operation. Includes exports and reports.
* [**Cost Control**](/ai-workbench-qore/control-center/cost-control) — track credit usage and set hard limits and alerts.
* [**Evals**](/ai-workbench-qore/control-center/evals) — define evaluators that score agent output, watch them run on live traffic, and review flagged executions by hand.
* [**Govern**](/ai-workbench-qore/control-center/govern) — stop agents in an emergency, review the connectors agents may reach, and load a governed graph.
* [**AI Gateway**](/ai-workbench-qore/control-center/ai-gateway) — set the model families and models used across Console building and usage.
* [**Admin**](/ai-workbench-qore/control-center/admin) — manage users and their roles, group them into teams scoped to product spaces, and issue API keys.

## How Control Center fits together

The modules are separate views over the same account activity, so one agent run shows up in several places, each from a different angle: as a thread in **Agent Analytics**, a scored execution in **Online Eval**, a task in **Human Review** when its confidence is low, the model calls it made in **LLM Logs**, and the records it changed in **Audit Trails** and **DB Query Logs**.

Knowing which module answers which question is most of what it takes to work quickly here:

* *Is anyone using this?* → Observe.
* *Is the output any good?* → Evals.
* *Can I stop it, and what can it reach?* → Govern.
* *Who changed what?* → Observe › Audit Trails.
* *What exactly did it call and write?* → Observe › LLM Logs, Request Logs, and DB Query Logs.
* *What is it costing?* → Cost Control.
* *Who can do what?* → Admin.

***

{% 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 %}


# Org Settings

Manage tenant accounts, usage controls, and platform branding.

Org Settings lets super admins manage tenant accounts and brand kits. Open **Org Settings** from your profile.

### Manage platform settings

<table data-view="cards"><thead><tr><th>Section</th><th>Description</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td>Accounts</td><td>Create tenant accounts, set credit limits, and receive usage alerts.</td><td><a href="/ai-workbench-qore/control-center/accounts">Accounts</a></td></tr><tr><td>Brands</td><td>Create, update, apply, and remove tenant brand kits.</td><td><a href="/ai-workbench-qore/start-here/org-settings/brands">Brands</a></td></tr></tbody></table>

***

{% 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 %}


# Brands

Create, update, apply, and remove tenant brand kits.

Brands lets enterprise customers customize Qore Workbench and deployed apps to match brand guidelines.

A brand kit stores your tenant’s platform name, logos, and color scheme. White-labeling lets you deliver Qore under your own brand across deployments.

Qore uses the applied kit across branded platform surfaces.

| Topic        | Details                                                                               |
| ------------ | ------------------------------------------------------------------------------------- |
| Access       | Super admins manage brands at **Super Admin Settings → Brands**.                      |
| Brand kit    | Stores a brand name, platform name, logo assets, colors, and advanced theme settings. |
| Active brand | One brand is applied at a time.                                                       |
| Main actions | Create, update, apply, or delete brand kits.                                          |

## Overview

The applied brand represents your tenant in Console and user-facing flows. It also appears in transactional emails, generated documents, and exports.

A tenant can store several brand kits. Only the applied kit is visible to users.

### Key concepts

| Concept       | Meaning                                                     |
| ------------- | ----------------------------------------------------------- |
| Brand name    | An internal label for identifying a kit in the list.        |
| Platform name | The name shown on branded user-facing surfaces.             |
| Brand assets  | The **Large logo**, **Small logo**, and **Favicon** images. |
| Applied brand | The kit currently used across every branded surface.        |

## Manage brands

The Brands list shows every brand kit as a card. The **Create custom Brand** card starts a new kit.

Each existing card shows its thumbnail, **Brand Name**, and **Last updated on** date. Select a card to update it.

Use **Apply** to activate a kit. Use the **⋮** menu to delete one.

### Use a theme template

Qore includes theme templates. Select a template, then select **Apply** to use it.

### Create a brand

Create a kit to prepare a new tenant identity. It isn't applied automatically.

{% stepper %}
{% step %}

### Start a brand kit

Select **Create custom Brand**. The **Brand Kit** view opens with a live preview.
{% endstep %}

{% step %}

### Add brand details

Enter a **Brand Name** and **Platform Name**. The brand name stays internal.
{% endstep %}

{% step %}

### Add assets and colors

Upload a **Large logo**, **Small logo**, and **Favicon**. Set **Primary Brand Color** and **Secondary Brand Color**.

Use **Advanced Customization** for additional theme controls. The preview updates as you edit.
{% endstep %}

{% step %}

### Save the brand

Select **Create Brand**. Qore adds the kit to the Brands list.
{% endstep %}
{% endstepper %}

### Update a brand

Select a brand card to open **Update Brand Kit**. Change its details, then select **Save**.

Saving changes doesn't apply an inactive kit. Changes to the applied kit appear immediately.

### Apply a brand

Select **Apply** on a card to activate its brand kit. Qore replaces the previous applied kit everywhere.

The change updates Console and user-facing surfaces. Newly generated documents and exports use the active kit.

### Delete a brand

Open the card's **⋮** menu and select **Delete**. Confirm the removal.

{% hint style="danger" %}
Deletion is permanent. Apply a different brand before removing the active kit.
{% endhint %}

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td>Accounts</td><td>Manage tenant accounts, credit limits, and usage alerts.</td><td><a href="/ai-workbench-qore/control-center/accounts">Accounts</a></td></tr><tr><td>Cost Control</td><td>Track credit consumption and control spending.</td><td><a href="/ai-workbench-qore/control-center/cost-control">Cost Control</a></td></tr></tbody></table>

***

{% 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 %}


# Deployment options

The cloud providers Qore is deployed on, and the cloud services it uses on each.

Qore is deployed on Google Cloud and Microsoft Azure. Support for Amazon Web Services is coming soon. Other cloud providers are supported on request.

## Supported cloud providers

| Cloud provider            | Status      |
| ------------------------- | ----------- |
| Google Cloud (GCP)        | Available   |
| Microsoft Azure           | Available   |
| Amazon Web Services (AWS) | Coming soon |
| Other cloud providers     | On request  |

## Cloud services Qore uses

On each cloud provider, Qore uses that provider's managed services:

| Service         | Google Cloud             | Microsoft Azure               |
| --------------- | ------------------------ | ----------------------------- |
| Database        | Cloud SQL for PostgreSQL | Azure Database for PostgreSQL |
| Secrets         | Secret Manager           | Key Vault                     |
| Encryption keys | Cloud KMS                | Key Vault                     |
| File storage    | Cloud Storage            | Blob Storage                  |
| Messaging       | Pub/Sub                  | Event Grid                    |

{% hint style="info" %}
The cloud provider Qore is deployed on doesn't decide where AI models run. Every model request passes through AI Gateway, which sends it through the provider configured for that model family. See [How model routing works](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works).
{% endhint %}

## Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>What is Qore</strong></td><td>The builders and how they work together.</td><td><a href="/ai-workbench-qore/start-here/what-is-qore">What is Qore</a></td></tr><tr><td><strong>Security FAQ</strong></td><td>Security and data residency for bank-owned deployments.</td><td><a href="/ai-workbench-qore/control-center/detailed-security-and-runtime-faq">Security FAQ</a></td></tr><tr><td><strong>How model routing works</strong></td><td>Families, providers, and where model requests go.</td><td><a href="/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works">How Model Routing Works</a></td></tr></tbody></table>

***

{% 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 %}


# Glossary

A reference for common Qore terms.

Reference entries for UI terms, acronyms, and platform-specific vocabulary used across Console and Control Center, plus richer concept entries for the domain ideas the screens reference. Reference entries are short (one to three sentences) and point to the page where the term is most fully discussed. Concept entries are longer (two to four sentences) and carry the teaching weight the screen pages keep light.

Entries are alphabetized. The page is intended for lookup — search the page, or follow an in-page anchor link from another page in the guide.

### A

#### Account <a href="#account" id="account"></a>

A business unit inside a [tenant](#organization) — the boundary for billing, access, governance, and account-wide controls. An account contains projects, users (by membership), roles, teams, API keys, credit limits, and alerts. Users with multiple accounts can switch from the account panel. See [Accounts](/ai-workbench-qore/control-center/accounts).

#### Admin <a href="#admin" id="admin"></a>

The Control Center module for managing users, teams, roles, and API keys. Roles apply across the account. Teams organize members and associate them with Console, Control Center, or both. See [Admin](/ai-workbench-qore/control-center/admin).

#### Agent Builder <a href="#agent-builder" id="agent-builder"></a>

The Console surface you use to configure one AI agent — its identity, instructions, attached resources, runtime settings, and integrations. Reached at `/platform/agent-builder/<agentId>`. See [Get Started](/ai-workbench-qore/console/agent-builder/get-started).

#### Agent Capability <a href="#agent-capability" id="agent-capability"></a>

A dropdown on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#agent-capability) that controls how deeply the agent thinks about each request: `Auto`, `Intelligent Planner`, `Next Best Step`, or `Fast`. Default is `Auto`. `Fast` leaves out persona memory, FAQ memory, CoT validation, and learning cases for lower latency.

#### Agent Config <a href="#agent-config" id="agent-config"></a>

The configuration panel that holds the agent's settings — basic details, instructions, behavior, skills, triggers, secrets, access and authentication, guardrails, evals, and reinforcement learning. Opened with **Agent Config** in the canvas header.

#### Agent Controls <a href="#agent-controls" id="agent-controls"></a>

The Control Center page, under **Govern**, that shows whether each agent in the account is **Running** or **Idle** and stops its active runs. **Stop all agents** stops every agent after a confirmation. Stopping a system agent, such as the Operator, also stops every run and helper agent it started. See [Agent Controls](/ai-workbench-qore/control-center/govern/agent-controls).

#### Agent enablement <a href="#agent-enablement" id="agent-enablement"></a>

The tab on **Control Center → Evals → Evaluators** where you assign [evaluators](#evaluator) to an agent, set its **Sampling**, and turn on its **Online eval** toggle. Assigning evaluators doesn't start scoring until the toggle is on. See [Evaluators](/ai-workbench-qore/control-center/evals/evaluators#agent-enablement).

#### Agent Output Format <a href="#agent-output-format" id="agent-output-format"></a>

A dropdown on [Basic Details](/ai-workbench-qore/console/agent-builder/build/basic-details#agent-output-format) that controls how the agent's text responses are rendered. Options are `Markdown` and `Json`.

#### Agent Preview <a href="#agent-preview" id="agent-preview"></a>

Agent Builder has no Agent Preview pane in 2.16. To chat with the agent, select **Try Agent**, which opens the Agent Playground in a new tab. See [Get Started](/ai-workbench-qore/console/agent-builder/get-started).

#### Agent team <a href="#agent-team" id="agent-team"></a>

The set of agents an [Operator](#operator) can hand work to. The Operator picks from them by their names and descriptions. The Governance Operator's UI calls it an *operating team*. See [Operator](/ai-workbench-qore/core-concepts/operator).

#### AI Gateway <a href="#ai-gateway" id="ai-gateway"></a>

The platform layer that every model request passes through, including every call an agent makes. It resolves a request to a model family, a tier, and an available provider, and applies the configured credentials. See [AI Gateway](/ai-workbench-qore/control-center/ai-gateway) and [How Model Routing Works](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works).

#### Allowed Domains <a href="#whitelisted-domains" id="whitelisted-domains"></a>

The list of web origins where the agent's embedded widget may run, on [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication#allowed-domains). A widget-key request from an origin not on the list is refused; with the list empty, the widget runs nowhere outside the platform. The Embedded Chat setup calls this step **Whitelist domains**.

#### Allowed LLM Families and Providers <a href="#allowed-llm-families-and-providers" id="allowed-llm-families-and-providers"></a>

The two **Model Policy** guardrails. They are **Always enforced**: AI Gateway applies your organization's approved model families and providers to every model request, and they can't be turned off per agent. See [Guardrails](/ai-workbench-qore/console/agent-builder/deploy/guardrails#model-policy-guardrails).

#### API Call (skill) <a href="#api-call-skill" id="api-call-skill"></a>

A Skill Library skill that lets the agent reach external HTTP APIs at runtime. Use it for services not covered by [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services) connectors. See [API Call](/ai-workbench-qore/platform-resources/skill-library/api-call).

#### API Integration <a href="#api-integration" id="api-integration"></a>

One of the ways to integrate an agent: the **Agent API** tab, `raw (HTTP)` client, on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration). Calls the agent server-to-server with an API key and secret.

#### App <a href="#app-in-uptiq" id="app-in-uptiq"></a>

Something built in [App Builder](/ai-workbench-qore/console/app-builder) — not the same thing as a [project](#project). An app can attach many agents, and one agent can be attached to several apps; an app is scoped to a project. The builder URL's `appId` parameter identifies the app itself, not the project it lives in.

#### App workspace <a href="#app-workspace" id="app-workspace"></a>

The editor for one app. It includes the build conversation, live preview, and action bar. See [App Workspace](/ai-workbench-qore/console/app-builder/app-workspace).

#### Authentication (agent) <a href="#authentication-agent" id="authentication-agent"></a>

The Agent Config page that verifies the person calling the agent, through **Microsoft Entra ID** or **Google**. A verified token is available to the agent's MCP connections as `$auth.token`. A request without a token still runs; a request with an invalid token is rejected. Distinct from [Single Sign-On](#single-sign-on), which is how people sign in to Qore itself. See [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1).

#### Auto sync <a href="#auto-sync" id="auto-sync"></a>

A dataset setting that syncs eligible new files into the knowledge base automatically, instead of waiting for a manual [sync](#sync). See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

#### Auto-compaction <a href="#auto-compaction" id="auto-compaction"></a>

A toggle on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#auto-compaction) that summarizes the conversation when it nears the context window. **Compaction threshold** sets the point, from 50% to 95% of the window. Shown when the agent's executor version supports it.

#### Autonomy <a href="#autonomy" id="autonomy"></a>

A slider on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#autonomy) controlling how independently the agent commits to multi-step plans. Marked `Low` / `Med` / `High`; default `Med`. Higher autonomy means fewer confirmations between steps.

***

### B

#### Basic Details <a href="#basic-details" id="basic-details"></a>

The first section in **Agent Config**, holding the agent's identity — avatar, name, description, and output format. See [Basic Details](/ai-workbench-qore/console/agent-builder/build/basic-details).

#### Bring your own key <a href="#bring-your-own-key" id="bring-your-own-key"></a>

Abbreviated **BYOK**. In [AI Gateway](/ai-workbench-qore/control-center/ai-gateway), the option where your organization supplies its own model-provider credential and the provider bills your organization directly. The alternative is a [UPTIQ managed key](#uptiq-managed-key). For integration credentials rather than model credentials, see [Connect BYOK](#connect-byok).

#### Build version <a href="#build-version" id="build-version"></a>

Each app build is a numbered version tied to a commit. The version selector marks the newest build as **Latest** and the live build as **Published**. Testing, security, and data flow reports each apply to one version.

***

### C

#### Capability <a href="#capability" id="capability"></a>

One permission a [role](#role) grants, such as **Build Evals** or **Export Agent**. A person's capabilities are the sum of their roles in that account. An action that needs a capability you don't have is disabled. See [Roles](/ai-workbench-qore/control-center/admin/roles#capabilities-by-role).

#### Chain of Thought <a href="#chain-of-thought" id="chain-of-thought"></a>

A reasoning approach where a language model produces, in addition to its final answer, the intermediate steps it took to reach the answer. The platform's [CoT Reasoning](#cot-reasoning) toggle is deprecated.

#### Checklist <a href="#checklist" id="checklist"></a>

A reusable execution plan — a sequence of skill calls the agent follows when a request matches it, generated and refined from the agent's successful runs. See [Execution Plan/Checklist](/ai-workbench-qore/console/agent-builder/build/execution-plan-checklist), and the [Planner](#planner) entry for how a checklist fits into runtime execution.

#### Connect (button) <a href="#connect-button" id="connect-button"></a>

The action revealed on hover over an integration row in [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services). Starts the integration's connection flow, typically OAuth, so the agent can call the service at runtime.

#### Connect BYOK <a href="#connect-byok" id="connect-byok"></a>

The connect method where you supply credentials for your own account with the provider — usually an API key, OAuth client, or webhook secret — stored encrypted for runtime use. Some integrations also offer per-user credentials or **Use Platform Managed Keys**. See [Connect Methods](/ai-workbench-qore/console/integrations-hub/connect-methods).

#### Connect Method <a href="#connect-method" id="connect-method"></a>

How an integration in the [Integrations Hub](/ai-workbench-qore/console/integrations-hub) connects: [Connect BYOK](#connect-byok), a [sandbox account](#mcp-sandbox-account) through Kinective, or [Connect via UDG](#connect-via-udg). See [Connect Methods](/ai-workbench-qore/console/integrations-hub/connect-methods).

#### Connect via UDG <a href="#connect-via-udg" id="connect-via-udg"></a>

The connect method for integrations brokered through [UDG](#udg). In 2.16 their **Connect via UDG** button is disabled, so they can't be connected yet. See [Connect Methods](/ai-workbench-qore/console/integrations-hub/connect-methods#connect-via-udg).

#### Connectors <a href="#connectors" id="connectors"></a>

The Control Center page, under **Govern**, that lists what the account has made available to agents, in three tabs: **Integrations**, **MCP Servers**, and **Platform Skills**. It is the outer limit every agent inherits: an agent can't use a connector the account hasn't made available. See [Connectors](/ai-workbench-qore/control-center/govern/connectors).

#### Console <a href="#console" id="console"></a>

The project-scoped Qore space where you build and run apps, agents, knowledge bases, flows, and design systems. It uses the project selected in the header. See [Console](/ai-workbench-qore/start-here/console) and [Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized).

#### Console Operator <a href="#console-operator" id="console-operator"></a>

The [Operator](#operator) in Console: a chat that plans the work and hands each part to the right agent, within the selected project. It acts as soon as you ask, with no approval step. See [Console Operator](/ai-workbench-qore/console/console-operator).

#### Control Center <a href="#control-center" id="control-center"></a>

The account-scoped Qore space for governance, monitoring, administration, and cost control. Screens can filter account data by project, but Control Center has no global project selection. See [Control Center](/ai-workbench-qore/start-here/control-center).

#### CoT Reasoning <a href="#cot-reasoning" id="cot-reasoning"></a>

A toggle on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#cot-reasoning-beta), marked **Deprecated**. It can no longer be turned on; an agent that already has it on can turn it off, and then it can't be turned on again.

#### Custom skill <a href="#custom-skill" id="custom-skill"></a>

Your own procedure or know-how, uploaded to an agent as a folder with a `SKILL.md` file and up to 10 supporting files, from the **Custom Skills** tab of Add Skill. See [Custom skills](/ai-workbench-qore/platform-resources/skill-library/custom-skills).

#### Custom Trigger <a href="#custom-trigger" id="custom-trigger"></a>

The detail form for editing or creating one trigger, reached from the expanded **Agent Triggers** modal. Carries three required fields: Trigger Source, Trigger Name, and Description. See [Triggers](/ai-workbench-qore/console/agent-builder/build/triggers).

#### CVE / GHSA <a href="#cve-ghsa" id="cve-ghsa"></a>

Public advisory identifiers for vulnerabilities. CVE means Common Vulnerabilities and Exposures. GHSA means GitHub Security Advisory. See [Security](/ai-workbench-qore/console/app-builder/security-scans).

***

### D

#### Dataset (eval) <a href="#dataset" id="dataset"></a>

A collection of [test cases](#test-case) used to evaluate one agent. In [Evals](/ai-workbench-qore/console/agent-builder/test/evals), a dataset is read from an uploaded document (up to 500 test cases), generated with AI (1 to 50), or built manually. Each agent can have up to 100 datasets. Not the same thing as a [knowledge dataset](#knowledge-dataset).

#### Dataset (knowledge) <a href="#knowledge-dataset" id="knowledge-dataset"></a>

A named grouping of source files in **Knowledge**. It tracks ingestion but doesn't interpret content; a [knowledge base](#knowledge-base) is built from datasets. One dataset can feed several knowledge bases. Not the same thing as an [eval dataset](#dataset). See [Datasets](/ai-workbench-qore/console/knowledge/datasets).

#### Design System <a href="#design-system" id="design-system"></a>

A project's stored visual identity — visual style, logos, fonts, and colors — that apps in the project use. Create one by describing a brand; every save creates a version you can restore. See [Design Systems](/ai-workbench-qore/console/design-systems).

#### DLP <a href="#dlp" id="dlp"></a>

Short for **Data Loss Prevention**. Google Cloud DLP is a [masking provider](#masking-provider) that detects sensitive data from a large catalog of [infoTypes](#infotype).

#### Draft Version <a href="#draft-version" id="draft-version"></a>

The working version of an agent, shown as **Draft Version** in the canvas header's version selector; saved versions show as numbers such as **v1.0**. See [The Builder Canvas](/ai-workbench-qore/console/agent-builder/the-canvas#the-headers). Distinct from [Executor Version](#executor-version), the platform runtime version the agent uses.

***

### E

#### Effort <a href="#effort" id="effort"></a>

A control in the [Console Operator](#console-operator) composer that sets how hard the Operator reasons before it answers: **Minimal**, **Low**, **Medium**, or **High**. It applies to each message you send, not to the agents the Operator hands work to. See [Console Operator](/ai-workbench-qore/console/console-operator#the-composer).

#### Embedded Chat <a href="#embed-agent" id="embed-agent"></a>

One of the ways to integrate an agent: the **Embedded Chat** tab on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration). Produces an embeddable widget that surfaces the agent as a chat on a web page, using a [widget key](#widget-key).

#### Eval Run <a href="#eval-run" id="eval-run"></a>

One execution of a [dataset](#dataset) against a live agent in [Evals](/ai-workbench-qore/console/agent-builder/test/evals). An eval run tracks status, progress, per-test-case results, scores, and any generated suggestions.

#### Evals <a href="#evals" id="evals"></a>

The offline evaluation framework in Agent Builder for testing agent quality against scored datasets before deployment. An LLM scorer rates each response from 0 to 10; 7 or higher passes. See [Evals](/ai-workbench-qore/console/agent-builder/test/evals). For production scoring, see [Online Evals](#online-evals).

#### Evaluator <a href="#evaluator" id="evaluator"></a>

An account-level scoring method for [Online Evals](#online-evals), defined in **Control Center → Evals → Evaluators**. It sets the framework (**Single judge** or [Jury](#jury)), the evaluation method (**Answer Relevancy**, [Faithfulness](#faithfulness), **Safety**, or **Task Completion**), the judge model or models, a confidence threshold (default `50%`), and whether low-confidence results route to [Human Review](#human-review). See [Evaluators](/ai-workbench-qore/control-center/evals/evaluators).

#### Executor <a href="#executor" id="executor"></a>

The part of the agent runtime that invokes the skills the planner chose, passes their results back through the model, and renders the final response. The [Execution Model](/ai-workbench-qore/console/agent-builder/build/agent-behavior#execution-model) setting selects its model. Pair this with the [Planner](#planner) entry.

#### Executor Version <a href="#executor-version" id="executor-version"></a>

The platform runtime version the agent runs on, such as `1.4`. Set on [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning). New agents use the latest version available to your tenant; existing agents stay on theirs until you migrate them. It controls which features are available — for example PII tokenization and Auto-compaction.

#### Export Agent <a href="#export-agent" id="export-agent"></a>

The canvas header action that packages the agent's configuration for reuse elsewhere. The package is delivered by email, with a download link. Needs the **Export Agent** capability. See [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent).

***

### F

#### Faithfulness <a href="#faithfulness" id="faithfulness"></a>

An [evaluator](#evaluator) method that rates how much of what the agent said is supported by the context it was given: retrieved context, tool results, and what the user said. The score is the share of the response's factual claims the context supports. See [Evaluators](/ai-workbench-qore/control-center/evals/evaluators#faithfulness).

#### FAQ memory <a href="#faq-memory" id="faq-memory"></a>

**Enable FAQ**, on the **FAQ** tab under **Agent Config → Reinforcement Learning**, controls whether the agent uses stored FAQs and their canonical answers when a question matches a known FAQ. Off on a new agent. See [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#faq-memory).

#### Flow (tab) <a href="#flow-tab" id="flow-tab"></a>

The second tab on [The Builder Canvas](/ai-workbench-qore/console/agent-builder/the-canvas#overview-and-flow-tabs), formerly **Plan**. Shows the agent's execution steps, under *What the Agent will do*, when [Execution Plan/Checklist](/ai-workbench-qore/console/agent-builder/build/execution-plan-checklist) entries exist. Reads **No Plan Found** when none do.

#### Flows <a href="#flows" id="flows"></a>

A preview Console area for building a fixed, multi-step process. A flow and its versions belong to one project, and you add a flow to an agent in that project as a single skill. See [Flows](/ai-workbench-qore/console/flows).

***

### G

#### Gates <a href="#gates" id="gates"></a>

The top-bar page that lists the Operator conversations you started that ended on a question for you. Console and Control Center each have their own. Only you can answer your requests. See [Gates](/ai-workbench-qore/console/console-operator/gates).

#### Governance Operator <a href="#governance-operator" id="governance-operator"></a>

The [Operator](#operator) in Control Center. It answers account-wide questions through a team of governance-review agents and stages any change for your approval instead of acting on its own. See [Governance Operator](/ai-workbench-qore/control-center/governance-operator).

#### Governed Graph <a href="#governed-graph" id="governed-graph"></a>

An institution's knowledge graph — products, pricing, policies, document requirements, rules — loaded from a graph package in **Control Center → Govern → Governed Graph**. Each fact keeps its source, owner, confidence, and effective date. It is account-scoped, and agents query it with [Knowledge Graph Search](#knowledge-graph-search). See [Governed Graph](/ai-workbench-qore/control-center/govern/governed-graph).

#### Guardrail <a href="#guardrail" id="guardrail"></a>

A control on an agent's run, listed on **Agent Config → Guardrails** with a **Name**, **Type**, and **Status**. [Sensitive Data Masking](#sensitive-data-masking) and [Tool Execution Approval](#tool-execution-approval) are toggled per agent; the [model policy guardrails](#allowed-llm-families-and-providers) are always enforced by AI Gateway. See [Guardrails](/ai-workbench-qore/console/agent-builder/deploy/guardrails).

***

### H

#### Headless Agent Integration <a href="#headless-agent-integration" id="headless-agent-integration"></a>

One of the ways to integrate an agent: the **Agent API** tab, `TypeScript SDK` client, on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration). Runs in the browser, with your own UI instead of the prebuilt widget.

#### Human Review <a href="#human-review" id="human-review"></a>

The Control Center queue where reviewers record a verdict on low-confidence [Online Evals](#online-evals) results. A flagged result becomes a task only when its evaluator routes to human review. Tasks move from **Review Pending** to **Reviewed**. See [Human Review](/ai-workbench-qore/control-center/evals/human-review).

***

### I

#### Improve with AI <a href="#improve-with-ai" id="improve-with-ai"></a>

A button above the [Instructions](/ai-workbench-qore/console/agent-builder/build/instructions) editor. Runs an AI pass over the current instructions and proposes improvements.

#### infoType <a href="#infotype" id="infotype"></a>

Google Cloud DLP’s name for a detectable sensitive-data type. It includes built-in types, such as card numbers and emails, plus custom types.

#### Integrations Hub <a href="#integrations-hub" id="integrations-hub"></a>

The catalog and management surface for third-party integrations. Use it to discover available integrations, configure credentials, and make integrations available to agents, skills, flows, apps, and the Console Operator. See [Integrations Hub](/ai-workbench-qore/console/integrations-hub).

***

### J

#### JavaScript Code (skill) <a href="#javascript-code-skill" id="javascript-code-skill"></a>

A Skill Library skill that runs JavaScript you wrote, at runtime. Distinct from the built-in **Run JavaScript** skill, where the agent writes the code. See [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).

#### Jury <a href="#jury" id="jury"></a>

An [evaluator](#evaluator) framework that scores each output with 2 to 5 judge models and combines their votes into one weighted verdict. A jury's models can come from different providers. The alternative is **Single judge**. See [Evaluators](/ai-workbench-qore/control-center/evals/evaluators#choose-a-framework).

***

### K

#### Knowledge <a href="#knowledge" id="knowledge"></a>

The Console area where you build [knowledge bases](#knowledge-base) from your documents and manage their [datasets](#knowledge-dataset). Agents read knowledge at runtime through the knowledge search skills. See [Knowledge](/ai-workbench-qore/console/knowledge) and [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent).

#### Knowledge base <a href="#knowledge-base" id="knowledge-base"></a>

What Qore builds from datasets or attached files: a table of contents, tags, and embeddings that agents query. It changes only when you [sync](#sync) it, and each sync creates a [knowledge version](#knowledge-version). One knowledge base can serve many agents. See [Knowledge](/ai-workbench-qore/console/knowledge).

#### Knowledge Graph Search <a href="#knowledge-graph-search" id="knowledge-graph-search"></a>

The built-in General skill that answers questions about entities and relationships in an attached [governed graph](#governed-graph). It is the only skill that reads a governed graph. Off by default. See [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills).

#### Knowledge version <a href="#knowledge-version" id="knowledge-version"></a>

A numbered state of a knowledge base, created by each sync. Agents use the latest completed version; there is no draft or publish stage. The **vN ▾** menu shows each version and what created it. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

***

### L

#### Layout (tab) <a href="#layout-tab" id="layout-tab"></a>

The former name of the [Overview (tab)](#overview-tab) on The Builder Canvas.

#### Learning case <a href="#learning-case" id="learning-case"></a>

A correction captured from real production behavior — what the agent should have done. A learning case enters memory only after a person approves it; auto-approval is intentionally disabled. On the **Learning Cases** tab under [Reinforcement Learning](#reinforcement-learning). See [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings).

#### LLM <a href="#llm" id="llm"></a>

Short for **large language model**. An LLM reasons over requests and generates agent responses. Organization policies control which LLM families and providers an agent may use.

***

### M

#### Managed DB <a href="#managed-db" id="managed-db"></a>

The PostgreSQL database the platform runs for an app. The UI shows it with the platform's name, as **… Managed DB**.

#### Markdown (output format) <a href="#markdown-output-format" id="markdown-output-format"></a>

One of two options for the [Agent Output Format](#agent-output-format). The agent's text responses render as Markdown — headings, bullets, code blocks, and links all formatted.

#### Masking provider <a href="#masking-provider" id="masking-provider"></a>

The service that detects PII for [Sensitive Data Masking](#sensitive-data-masking). The provider decides which entity types can be detected: **Regex** exposes six types and **Google Cloud DLP** exposes 133. **Off** doesn't mask content. See [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking).

#### MCP <a href="#mcp" id="mcp"></a>

Short for **Model Context Protocol**. An open protocol for connecting language models to external tools and data sources through a standardized interface. Connecting an MCP server adds its tools to the agent's reach. See [MCP](/ai-workbench-qore/core-concepts/mcp) and [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools).

#### MCP connection <a href="#mcp-connection" id="mcp-connection"></a>

An agent's saved link to one MCP server: its name, URL, credentials, headers, and which of the server's tools the agent may use. Created in **Create MCP Connection**, from the [MCP Marketplace](#mcp-marketplace) or the [MCP Server](#mcp-server-skill) skill. Each connection belongs to one agent. See [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools).

#### MCP Marketplace <a href="#mcp-marketplace" id="mcp-marketplace"></a>

A tab in [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent) that lists the MCP servers you can connect to an agent, grouped by category. See [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools).

#### MCP Sandbox Account <a href="#mcp-sandbox-account" id="mcp-sandbox-account"></a>

The earlier name for the **sandbox account** connect method used by the core banking integrations reached through Kinective. They are available in Agent Builder only, connect with **Connect sandbox account**, and use Platform Managed Keys. See [Connect Methods](/ai-workbench-qore/console/integrations-hub/connect-methods#mcp-sandbox-account).

#### MCP Server (skill) <a href="#mcp-server-skill" id="mcp-server-skill"></a>

A Skill Library skill that lets the agent connect to a third-party MCP server. Reached from [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent). It opens the same **Create MCP Connection** form as a catalog server in [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools), blank.

#### Memory <a href="#memory" id="memory"></a>

**Enable User Persona**, on the **User Persona** tab under **Agent Config → Reinforcement Learning**, controls whether the agent remembers what an individual user has asked about, preferred, or corrected, across conversations. Off on a new agent. Distinct from [FAQ memory](#faq-memory). See [Memory & Learning](/ai-workbench-qore/core-concepts/memory-and-learning).

#### Model family <a href="#model-family" id="model-family"></a>

A group of related models, such as GPT or Gemini. Your organization approves families in AI Gateway; agents can use **Google** and **OpenAI** in production. **Model Family** on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#model-family) filters an agent's model lists.

#### Model provider <a href="#model-provider" id="model-provider"></a>

The vendor that hosts a model, such as OpenAI, Anthropic, AWS Bedrock, or Azure OpenAI. A family can have more than one provider, and the provider decides which cloud account and region serves the request. See [How Model Routing Works](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works).

#### Model tier <a href="#model-tier" id="model-tier"></a>

A named capability level — **Economy**, **Smart**, or **Premium** — that each model family maps to one of its models. Applications request a tier rather than a model name, so an administrator can change the model behind a tier without editing any agent. Configured in [Gateway Settings](/ai-workbench-qore/control-center/ai-gateway/gateway-settings).

#### Monitoring (section) <a href="#monitoring-section" id="monitoring-section"></a>

The Agent Config section that lists the agent's historical executions, one row per run. See [Monitoring](/ai-workbench-qore/console/agent-builder/monitor).

***

### N

#### Native on Cloud <a href="#native-on-cloud" id="native-on-cloud"></a>

A deployment where model hosting and inference stay inside a cloud tenancy your organization controls, reached through providers such as GCP Model Garden, Google Agent Platform, or Azure OpenAI, so the deployment makes no calls to public AI APIs. See [Security FAQ](/ai-workbench-qore/control-center/detailed-security-and-runtime-faq).

***

### O

#### OAuth client credentials (M2M) <a href="#oauth-client-credentials" id="oauth-client-credentials"></a>

A way to connect an MCP server that issues a client ID and secret instead of a sign-in page, so no user sign-in is needed. Turn on **Authenticate M2M (OAuth client credentials)** under **Advanced Settings** when connecting. See [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools#connect-with-client-credentials).

#### OnBuild <a href="#onbuild" id="onbuild"></a>

The trigger that runs automated tests when an app builds.

#### Online Evals <a href="#online-evals" id="online-evals"></a>

Production-side evaluation: [evaluators](#evaluator) score live executions in the background after an agent is deployed, without delaying responses. **Online Eval** in Control Center shows **Scores**, with the judge's evidence and a link to the judged conversation, and **Runs**, with each evaluator's run status. It complements offline [Evals](#evals). See [Online Eval](/ai-workbench-qore/control-center/evals/online-eval).

#### OpenRouter <a href="#openrouter" id="openrouter"></a>

An alternative gateway for a model family, using your organization's own OpenRouter API key. Requests are proxied to whichever upstream provider OpenRouter selects, so the serving provider and its region aren't yours to control. The default is the **UPTIQ AI Gateway**. See [How Model Routing Works](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works).

#### Operator <a href="#operator" id="operator"></a>

The coordinator that runs a team of specialized agents from one conversation. You describe a goal; it picks the agent whose description fits, hands the work off, and returns the result, keeping one conversation across every hand-off. Each space has one: the [Console Operator](#console-operator) and the [Governance Operator](#governance-operator). See [Operator](/ai-workbench-qore/core-concepts/operator).

#### Organization <a href="#organization" id="organization"></a>

Qore's top-level boundary, also called the **tenant** — one deployment for a customer, holding its own users, org-wide roles, brands, and one or more [accounts](#account). Org Settings manages the organization's accounts and brands; day-to-day work happens inside an account. See [Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized).

#### Overview (tab) <a href="#overview-tab" id="overview-tab"></a>

The default tab on [The Builder Canvas](/ai-workbench-qore/console/agent-builder/the-canvas#overview-and-flow-tabs), formerly **Layout**. Shows the agent with its Triggers, Knowledge, Skills, and Integrations cards around it.

***

### P

#### PII <a href="#pii" id="pii"></a>

Short for **personally identifying information**. PII includes data that identifies a person, such as a Social Security number, card number, email address, or phone number.

#### PII tokenization <a href="#pii-tokenization" id="pii-tokenization"></a>

Replacing detected PII values with opaque tokens before content reaches a model. The original value stays in the [vault](#vault), and a permitted downstream step can restore it. This is what [Sensitive Data Masking](#sensitive-data-masking) does; tokenization needs a compatible executor version. See [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking).

#### Plan (tab) <a href="#plan-tab" id="plan-tab"></a>

The former name of the [Flow (tab)](#flow-tab) on The Builder Canvas.

#### Planner <a href="#planner" id="planner"></a>

The part of the agent runtime that decides what skills to call, in what order, for each incoming request. The planner reads the agent's instructions and the user's input, then picks from [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities). When a [Checklist](#checklist) matches the request, the planner follows it; otherwise it plans dynamically. Pair this with the [Executor](#executor) entry.

#### Planning Model <a href="#planning-model" id="planning-model"></a>

A dropdown on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#planning-model) selecting the model used for planning tasks. It appears in `Advanced` mode with `Auto`, `Intelligent Planner`, or `Fast`, and can differ from the [Execution Model](/ai-workbench-qore/console/agent-builder/build/agent-behavior#execution-model).

#### Platform package <a href="#platform-package" id="platform-package"></a>

An app exported from Qore. Importing a Platform package restores it as exported. Git repositories and projects from other builders are converted into Platform apps.

#### Pre-attached Skills <a href="#pre-attached-skills" id="pre-attached-skills"></a>

The built-in skills every agent has, in two groups: [General](/ai-workbench-qore/platform-resources/skill-library/general-skills) and [Document](/ai-workbench-qore/platform-resources/skill-library/document-skills). Enable one from the **Pre-attached Skills** tab of [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).

#### Preprocessing Pipeline <a href="#preprocessing-pipeline" id="preprocessing-pipeline"></a>

A checkbox in the [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent) flow that runs additional preparation on uploaded content — chunking, OCR for scanned PDFs, and layout-aware extraction — before indexing.

#### Preview build vs. published build <a href="#preview-build-vs-published-build" id="preview-build-vs-published-build"></a>

An app has a **Preview** build and a **Published** build. Preview is the build you edit in the workspace. Published is the build users see at the live URL. DB Explorer and environment variables can use either scope.

#### Project <a href="#project" id="project"></a>

A container within an [account](#account) for related apps, agents, knowledge bases, flows, and design systems. Its resources share project context and remain isolated from other projects. You can pin the projects you use most. Earlier releases called this a **workspace**. See [Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized) and [Projects](/ai-workbench-qore/console/projects).

#### Prompt Sanitization <a href="#prompt-sanitization" id="prompt-sanitization"></a>

A toggle on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#enable-prompt-sanitization) that detects malicious user prompts before they reach the model. Shown as `Not Supported`, and saved as off, when the agent's executor version doesn't support it.

#### Python Code (skill) <a href="#python-code-skill" id="python-code-skill"></a>

A Skill Library skill that runs Python you wrote, at runtime. Distinct from the built-in **Run Python** skill, where the agent writes the code. See [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).

***

### Q

#### query\_knowledge <a href="#query_knowledge" id="query_knowledge"></a>

The ID of the built-in **Knowledge Search** skill, which searches the agent's attached knowledge by meaning. **Knowledge Lexical Search** matches the words themselves, and [Knowledge Graph Search](#knowledge-graph-search) reads governed graphs. All three are left out of a run when the agent has no knowledge attached. See [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills).

***

### R

#### reason <a href="#reason" id="reason"></a>

The ID of the built-in **AI Reasoning** skill, which the agent uses to think through complex topics, make decisions, or generate summaries. See [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills).

#### Reinforcement Learning <a href="#reinforcement-learning" id="reinforcement-learning"></a>

A **Agent Config** section, marked Preview, with three tabs: **Learning Cases**, **FAQ**, and **User Persona**. It holds what the agent carries forward, and the approval gate for [learning cases](#learning-case). See [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) and [Memory & Learning](/ai-workbench-qore/core-concepts/memory-and-learning).

#### Response Mode <a href="#response-mode" id="response-mode"></a>

A dropdown on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#response-mode) controlling the speed-versus-quality trade-off in responses: `Advanced`, `Balanced`, or `Flash`. Default `Advanced` produces higher-quality but slower responses.

#### Role <a href="#role" id="role"></a>

A named set of [capabilities](#capability) assigned to a user, held **per account membership** — the same person can hold different roles in different accounts, and several roles in one account. Qore has eight standard roles: Viewer, Billing Manager, Approver, Developer, Governance Manager, Auditor, Account Admin, and Organisation Admin. Roles your organization creates appear under **Custom Roles**. See [Roles](/ai-workbench-qore/control-center/admin/roles).

***

### S

#### Schedule <a href="#schedule" id="schedule"></a>

A saved instruction that runs an [Operator](#operator) at a set time, from **Schedules** in the top bar. Set it with a preset (hourly, daily, weekly, monthly) or a cron expression, in UTC, and choose the agents each run may use. Schedules made in Console run the Console Operator; those made in Control Center run the Governance Operator. See [Schedules](/ai-workbench-qore/console/console-operator/schedules).

#### Secret <a href="#secret" id="secret"></a>

An encrypted value — API key, token, or password — stored on [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) and referenced elsewhere as `$secret.{name}`. See also [Variable](#variable).

#### Sensitive Data Masking <a href="#sensitive-data-masking" id="sensitive-data-masking"></a>

The per-agent guardrail that replaces detected PII with opaque tokens before it reaches a model. Choose a [masking provider](#masking-provider), then a **Deny list** (mask only selected entity types) or an **Allow list** (mask every type except the selected ones). When it is off, content reaches the model unmasked. See [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking).

#### Setup Identity Token <a href="#setup-identity-token" id="setup-identity-token"></a>

A widget action that lets you try an agent as a specific signed-in person by pasting their token, for an agent with [Authentication](#authentication-agent) turned on. It appears under **Developer Mode**. **Available on request.** See [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1#setup-identity-token).

#### Single Sign-On <a href="#single-sign-on" id="single-sign-on"></a>

Signing in to Qore with **Continue with Google** or **Continue with Microsoft**, including Microsoft Entra ID work and school accounts. Each button is turned on per deployment. Access stays invite-only: an administrator invites each person first. See [Single Sign-On](/ai-workbench-qore/control-center/admin/single-sign-on).

#### Skill <a href="#skill" id="skill"></a>

A callable capability the agent can invoke at runtime — a built-in skill, a Skill Library skill, a tool from an MCP server or integration, a [custom skill](#custom-skill), a [flow](#flows), or another agent. Every skill the agent has appears in [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities). See [Skills & Tools](/ai-workbench-qore/core-concepts/skills-and-tools).

#### Skill Library <a href="#skill-library" id="skill-library"></a>

The platform's skills, documented in [Skill Library](/ai-workbench-qore/platform-resources/skill-library). It covers the built-in **General** and **Document** skills, and the skills you configure, such as API Call, JavaScript Code, Python Code, MCP Server, and Structured Data Query. **Skill Library** is also a tab in [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).

#### Space <a href="#space" id="space"></a>

A Qore product surface: **Console**, for project work, or **Control Center**, for account-wide governance. A switcher beside the platform logo moves between them, and teams can be associated with either or both. See [Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized).

#### SSN <a href="#ssn" id="ssn"></a>

Short for **Social Security number**. `SSN` is a US identity entity type available through the Regex masking provider.

#### Structured Data Query (skill) <a href="#structured-data-query-skill" id="structured-data-query-skill"></a>

A Skill Library skill that lets the agent ask questions of a database in natural language. The platform translates those questions to SQL and runs them. Reached from [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).

#### Suggested Changes <a href="#suggested-changes" id="suggested-changes"></a>

AI-generated recommendations produced by [Evals](#evals) after a run. Suggestions can target instructions, skills, knowledge, or guardrails, and can be applied back to the agent from the run results. See [Evals](/ai-workbench-qore/console/agent-builder/test/evals).

#### Sync <a href="#sync" id="sync"></a>

The step that brings changed files from a dataset into a knowledge base. Updating a file does nothing to the knowledge base until it syncs; each sync creates a new [knowledge version](#knowledge-version), and a completed sync is live. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

#### System agent <a href="#system-agent" id="system-agent"></a>

An agent provided with Qore and preconfigured for the account, such as **App Builder Agent**, **Agent Builder Agent**, **Knowledge Builder Agent**, **Document AI Agent**, or **Platform Q\&A Agent**. In Console, the Operator's system agents start on, and you can turn one off. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections).

***

### T

#### Team <a href="#team" id="team"></a>

A group of account members managed in **Admin**. Teams associate members with Console, Control Center, or both, and grant them access to specific agents and apps. See [Teams](/ai-workbench-qore/control-center/admin/teams).

#### Tenant <a href="#tenant" id="tenant"></a>

See [Organization](#organization).

#### Test Case <a href="#test-case" id="test-case"></a>

One evaluation item inside a [dataset](#dataset). In [Evals](/ai-workbench-qore/console/agent-builder/test/evals), a test case includes a question, an expected answer, and optional document context or attachments.

#### Toggle Panel <a href="#toggle-panel" id="toggle-panel"></a>

The icon in the chat header that hides or shows the builder chat. See [The Builder Canvas](/ai-workbench-qore/console/agent-builder/the-canvas).

#### Tool Execution Approval <a href="#tool-execution-approval" id="tool-execution-approval"></a>

The per-agent guardrail that pauses the agent before selected skills run and asks the user to **Allow** or **Deny** each call. A denied call is skipped and the run continues. **Enable for all skills** covers every current and future skill. See [Tool execution approval](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution).

#### Trigger <a href="#trigger" id="trigger"></a>

A named condition described in prose that, when met, fires the agent. Each trigger has a Source, Name, and Description. The description is interpreted by a runtime model rather than parsed as a rules expression. See [Triggers](/ai-workbench-qore/console/agent-builder/build/triggers).

#### Trigger Source <a href="#trigger-source" id="trigger-source"></a>

A required dropdown on the [Custom Trigger](#custom-trigger) form selecting the kind of event the trigger watches for. The sources available depend on the agent's setup. See [Triggers](/ai-workbench-qore/console/agent-builder/build/triggers).

#### Trivy <a href="#trivy" id="trivy"></a>

The scanner that [Security](/ai-workbench-qore/console/app-builder/security-scans) uses to find dependency vulnerabilities.

#### Try Agent <a href="#try-agent" id="try-agent"></a>

The canvas header action that opens the Agent Playground in a new tab, where you can chat with the agent. Needs the **Trigger Agent** capability, and the agent needs a widget key. See [The Builder Canvas](/ai-workbench-qore/console/agent-builder/the-canvas#canvas-header).

#### Try Knowledge <a href="#try-knowledge" id="try-knowledge"></a>

The page where you query a knowledge base, at any version, and see the chunks behind each answer. Opened with **▷** on a knowledge base. See [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge).

***

### U

#### UDG <a href="#udg" id="udg"></a>

Short for **Uptiq Data Gateway**. A managed integration layer that brokers connections to partner services in the [Integrations Hub](/ai-workbench-qore/console/integrations-hub), for integrations that use [Connect via UDG](#connect-via-udg).

#### UPTIQ managed key <a href="#uptiq-managed-key" id="uptiq-managed-key"></a>

The [AI Gateway](/ai-workbench-qore/control-center/ai-gateway) option where the platform supplies the model-provider credential and usage draws on your credit balance rather than a bill from the provider. The alternative is [Bring your own key](#bring-your-own-key). Track the spend in [Credit Usage](/ai-workbench-qore/control-center/cost-control/credit-usage).

***

### V

#### Variable <a href="#variable" id="variable"></a>

A non-sensitive value stored on [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) — base URLs, identifiers, and defaults — referenced elsewhere as `$agent.{name}`. See also [Secret](#secret).

#### Vault <a href="#vault" id="vault"></a>

The secure store that maps an original PII value to its opaque token. Authorized downstream steps can restore the original value when needed.

***

### W

#### web\_search <a href="#web_search" id="web_search"></a>

The ID of the built-in **Web Search** skill, which runs a web search through the language model to retrieve up-to-date information. See [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills).

#### Widget Key <a href="#widget-key" id="widget-key"></a>

A key type on [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication#key-types) used by the Embedded Chat widget and the TypeScript SDK client. It is safe to ship in browser code, because it works only from the platform itself and the [Allowed Domains](#whitelisted-domains).

***

### X

#### x-platform-key <a href="#x-platform-key" id="x-platform-key"></a>

The request header that carries a platform API key from **Admin → API Keys**. Agent runtime routes don't accept it; to call an agent, use the agent's own API key and secret. See [API Keys](/ai-workbench-qore/control-center/admin/api-keys).

***

{% 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 %}


# Steering & Reasoning

How the agent decides what to do.

An agent is not a chatbot with a script. Given a request, it decides what to do — which actions to take, in what order, and when it has done enough. **Steering** is how you influence that decision without writing the decision yourself.

Four things shape it: what you told the agent to do, how much rope you gave it, how hard it thinks, and whether it has done this before.

## The planner and the executor

Every request goes through two stages.

The **planner** reads your instructions and the user's input, then decides which skills to call and in what order. The **executor** runs that plan, calling each skill and feeding results forward.

They can run on **different models**. Planning happens once per request; execution may run many tool calls. A common pattern is a heavier model for planning and a lighter one for execution. Both are set on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior), from the models [AI Gateway](/ai-workbench-qore/control-center/ai-gateway) serves for your organization. Every model request an agent makes passes through AI Gateway.

{% hint style="info" %}
The planner can only choose from the agent's attached [Skills & Tools](/ai-workbench-qore/core-concepts/skills-and-tools). A skill that isn't attached cannot be used, no matter what your instructions say.
{% endhint %}

## Instructions: the one that matters most

[Instructions](/ai-workbench-qore/console/agent-builder/build/instructions) are the agent's operating brief. The platform feeds them to the model on every turn, so the rules, tone, examples, and procedures you write there shape every response.

A vague or self-contradicting brief produces an agent that fails in ways that are hard to debug, because nothing is technically broken.

## The levers

These sit on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior). Each trades something away.

| Lever                                                                                             | What it trades                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Autonomy** (`Low` / `Med` / `High`, default `Med`)                                              | Independence against visibility. High lets the agent commit to multi-step plans alone; Low makes it confirm more steps. See [Human-in-the-Loop](/ai-workbench-qore/core-concepts/human-in-the-loop).                                            |
| **Agent Capability** (`Auto` / `Intelligent Planner` / `Next Best Step` / `Fast`, default `Auto`) | Depth against latency and cost. `Auto` lets the platform decide per request. `Fast` lowers latency by leaving out persona memory, FAQ memory, CoT validation, and learning cases.                                                               |
| **Response Mode** (`Advanced` / `Balanced` / `Flash`, default `Advanced`)                         | Quality against speed. `Advanced` is slower and better; faster modes process more shallowly.                                                                                                                                                    |
| **Execution / Planning Model**                                                                    | Cost against reasoning quality — independently, per stage. **Model Family** filters both lists. Both models are chosen in `Advanced` mode, and the Planning Model only with a capability that plans (`Auto`, `Intelligent Planner`, or `Fast`). |

{% hint style="warning" %}
Behavior settings change the agent's **character**, not just its performance. The same instructions run by two different models produce two different agents.
{% endhint %}

## Planning fresh, or following a checklist

By default the planner builds a plan for every request from scratch. That is flexible and handles anything, but two runs of the same request may plan differently.

A [Execution Plan/Checklist](/ai-workbench-qore/console/agent-builder/build/execution-plan-checklist) is a reusable execution plan — a known-good sequence of skill calls. The agent derives them from its own successful runs: recurring patterns become reusable plans. When a request matches one, the planner follows it instead of improvising.

The trade is flexibility against predictability.

* **Checklists suit** repeated requests, multi-step workflows with a known order, and anything you need to review, explain, or audit.
* **Dynamic planning suits** varied requests, new agents whose usage patterns you don't know yet, and workflows that keep changing.

Most agents initially operate without checklists, and gain them as repeated execution patterns emerge.

## Making reasoning visible

The **execution trace** in the builder shows you how the agent read your instructions, which skills it chose, and how long each took. It is the first place to look when an agent does something surprising.

{% hint style="info" %}
**CoT Reasoning (beta) is deprecated.** It can no longer be turned on. An agent that already has it on can turn it off on Agent Behaviour, but once it is off it can't be turned on again.
{% endhint %}

## Where this is configured

* [Instructions](/ai-workbench-qore/console/agent-builder/build/instructions) — the operating brief
* [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior) — autonomy, capability, response mode, model family, models
* [Execution Plan/Checklist](/ai-workbench-qore/console/agent-builder/build/execution-plan-checklist) — reusable plans
* [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning) — which executor version runs the agent

***

{% 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 %}


# Skills & Tools

What an agent can actually do.

A reasoning model can produce text. An **agent** can act — send the email, write the record, query the ledger, read the document. Skills are what turn one into the other.

A skill is a single action the agent can take. The set of skills attached to an agent is its complete vocabulary of actions, and the planner chooses from exactly that set. Nothing else is available to it, whatever the instructions say.

{% hint style="info" %}
**The list is the planner's universe.** A skill that isn't attached cannot be used. A skill that is attached but whose description doesn't match the requests users actually send won't get picked. Auditing that list is the highest-value thing you can do when an agent isn't behaving as expected — see [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities).
{% endhint %}

## Where skills come from

Seven kinds of skill, all landing in the same list. [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent#understanding-skills) compares them side by side.

**Built-in.** Every agent has the same built-in skills, in two groups in its **Skills** panel. **General** covers reasoning, web search, knowledge search, code execution, files, and messages. **Document** covers extracting, classifying, summarizing, and generating documents. Enable or disable each one from the **Pre-attached Skills** tab of Add Skill. See [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills) and [Document skills](/ai-workbench-qore/platform-resources/skill-library/document-skills). An agent with a governed graph attached queries it with the **Knowledge Graph Search** skill; see [Knowledge & Context](/ai-workbench-qore/core-concepts/knowledge-and-context).

**The Skill Library.** Skills that you add and configure for your own systems and logic, such as **API Call**, **JavaScript Code**, **Python Code**, **MCP Server**, and **Web Crawler**. See the [Skill Library](/ai-workbench-qore/platform-resources/skill-library) reference.

**Connectors.** Connecting an integration or an MCP server registers its skills into the agent automatically. Two catalogs:

| Catalog                                                                             | Holds                                                                               | Reach for it when                                                          |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services) | Pre-built connectors to recognized SaaS products — Stripe, Resend, Twilio           | The action involves a product with a logo and a stable customer-facing API |
| [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools)               | Model Context Protocol servers — market data, scraping, search, knowledge retrieval | The action involves a data API or a generic tool                           |

The catalogs overlap, so the same service can appear in both.

**Control Center → Govern →** [**Connectors**](/ai-workbench-qore/control-center/govern/connectors) lists what the account has made available, in three tabs: **Integrations**, **MCP Servers**, and **Platform Skills**. It is the outer limit every agent inherits: an agent can't use a connector the account hasn't made available, whatever its own configuration requests.

**Custom skills.** Your own procedures and know-how, written in a `SKILL.md` file and uploaded to the agent. See [Custom skills](/ai-workbench-qore/platform-resources/skill-library/custom-skills). To reach a service that isn't in either catalog, add an [API Call](/ai-workbench-qore/platform-resources/skill-library/api-call) skill instead.

**Flows.** A multi-step process you built in Flows, added to the agent as one skill. Use a flow when the steps are fixed and should always run in the same order. See [Flows](/ai-workbench-qore/console/flows).

**Other agents.** Another agent in the project, added as a sub-agent. Use one when a different agent is better suited to part of the job. See [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent#add-another-agent-as-a-skill).

## Skills versus protocols

A skill is *an action*. A protocol is *a way of reaching things*. MCP is a protocol: connecting one MCP server can register several skills at once. That's why MCP appears both here and in [Protocols](/ai-workbench-qore/core-concepts/protocols) — it's the mechanism by which a class of skills arrives.

## Turning skills off

Every attached skill is a choice the planner can make. A disabled skill is one the agent can't use.

Built-in skills can be disabled one at a time, without affecting the ones that remain. Open [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities) to see every skill on the agent. To require a person's approval before selected skills run, use Tool Execution Approval; see [Guardrails & Validation](/ai-workbench-qore/core-concepts/guardrails-and-validation).

## Where this is configured

* [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities) — the full list, and the planner's universe
* [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent) — the flow for attaching one
* [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services) — SaaS connectors, per agent
* [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools) — MCP servers, per agent
* [Skill Library](/ai-workbench-qore/platform-resources/skill-library) — the built-in skills, and the skills you configure

***

{% 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 %}


# Knowledge & Context

What the agent can read.

A model knows what it was trained on. It does not know your credit policy, your product catalogue, or what your customer asked for last Tuesday. **Knowledge** is how you give an agent something to read that the model was never trained on.

The mechanism is retrieval: rather than putting everything in front of the model, the agent searches your material for the parts relevant to *this* request and pulls only those into context.

## Why retrieval instead of just uploading everything

Context is finite. A model can only hold so much at once, and filling it with material that isn't relevant to the current question makes answers worse, not better — the signal is still in there, but so is everything else.

Retrieval means your knowledge can be far larger than any context window, and what reaches the model is the part that matters. The cost is that retrieval has to find the right material. Two places show you what it works from:

* [Document processing](/ai-workbench-qore/console/knowledge/document-processing) — see how Qore split, tagged and extracted each document.
* [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge) — query a knowledge base and see the chunks behind each answer.

## Getting knowledge into an agent

Two steps, and they're separate on purpose.

1. [Knowledge](/ai-workbench-qore/console/knowledge) — build a knowledge base from your files. Qore processes them into a table of contents, tags, and embeddings. It exists whether or not any particular agent uses it. You can build one on the **Knowledge** page, by asking the [Console Operator](/ai-workbench-qore/console/console-operator), or from the Agent Builder chat.
2. [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent) — point a specific agent at a knowledge base so its planner can query it.

Separating them means one body of knowledge can serve many agents, and an agent can draw on more than one.

## Keeping knowledge current

A knowledge base changes only when you **sync** it. Updating a file in a dataset does nothing to the knowledge base until that file is synced. Each sync creates a new **knowledge version**, and agents use the latest completed version. There is no draft or publish stage: a completed sync is live.

You can upload a new version of a file to an existing dataset, including from Google Drive, OneDrive, SharePoint, or a website. A dataset with auto sync turned on syncs eligible new files automatically. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

## Governed graphs

A [governed graph](/ai-workbench-qore/control-center/govern/governed-graph) is an institution's knowledge graph: its products, pricing, policies, document requirements, rules, and the sources behind each fact. You upload it in **Control Center → Govern → Governed Graph**. It is created for the whole account, so every project can read it.

Once uploaded, a graph is knowledge in the account, and you attach it to an agent like any other knowledge. The agent queries it with the **Knowledge Graph Search** skill, for structured questions such as which documents a product requires, rather than searching it as text.

## Knowledge is not memory

Easy to conflate, different in an important way.

* **Knowledge** is what you give the agent to read — deliberate, curated, the same for everyone.
* [Memory & Learning](/ai-workbench-qore/core-concepts/memory-and-learning) is what the agent carries forward from its own experience — accumulated, per-user or per-agent, and gated by approval where it changes behavior.

An agent answering "what is our maximum LTV?" is using knowledge. An agent remembering that *you* always ask about commercial rather than retail is using memory.

## How the agent reaches it

At runtime, the planner uses a skill to search attached knowledge: **Knowledge Search**, which finds passages by meaning, or **Knowledge Lexical Search**, which matches the words themselves. Both are built-in General skills. A governed graph is reached through **Knowledge Graph Search**. Retrieval is subject to the same rule as everything else the agent does: if the skill isn't enabled, the knowledge can't be reached, however well the knowledge base is built. See [Skills & Tools](/ai-workbench-qore/core-concepts/skills-and-tools).

## Where this is configured

* [Knowledge](/ai-workbench-qore/console/knowledge) — building knowledge bases from your files
* [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions) — sync, knowledge versions, and auto sync
* [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent) — pointing an agent at a knowledge base or a governed graph
* [Governed Graph](/ai-workbench-qore/control-center/govern/governed-graph) — uploading a governed graph
* [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills) — Knowledge Search and Knowledge Lexical Search, the built-in skills that query attached knowledge

***

{% 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 %}


# Memory & Learning

What the agent carries forward — and what it deliberately doesn't.

By default, an agent starts every conversation knowing nothing about who it is talking to. That is often correct: an agent processing loan documents doesn't need to remember anyone.

But some agents get better by remembering, and Qore separates that into distinct kinds — because they have different scopes, different risks, and different rules about what may enter them.

## Three kinds of memory

All three live under **Agent Config → Reinforcement Learning** (Preview), one tab each.

| Kind                    | Tab                | What it carries                                                  | Default              |
| ----------------------- | ------------------ | ---------------------------------------------------------------- | -------------------- |
| **User persona memory** | **User Persona**   | What an individual user has asked about, preferred, or corrected | Off                  |
| **FAQ memory**          | **FAQ**            | Canonical answers to questions the agent already knows           | Off                  |
| **Learning cases**      | **Learning Cases** | Reviewed corrections from real production behavior               | Manual approval only |

**User persona memory** remembers what an individual user has asked about, preferred, or corrected — across conversations. Turn it on with **Enable User Persona**. The tab lists the stored persona memories, and you can delete one.

**FAQ memory** lets the agent reuse a stored canonical answer when a question matches a known FAQ, rather than answering from scratch each time. Turn it on with **Enable FAQ**. The tab lists the stored FAQs and their answers.

**Learning cases** are corrections captured from real production behavior — a case where the agent got something wrong and a person recorded what the right answer would have been.

{% hint style="info" %}
**The Fast capability leaves memory out.** With **Agent Capability** set to `Fast`, the agent doesn't use persona memory, FAQ memory, or learning cases, and the User Persona tab can't be changed. See [Steering & Reasoning](/ai-workbench-qore/core-concepts/steering-and-reasoning).
{% endhint %}

## Why learning cases require a human

Learning cases do not enter memory automatically. Each one is reviewed and approved by a person first.

{% hint style="warning" %}
**Approval is manual. Auto-approval is intentionally disabled,** so a malicious or mistaken input cannot quietly change the agent's behavior.
{% endhint %}

See [Human-in-the-Loop](/ai-workbench-qore/core-concepts/human-in-the-loop).

## The improvement loop

Memory is where the operating loop closes.

1. [Monitor](/ai-workbench-qore/console/agent-builder/monitor) production behavior and score live conversations to find where the agent missed.
2. Record what the correct behavior should have been — a **learning case**.
3. **Review and approve** it. This is the gate.
4. Validate the improvement with [Evals](/ai-workbench-qore/console/agent-builder/test/evals) before rolling it out more broadly.

The agent improves from real outcomes, not just from isolated test runs — but only through a door a person opens.

## Context is not memory

A related idea, easy to confuse. **Memory** is what the agent carries across conversations. **Context** is what it holds within one — the conversation so far, retrieved documents, tool results.

Context is finite. Long conversations eventually exceed what the model can hold. **Auto-compaction**, on [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior), summarizes the conversation when it nears the context window, at a threshold you set between 50% and 95% of the window. It appears when the agent's executor version supports it. Retrieval — pulling only the relevant material into context rather than everything — is covered in [Knowledge & Context](/ai-workbench-qore/core-concepts/knowledge-and-context).

## Where this is configured

* [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) — Learning Cases, FAQ, and User Persona, and the learning-case approval flow
* [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior) — Agent Capability and Auto-compaction
* [Monitor](/ai-workbench-qore/console/agent-builder/monitor) and [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval) — where misses are found
* [Evals](/ai-workbench-qore/console/agent-builder/test/evals) — validating an improvement before it ships

***

{% 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 %}


# Guardrails & Validation

Protect agent runs with PII masking, tool approval, and model policies.

Instructions guide an agent’s decisions. Guardrails enforce controls around its execution.

Guardrails protect sensitive data before model requests. They can also pause selected skills for user approval. Organization-level policies restrict approved model families and providers.

Open **Agent Config → Guardrails** to manage the controls for an agent.

{% hint style="info" %}
**Preview.** Guardrails is a Preview feature. Controls and labels may change.
{% endhint %}

## What guardrails protect

| Guardrail                          | Protection                                                          | Configuration                                                                               |
| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Sensitive Data Masking             | Replaces detected PII with opaque tokens before it reaches a model  | [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking)       |
| Tool Execution Approval            | Pauses selected skill calls until the user allows or denies them    | [Tool execution](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution) |
| Allowed LLM Families and Providers | Limits model requests to organization-approved models and providers | [AI Gateway](/ai-workbench-qore/control-center/ai-gateway)                                  |

Sensitive Data Masking and Tool Execution Approval are toggleable per agent. Model policy guardrails are always enforced by the AI Gateway.

## Configure guardrails

1. Open **Agent Config → Guardrails**.
2. Turn on **Sensitive Data Masking** or **Tool Execution Approval**.
3. Select the **gear** in that row to define its coverage.

The Guardrails page lists each guardrail’s **Name**, **Type**, and **Status**. A toggle controls per-agent guardrails. An **Always enforced** badge marks organization-level model policies.

## Mask PII before model requests

PII masking detects selected entities and tokenizes their values. The original value stays in a secure vault. A permitted downstream step can restore it when needed.

Choose a provider, then define the entity rule:

* A **Deny list** masks only selected entity types.
* An **Allow list** masks every type except selected entities.

Unselected entities reach the model in clear text.

Tokenization requires a compatible executor version. See [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking) for providers, entity types, and tokenization details.

## Require approval before skill calls

Tool Execution Approval pauses an agent before it runs selected skills. The user can allow the call or deny it. When denied, the agent continues without that call.

You can select individual skills, or turn on **Enable for all skills** to require approval for every current and future skill.

See [Tool execution](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution) for approval settings and the user experience.

## Keep model use within policy

Every model request an agent makes passes through the AI Gateway: chat, reasoning, tool calls, document classification, summaries, conversation titles, and knowledge queries. The AI Gateway enforces the approved LLM families and providers for every model request. These guardrails are set by your organization. You can’t disable them per agent.

## Stop an agent in an emergency

Guardrails act inside a run. To stop runs that are already in flight, use **Control Center → Govern → Agent Controls**. Stop one agent, or every agent at once. Stopping a system agent, such as the Operator, also stops every run and helper agent it started. See [Agent Controls](/ai-workbench-qore/control-center/govern/agent-controls).

#### Related

* [Guardrails](/ai-workbench-qore/console/agent-builder/deploy/guardrails) — configure per-agent controls
* [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking) — choose providers and masked entities
* [Tool execution](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution) — require approval before skills run
* [AI Gateway](/ai-workbench-qore/control-center/ai-gateway) — the AI Gateway, where model policy is set
* [Agent Controls](/ai-workbench-qore/control-center/govern/agent-controls) — stop agents in an emergency

***

{% 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 %}


# Human-in-the-Loop

The points where a person stays in the decision.

An agent that acts on its own is the point. An agent that acts on its own *where it shouldn't* is the risk. In a bank, the difference is usually not whether the agent is capable — it's whether a person is standing in the right place when it commits to something.

Qore's controls fall into two families, and it's worth being precise about which is which:

* **Automated controls** — [Guardrails & Validation](/ai-workbench-qore/core-concepts/guardrails-and-validation) such as Sensitive Data Masking and model policy, and [Evals](/ai-workbench-qore/core-concepts/evals) scoring live traffic. A machine checks the agent.
* **Human controls** — the subject of this page. A person checks the agent.

## Where a person can stand

### Before the agent commits: Autonomy

[Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior#autonomy) is a slider — `Low`, `Med`, `High`, defaulting to `Med`. It sets how independently the agent acts without checking back.

* **High** — the agent commits to multi-step plans on its own.
* **Low** — the agent confirms more steps before proceeding.

This is a dial rather than a switch.

### Before a skill runs: Tool Execution Approval

[Tool execution](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution) pauses the agent before it runs selected skills and asks the user whether the call should proceed. **Allow** runs the skill and continues the run. **Deny** blocks the call, and the agent continues without it. Choose the skills one by one, or turn on **Enable for all skills** to cover every current and future skill.

### When an agent needs an answer: questions and Gates

In an Operator conversation, an agent that needs a decision stops and asks. The question appears as a card above the composer. Pick a numbered answer, write your own, attach a file when the agent asks for one, or select **Skip**.

A conversation that ends on a question waits until you answer. It is listed on [Gates](/ai-workbench-qore/console/console-operator/gates), in the top bar of Console and of Control Center. Only your requests appear there, and only you can answer them.

### Before a governance change runs: staged actions

The [Governance Operator](/ai-workbench-qore/control-center/governance-operator) in Control Center doesn't act on its own. It stages each proposed change, and nothing runs until you approve it. The Console Operator, by contrast, dispatches work as soon as you ask.

### When an evaluator is unsure: Human Review

An evaluator scores each live execution with a rating and a confidence. When the confidence is below the evaluator's threshold and routing to human review is turned on, the result becomes a task in [Human Review](/ai-workbench-qore/control-center/evals/human-review), where a reviewer records a verdict. See [Evals](/ai-workbench-qore/core-concepts/evals).

### Before the agent learns: learning-case approval

The agent can improve from its own production history — but nothing enters its memory without a person approving it.

{% hint style="warning" %}
**Auto-approval is intentionally disabled,** so a malicious or mistaken input cannot quietly change the agent's behavior.
{% endhint %}

See [Memory & Learning](/ai-workbench-qore/core-concepts/memory-and-learning) and [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings).

### Before code exists: plan review

In [App Builder](/ai-workbench-qore/console/app-builder/plan), **Plan Mode** presents a proposed architecture — features, logic, extra ideas — and waits. You click **Start building** to commit, or **Revise plan** to iterate. Nothing is generated until you agree. See [Plan](/ai-workbench-qore/console/app-builder/plan).

## Seeing enough to intervene

A person can only stay in the loop if they can see what the agent did:

* **The execution trace** — in the builder, the full record of how the agent read your instructions, which skills it chose, and how long each took. For builders, not end users.
* **The Operator transcript** — each step the Operator took, each question it asked with the answer beneath it, and a card for each agent it handed work to. **Open full run** shows every step that agent took. See [Console Operator](/ai-workbench-qore/console/console-operator).
* [Monitor](/ai-workbench-qore/console/agent-builder/monitor) **and** [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval) — what the agent actually did in production, scored.

## The human controls at a glance

| Control                 | Where it is set                                        | What the person does                          |
| ----------------------- | ------------------------------------------------------ | --------------------------------------------- |
| Autonomy                | Agent Config → Agent Behaviour                         | Sets how many steps the agent confirms        |
| Tool Execution Approval | Agent Config → Guardrails                              | Allows or denies each selected skill call     |
| Questions and Gates     | Operator conversations; **Gates** in the top bar       | Answers, attaches a file, or skips            |
| Staged actions          | Governance Operator, in Control Center                 | Approves a proposed change before it runs     |
| Human Review            | Control Center → Evals                                 | Records a verdict on a low-confidence score   |
| Learning-case approval  | Agent Config → Reinforcement Learning → Learning Cases | Approves a correction before it enters memory |
| Plan review             | App Builder, Plan Mode                                 | Starts building or revises the plan           |

## Where this is configured

* [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior) — Autonomy
* [Tool execution](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution) — approval before skills run
* [Gates](/ai-workbench-qore/console/console-operator/gates) — conversations waiting for your answer
* [Governance Operator](/ai-workbench-qore/control-center/governance-operator) — staged actions
* [Human Review](/ai-workbench-qore/control-center/evals/human-review) — reviewing low-confidence scores
* [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) — learning-case approval
* [Plan](/ai-workbench-qore/console/app-builder/plan) — Plan Mode review, in the App Builder
* [Guardrails & Validation](/ai-workbench-qore/core-concepts/guardrails-and-validation) — the automated counterpart

***

{% 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 %}


# Protocols

How the agent reaches out, and how your product reaches in.

An agent that can only be used inside the builder isn't much use. Two directions matter, and they're easy to confuse because the product uses the word "integration" for both.

* **Outbound** — the agent reaching *out* to systems your business runs on. Covered in [Skills & Tools](/ai-workbench-qore/core-concepts/skills-and-tools) and the shared [Integrations Hub](/ai-workbench-qore/console/integrations-hub) catalog.
* **Inbound** — your product reaching *in* to the agent. That's this page.

## MCP: the outbound protocol

**Model Context Protocol (MCP)** is a general protocol for connecting external tools to an agent. Connecting one MCP server can register several tools at once — that's what distinguishes it from a single skill: it's a mechanism by which a class of capability arrives.

Qore ships a catalog of MCP servers — market data, SEC filings, web scraping, search APIs, knowledge-base retrieval. Each server's tools become available to the planner through [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities).

MCP is how an agent reaches the long tail of capability the platform doesn't ship as a first-party connector. See [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools).

An MCP server that issues a client ID and secret instead of showing a sign-in page can be connected with **OAuth client credentials (M2M)**, so no user sign-in is needed. See [Connect with client credentials](/ai-workbench-qore/console/agent-builder/build/mcp-tools#connect-with-client-credentials).

For every way to connect a server, how connections authenticate, where they're governed, and Qore's own MCP servers for coding agents, see [MCP](/ai-workbench-qore/core-concepts/mcp).

## Three ways in

Once an agent works, you wire it into your product one of three ways. The right choice depends on where the agent runs and how much of the interface you want to own.

| If you want to…                                           | Use                                             | Runtime                      |
| --------------------------------------------------------- | ----------------------------------------------- | ---------------------------- |
| Drop a chat onto a web page with no UI to build           | **Embedded Chat**                               | Browser, prebuilt UI         |
| Call the agent from a backend, service, or scheduled job  | **Agent API**, with the `raw (HTTP)` client     | Server-to-server, no browser |
| Drive the agent from your own front end, with your own UI | **Agent API**, with the `TypeScript SDK` client | Browser, your UI             |

They share the same credentials and domain rules. All three are documented in full on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration). For the concepts behind them, see [Embed Agent](/ai-workbench-qore/core-concepts/embed-agent) and [Widget](/ai-workbench-qore/core-concepts/widget).

### What the choice implies

The decision isn't only about convenience — it changes what the agent should be configured to do.

* **Embedded Chat and the TypeScript SDK run in a browser**, so [Allowed Domains](/ai-workbench-qore/console/agent-builder/deploy/authentication#allowed-domains) applies: you declare where the agent may be embedded, and it refuses to run anywhere else.
* **The raw HTTP client is server-to-server**, with no browser. It uses an API key and secret, and Allowed Domains doesn't apply.
* **Output format follows the consumer.** **Agent Output Format** is `Markdown` or `Json`, set on [Basic Details](/ai-workbench-qore/console/agent-builder/build/basic-details).

## Who is calling: Authentication

Access keys identify the calling application. [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) identifies the person. Turn it on for an agent, choose **Microsoft Entra ID** or **Google**, and Qore verifies the caller's token before each run.

* Send the token beside the message in an Agent API request, or pass it to the Embedded Chat widget.
* A verified token is available to the agent's MCP connections as `$auth.token`, so the downstream system can apply that person's permissions. Skills and instructions can't read it.
* A request without a token still runs, without `$auth.token`. A request with an invalid token is rejected.
* **Setup Identity Token** lets you try an agent as a specific signed-in person by pasting their token. It is available on request.

## Versions travel together

An integration is a contract between your code and a specific agent runtime, so the versions matter.

{% hint style="info" %}
Versions are per agent. Read the **SDK version** and **Executor version** from the agent's **Agent Config Panel**, and use those in your app and API calls. See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration).
{% endhint %}

The executor changes over time — new versions add capabilities, fix issues, and sometimes deprecate older behaviors. New agents use the latest version available to your tenant; existing agents stay on their current version until you migrate them. [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning) is where that is set.

## Where this is configured

* [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration) — Embedded Chat, the Agent API, the TypeScript SDK, and their credentials
* [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools) — the outbound MCP catalog, and connecting with client credentials
* [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication) — the keys each integration uses
* [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) — verifying the person who calls the agent
* [Allowed Domains](/ai-workbench-qore/console/agent-builder/deploy/authentication#allowed-domains) — where browser integrations may run
* [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning) — executor version

***

{% 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 %}


# MCP

How Qore uses the Model Context Protocol: agents connecting to outside MCP servers, and coding agents connecting to Qore's own MCP servers.

**Model Context Protocol (MCP)** is an open protocol for connecting language models to external tools and data. An **MCP server** exposes a set of **tools**; an **MCP client** connects to the server, lists its tools and calls them.

Qore is on both sides of that protocol:

| Direction    | MCP client                                       | MCP server                                                | Where it's set up                                                |
| ------------ | ------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------- |
| **Outbound** | A Qore agent                                     | An MCP server run by a vendor, by your company, or by you | Agent Builder: **Create MCP Connection**                         |
| **Inbound**  | Your coding agent, such as Claude Code or Cursor | Qore's own MCP servers                                    | **Build from your IDE** in the Agent Builder and the App Builder |

In neither direction do you build an MCP server inside Qore. Outbound, the server already exists somewhere else and the agent connects to it. Inbound, Qore runs the servers and your coding agent connects to them.

## MCP terms in Qore

| Term                      | What it is in Qore                                                                                                                                                               |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP server**            | A program, reached at a URL, that exposes tools over MCP. In Qore it's always outside the agent: a vendor's, your company's, or one of Qore's own.                               |
| **MCP tool**              | One action an MCP server exposes. Each tool becomes something the agent can call.                                                                                                |
| **MCP connection**        | An agent's saved link to one MCP server: its name, URL, credentials, headers, and which of the server's tools the agent may use. It belongs to one agent.                        |
| **Create MCP Connection** | The form that creates an MCP connection. Every route to an outside server opens it.                                                                                              |
| **MCP Tools**             | The page under **Agent Config** › **Integration Tools & Connectors** that lists the catalog of servers.                                                                          |
| **MCP Marketplace**       | The tab in **Add Skill** that lists the same catalog. Each entry holds a server's name, URL, category, description and the fields it needs from you.                             |
| **MCP Server** (skill)    | The Skill Library entry that opens Create MCP Connection blank, for any server by URL.                                                                                           |
| **Web Crawler** (skill)   | A Skill Library entry that opens Create MCP Connection prefilled for Firecrawl.                                                                                                  |
| **MCP configuration**     | In Export Agent, a connection's credentials and settings: OAuth client ID and secret, headers and tokens. Off by default. See [What an export carries](#what-an-export-carries). |
| **MCP config file**       | A JSON file with an `mcpServers` object, the format MCP clients use. **Import Config File** fills the form from the first server in it.                                          |
| **Connector**             | The Control Center word for anything an agent can reach. **Connectors** › **MCP Servers** lists every MCP connection in the account.                                             |
| **Redirect URL**          | The callback address Qore gives you to register in an MCP server's OAuth app, so the server can return to Qore after someone signs in.                                           |
| **M2M**                   | Machine-to-machine: the OAuth client credentials grant. The agent signs in to the server as itself, with no person involved.                                                     |
| **`$auth.token`**         | The verified identity token of the person calling the agent, available only inside MCP connection settings.                                                                      |
| **Supervision mode**      | Per tool: **Always Ask Permissions** or **Allow Unsupervised**.                                                                                                                  |
| **Build from your IDE**   | The dialogs in the Agent Builder (**Connect to coding agents (MCP)**) and the App Builder that give your coding agent Qore's MCP servers.                                        |
| **`x-platform-key`**      | The header that carries the API key for Qore's MCP servers. These keys are separate from an agent's API keys and widget keys.                                                    |

## Outbound: an agent connecting to an MCP server

An MCP connection is a skill. Once it's created, the server's enabled tools are available to the agent, and the agent chooses among them at run time. See [Skills & Tools](/ai-workbench-qore/core-concepts/skills-and-tools).

### One form, three starting points

Every outbound connection is made in **Create MCP Connection**. The three routes differ only in what's filled in for you.

| Start from                                                                                 | What's filled in                                                                                                              |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| A server in **MCP Marketplace** or **MCP Tools**                                           | **Connection Name** and **Remote MCP Server URL**, plus a required field for each value the server needs, such as **Api Key** |
| **MCP Server** in the [Skill Library](/ai-workbench-qore/platform-resources/skill-library) | Nothing. Enter any server's name and URL                                                                                      |
| **Web Crawler** in the Skill Library                                                       | Name **Web Crawler** and Firecrawl's URL, with `{{api_key}}` for you to replace                                               |

Every route shows the same warning first: *This connector hasn't been officially verified by UPTIQ. Make sure you trust it before using it, as you'll be responsible for any actions it performs.* It appears for catalog servers too.

#### How catalog fields are used

A catalog server's URL or headers can hold placeholders, such as `{{api_key}}`. Qore replaces each placeholder with what you enter in the matching field, then saves the result.

| Catalog server                                                        | Field you fill in | Where Qore puts it                |
| --------------------------------------------------------------------- | ----------------- | --------------------------------- |
| Tavily, Alpha Vantage, Finfeed SEC, Finfeed Stock, CoinAPI, Firecrawl | **Api Key**       | The server URL                    |
| Core Banking Sandbox API                                              | **Token**         | An `Authorization: Bearer` header |
| AWS Knowledge Base Retrieval                                          | None              | —                                 |

{% hint style="warning" %}
**A key placed in the URL is saved in the URL.** [Connectors](/ai-workbench-qore/control-center/govern/connectors) shows each connection's URL in full, so anyone who can open it can read the key. Enter a `$secret.` reference, such as `$secret.TAVILY_API_KEY`, instead of the key itself: the saved URL then holds the reference. See [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables).
{% endhint %}

{% hint style="warning" %}
**Core Banking Sandbox API returns simulated data.** Use it to build and test an agent, not to reach a real core banking system.
{% endhint %}

### Advanced Settings: how Qore signs in to the server

**Advanced Settings** doesn't create anything on the Qore side. It holds the credentials that Qore, as the client, presents to the MCP server. Use it for any server, from the catalog or your own.

| Setting                                         | Use it when                                                        | What happens                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Register this Redirect URL**                  | The server signs people in through OAuth                           | Copy the Redirect URL and add it as an allowed redirect URI in the OAuth app on your MCP server. **OAuth Client ID** and **OAuth Client Secret** are optional: if the server's authorization service supports dynamic client registration, Qore registers itself; if it doesn't, enter the client ID the OAuth app gave you, or the connection fails. The banner shows only when the agent's executor version supports it, and M2M is off. |
| **Authenticate M2M (OAuth client credentials)** | The server issues a client ID and secret instead of a sign-in page | **Token URL**, **OAuth Client ID** and **OAuth Client Secret** become required; **Scope** is optional. The agent requests its own token. There's no sign-in step and no Redirect URL. See [Connect with client credentials](/ai-workbench-qore/console/agent-builder/build/mcp-tools#connect-with-client-credentials).                                                                                                                     |
| **Headers**                                     | The server takes a key or token in a header                        | Key and value pairs sent with every request to the server.                                                                                                                                                                                                                                                                                                                                                                                 |

#### References you can use in the form

* `$secret.<name>` and `$agent.<name>` resolve to the agent's stored [secrets and variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables). Qore resolves them across the whole connection, including the URL and headers.
* `$auth.token` is offered in the catalog fields, **OAuth Client ID**, **OAuth Client Secret** and **Headers** when the agent has [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) turned on. It resolves to the verified token of the person calling the agent, so the server can apply that person's permissions. It works only in MCP connection settings: skills and instructions can't read it. Without a token in the request, it resolves empty.

### The connection flow

{% stepper %}
{% step %}

#### Enter the connection

Fill in the form, or **Import Config File**, then select **Next**. Qore connects to the server to check it.
{% endstep %}

{% step %}

#### Authorize, if the server asks

If the server needs an OAuth sign-in and Qore has no token for it, **Waiting for Authorization** appears. Select **Connect to Authorize**, sign in to your account in the pop-up and grant the permissions. The dialog continues by itself once you're authorized. Qore skips this check for M2M connections and for URLs ending in `/sse`.
{% endstep %}

{% step %}

#### Choose tools and settings

**Tools and Settings** lists the server's tools, all enabled, with a count such as `5 of 5 tools enabled`.

* **Enable All Tools** turns every tool on or off.
* Each tool has its own switch.
* Each tool has a supervision mode: **Always Ask Permissions**, the default, or **Allow Unsupervised**. The menu beside **Enable All Tools** sets it for every tool at once.
* Select the pencil beside a tool's description to rewrite it.
* A warning icon marks a tool whose input schema is invalid, which might not work with every model.
  {% endstep %}

{% step %}

#### Create the connection

Select **Create Connection**.
{% endstep %}
{% endstepper %}

### Managing a connection

Open an existing connection to see **MCP Server Connection**: its name and URL, its tools, and these actions.

| Action                       | What it does                                                                                                                                                                                          |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect** / **Disconnect** | Turns the connection on or off. Disconnecting asks first: *Disconnecting will stop all ongoing sessions using this MCP server.*                                                                       |
| **Remove**                   | Permanently removes the MCP server from the agent, after a confirmation.                                                                                                                              |
| **Initialize**               | Shown instead of Connect for a connection that has no credentials yet, such as one imported without its MCP configuration. Reopens Create MCP Connection with its name and URL, so you can finish it. |
| Manage tools                 | Change which tools are enabled, their supervision modes and descriptions. You can refresh the tool list from the server.                                                                              |

{% hint style="info" %}
**Re-enter the client secret when you edit an M2M connection.** It isn't shown again after saving.
{% endhint %}

### What an export carries

[Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent) always includes the agent's MCP connections. **Include MCP configuration**, off by default, decides whether their credentials go too.

| Include MCP configuration | Each connection in the package                                                        | After import         |
| ------------------------- | ------------------------------------------------------------------------------------- | -------------------- |
| Off (default)             | Without its OAuth client ID and secret, headers or tokens, and marked not initialized | Shows **Initialize** |
| On                        | As it is, with its credentials and settings                                           | Ready as it was      |

Ticking it shows a warning that exporting MCP configuration may expose sensitive credentials, internal tools or privileged access.

### Where a connection shows up

| Place                                                                                                | What it shows                                                                         |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| The [canvas](/ai-workbench-qore/console/agent-builder/the-canvas)                                    | A node in the Skills band, with the server's name                                     |
| [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities)      | The server's tools                                                                    |
| [Connectors](/ai-workbench-qore/control-center/govern/connectors) › **MCP Servers** (Control Center) | One row per connection: name and full URL, **Standing**, **Project**, and **Used by** |
| [DB Query Logs](/ai-workbench-qore/control-center/observe/db-query-logs) (Control Center)            | Database operations in the **MCP** module                                             |

### Scope

* **A connection belongs to one agent.** Connectors lists the same server once for each agent that connects to it, with that agent's project.
* **The account sets the outer limit.** An agent can't use a connector the account hasn't made available, whatever its own configuration requests.

### MCP compared to Apps & Services

Both add outside capability to an agent, and the catalogs overlap. [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services) lists SaaS connectors such as Stripe and Resend, connected through the [Integrations Hub](/ai-workbench-qore/console/integrations-hub). MCP connections reach any MCP server by URL. For an HTTP endpoint that isn't an MCP server, use the [API Call](/ai-workbench-qore/platform-resources/skill-library/api-call) skill.

## Inbound: a coding agent connecting to Qore

Qore runs MCP servers of its own, so an MCP-capable coding agent can build on Qore from your editor. Your coding agent is the client; Qore is the server.

### The three servers in Connect to coding agents (MCP)

In the Agent Builder, **Build from your IDE** opens **Connect to coding agents (MCP)**, with an example `claude mcp add` command for each server.

| Server                 | Endpoint                                  | What a coding agent can do with it                                                                                                                                                                                                                                                                       |
| ---------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent Builder MCP**  | `<BASE_URL>/agent-builder/mcp`            | Build and manage agents: create, update and delete agents; skills, knowledge, guardrails, execution plans, memory, secrets and access keys; MCP connections and integrations; versions, export and import; plus audit logs, models and usage.                                                            |
| **Knowledge MCP**      | `<BASE_URL>/agent-builder/knowledge/mcp`  | Manage knowledge: datasets and data sources, including uploads and Google Drive, OneDrive, SharePoint and website imports; ingestion, versions and sync; querying; governed graphs; attaching knowledge to agents. It's a separate server so a knowledge client isn't offered the rest of Agent Builder. |
| **Agent Executor MCP** | `<BASE_URL>/agent-executor/<version>/mcp` | Run agents: trigger an agent, follow or abort a run, read conversations and artifacts, answer an agent's questions, and handle documents. The **Executor version** menu, such as **1.4**, sets `<version>` in the command.                                                                               |

{% code title="Add the Agent Builder MCP server (Claude Code)" overflow="wrap" %}

```bash
claude mcp add --transport http agent-builder <BASE_URL>/agent-builder/mcp \
  --header "x-platform-key: <YOUR_API_KEY>"
```

{% endcode %}

The servers use streamable HTTP and are stateless: every request stands alone.

### The App Builder server

In the App Builder, **Build from your IDE** gives one server, at `<BASE_URL>/app-builder/api/v1/mcp`. Through it, a coding agent creates an app, follows its build, approves its plan, and makes the choices along the way, such as the design system, the database, and where each service is published. See [Build from your IDE](/ai-workbench-qore/console/app-builder/creating-and-importing-apps#build-from-your-ide).

### Keys for Qore's servers

* Every request carries the key in the `x-platform-key` header.
* Create keys in the dialog, under **API keys** › **+ Add Key**, and **Revoke** them at any time.
* **A key made in Connect to coding agents (MCP)** is valid only for the current workspace and account. It carries the agent capabilities you hold yourself, limited to building, viewing, importing, exporting, publishing, triggering and sharing agents, managing versions, attaching governed graphs, querying knowledge, stopping agents, and viewing credit usage and traces. A coding agent using the key can't do more than you can.
* The App Builder dialog has its own list of keys.

Treat a key as a credential: it lets an outside tool act in Qore as far as the key allows.

## Under the hood

Two more uses of MCP need no setup and don't appear as MCP connections:

* **Flows and Integrations Hub skills** reach the agent executor through Qore's own internal MCP servers.
* **MCP tools can return an interactive view.** A tool result of type `text/html;profile=mcp-app` is rendered in a sandboxed view in the chat.

## Where this is configured

* [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools): the catalog and client credentials
* [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent): the MCP Marketplace tab
* [Skill Library](/ai-workbench-qore/platform-resources/skill-library): the MCP Server and Web Crawler skills
* [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1): `$auth.token`
* [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent): Include MCP configuration
* [Connectors](/ai-workbench-qore/control-center/govern/connectors): every MCP connection in the account
* [Get Started](/ai-workbench-qore/console/agent-builder/get-started) and [Importing apps](/ai-workbench-qore/console/app-builder/creating-and-importing-apps): Build from your IDE

***

{% 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 %}


# Embed Agent

Put a Qore agent inside your own app, product or website: the ways in, the credentials each one uses, and what they share.

**Embedding an agent** makes an agent you built in the Agent Builder usable outside Qore: in your own app, product or website. The agent itself stays in Qore. It keeps its instructions, skills, knowledge, and secrets and variables; your product sends it messages and shows its replies.

Set it up from **Agent Config** › **Integrate Agent**, under *Credentials & access*. The panel has two tabs, **Embedded Chat** and **Agent API**. See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration).

## The ways in

The choice depends on where your code runs and how much of the interface you want to own.

| Way in                                                                                                                | Package                | Runs in          | You build the UI? | Credential                                              | Allowed Domains applies? |
| --------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------- | ----------------- | ------------------------------------------------------- | ------------------------ |
| **Embedded Chat** ([widget](/ai-workbench-qore/core-concepts/widget))                                                 | `@uptiqai/widgets-sdk` | Browser          | No                | Widget key                                              | Yes                      |
| **Headless Agent JS SDK**                                                                                             | `@uptiqai/widgets-sdk` | Browser          | Yes               | Widget key                                              | Yes                      |
| **Agent API**, `raw (HTTP)` client                                                                                    | None                   | Server-to-server | Yes               | API key and secret                                      | No                       |
| **Agent API**, `TypeScript SDK` client ([Agent SDK](/ai-workbench-qore/platform-resources/the-agent-development-sdk)) | `@uptiqai/agent-sdk`   | Node or browser  | Yes               | API key and secret on a server; widget key in a browser | In a browser             |

The **Python SDK** client is listed on the Agent API tab as **Coming soon**.

### Embedded Chat

A prebuilt chat interface you mount on a page. The panel walks you through three steps:

1. **Widget key**: use an existing key or generate a new one.
2. **Whitelist domains**: add each domain the widget will run on.
3. **Install widget**: install the package and mount the widget.

What the widget is and what it handles is on [Widget](/ai-workbench-qore/core-concepts/widget).

### Agent API

Your own code calls the agent. The tab generates one code sample from three selectors:

| Selector    | Options                                                                                 |
| ----------- | --------------------------------------------------------------------------------------- |
| **Client**  | `raw (HTTP)`, `TypeScript SDK`, `Python SDK` (**Coming soon**)                          |
| **Mode**    | `Sync`, `Async`, `Realtime`                                                             |
| **Dialect** | `Native`, Qore's own request and response shape; `OpenAI`, an OpenAI-compatible surface |

The trigger endpoint is `POST /agent-executor/<version>/agents/:agentId/trigger`. Executions default to async: the reply is an `executionId`, and the result arrives by polling or by webhook. Webhooks need executor version 1.2 or later, and each carries an `X-Webhook-Signature` you verify against the public key on the Agent API tab.

A trigger request can also carry:

* `documents`, uploaded first through a signed upload URL
* `uid`, the calling user's ID in your system
* `variables`, whose keys must already be declared in the agent's **Agent Variables**
* `businessId`, to attribute the run to a business or tenant of your own
* `responseFormat`, `Markdown` or `Json`
* `token`, the caller's identity token

Further endpoints check an execution's queue, cancel a pending message, abort a run, and list or read conversations. See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration#agent-api).

## What every way in shares

### Credentials, on Access & Security

All ways in use credentials from the agent's [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication) page. Integrate Agent creates and uses the same keys and domains.

| Credential           | Sent as                            | Safe in a browser?                                       |
| -------------------- | ---------------------------------- | -------------------------------------------------------- |
| **Widget key**       | `x-widget-key`                     | Yes. It works only from the platform and Allowed Domains |
| **API key + secret** | `x-api-key` and `x-api-key-secret` | No. Keep both server-side                                |

* **The API secret is shown once**, when the pair is generated. If you lose it, generate a new pair.
* **There's no rotate action.** Add a new key, move your integrations to it, then deactivate the old one. Deactivation can't be undone.
* **Download as MD**, on both tabs, saves the integration spec for your agent. On the Agent API tab, **Include secrets** writes the API key and secret into the file, which makes the file a credential.

### Allowed Domains, for browser integrations

Browser integrations run only from the origins on the agent's **Allowed Domains** list, or from the platform's own domain. With the list empty, they run nowhere outside the platform. Server-to-server calls have no web origin, so the list doesn't apply to them. See [Allowed Domains](/ai-workbench-qore/console/agent-builder/deploy/authentication#allowed-domains).

### Who is calling

Two layers identify the caller:

* **The application.** Access keys say which integration is calling.
* **The person.** [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1), when turned on, verifies a Microsoft Entra ID or Google token before each run. Send it as `token` in an Agent API request, `authToken` in the widget or headless SDK, or `authToken` on the Agent SDK client. A verified token reaches the agent's MCP connections as `$auth.token`. See [MCP](/ai-workbench-qore/core-concepts/mcp).

A request without a token still runs. A request with an invalid token is rejected.

{% hint style="warning" %}
**The `user` object and the identity token must come from your own authenticated session**, never from URLs, form fields or other user-controlled input.
{% endhint %}

### Versions

Versions are per agent. Read the **SDK version** and **Executor version** from your agent's **Agent Config Panel**, and use those in your app and API calls. The executor version appears in the API path and in the widget's `agentExecutorVersion`. The widget package version is released alongside an executor version. See [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning).

### Runtime configuration

The widget, the SDKs and the API all run the agent against the same configured [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables).

## Scope

| Item                    | Belongs to |
| ----------------------- | ---------- |
| Widget keys, API keys   | One agent  |
| Allowed Domains         | One agent  |
| Authentication provider | One agent  |
| Executor version        | One agent  |

## Where embedded runs show up

* [Monitoring](/ai-workbench-qore/console/agent-builder/monitor) lists each execution, whether from the embedded widget, an API call or a trigger.
* The conversation endpoints, and `conversations` in the Agent SDK, list and read the agent's conversations from your own code.

## Embedding compared to exporting

Embedding runs the agent live in Qore and calls it from your product. [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent) instead packs the agent's configuration into a portable package, to import elsewhere.

## Related

* [Widget](/ai-workbench-qore/core-concepts/widget): the prebuilt chat interface
* [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration): setup steps, samples and endpoints
* [Agent SDK](/ai-workbench-qore/platform-resources/the-agent-development-sdk): `@uptiqai/agent-sdk`
* [Protocols](/ai-workbench-qore/core-concepts/protocols): how the agent reaches out and how your product reaches in
* [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent): the task guide

***

{% 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 %}


# Widget

The prebuilt chat interface that puts a Qore agent on your web page: what it is, what it needs, and what it handles for you.

The **widget** is Qore's prebuilt chat interface for an agent, delivered in the `@uptiqai/widgets-sdk` package. You mount it on your own web page, and your users chat with the agent there. It handles conversation state, history and messaging for you.

The widget is the UI behind **Embedded Chat**, one of the ways to [embed an agent](/ai-workbench-qore/core-concepts/embed-agent). Set it up from **Agent Config** › **Integrate Agent** › **Embedded Chat**. See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration#embedded-chat).

## Forms of the widget

The same package ships the widget in two technologies and two layouts, plus a headless option with no UI at all.

| Form                      | React                           | HTML web component                | Layout                                                                         |
| ------------------------- | ------------------------------- | --------------------------------- | ------------------------------------------------------------------------------ |
| **Chat Widget**           | `ChatWidget`                    | `<uptiq-chat-widget>`             | A floating popover                                                             |
| **Full Screen**           | `FullScreenChatWidget`          | `<uptiq-full-screen-chat-widget>` | Full screen, with sidebar navigation                                           |
| **Headless Agent JS SDK** | `createHeadlessAgentInstance()` | —                                 | None: you build the UI; the SDK handles sockets, agent events and file uploads |

React takes **props** as objects. The web component takes **attributes** as JSON strings with kebab-case names. Otherwise they map one to one.

## What the widget does for you

* A chat interface, as a floating popover or full screen
* A conversation sidebar, and new chats
* Message history kept across sessions
* Real-time messaging with the agent
* The agent's avatar on the trigger button
* Theming to match your brand

## What it needs

Two props are required.

| Prop     | Holds                                                                                         |
| -------- | --------------------------------------------------------------------------------------------- |
| `config` | `serverUrl`, the Qore API host; `agentId`; `widgetKey`; and optionally `agentExecutorVersion` |
| `user`   | The signed-in person in your app: `uid`, `firstName` and `email`, and optionally `lastName`   |

{% hint style="warning" %}
**Fill `user` from your own authenticated session**, never from query parameters, form input or other untrusted sources.
{% endhint %}

The headless SDK also requires an `instanceId`, used for socket scoping.

### The widget key

The widget authenticates with a **widget key**, created on the agent's [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication#key-types) page or in step 1 of the Embedded Chat setup.

* **It's safe to ship in browser code**, because it works only from the platform itself and the domains on the agent's **Allowed Domains** list.
* It's sent as the `x-widget-key` header.
* The same key type is used by the headless SDK, and by the [Agent SDK](/ai-workbench-qore/platform-resources/the-agent-development-sdk) in the browser.
* **Try Agent**, which opens the Agent Playground, needs the agent to have a widget key.

An API key and secret, by contrast, are for server-to-server calls and must never reach a browser.

### Allowed Domains

**Allowed Domains** lists the web origins where the agent's widget may run. A widget-key request is accepted only from a page on the list, or from the platform's own domain.

* **With the list empty, the widget runs nowhere outside the platform.**
* Enter each domain exactly as the browser sends it. A mismatch in protocol, subdomain or port is refused.
* Step 2 of the Embedded Chat setup, **Whitelist domains**, adds to the same list.

## Scope

| Item             | Belongs to                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| Widget key       | One agent. An agent can have several keys; each can be renamed or deactivated, and deactivation can't be undone |
| Allowed Domains  | One agent, shared by all of its widget keys                                                                     |
| A mounted widget | One agent, through `agentId`. Give each widget on a page its own `instanceId` to show several agents            |

## Options

| Prop / attribute                              | What it does                                                                                                                                   |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `theme` / `theme`                             | Palette overrides, such as `primary`, `background`, `foreground` and `sidebar`                                                                 |
| `instanceId` / `instance-id`                  | Distinguishes several widgets on one page                                                                                                      |
| `defaultOpen` / `default-open`                | Opens the widget on mount                                                                                                                      |
| `hideTrigger` / `hide-trigger`                | Full Screen only: hides the default launcher, so you open it from your own button                                                              |
| `widgetRef`                                   | React only: `open()` and `close()` for programmatic control                                                                                    |
| `defaultExecutionId` / `default-execution-id` | Opens a specific conversation, to continue a previous chat                                                                                     |
| `onExecutionChange`, `onClose`                | React only: callbacks when the conversation changes or the widget closes                                                                       |
| `authToken` / `auth-token`                    | The signed-in person's identity token, for an agent with [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) on |
| `allowDeveloperMode` / `allow-developer-mode` | **Available on request.** Shows a **Developer Mode** switch, which reveals **Setup Identity Token**                                            |

The full list, with types and examples, is on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration), under **Props / attributes reference**.

## Identity in the widget

`user` tells the agent who your app says the person is. `authToken` lets Qore verify it.

* With Authentication on, the widget sends `authToken` with new chats, follow-up turns, and permission or credential requests. The headless SDK's `setAuthToken()` replaces it after your app refreshes it.
* Qore exposes the verified token to the agent's MCP connections as `$auth.token`. See [MCP](/ai-workbench-qore/core-concepts/mcp).
* The widget keeps the token only in session memory.
* **Setup Identity Token**, under **Developer Mode**, lets you try the agent as a specific person by pasting their token. It lasts for the session and is never stored. A token passed as `authToken` replaces one entered by hand.

## Versions

The widget package version is released alongside an executor version. Pin the version that the Embedded Chat panel shows for your agent, so the widget and the executor stay in step. To get a newer widget, upgrade the agent's executor version first. See [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning).

## Where widget activity shows up

[Monitoring](/ai-workbench-qore/console/agent-builder/monitor) lists the agent's executions, including those from the embedded widget, alongside API calls and triggers.

## Related

* [Embed Agent](/ai-workbench-qore/core-concepts/embed-agent): choosing between the widget, the headless SDK and the Agent API
* [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration): setup steps, props and examples
* [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication): widget keys and Allowed Domains

***

{% 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 %}


# Evals

Measure agent quality before release and in production.

Agents can give different answers to the same request. Evals make quality measurable, repeatable, and reviewable.

Use evals to test changes before release and monitor quality after deployment.

#### At a glance

* **Before release:** Test known scenarios against expected answers.
* **In production:** Score live executions and route uncertain results for review.
* **Over time:** Add reviewed misses to your test dataset.

## Two evaluation loops

Qore evaluates agents before and after deployment.

| Loop                      | When it runs      | What it uses                          | Purpose                                          |
| ------------------------- | ----------------- | ------------------------------------- | ------------------------------------------------ |
| **Pre-release evals**     | Before deployment | Curated datasets and expected answers | Validate planned changes                         |
| **Production evaluation** | After deployment  | Live executions                       | Detect quality drift and route uncertain results |

Pre-release evals test known expectations. Production evaluation tests real traffic.

## Pre-release evals

In Agent Builder, an eval dataset contains test cases. Each case includes a question, an expected answer, and optional documents. Create a dataset three ways:

* **Upload a document.** The test cases are read out of it, up to 500. The document can list the cases, or describe the scenarios to cover.
* **Generate with AI.** An LLM writes the test cases, between 1 and 50.
* **Add them manually.**

Run the dataset against the agent. An LLM scorer assigns each response a score from 0 to 10, with its reasoning. Scores of 7 or higher pass. The results come with suggested changes to the agent.

For setup and results, see [Evals](/ai-workbench-qore/console/agent-builder/test/evals).

## Production evaluation

After deployment, online evaluation scores live executions in the background. It doesn't delay or change responses.

In **Control Center → Evals**, an **evaluator** defines how executions are scored. Evaluators are defined at the account level, so one evaluator can serve any agent it is assigned to.

| Setting                  | What it sets                                                                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Framework**            | **Single judge** scores with one model. **Jury** scores with 2 to 5 models and takes a weighted vote. A jury's models can come from different providers. |
| **Evaluation method**    | **Answer Relevancy**, **Faithfulness**, **Safety**, or **Task Completion**                                                                               |
| **Judge model(s)**       | The model or models that score. The picker lists the models your organization has enabled in AI Gateway.                                                 |
| **Confidence threshold** | From 0 to 100%, default `50%`. A result below the threshold is flagged, whatever its rating.                                                             |
| **Human Review routing** | Off by default. When on, a flagged result becomes a task in **Human Review**.                                                                            |

**Faithfulness** rates how much of what the agent said is supported by the context it was given: retrieved context, the results of the tools it called, and what the user said. The score is the share of the response's factual claims that the context supports.

To score an agent, assign evaluators to it in **Agent enablement** and turn on its **Online eval** toggle. **Sampling** sets the chance that each live conversation is evaluated, `100%` by default.

**Online Eval** shows the results in two tabs. **Scores** lists each scored execution, with the points the judge based its verdict on and a link to the conversation it judged. **Runs** lists each evaluator's run with its status: **Pending**, **Running**, **Completed**, or **Failed**, with the reason a run failed. Online-eval model usage appears on its own line in Credit Usage.

For organization-wide evaluation and review routing, see [Evals](/ai-workbench-qore/control-center/evals). For per-agent production monitoring, see [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval).

## How the loops connect

A reviewer in **Human Review** records a verdict for each low-confidence result, and can pass the findings to the agent team to update regression tests, instructions, or knowledge. You can add reviewed production misses as test cases in a pre-release dataset.

## How evals fit with other controls

Evals measure output quality. [Guardrails & Validation](/ai-workbench-qore/core-concepts/guardrails-and-validation) constrain what an agent can process or do. Neither replaces human review where judgment is required.

[Memory & Learning](/ai-workbench-qore/core-concepts/memory-and-learning) closes the loop. Reviewed production feedback becomes learning cases. Evals validate those improvements before broader rollout.

## Where this is configured

* [Evals](/ai-workbench-qore/console/agent-builder/test/evals)—create datasets, run tests, and review scored results
* [Evals](/ai-workbench-qore/control-center/evals)—define evaluators, inspect online results, and manage Human Review
* [Evaluators](/ai-workbench-qore/control-center/evals/evaluators)—frameworks, evaluation methods, and agent enablement
* [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval)—monitor per-agent production scoring
* [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings)—approve learning cases from reviewed feedback

***

{% 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 %}


# Operator

Coordinate specialized agents to complete requests with shared conversational context.

An Operator is not a single agent that does everything. It's the coordinator that runs a *team* of specialised agents on your behalf.

You give it a request; it decides which of your agents fits, hands the work off, and brings back what they produce.

### Multi-agent orchestration, in one loop

Every Operator works the same way. You ask; the Operator reads which agents are available and what the conversation has covered so far; it picks the agent whose description fits; it dispatches; the agent's results come back through it. Each turn is saved so the next one has context.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FC5rMXMQKXlYNzAIslnsJ%2Foperator-concept-qore%20II.png?alt=media&amp;token=d637b771-b125-48b2-ab76-b59f1fd0478b" alt=""><figcaption></figcaption></figure>

The pattern is called **multi-agent orchestration**: a coordinator that routes each request to the specialist best suited to it, so no single agent has to do everything and each agent can be tuned to one thing.

### What it solves

Four problems that show up as your agent team grows — and the Operator's answer to each.

<details>

<summary><strong>Users don't know which agent to call.</strong></summary>

* Asking a business user to open the list of agents, read every description, and pick the right one is a job they didn't ask for.
* The Operator does the picking from the request itself, so the user's task stays *"describe what you want"* — not *"choose the right specialist."*

</details>

<details>

<summary><strong>Context resets between agents.</strong></summary>

* Talk to one agent about a customer, then need help from another, and the second one starts with nothing.
* The Operator holds one conversation across every hand-off — you don't repeat yourself, and the agents don't miss what came before.

</details>

<details>

<summary><strong>Governance answers live in many places.</strong></summary>

* A plain question like *"what's driving cost this month?"* usually means reconciling data across several Control Center screens by hand.
* The Governance Operator takes the question as asked and routes to the governance-review agent that has the answer.

</details>

<details>

<summary><strong>Auto-fixes are either off or risky.</strong></summary>

* Without an approval step, the only safe posture for a governance surface is *look, don't touch* — every remediation becomes a manual ticket, which cancels most of the point of orchestration.
* Staged actions let the Governance Operator write down the fix it would make and wait for you to approve it.

</details>

### Key terms

| Term                     | Definition                                                                                                                                                                                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Operator**             | An **Operator** is the coordinator. Each space, Console and Control Center, has one Operator.                                                                                                                                                                                             |
| **Agent team**           | An **agent team** is the set of agents an Operator can dispatch to. Each agent carries a name and a short description; the Operator uses those descriptions when deciding who fits a request. (The Governance Operator's UI calls this an *operating team* — same idea, different label.) |
| **Agent**                | An **agent** is a purpose-built worker, built and configured in Console, that does one thing well.                                                                                                                                                                                        |
| **Conversation history** | **Conversation history** is the running record of what you asked and how the Operator and its agents answered. The Operator reads it before each turn so context carries forward.                                                                                                         |

### Spaces and Operators

The core loop is the same in both spaces. What changes is the *shape* of the request and what the Operator does with it.

| Space              | Operator's job                                                                                                | Default scope | Dispatches to                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Console**        | Build and run. It builds apps, agents, knowledge bases, and agentic applications, and routes tasks to agents. | Project       | **System** agents, such as **App Builder Agent**, **Agent Builder Agent**, **Knowledge Builder Agent**, and **Document AI Agent**, and the project's own agents you turn on. |
| **Control Center** | Inspect the account and stage any action for your approval.                                                   | Account       | A team of governance-review agents, such as **Agent Performance Analyst** and **Billing & Credit Manager**.                                                                  |

#### Current capabilities

The Operator's capabilities depend on its space and may expand over time.

| Space              | It can do today                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Console**        | Build apps, agents, knowledge bases, and agentic applications. Search the web or crawl a website, and turn the content into a knowledge base or a design system. Create, change, or delete the project's design systems. Extract, classify, summarize, and generate documents, and save document templates. Act in third-party systems through the connections you turn on. Tell you who is in the account and which teams it has, and manage the account's projects. Run on a schedule. |
| **Control Center** | Answer account-wide questions about usage, cost, access, guardrails, and change history, such as published apps, recently created agents, and credit use. Narrow a question to one project. Stage changes for approval. Run on a schedule.                                                                                                                                                                                                                                               |

For details, see [Console Operator](/ai-workbench-qore/console/console-operator), [Governance Operator](/ai-workbench-qore/control-center/governance-operator), and [Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized).

One difference worth naming.

**The Governance Operator stages actions for your approval.** The Console Operator dispatches a task the moment you ask. In Control Center, anything the Operator would change is written down and waits for you to approve it before it runs.

### Running without you, and waiting for you

* **Schedules.** **Schedules** in the top bar runs an Operator at a set time, with instructions you write once and the agents each run may use. Schedules made in Console run the Console Operator; schedules made in Control Center run the Governance Operator. Times are set in UTC. See [Schedules](/ai-workbench-qore/console/console-operator/schedules).
* **Gates.** When an agent needs a decision, it asks in the conversation, and you answer, attach a file, or skip. A conversation that ends on a question is listed on **Gates** in the top bar until you answer. Each space has its own Gates page. See [Gates](/ai-workbench-qore/console/console-operator/gates).
* **Long-running work.** Building an app or ingesting knowledge can take several minutes. The Console Operator tracks these builds as background tasks, so it reports the real outcome when the build finishes, even if the conversation was interrupted.

### What you control

In Console, you choose which agents and connections the Operator may use. **System** agents start on; your own project agents start off, and the Operator doesn't consider an agent that is off. Integration Hub connections also start off. With a connection on, the Operator can act in that system; when a request needs a system it has no connection for, it tells you which connection to turn on or which integration you could connect. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections). In Control Center, the Governance Operator's agents are always available.

In the Console composer, you choose the Operator's **model** and **effort** (**Minimal**, **Low**, **Medium**, or **High**). The choice applies to each message you send. Agents the Operator hands work to run on their own configured model and effort.

To stop the Operator and everything it started, use **Control Center → Govern → Agent Controls**. Stopping a system agent also stops every run and helper agent it started. See [Agent Controls](/ai-workbench-qore/control-center/govern/agent-controls).

### What both share

Under the starter cards on every Operator surface sits the same line: *Operator plans the work and hands each part to the right agent.* That's the concept in one sentence.

Two other invariants worth naming.

* **Read before dispatch.** Every Operator reads the conversation history and the current agent team's descriptions before it picks. That's how routing stays sensible turn to turn.
* **Show the work.** The Operator shows its work in the conversation as it goes: each step it takes, each question it asks, and a card for each agent it hands work to, with that agent's status.

{% hint style="info" %}
**This surface is evolving.** The pattern above is settled. What each Operator can do, and how its agent team is composed, will change as the feature matures. Use this page for the *shape*; check the space-specific pages for what a given Operator can do today.
{% endhint %}

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Agents</strong></td><td>How each agent on an Operator's team is defined and configured.</td><td><a href="/ai-workbench-qore/start-here/core-concepts">Agent Foundations</a></td></tr><tr><td><strong>Apps</strong></td><td>The artifacts the Console Operator builds and runs.</td><td><a href="/ai-workbench-qore/console/app-builder/app-workspace">App Workspace</a></td></tr><tr><td><strong>Agent Controls</strong></td><td>Stop individual agents, or all agent activity, during an emergency.</td><td><a href="/ai-workbench-qore/control-center/govern/agent-controls">Agent Controls</a></td></tr><tr><td><strong>Steering &#x26; Reasoning</strong></td><td>How an agent decides — the concept sitting alongside the Operator.</td><td><a href="/ai-workbench-qore/core-concepts/steering-and-reasoning">Steering &amp; Reasoning</a></td></tr></tbody></table>

***

{% 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 %}


# Overview

Build, test, deploy, and operate apps, agents, automations, and connected services.

Console is where you build and run Qore solutions. Organize work in projects, then create agents, apps, knowledge bases, flows, and design systems. Connect services once, and use them across your work. Choose a module to start building or managing a solution.

### Explore Console

<table data-view="cards"><thead><tr><th>Module</th><th data-card-target data-type="content-ref">Open module</th></tr></thead><tbody><tr><td>Projects</td><td><a href="/ai-workbench-qore/console/projects">Projects</a></td></tr><tr><td>Console Operator</td><td><a href="/ai-workbench-qore/console/console-operator">Console Operator</a></td></tr><tr><td>Agent Builder</td><td><a href="/ai-workbench-qore/console/agent-builder">Agent Builder</a></td></tr><tr><td>App Builder</td><td><a href="/ai-workbench-qore/console/app-builder">App Builder</a></td></tr><tr><td>Knowledge</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td>Flows</td><td><a href="/ai-workbench-qore/console/flows">Flows</a></td></tr><tr><td>Store</td><td><a href="/ai-workbench-qore/console/store">Store</a></td></tr><tr><td>Integrations Hub</td><td><a href="/ai-workbench-qore/console/integrations-hub">Integrations Hub</a></td></tr><tr><td>Design Systems</td><td><a href="/ai-workbench-qore/console/design-systems">Design Systems</a></td></tr></tbody></table>


# Projects

Organize related apps, agents, knowledge bases, and design systems in one shared workspace.

Projects live in **Console**, under **Accounts**. They keep the artifacts for one product together. Each project has shared context, a database, infrastructure, and a design system.

Use separate projects for unrelated work. This keeps their artifacts and context isolated.

{% hint style="info" %}
Projects aren't available from **Control Center**. Open **Console**, then select **Accounts**.
{% endhint %}

### Project scope

{% columns %}
{% column %}

#### Project artifacts

Projects contain apps, agents, knowledge bases, and design systems. These artifacts stay within the project.
{% endcolumn %}

{% column %}

#### Account controls

Accounts manage **Cost Control**, access, governance, and other controls across their projects.
{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
Create a separate project when artifacts must not share context.
{% endhint %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FVcMuGSQg30U4jfpmgHL4%2Fchrome_zrArDAZpDf.png?alt=media&amp;token=2c2b46c3-5c8b-4ebf-9c00-7ae5f0b83dff" alt="Project workspace showing the New artifact option"><figcaption><p>Open Projects from Accounts in Console.</p></figcaption></figure>

### Find projects

Open **Console**, then open the account and project switcher at the top of the sidebar. **Projects** lists the current account's projects, with a check mark on the one you're in. Select a project to open it.

To search every project in the account, select **See All Projects**. The **Projects** dialog describes a project as *One container for every app, agent and knowledge base that belongs to the same product — sharing one database, one infra instance and one design system.*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2F0HxGYiBnipoHx6hfeTee%2Fchrome_PzI7GSWpCG.png?alt=media&amp;token=f3bd238c-509a-4a42-bc88-0492a5ea5221" alt="Projects page showing the New Project option"><figcaption><p>Choose a project from available Projects in the Account to open.</p></figcaption></figure>

### Pin a project

Pin a project and Qore opens it when you sign in.

1. Open the account and project switcher at the top of the Console sidebar.
2. Hover over the project and select the pin icon, **Pin project**.

Qore confirms with *Pinned ‹project name›*. The pinned project moves to the top of the project list, both in the switcher and in **See All Projects**, and keeps a filled pin icon.

You can pin one project at a time, across all your accounts. Pinning another project, even one in a different account, replaces the pin. To unpin, select the filled pin again (**Unpin project**). You can pin and unpin only from the switcher; **See All Projects** shows the pin but doesn't change it.

The pin decides where you land when you sign in: Qore opens the pinned project and switches to its account if needed. A link to a specific project still opens that project instead. Between sign-ins, Qore keeps you in whichever project you last selected. The pin is yours alone; it doesn't change what other members of the account see.

### Create a project

Create a project before you create artifacts for a new product.

1. Open the account and project switcher at the top of the Console sidebar. Under **Accounts**, select the account the project belongs to.
2. Select **New project**. **See All Projects** has the same option, **New Project**.
3. In **Create New Project**, enter a name. Project names are unique within an account.
4. Select **Create Project**.

Qore confirms with *Project added successfully*. The project is created in the current account and appears under **Projects** in the switcher. In the switcher, **New project** shows only to roles with **Create a project**: **Developer**, **Account Admin**, and **Organisation Admin**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-d1cced7baf3ac874e098b18be18fa71e2ef70627%2Fqore_console_create-new-project_rounded_shadow.png?alt=media" alt="The Create New Project dialog with a Provide name to project field and Cancel and Create Project buttons"><figcaption><p>Create New Project.</p></figcaption></figure>

{% hint style="info" %}
An account can contain multiple projects. Select the project that matches the product you are building.
{% endhint %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Ffe3EDySybuz5p4hZepGn%2Fchrome_us8MCJWRqr.png?alt=media&amp;token=04a15f22-e01b-428b-b986-2072b445fa33" alt="Console navigation with Accounts and Projects available in the left sidebar"><figcaption><p>Create a new Project from Accounts in Console.</p></figcaption></figure>

### Work in a project

Select a project to open its workspace. Its navigation provides these artifact areas:

| Area                | Use it for                                      |
| ------------------- | ----------------------------------------------- |
| **Overview**        | Review the project at a glance.                 |
| **Apps**            | Build and manage project apps.                  |
| **Agents**          | Build and manage project agents.                |
| **Knowledge Bases** | Create and manage project knowledge.            |
| **Design Systems**  | Create reusable visual styles for project apps. |

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FbesY4J1Tw36AF8gaFuVC%2Fchrome_d2HtLLHywN.png?alt=media&amp;token=06888edb-e120-487e-84b6-cd162b27f7f2" alt="A selected project showing artifact areas, including Overview, Apps, Agents, Knowledge Bases, and Design Systems"><figcaption><p>Project artifacts are available from the project workspace.</p></figcaption></figure>

### Add an artifact

1. Open the project where the artifact belongs.
2. Select **New artifact**.
3. Select the artifact type.

The artifact is added to the selected project. It can use the project's shared context.

### Related resources

{% content-ref url="/pages/c9LqRJACw0U64C4Joa5F" %}
[Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized)
{% endcontent-ref %}

***

{% 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 %}


# Console Operator

The Console Operator—build and run work from one chat, scoped to a project.

The Console Operator is the chat surface in Console. Describe your goal, and it plans the work, hands each part to the right agent, and returns the result in the same conversation.

Use it to build and use apps, agents, knowledge bases, and agentic applications. It can also search the web, crawl a website, answer questions about data, generate documents, and run on a schedule.

It replaced the Console dashboard. The dashboard listed existing assets. The Operator gives you one place to ask and act.

For general orchestration, see [Operator](/ai-workbench-qore/core-concepts/operator). This page covers Console behavior. For every task in one place, see [Use the Console Operator](/ai-workbench-qore/task-guides/use-the-console-operator).

## At a glance

* **Where:** **Operator** in the Console sidebar, in your selected project
* **Scope:** **Project** apps, agents, knowledge bases, design systems, and context
* **Acts:** immediately. It dispatches when you ask—there is no approval step
* **Also builds:** apps, agents, knowledge bases, and agentic applications
* **Searches:** the web and public websites
* **Runs on its own:** on a schedule you set. See [Schedules](/ai-workbench-qore/console/console-operator/schedules)
* **Waits for you:** when an agent needs an answer. See [Gates](/ai-workbench-qore/console/console-operator/gates)

## Start a conversation

The Operator opens on a greeting with your name, such as *"Good evening, Abhishek"*, and the subtitle *"Ask a question or tell me what you need, I'll bring the outcome."*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a2f32a13c75a31b7f423a8ffa5bde937fd142ab0%2F007_console_operator_home.png?alt=media" alt="The Console Operator home: the greeting Good evening, Abhishek above a composer reading How can I help you today? with Gemini 3.7 Flash and Low selected, a row of starters including Approval Flow and Review a Policy, with arrows either side, and Recent chats listing four conversations with View all chats"><figcaption><p>The Operator home, with starters and recent chats.</p></figcaption></figure>

Type your request in **How can I help you today?** and send it, or pick a starter from the row under the composer, such as **Approval Flow** or **Review a Policy**. Arrows either side of the row scroll through the starters.

**Recent chats** lists your latest conversations, each with a time such as `5 Hrs ago`. **View all chats** opens the full list.

## Work in a conversation

A conversation has three columns.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-1b77c0a330996aa2d41d0dd1b7ec82726827e68e%2F001_console_operator_conversation.png?alt=media" alt="A Console Operator conversation titled Building A To Do Application: Conversation History on the left, the transcript in the middle with answered questions and a This is taking a while banner above the composer, and on the right the Agents panel with System and User tabs, Connections with All integrations 228, and Outputs listing two ToDo List App entries"><figcaption><p>Conversation history, the transcript, and the side panel.</p></figcaption></figure>

**Conversation History, on the left.** Your conversations in the project, newest first. Conversations are specific to each user, so you see only the ones you started. **Search conversations** filters them by title.

**The transcript, in the middle.** The Operator shows its work as it goes: how long it thought, each step it took (such as **Update Plan Steps** or **List Database Providers**), and each question it asked with the answer beneath it. When it hands work to an agent, the agent appears as a card with its step count, for example **App Builder Agent · 49 steps**, and a **Working** status while it runs. Select **Open full run** on the card to see every step the agent took. **Jump to latest** returns to the bottom. **+ New Conversation**, top right, starts over.

**The side panel, on the right**, in four sections:

**Agents** — the agents the Operator can hand work to, under **System** and **User**. A count shows how many are working now, for example `1 working`. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections).

**Connections** — the Integration Hub connections the Operator can use, and **All integrations**. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections#connections).

**Outputs** — what the conversation built, such as an app, with a link to open it.

**Artifacts** — files and documents created during the task: *"Artifacts created during the task land here."*

### When an agent asks you something

Agents stop to ask when they need a decision, for example *"There are two apps named ToDo List App in your project. Which one would you like to update?"* The question appears as a card above the composer. Pick one of the numbered answers, write your own in **Answer in your own words…**, or select **Skip**. When the agent asks for a file, such as a brand guide, attach it as your answer. A conversation that ends on a question also appears on the [Gates](/ai-workbench-qore/console/console-operator/gates) page until you answer.

### Long-running work

Building an app or ingesting knowledge can take several minutes. The Operator tracks these builds as background tasks, so it reports the real outcome when the build finishes, even if the conversation was interrupted. You may see *"Resuming 1 interrupted tool calls…"* when it picks one back up.

When a turn runs long, a banner appears above the composer:

> **This is taking a while**\
> *"You can pick this up in a new conversation with a summary of where things stand. The work here keeps running either way."*

Select **Continue in a new conversation** to carry on elsewhere with a summary, or **Stay here** to keep watching. The build keeps running whichever you choose.

## The composer

The composer at the bottom holds your message and four controls:

**+** — opens **Attach files**, to add files to your message, and **Connections**, to turn the Operator's connections on or off. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections#connections).

**Model** — the model the Operator runs on, for example **Gemini 3.7 Flash** or **GPT 5.4**.

**Effort** — how hard the Operator reasons before it answers: **Minimal**, **Low**, **Medium** or **High**. More effort usually gives better plans on complex requests, at the cost of time and credits.

**Context gauge** — how full the conversation's context is, for example `0%`. Hover over it for the detail, such as `18 / ~200.0K tokens`. When it fills up, start a new conversation.

Your model and effort choice applies to each message you send, so you can switch mid-conversation: plan on one model, then build on another. The composer remembers your last choice for your next conversation.

The choice applies to the Operator only. Agents it hands work to, such as the App Builder Agent, run on their own configured model and effort.

## What it does

**It routes work to your agents.** The Operator interprets your intent, identifies the agent that can complete each task, and combines its updates into one response.

**It builds.** Ask for a knowledge base, app, agent, or agentic application. The Operator creates it in the current project. You can test a new agent in the same conversation. When you ask for an app, the App Builder Agent asks which of the project's [design systems](/ai-workbench-qore/console/design-systems) to use, or you can name one in your request. If the branding doesn't exist yet, it saves a new design system as part of the build.

**It uses the web as input.** Ask it to search the web or crawl a public website. Given a URL, it can use the site's content to create a knowledge base. It can also use the website's design system when building an app.

**It works with documents.** The **Document AI Agent** extracts data from documents, classifies and summarises them, answers questions from them, and generates new ones. It can save a **document template**—sections and their order, layout, and a theme—and generate later documents from it. A document generated from the same template twice has the same structure and look, and a design system saved with the template keeps its branding without being named again. Before it generates a document, the agent lists the project's saved templates and asks you to choose one; it never picks one for you.

**It manages design systems.** Ask it to create, change or delete one of the project's [design systems](/ai-workbench-qore/console/design-systems#design-systems-in-console-operator), for example from a brand's website. To set a logo, attach the image to the conversation. When it generates a document, it asks which design system to brand it with, and the document takes that design system's colours.

**It uses your connections.** With a connection turned on, the Operator can act in that third-party system. When a request needs a system it has no connection for, it tells you which existing connection to turn on, or which integration you could connect. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections#connections).

**It helps you look after the account.** Ask who is in the account and which teams it has. The Operator can tell you, but it can't add, remove or change people or teams; that stays in [Users](/ai-workbench-qore/control-center/admin/users) and [Teams](/ai-workbench-qore/control-center/admin/teams). It can also manage the account's projects for you.

**It works inside one project.** Everything it creates belongs to the selected project. Switching projects changes what the Operator can reach. See [Accounts, Projects, Spaces](/ai-workbench-qore/start-here/how-qore-is-organized) for these boundaries.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-9850faaa57ea7d86d8553ac2c87972d225f5639d%2F008_console_account_project_switcher.png?alt=media" alt="The account and project switcher open at the top of the Console sidebar: Accounts lists two accounts, Projects lists the account&#x27;s projects under Search projects, with a Pin project option on the selected project, and New project and See All Projects at the bottom"><figcaption><p>The account and project switcher, at the top of the Console sidebar.</p></figcaption></figure>

## What you control, and what you don't

The **System** agents the Operator dispatches to are **preconfigured for the account**. You don't assemble that team, and you can't edit its agents from the Operator. The set is expected to grow as more capabilities ship.

What you do control is which agents and connections the Operator may use: turn a system agent off, turn your own project agents on, and choose which connections it can reach. See [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections).

For common questions and fixes, see [Console Operator: FAQs & Troubleshooting](/ai-workbench-qore/console/console-operator/console-operator-faqs-and-troubleshooting).

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Agents &#x26; connections</strong></td><td>Choose which agents and connections the Operator can use.</td><td><a href="/ai-workbench-qore/console/console-operator/agents-and-connections">Agents &amp; connections</a></td></tr><tr><td><strong>Schedules</strong></td><td>Run the Operator on a schedule.</td><td><a href="/ai-workbench-qore/console/console-operator/schedules">Schedules</a></td></tr><tr><td><strong>Gates</strong></td><td>Conversations waiting for your answer.</td><td><a href="/ai-workbench-qore/console/console-operator/gates">Gates</a></td></tr><tr><td><strong>Operator</strong></td><td>How an Operator coordinates a team of agents.</td><td><a href="/ai-workbench-qore/core-concepts/operator">Operator</a></td></tr><tr><td><strong>Governance Operator</strong></td><td>The Control Center Operator, and how it differs.</td><td><a href="/ai-workbench-qore/control-center/governance-operator">Governance Operator</a></td></tr><tr><td><strong>Console</strong></td><td>The project workspace where the Operator works.</td><td><a href="/ai-workbench-qore/start-here/console">Console</a></td></tr></tbody></table>

***

{% 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 %}


# Agents & connections

Choose which agents and Integration Hub connections the Console Operator can use.

The Console Operator gets work done through agents, and reaches third-party systems through connections. The side panel of every conversation shows both, and lets you decide which ones the Operator may use.

Open any Operator conversation. The side panel is on the right; if it is hidden, use the panel icon beside **+ New Conversation**.

## At a glance

| Task                                    | Where                                                                                | Scope of the change  |
| --------------------------------------- | ------------------------------------------------------------------------------------ | -------------------- |
| Stop the Operator using a system agent  | **Agents** → **System** → the agent's **⋯**                                          | You, in this project |
| Let the Operator use one of your agents | **Agents** → **User** → the agent's **⋯**                                            | You, in this project |
| Let the Operator use a connection       | **Connections** → the connection's **⋯**, or **+** → **Connections** in the composer | The Console Operator |
| Connect a new system                    | **All integrations**                                                                 | The project          |

## Agents

**Agents** lists the agents the Operator can hand work to, in two tabs.

**System** — agents provided with Qore and preconfigured for the account:

| Agent                           | Takes on                                                      |
| ------------------------------- | ------------------------------------------------------------- |
| **App Builder Agent**           | Building and changing apps                                    |
| **Agent Builder Agent**         | Building and changing agents                                  |
| **Knowledge Builder Agent**     | Building knowledge bases from files and websites              |
| **Document AI Agent**           | Extracting, classifying, summarising and generating documents |
| **Treasury Operations Analyst** | Treasury operations questions                                 |
| **Platform Q\&A Agent**         | Questions about how Qore works                                |

**User** — agents built in this project, for example a `Knowledge Base Resolver` you created. Only agents on the current agent runtime are listed; an agent on an older runtime doesn't appear until it is moved to the current one.

System agents start **on**. Your own agents start **off**, so the Operator never hands work to one of them until you choose to. An agent created later also appears **off**. Use an agent's **⋯** menu to turn it on or off. Each agent is turned on or off individually; there is no switch for all of them at once.

A turned-off agent is invisible to the Operator: it doesn't consider it, mention it, or delegate to it. With every agent off, the Operator still answers, and says it has nothing to hand the work to.

The setting applies to you, in this project; colleagues keep their own choices. It sticks across new conversations and sessions. A change takes effect on your next request; work already running isn't cancelled. You can't turn an agent off while it is working on a run.

Keep the list to the agents you need. The Operator reads the description of every agent that is on each time it plans, so a long list costs it room to think and makes its choice of agent less accurate.

While agents run, the section header counts them, for example `1 working`, and a green dot marks each busy agent.

## Connections

**Connections** lists the Integration Hub connections already set up for this project, with whether the Operator may use each one. When the project has none, it reads *"No connections configured for this project."*

Every connection starts **off**: having a connection in Integration Hub doesn't by itself let the Operator use it. Turn one on, and the Operator can act in that system on your behalf; turn it off again, and it can't. The setting isn't tied to one chat; it applies to every conversation.

Some connections have each person bring their own credentials. Turning one of those on asks for nothing; you are asked for your credentials the first time the Operator actually needs the connection.

A connection removed in Integration Hub disappears from this list too.

Each connection's **⋯** menu holds:

**Manage** — choose which of the connection's actions the Operator may use, and how closely each is supervised.

**Enable / Disable** — let the Operator use the connection, or stop it.

**Manage in Integrations** — open the connection's details in the integrations catalog.

Select a connection's name to open its page in Integrations in a new tab.

The same list is in the composer: select **+** → **Connections**. A chip beside the effort picker shows the icons of the connections that are on; select it to open the list.

Only the Operator itself uses these connections. Agents it hands work to don't inherit them.

### Connect a new system

**All integrations**, under the list, opens the full integrations catalog in a window, with a count of what is available, for example `228`. Connect one there, and it appears in **Connections** when you close the window, turned off until you turn it on.

When a request needs a system the Operator has no connection for, it says so in the conversation: it names an existing connection to turn on, or an integration you could connect.

## Notes and limitations

* **This is Console only.** In Control Center, the Governance Operator's agents are always available: its side panel lists its agents and connections, but you can't turn any of them on or off.

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Console Operator</strong></td><td>Conversations, the composer, and what the Operator does.</td><td><a href="/ai-workbench-qore/console/console-operator">Console Operator</a></td></tr><tr><td><strong>Integrations Hub</strong></td><td>The catalog of systems you can connect.</td><td><a href="/ai-workbench-qore/console/integrations-hub">Integrations Hub</a></td></tr><tr><td><strong>Schedules</strong></td><td>Choose which agents a scheduled run may use.</td><td><a href="/ai-workbench-qore/console/console-operator/schedules">Schedules</a></td></tr></tbody></table>

***

{% 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 %}


# Schedules

Run the Operator on a schedule, with instructions and the agents each run may use.

A schedule runs the Operator for you at a set time, with instructions you write once: *"Summarise yesterday's failed runs and list the top three causes with a suggested fix for each"*, every morning at nine. Each run is an Operator conversation like one you started yourself, and it appears in your **Conversation History** afterwards.

Select **Schedules** in the top bar. The page reads *"Run tasks on a schedule or whenever you choose."* It is in both Console and Control Center: schedules made in Console run the Console Operator, and schedules made in Control Center run the Governance Operator.

## At a glance

| Task                          | How                      | Result                                         |
| ----------------------------- | ------------------------ | ---------------------------------------------- |
| Create a schedule             | **+ Add Schedule**       | A schedule that runs at the time you set       |
| Have the Operator set one up  | Ask it in a conversation | The same, created for you                      |
| Pause, resume, edit or delete | The schedule's **⋯**     | The schedule changes; past runs are unaffected |
| Find one                      | **Search schedules…**    | The list, filtered                             |

## Create a schedule

Select **+ Add Schedule**. When there are no schedules yet, the page reads **No schedules yet.** with the same button.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-91b83024b5fa42b9c5e3c584102dd08adc26fd14%2F003_add_schedule_form.png?alt=media" alt="The Add Schedule dialog: Name, Schedule with Preset and Custom cron, Frequency set to Daily, Time (UTC) 09:00 AM, Instructions with Plain Text and JSON, Agents this run may use, and a summary reading Runs every day at 09:00 UTC beside Cancel and Add Schedule"><figcaption><p>The Add Schedule dialog, with its summary of when the schedule runs.</p></figcaption></figure>

**Name** — required. An identifier for the list, for example `Daily Report`. A name of only spaces isn't accepted.

**Schedule** — when it runs, set one of two ways:

* **Preset** — pick a **Frequency**: **Hourly**, **Daily**, **Weekly** or **Monthly**, then a **Time (UTC)** in hours, minutes and **AM** / **PM**.
* **Custom cron** — enter a **Cron Expression**, for example `0 9 * * *` for every day at 09:00 UTC. **Get your cron expression** helps you build one.

**Instructions** — required. What you want done each time it runs: *"Describe what you want done each time this runs."* Write them in **Plain Text**, or switch to **JSON** to pass a structured object. In JSON mode the instructions must be a non-empty JSON object.

**Agents this run may use** — the agents each run can hand work to, picked from a searchable list. In Console, that is the Console Operator's agents, such as **App Builder Agent** or **Document AI Agent**, and your own project agents. In Control Center, it is the governance agents, such as **Agent Performance Analyst**, **Billing & Credit Manager** or **Platform Audit Investigator**. Leave it empty *"to let the run reach every agent in the pool."*

The footer confirms the timing in words before you save, for example **Runs every day at 09:00 UTC**. Select **Add Schedule** to save it, or **Cancel**.

{% hint style="info" %}
**Times are set in UTC.** Convert from your local time when you pick one. The schedules list then shows the next run in your local time, so a schedule for `09:00 UTC` can read `Next run … 2:30 PM` in India.
{% endhint %}

Limit **Agents this run may use** to what the task needs. A reporting schedule that can only reach an analyst agent can't build or change anything, however its instructions are read.

### Ask the Operator to schedule it

You can also describe the schedule in a conversation, for example *"Every Monday at 8 AM UTC, check which knowledge bases have files that need syncing and tell me."* The Operator sets up the schedule for you, and it appears on the **Schedules** page.

## Manage schedules

Each schedule shows its name, when it runs (for example `Runs every day at 09:00 UTC`), its status, and for active schedules the next run, for example `Next run Oct 1, 2026, 2:30 PM`. Switch between list and grid with the icons beside the search.

The list shows only schedules you created, from every project, not just the one selected. Colleagues' schedules don't appear.

The **⋯** menu on a schedule lets you:

* **Pause** it: it stays in the list as **Paused**, shows no next run, and doesn't run until you resume it.
* **Resume** it: it becomes **Active** again and shows its next run.
* **Edit** it: change any field in the same dialog.
* **Delete** it.

There is no **Run now**. To run the same instructions straight away, ask the Operator in a conversation.

## Notes and limitations

* **A scheduled run acts with no one watching.** The Console Operator dispatches without an approval step. Keep scheduled instructions to work you are comfortable having done unattended.
* **Write instructions that need no answers.** Nobody is present during a scheduled run, so give it everything it needs up front.
* **A run skips an agent that isn't available.** If the Operator a schedule runs isn't active, the run is skipped rather than failing silently.
* **Your role decides what you can do.** Creating and changing schedules needs a role that allows it; actions you can't take are unavailable, with a tooltip saying why.

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Console Operator</strong></td><td>Conversations, the composer, and what the Operator does.</td><td><a href="/ai-workbench-qore/console/console-operator">Console Operator</a></td></tr><tr><td><strong>Gates</strong></td><td>Conversations waiting for your answer.</td><td><a href="/ai-workbench-qore/console/console-operator/gates">Gates</a></td></tr><tr><td><strong>Agents &#x26; connections</strong></td><td>Which agents the Operator can reach.</td><td><a href="/ai-workbench-qore/console/console-operator/agents-and-connections">Agents &amp; connections</a></td></tr></tbody></table>

***

{% 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 %}


# Gates

Operator conversations that have stopped to wait for your answer.

**Gates** lists the Operator conversations you started that ended on a question for you. An agent working for you needed a decision, and nothing moves until you answer.

Select **Gates** in the top bar. The page describes itself exactly: *"Conversations you started that have stopped to ask you something. Open one to answer it."* It is in both Console and Control Center, and the two are independent: Console's **Gates** lists only Console Operator conversations, and Control Center's lists only Governance Operator conversations.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-45c4b39fb782101f9d5c547e223d8c638a0c66b9%2F004_gates_page.png?alt=media" alt="The Gates page in Console, listing one request: Add Dashboard Page with Key Metrics, asked by App Builder Agent, Requested 11 mins ago, with an arrow to open it"><figcaption><p>A request waiting on you, and the agent that asked.</p></figcaption></figure>

## What each request shows

| Part          | What it tells you                                                                |
| ------------- | -------------------------------------------------------------------------------- |
| **Title**     | The conversation it came from, for example `Add Dashboard Page with Key Metrics` |
| **Agent**     | Who is asking, for example `App Builder Agent`                                   |
| **Requested** | How long it has waited, for example `Requested 11 mins ago`                      |

Select a request, or its arrow, to open the conversation at the question. A request from another project opens in that project. The page refreshes on its own while it is open, so new requests appear without reloading. Switch between list and grid with the icons at the top right.

**Only your requests appear here, and only you can answer them.** A conversation you started waits for you, not for a colleague who happens to open it.

## Answer a request

In the conversation, the question sits in a card above the composer, naming the agent that asked:

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-46a763c26d9ae46ab6a5864e777541cd3ecfea14%2F002_operator_question_card.png?alt=media" alt="An Operator conversation with a question card from App Builder Agent: There are two apps named ToDo List App in your project. Which one would you like to update? Two numbered options follow, then an Answer in your own words… field with a paperclip and a Skip button"><figcaption><p>Pick an answer, write your own, attach a file, or skip.</p></figcaption></figure>

* **Pick a numbered answer**, when the agent offers choices.
* **Write your own** in **Answer in your own words…**.
* **Attach a file**, when the agent asks for one, such as a brand guide or a spreadsheet. A question that offers numbered answers doesn't take a file.
* **Skip**, to let the agent carry on without an answer.

Once you answer, the request leaves **Gates** and the work continues.

## Notes and limitations

* **An unanswered request holds up the work.** A conversation that ends on a question waits until you answer. Check **Gates** when something you started hasn't finished.
* **Requests are per space.** Console's **Gates** doesn't show Control Center conversations, and the other way round.

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Console Operator</strong></td><td>Conversations, the composer, and what the Operator does.</td><td><a href="/ai-workbench-qore/console/console-operator">Console Operator</a></td></tr><tr><td><strong>Schedules</strong></td><td>Run the Operator at a set time.</td><td><a href="/ai-workbench-qore/console/console-operator/schedules">Schedules</a></td></tr><tr><td><strong>Governance Operator</strong></td><td>The Control Center Operator, whose requests show in Control Center's Gates.</td><td><a href="/ai-workbench-qore/control-center/governance-operator">Governance Operator</a></td></tr></tbody></table>

***

{% 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 %}


# Console Operator: FAQs & Troubleshooting

Answers to common Console Operator questions, and fixes for agents it won't use, missing connections, stalled work, and schedules.

This page answers common questions about the Console Operator, its agents and connections, Schedules, and Gates. Use the troubleshooting entries when the Operator doesn't use an agent or connection, work doesn't finish, or a schedule doesn't run as expected.

## FAQs

### Conversations

<details>

<summary>Does the Console Operator ask before it acts?</summary>

No. It dispatches as soon as you ask; there's no approval step. The Governance Operator in Control Center is the one that stages changes for approval. See [Console Operator](/ai-workbench-qore/console/console-operator#at-a-glance).

</details>

<details>

<summary>Can colleagues see my conversations?</summary>

No. Conversations are specific to each user; you see only the ones you started. See [Work in a conversation](/ai-workbench-qore/console/console-operator#work-in-a-conversation).

</details>

<details>

<summary>What does the Operator work on?</summary>

The selected project. Everything it creates belongs to that project, and switching projects changes what it can reach. See [What it does](/ai-workbench-qore/console/console-operator#what-it-does).

</details>

<details>

<summary>Do the model and effort I choose apply to the agents it hands work to?</summary>

No. They apply to the Operator only, per message. Agents it hands work to, such as the App Builder Agent, run on their own configured model and effort. See [The composer](/ai-workbench-qore/console/console-operator#the-composer).

</details>

<details>

<summary>Can the Operator add or remove people or teams?</summary>

No. It can tell you who is in the account and which teams it has, but changes stay in [Users](/ai-workbench-qore/control-center/admin/users) and [Teams](/ai-workbench-qore/control-center/admin/teams). See [What it does](/ai-workbench-qore/console/console-operator#what-it-does).

</details>

<details>

<summary>Does long work stop if I leave the conversation?</summary>

No. Builds such as an app or a knowledge base run as background tasks, and the Operator reports the real outcome when they finish. **Continue in a new conversation** and **Stay here** both leave the work running. See [Long-running work](/ai-workbench-qore/console/console-operator#long-running-work).

</details>

### Agents and connections

<details>

<summary>Which agents does the Operator use?</summary>

**System** agents, provided with Qore, start on. Your own project agents start off, so the Operator never hands work to one until you turn it on. The setting applies to you, in this project. See [Agents](/ai-workbench-qore/console/console-operator/agents-and-connections#agents).

</details>

<details>

<summary>Can I edit the System agents?</summary>

No. They're preconfigured for the account. You can turn each one on or off for yourself. See [What you control](/ai-workbench-qore/console/console-operator#what-you-control-and-what-you-dont).

</details>

<details>

<summary>Does a connection in Integrations Hub let the Operator use it?</summary>

Not on its own. Every connection starts off in the Operator; turn it on under **Connections**. The setting applies to every conversation. Agents the Operator hands work to don't inherit its connections. See [Connections](/ai-workbench-qore/console/console-operator/agents-and-connections#connections).

</details>

### Schedules and Gates

<details>

<summary>Which time zone do schedules use?</summary>

UTC. The schedules list then shows the next run in your local time. See [Create a schedule](/ai-workbench-qore/console/console-operator/schedules#create-a-schedule).

</details>

<details>

<summary>Can I run a schedule now?</summary>

There's no **Run now**. Ask the Operator in a conversation to run the same instructions straight away. See [Manage schedules](/ai-workbench-qore/console/console-operator/schedules#manage-schedules).

</details>

<details>

<summary>Can I see a colleague's schedules or Gates?</summary>

No. Schedules lists only the schedules you created, from every project. Gates lists only conversations you started, and only you can answer them. See [Schedules](/ai-workbench-qore/console/console-operator/schedules#manage-schedules) and [Gates](/ai-workbench-qore/console/console-operator/gates).

</details>

<details>

<summary>Are Console and Control Center schedules and Gates the same?</summary>

No. Console's run and list Console Operator conversations; Control Center's run and list Governance Operator conversations. See [Gates](/ai-workbench-qore/console/console-operator/gates).

</details>

## Troubleshooting

### Conversations

<details>

<summary>I can't see a colleague's conversation</summary>

Conversations are specific to each user. See [Work in a conversation](/ai-workbench-qore/console/console-operator#work-in-a-conversation).

</details>

<details>

<summary>Something I started hasn't finished</summary>

Check **Gates** in the top bar: the conversation may be waiting for your answer, and nothing moves until you answer. See [Gates](/ai-workbench-qore/console/console-operator/gates).

</details>

<details>

<summary>"This is taking a while" appears above the composer</summary>

The turn is running long. Select **Continue in a new conversation** to carry on with a summary, or **Stay here**. The work keeps running either way. See [Long-running work](/ai-workbench-qore/console/console-operator#long-running-work).

</details>

<details>

<summary>The context gauge is nearly full</summary>

Start a new conversation. See [The composer](/ai-workbench-qore/console/console-operator#the-composer).

</details>

### Agents and connections

<details>

<summary>The Operator didn't use my agent</summary>

Your own agents start off. Turn it on under **Agents** › **User**. Agents on an older runtime aren't listed until they're moved to the current one. See [Agents](/ai-workbench-qore/console/console-operator/agents-and-connections#agents).

</details>

<details>

<summary>I can't turn an agent off</summary>

An agent can't be turned off while it's working on a run. Try again when its run finishes. See [Agents](/ai-workbench-qore/console/console-operator/agents-and-connections#agents).

</details>

<details>

<summary>The Operator says it has nothing to hand the work to</summary>

Every agent is turned off. Turn on the agents you need under **Agents**. See [Agents](/ai-workbench-qore/console/console-operator/agents-and-connections#agents).

</details>

<details>

<summary>The Operator says it has no connection for a system</summary>

Turn on the connection it names under **Connections**, or connect one from **All integrations**. A new connection appears turned off until you turn it on. See [Connect a new system](/ai-workbench-qore/console/console-operator/agents-and-connections#connect-a-new-system).

</details>

<details>

<summary>Connections reads "No connections configured for this project"</summary>

The project has no Integration Hub connections yet. Connect one from **All integrations**. See [Connections](/ai-workbench-qore/console/console-operator/agents-and-connections#connections).

</details>

### Schedules

<details>

<summary>A schedule won't save</summary>

**Name** and **Instructions** are required, and a name of only spaces isn't accepted. In **JSON** mode, the instructions must be a non-empty JSON object. See [Create a schedule](/ai-workbench-qore/console/console-operator/schedules#create-a-schedule).

</details>

<details>

<summary>A schedule ran at the wrong time</summary>

Schedule times are in UTC. Convert from your local time. See [Create a schedule](/ai-workbench-qore/console/console-operator/schedules#create-a-schedule).

</details>

<details>

<summary>A schedule didn't run</summary>

Check that it's **Active**, not **Paused**. If the Operator a schedule runs isn't active, the run is skipped. See [Notes and limitations](/ai-workbench-qore/console/console-operator/schedules#notes-and-limitations).

</details>

<details>

<summary>A scheduled run didn't do what I expected</summary>

Nobody is present to answer its questions. Put everything the run needs in the instructions, and check which agents **Agents this run may use** allows. See [Notes and limitations](/ai-workbench-qore/console/console-operator/schedules#notes-and-limitations).

</details>

<details>

<summary>A schedule action is unavailable</summary>

Creating and changing schedules needs a role that allows it; hover over the action for the reason. See [Roles](/ai-workbench-qore/control-center/admin/roles).

</details>

### Related

* [Console Operator](/ai-workbench-qore/console/console-operator), [Agents & connections](/ai-workbench-qore/console/console-operator/agents-and-connections), [Schedules](/ai-workbench-qore/console/console-operator/schedules), and [Gates](/ai-workbench-qore/console/console-operator/gates)
* [Use the Console Operator](/ai-workbench-qore/task-guides/use-the-console-operator): every Console Operator task
* [Governance Operator FAQs](/ai-workbench-qore/control-center/governance-operator#faqs)

***

{% 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 Builder

Configure, test, deploy, and monitor production-ready AI agents in Qore.

The **Agent Builder** is where you configure an agent — its purpose, its reasoning, the knowledge and tools it can reach, the controls that keep it safe, and the checks that tell you whether it works.

While the [Builder Canvas](/ai-workbench-qore/console/agent-builder/the-canvas) gives a visual overview of the agent and its connected components, the pages in this section are where the actual configuration and control happens.

***

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FwmRJi5SIj7BgAB70sGxo%2Fimage.png?alt=media&amp;token=f9ed69b2-e10b-4262-be35-59cbb034af6d" alt=""><figcaption></figcaption></figure>

## The agent lifecycle

This section is organized around the order you work in, not the order the settings panel happens to list.

* [**Build**](/ai-workbench-qore/console/agent-builder/build) — Define the agent’s purpose, instructions, and runtime behavior; connect apps, services, MCP tools, skills, knowledge, and triggers.
* [**Test**](/ai-workbench-qore/console/agent-builder/test) — Validate the agent against scored datasets before anyone depends on it.
* [**Deploy**](/ai-workbench-qore/console/agent-builder/deploy) — Ship the agent into your product, with the authentication, domain, PII, and guardrail controls that make that safe.
* [**Monitor**](/ai-workbench-qore/console/agent-builder/monitor) — Watch production behavior and turn what you learn into improvements, which feed back into Build.

Together these provide a complete control layer for building, deploying, evaluating, and operating production agents.

## Common paths

* **Go live in your product** — [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration) and [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication)
* **Improve quality before release** — [Evals](/ai-workbench-qore/console/agent-builder/test/evals), [Instructions](/ai-workbench-qore/console/agent-builder/build/instructions), [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities), and [Guardrails (Beta)](/ai-workbench-qore/console/agent-builder/deploy/guardrails)
* **Improve quality after release** — [Monitoring](/ai-workbench-qore/console/agent-builder/monitor), [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval), and [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings)
* **Move an agent between environments** — [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent), [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables), and [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning)

For common questions and fixes, see [Agent Builder: FAQs & Troubleshooting](/ai-workbench-qore/console/agent-builder/agent-builder-faqs-and-troubleshooting).

***

{% 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 %}


# Get Started

The two surfaces of the builder, and how to find your way around.

Each agent in the Qore Agent Builder is a dedicated record. What you configure here — instructions, knowledge, tools, triggers, integrations, credentials, security controls — becomes how the agent behaves at runtime, inside whatever application embeds it.

## The two surfaces

**The Builder Canvas** is the visual workspace. It shows the agent's connected knowledge, skills, triggers, and configuration as a diagram, so you can see at a glance how the agent is wired — which connectors are attached, what knowledge it can reach.

**The builder chat** is on the left. Describe changes to the agent there, and the builder applies them. To chat with the agent itself, select **Try Agent** in the canvas header: the Agent Playground opens in a new tab.

A header across the top carries the global actions: the **Overview** and **Flow** tabs, the version selector, **Integrate Agent**, **Export Agent**, **Agent Config**, and **Try Agent**. See [The headers](/ai-workbench-qore/console/agent-builder/the-canvas#the-headers).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-877b15fb55c254f7e57caded5466151b00fd3b72%2Fqore_console_console-agent-builder-agents-list_rounded_shadow.png?alt=media" alt="The Agent Builder landing screen, with the Create New Agent prompt and a My Agents list"><figcaption><p>The Agent Builder landing screen.</p></figcaption></figure>

## Start an agent

**Create New Agent** reads *Describe the task. I'll build the agent to do it.* Describe the agent in **Describe the agent you want to build…** (select **+** to attach files), or select a template chip below the prompt, such as **Collections Agent**. Not starting from a prompt? Two links sit below the chips:

* **Import an existing agent** — bring in an agent package exported from Platform: a ZIP file up to 50 MB. Select **Next** to continue. See [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent#knowledge-in-the-package) for what an import restores.
* **Build from your IDE** — **Connect to coding agents (MCP)** connects your agents to an MCP-capable coding agent, such as Claude Code or Cursor, with an API key.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-653f57dc4be6aff015e4525d972215e1dd388098%2Fqore_agent-builder_how-to-import-existing-agent_rounded_shadow.png?alt=media" alt="The Import an existing agent dialog: Bring in an agent package exported from Platform, a ZIP upload area (up to 50 MB), and Cancel and Next buttons"><figcaption><p>Import an existing agent.</p></figcaption></figure>

### Connect to coding agents (MCP)

The dialog lists three MCP servers, each with an example command for Claude Code:

| Server                 | What it does                                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Agent Builder MCP**  | Create, configure, and manage agents.                                                                                                                        |
| **Knowledge MCP**      | Build datasets, ingest documents, and query the knowledge attached to your agents.                                                                           |
| **Agent Executor MCP** | Interact with your deployed agents by invoking them through the trigger API. An **Executor version** menu, such as **1.4**, sets the version in the command. |

Every request needs the `x-platform-key` header. Under **API keys**, select **+ Add Key** to create a key. A key is valid only for the current workspace and account, and you can revoke it at any time. Before you've made one, the list reads *No keys yet.*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a31c4c2c7fe58114898927966e34d13289256885%2Fqore_agent-builder_how-to-build-from-your-ide_rounded_shadow.png?alt=media" alt="The Connect to coding agents (MCP) dialog: example claude mcp add commands for Agent Builder MCP, Knowledge MCP and Agent Executor MCP with the server addresses blurred, an Executor version menu set to 1.4, the required x-platform-key header, and an API keys section with Add Key and No keys yet"><figcaption><p>Connect to coding agents (MCP).</p></figcaption></figure>

## My Agents

**My Agents**, below the prompt, lists your agents with their name, description, and when each was last updated. Narrow the list with **Search agent…**, and switch between the list and grid layouts. The **▷** icon on a row is **Try Agent**.

Each agent's **•••** menu has:

* **Export Agent** — opens the same Export Agent Package dialog as the canvas header. See [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent).
* **Executor Version** — choose the runtime version. The current one is ticked, and **1.0** is marked **Deprecated**. See [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning).
* **Delete Agent**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-de412ee9f6524c9b4a4d38c8bf15a997a18adfd4%2Fqore_agent-builder_how-to-my-agents-menu_rounded_shadow.png?alt=media" alt="My Agents with the ••• menu open on an agent: Export Agent, Executor Version and Delete Agent, with the Executor Version submenu listing 1.4 (ticked), 1.3, 1.2, 1.1 and 1.0 Deprecated"><figcaption><p>An agent's ••• menu in My Agents.</p></figcaption></figure>

For every task in one place, see [Create an agent](/ai-workbench-qore/task-guides/create-an-agent).

→ [The Canvas](/ai-workbench-qore/console/agent-builder/the-canvas)

## Finding the setting you need

The builder's pages are organized by the order you work in, not by the order the settings panel happens to list them.

| Stage                                                           | What you do there                                                                                                         |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [**Build**](/ai-workbench-qore/console/agent-builder/build)     | Define the agent — identity, instructions, behavior, runtime, skills, MCP tools, connectors, knowledge, triggers, secrets |
| [**Test**](/ai-workbench-qore/console/agent-builder/test)       | Validate it against scored datasets before anyone depends on it                                                           |
| [**Deploy**](/ai-workbench-qore/console/agent-builder/deploy)   | Ship it into your product, with authentication, domain, PII, and guardrail controls                                       |
| [**Monitor**](/ai-workbench-qore/console/agent-builder/monitor) | Watch production behavior and feed what you learn back into Build                                                         |

If you're looking for one specific screen, the [Overview](/ai-workbench-qore/console/agent-builder) lists every page under its stage.

## Common paths

* **Go live in your product** — [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration) and [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication)
* **Improve quality before release** — [Evals](/ai-workbench-qore/console/agent-builder/test/evals), [Instructions](/ai-workbench-qore/console/agent-builder/build/instructions), [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities), and [Guardrails (Beta)](/ai-workbench-qore/console/agent-builder/deploy/guardrails)
* **Improve quality after release** — [Monitoring](/ai-workbench-qore/console/agent-builder/monitor), [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval), and [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings)
* **Move an agent between environments** — [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent), [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables), and [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning)

## Why the configuration matters

What you set here becomes the agent's runtime behavior. Model selection, response format, instructions, connected knowledge, enabled tools, secrets, guardrails — each one directly affects how the agent answers real users.

A clear configuration produces an agent that behaves predictably in production. An incomplete or ambiguous one produces an agent that fails in ways that are hard to debug later, because nothing is technically broken — the agent is doing exactly what an unclear brief told it to. This guide is written to help you make each choice deliberately rather than by default.

***

New to agents? [How an Agent Works](/ai-workbench-qore/start-here/how-an-agent-works) walks through building one end to end. For the ideas behind the settings, see [Core Concepts](/ai-workbench-qore/start-here/core-concepts).

***

{% 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 %}


# The Canvas

The Builder Canvas is the visual overview of the agent configuration inside the UPTIQ Qore Platform Agent Builder. It presents the agent at the center, with its connected knowledge, skills, triggers, and integrations arranged around it in a structured layout.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-3660516ba2ecbaeb4628573e0f4e5d76c12d6ae3%2Fqore_agent-builder_studio-agent-builder-attach-agent-canvas_rounded_shadow.png?alt=media" alt="The Builder Canvas, with the agent at the center and connected knowledge, skills, and triggers arranged around it"><figcaption><p>The Builder Canvas.</p></figcaption></figure>

The canvas acts as a high-level representation of how the agent has been configured. At a glance, you can quickly understand:

* What knowledge sources are attached
* Which skills and connectors are available
* How many triggers are configured
* What runtime capabilities the agent has access to

Most configuration changes happen through **Agent Config**, but the canvas serves as the primary navigation surface for understanding the agent setup and accessing related workflows.

***

## The core layout

The canvas follows a simple mental model: one agent with connected capabilities around it.

### Agent

The agent appears at the center of the layout with its avatar, name, and agent type.

### Knowledge

Knowledge sources appear to the left of the agent, below **Triggers**. These represent the files, documents, and connected data sources the agent can reference during execution.

### Skills and Integrations

Skills and connected integrations appear to the right of the agent. These include platform-provided skills, MCP-based integrations, external connectors, and additional capabilities attached to the agent.

### Triggers

Triggers appear to the left of the agent, above **Knowledge**. Triggers define the events or actions that can initiate agent execution.

Each section in this guide maps back to one of these areas of the canvas.

## The headers <a href="#the-headers" id="the-headers"></a>

The Agent Builder has two headers: one above the chat on the left, and one above the canvas on the right.

### Chat header

* **Agent name**: opens the agent's options menu, with **Back** and **Rename Agent**.
* **Chat history**: your past conversations with the builder.
* **New chat**: starts a fresh conversation with the builder.
* **Need Help? Report the Issue** (the **?** icon): opens a form to raise a request. See [Report an issue](#report-an-issue).
* **Toggle Panel**: hides or shows the chat.

### The builder chat

* **Attach Files**: select **+** beside **Type here…**, then **Attach Files** (*Upload files from your device*).
* **Context usage**: the ring beside the send arrow shows how much of the chat's context is used. Hover for how full it is, such as *11% Full*, the tokens used out of the total, such as *\~21.1K / \~200.0K Tokens*, and the tokens taken by **User messages**, **Assistant messages**, **Tool calls**, and **Tool results**.
* **Credits per reply**: each builder reply shows the credits it used, such as *70.3 credits · $0.0351*.
* **Chats from an older version**: these show *This chat was made in an older version.* Select **Migrate chat** to keep building in it with its history (migrating can take a while), or **Start new conversation**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-9c0e62353fda93798f14d726177fbb0b6c1039b4%2Fqore_agent-builder_how-to-context-usage_rounded_shadow.png?alt=media" alt="The context usage breakdown: 11% Full, about 21.1K of 200.0K tokens, with User messages, Assistant messages, Tool calls and Tool results"><figcaption><p>Context usage in the builder chat.</p></figcaption></figure>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-5476e3536479aab0160cefea4cfb292e26ce78cb%2Fqore_agent-builder_how-to-migrate-chat_rounded_shadow.png?alt=media" alt="The notice This chat was made in an older version, with Migrate chat and Start new conversation buttons"><figcaption><p>A chat from an older version.</p></figcaption></figure>

### Canvas header

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-4c319badc50b2ba5cb0fd89dddfbe4970eb4ca7e%2Fqore_agent-builder_header-2-16_rounded_shadow.png?alt=media" alt="The Agent Builder header: chat history, new chat, help and panel icons on the left; the Overview and Flow tabs; then credits and cost, the version selector, download, integrate and export icons, Agent Config and Try Agent"><figcaption><p>The Agent Builder header.</p></figcaption></figure>

From left to right:

* **Overview** and **Flow**: the two views of the agent. See [Overview and Flow tabs](#overview-and-flow-tabs).
* **Credits and cost**: what the agent has used, such as `1,530 credits` and `$0.77`. Hover for the breakdown.
* **Version selector**: the version you're viewing, such as **Draft Version** or **v1.0**. See [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning).
* **Download Agent Version** (download icon): downloads the selected version's file to your browser. It appears only when you're on a saved version with no unsaved changes.
* **Integrate Agent** (`</>`): the options for running the agent inside your own app. See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration).
* **Export Agent** (export icon): exports the agent as a package, delivered by email. You need the **Export Agent** capability; without it the button is disabled. See [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent).
* **Agent Config**: opens the agent's settings.
* **Try Agent**: opens the Agent Playground in a new tab, where you can chat with the agent. You need the **Trigger Agent** capability, and the agent needs a widget key.

***

## Overview and Flow tabs <a href="#overview-and-flow-tabs" id="overview-and-flow-tabs"></a>

The canvas has two tabs, in the canvas header.

### Overview

The default view. It shows the agent at the center with its **Triggers**, **Knowledge**, **Skills**, and **Integrations** cards around it.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-110b79580582985923ad6e49069a877d241acc94%2Fqore_agent-builder_canvas-overview-tab_rounded_shadow.png?alt=media" alt="The Overview tab: the agent at the center, Triggers and Knowledge cards to its left, and Skills and Integrations cards to its right"><figcaption><p>The Overview tab, the canvas's default view.</p></figcaption></figure>

### Flow

The Flow tab (formerly **Plan**) displays the agent’s decomposed execution flow as a sequence of steps the agent may follow during runtime, under *What the Agent will do*.

Instead of showing the visual layout of connected components, the Flow tab focuses on how the agent approaches task execution. It breaks the workflow into structured milestones, helping you understand:

* How the agent plans to solve a task
* The sequence of execution stages
* Which skills or integrations may be used during execution
* How larger workflows are decomposed into smaller operational steps

This view is useful for understanding orchestration logic, validating execution behavior, and reviewing how the agent is expected to progress through a task.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-968f801f416ba680900d4fa54b241f88731e7a8d%2Fqore_agent-builder_canvas-flow-tab_rounded_shadow.png?alt=media" alt="The Flow tab: What the Agent will do, followed by a sequence of steps such as Receive and Validate Request and Analyze and Extract Questions, each with a short description"><figcaption><p>The Flow tab.</p></figcaption></figure>

## Report an issue <a href="#report-an-issue" id="report-an-issue"></a>

To raise a request, select **Need Help? Report the Issue** (the **?** icon) in the chat header. The **Need Help? Raise a Request** form opens with the agent already filled in.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-9c1c59673e7016c150f3c495f44e05b25eac99af%2Fqore_agent-builder_report-issue-dialog_rounded_shadow.png?alt=media" alt="The Need Help? Raise a Request form, with the Agent field filled in, Title and What do you need help with? fields, an Upload button for attachments, and Cancel and Submit Request buttons"><figcaption><p>Raise a request from the Agent Builder.</p></figcaption></figure>

* **Title**: required, up to 200 characters.
* **What do you need help with?**: required, up to 2,000 characters. Explain the issue or the outcome you're trying to achieve.
* **Attachment**: optional. Upload up to five PNG or JPEG screenshots, each up to 10 MB.

Select **Submit Request**. Qore confirms with *Issue reported successfully. Thank you for your feedback!* The same form is available in App Builder.

## Interactive Areas on the Canvas

The canvas primarily acts as a visual overview rather than a direct editing surface.

Most nodes are informational summaries of the current agent state. Configuration changes are managed through **Agent Config** and related setup flows.

Some sections act as shortcuts into deeper workflows, such as:

* Adding knowledge
* Managing skills
* Configuring integrations
* Setting triggers

The visual layout helps you quickly understand what is connected to the agent and identify what may still need configuration.

***

## Why this matters

The Builder Canvas serves as the central navigation and visualization layer for the agent.

Understanding this layout makes it easier to:

* Review the current agent setup
* Navigate to the correct configuration area
* Validate attached knowledge and integrations
* Identify missing runtime capabilities
* Troubleshoot agent behavior during testing

Most pages in this guide either explain a section visible on the canvas or describe the configuration flows launched from it.

***

{% 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 %}


# Build

Define what the agent is and what it can reach.

**Build** is where the agent takes shape. You give it an identity, write the instructions that govern every response, choose how hard it thinks, attach the skills and knowledge it needs, and wire the credentials and triggers that let it run.

Most of your time in the Agent Builder is spent here, and most agent problems are traced back here. An agent that answers wrongly usually has an instructions problem, a knowledge problem, or a skills problem — not a deployment problem.

## Identity and reasoning

* [Basic Details](/ai-workbench-qore/console/agent-builder/build/basic-details) — Define the agent’s name, metadata, and ownership.
* [Instructions](/ai-workbench-qore/console/agent-builder/build/instructions) — Set the system instructions that guide responses and reasoning.
* [Agent Behavior](/ai-workbench-qore/console/agent-builder/build/agent-behavior) — Control autonomy, memory, and execution style.
* [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning) — Manage runtime settings, engine versions, and release history.
* [Execution Plan/Checklist](/ai-workbench-qore/console/agent-builder/build/execution-plan-checklist) — Define structured plans and guided execution steps.

## Capabilities

What the agent can *do* — the actions available to it at runtime.

* [Adding a Skill to the Agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent) — Give the agent an action it can take.
* [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities) — Attach reusable skills and actions.
* [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools) — Configure MCP servers and tool access.
* [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services) — Connect external apps and services.

## Knowledge

What the agent can *read* — the material it retrieves from at runtime.

* [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent) — Give the agent something to read.

## Execution and credentials

* [Triggers](/ai-workbench-qore/console/agent-builder/build/triggers) — Configure events that start the agent automatically.
* [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) — Store runtime credentials and reusable values.

***

Once the agent behaves the way you intend, move on to [Test](/ai-workbench-qore/console/agent-builder/test) to validate it against real cases before release.

***

{% 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 %}


# Basic Details

**Basic Details** is the agent's identity card. It carries the four pieces of information that travel with the agent everywhere it appears — in the host application, in the preview pane, in dashboards, in shared traces: a name, an avatar, a short description, and the format the agent renders its responses in. These settings are what users (and other systems) see; they are the agent's outside.

Agent Config → Basic Details

Reach this page by clicking **Agent Config** in the canvas header; Basic Details is the default section in the left navigation when the dialog opens.

### The fields <a href="#the-fields" id="the-fields"></a>

The right pane has four configurable items, top to bottom.

#### Agent Avatar <a href="#agent-avatar" id="agent-avatar"></a>

A small image that represents the agent visually in chat surfaces and in the Layout canvas. The avatar is optional. Two buttons sit next to the preview: **Upload** (pick a local image) and **Remove** (clear the current avatar). When no avatar is set, the platform shows a default icon.

#### Agent Name <a href="#agent-name" id="agent-name"></a>

The agent's display name. This is what shows in the header strip, in the agent-name selector menu, and on the agent-list dashboard. Renaming here is the same action as renaming through the agent-name menu in the header.

#### Agent Description <a href="#agent-description" id="agent-description"></a>

A short prose description of what the agent does. Used in tenant-facing listings of agents and in tooltips. Keep it action-oriented — what the agent does for users — rather than implementation-oriented.

#### Agent Output Format <a href="#agent-output-format" id="agent-output-format"></a>

A dropdown selecting how the agent's text responses are rendered:

* **Markdown** (default) — the agent's output is treated as Markdown. Headings, bullets, code blocks, bold, and links render with formatting.
* **Json** — the agent's output is treated as a JSON payload. The host application is responsible for parsing it.

Choose Markdown for any agent whose output is read by humans in chat. Choose Json when the agent's output is consumed by another system that needs a structured payload.

### Fields and obligation <a href="#fields-and-obligation" id="fields-and-obligation"></a>

| Field               | Obligation | Notes                           |
| ------------------- | ---------- | ------------------------------- |
| Agent Avatar        | Optional   | Default icon shown when empty.  |
| Agent Name          | Mandatory  | Recommended. Auto-generated.    |
| Agent Description   | Optional   | Recommended. Auto-generated.    |
| Agent Output Format | Mandatory  | `Markdown` (default) or `Json`. |

### Saving <a href="#saving" id="saving"></a>

The **Save** button sits in the top-right of the right pane. It activates when you've made unsaved changes. Clicking it commits the changes to the current draft of the agent.

Saved changes here do **not** automatically create a version snapshot — they're saved to the draft. To preserve the current state as a recoverable version, click **Draft Version** in the header strip after saving.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

These four fields are the agent's public face. The name and avatar are how every other surface — the dashboard, the chat, the Layout canvas, any embed of this agent in another application — refers to this agent. The description shapes how teammates decide whether *this* agent is the right one to invoke for a new use case. And the output format quietly decides whether your agent fits cleanly into the host application or generates parsing errors at runtime. Get these right at the start; revisiting them later means updating every surface that has already rendered the agent's identity.

***

{% 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 %}


# Instructions

**Instructions** is where you write what the agent does and how it does it — the agent's operating brief, in your words. The platform feeds this content to the underlying model on every turn, so the rules, tone, examples, and step-by-step procedures you put here shape every response the agent produces. It is the single most consequential page in the builder: a good set of instructions makes everything else work better; a vague or contradictory set makes the agent unreliable in ways that are difficult to debug later.

Agent Config → Instructions

Reach this page from **Agent Config → Instructions** in the left navigation.

### The three action buttons <a href="#the-three-action-buttons" id="the-three-action-buttons"></a>

Three buttons sit above the editor body:

* **Upload from file** (green) — bulk-import instructions from a file rather than typing them in the editor. Useful when the instructions exist elsewhere as a document and you want them in the agent verbatim.
* **Improve with AI** (sparkles icon) — runs an AI pass over the current instructions. The platform automatically reviews the instructions you've written and suggests or applies improvements, replacing the manual work of self-editing for clarity, structure, and consistency. Use it as a second opinion after you draft, not as a substitute for thinking through what the agent should do.
* **Best Practices to give instructions** — opens a side panel with the recommended template (see below). Useful as a structural scaffold the first time you author instructions, or when you're not sure your current set covers everything it should.

#### The Best Practices side panel <a href="#the-best-practices-side-panel" id="the-best-practices-side-panel"></a>

Instructions with the Best Practices side panel open

Clicking **Best Practices to give instructions** opens a side panel titled `Best Practices for General Purpose Agents`. The panel narrows the editor to the left and renders the platform's recommended structure on the right.

The general advice at the top:

1. Include a clear and concise objective or goal for the agent.
2. Include examples where possible.
3. Include details like format, data types, and any other relevant information.

The recommended template — use the sections that apply, skip the optional ones:

<table><thead><tr><th width="246.00006103515625">Section</th><th>What Goes Here</th></tr></thead><tbody><tr><td>Objective / Goal</td><td>The main purpose of the agent in one or two sentences.</td></tr><tr><td>Inputs Required</td><td>What information the agent needs to do its job.</td></tr><tr><td>Process / Steps</td><td>The procedure the agent follows.</td></tr><tr><td>Outputs / Deliverables</td><td>What the agent produces.</td></tr><tr><td>Constraints / Rules</td><td>Limitations, compliance requirements, things the agent must never do.</td></tr><tr><td>Tone / Interaction Style (optional)</td><td>How the agent communicates with users.</td></tr><tr><td>Additional Instructions (optional)</td><td>Anything else that didn't fit above.</td></tr></tbody></table>

Close the side panel with its own `×` when you're done; the editor returns to full width.

### What to put in instructions, and what not to <a href="#what-to-put-in-instructions-and-what-not-to" id="what-to-put-in-instructions-and-what-not-to"></a>

The instructions field is the agent's operating brief, not its credentials store. Put the agent's **behavior** in instructions — what it does, the steps it follows, the rules it observes, the tone it uses, the examples that anchor good outputs. Do **not** put **secrets** in instructions.

> **Important** Never paste API keys, passwords, tokens, or other credentials directly into the Instructions field. Credentials belong in Secrets & Variables. Reference them in skill configurations and instructions as `$secret.{name}`. Instructions content is included in every model call and may appear in execution traces, logs, and downstream systems — anywhere a secret pasted here would also appear.

The same rule applies to other sensitive data: personally identifying information, customer records, and internal documents that shouldn't accompany every model call all belong outside the instructions field, behind references the agent can resolve at runtime.

### Saving <a href="#saving" id="saving"></a>

The **Save** button sits in the top-right and activates when you've made changes. Saved changes go to the agent's draft; create a recoverable snapshot from the Draft Version popover.

After saving, send a test message with **Try Agent** to verify the agent follows the new instructions before relying on the change in production.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

Of every setting in the builder, the instructions field has the most direct effect on what the agent actually does. Two agents with the same model, same skills, and same attached knowledge will behave very differently if their instructions diverge. The Best Practices template exists because clean, well-structured instructions tend to produce predictable agents, and a few minutes spent putting the brief in the right shape prevents hours of debugging surprising behavior later. Treat this page as authoring, not as form-filling.

***

{% 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 Behavior

**Agent Behaviour** controls how the agent thinks and answers — not what it knows or what it can do, but how it goes about its work. The settings on this page choose the model that runs the agent, decide how independently the agent operates, balance response speed against response quality, and manage the conversation's context. These are the runtime levers; changing one here changes the agent's character across every task it handles.

Reach this page from **Agent Config → Agent Behaviour** in the left navigation. The page reads *"Control how your agent behaves, communicates, and handles tasks."*

The page is organized into two sections: **Core Controls** (the day-to-day levers) and **Advanced Controls** (model selection, context, and safety toggles).

### Core Controls <a href="#core-controls" id="core-controls"></a>

#### Autonomy <a href="#autonomy" id="autonomy"></a>

A slider with markers **Low**, **Med**, **High**: *"How independently the agent works."* The default is **Med**.

Higher autonomy means the agent commits to multi-step plans on its own; lower autonomy means it confirms more steps before proceeding.

#### Agent Capability <a href="#agent-capability" id="agent-capability"></a>

A dropdown: *"Controls how deeply the agent thinks."* The default is **Auto**.

| Option                  | Notes                                                                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto**                | The platform decides based on the input. Marked **Not Supported** on an executor version that doesn't support it.                                 |
| **Intelligent Planner** | —                                                                                                                                                 |
| **Next Best Step**      | The **Planning Model** field is hidden with this option.                                                                                          |
| **Fast**                | *"Fast strategy strips persona, FAQ, CoT validation, and learning cases for lower latency."* Available only on executor versions that support it. |

While **Response Mode** is **Flash**, Agent Capability can't be changed.

#### Response Mode <a href="#response-mode" id="response-mode"></a>

A dropdown: *"Speed vs quality of responses."* The options are **Advanced**, **Balanced**, and **Flash**. The default is **Advanced**.

**Advanced** produces higher-quality responses at a slower rate; faster modes return more quickly with shallower processing. The **Planning Model** and **Execution Model** fields appear only in **Advanced**. A mode that isn't available for the account is flagged, and the page can't be saved until you choose another.

#### Memory settings have moved <a href="#memory" id="memory"></a>

User persona memory and FAQ memory are no longer on this page. Both are under **Agent Config → Reinforcement Learning** (Preview), are **off** on a new agent, and aren't used while **Agent Capability** is **Fast**. See [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings).

**User Persona** tab — **Enable User Persona**. When on, the agent remembers what an individual user has asked about, preferred, or corrected, across conversations. The tab lists stored persona memories, and you can delete one.

#### FAQ memory <a href="#faq-memory" id="faq-memory"></a>

**FAQ** tab, under **Agent Config → Reinforcement Learning** — **Enable FAQ**. When on, the agent can use stored FAQs and their canonical answers when a question matches a known FAQ. The tab lists the stored FAQs.

### Advanced Controls <a href="#advanced-controls" id="advanced-controls"></a>

#### Model Family <a href="#model-family" id="model-family"></a>

A dropdown that filters the **Planning Model** and **Execution Model** lists to one provider family: *"Filter available models by provider family."* It lists the families [AI Gateway](/ai-workbench-qore/control-center/ai-gateway/how-model-routing-works#model-families-for-agents) serves for your organization. Agents can use **Google** and **OpenAI**. A family marked **Dev only** isn't available in production. Clear the selection with the **×** beside it.

If the saved family is no longer available in your AI Gateway, the page says so, and you choose another family before saving.

#### Planning Model <a href="#planning-model" id="planning-model"></a>

A dropdown selecting the model that the agent uses for planning tasks — deciding what to do, in what order, given an incoming request. The option list is the same as Execution Model. It appears when **Response Mode** is **Advanced** and **Agent Capability** is **Auto**, **Intelligent Planner**, or **Fast**.

The planning model can differ from the execution model. A common pattern is to use a heavier model for planning (because planning happens once per request) and a lighter model for execution (because the executor may run many tool calls per request).

#### Execution Model <a href="#execution-model" id="execution-model"></a>

A dropdown selecting the model that the agent uses to execute tasks. It appears when **Response Mode** is **Advanced**. The options are the models AI Gateway can serve for your organization, so the list differs between organizations and changes as models are added — open the dropdown to see yours. A model the gateway can't serve is greyed out. A saved model that's no longer available stays in the field, marked **Unavailable**. A model the agent's executor version doesn't support is marked **Not Supported**, and the page can't be saved until you choose another.

Below the model fields, a banner reads: *"Model output may differ across cloud providers (e.g. Azure, AWS, GCP) due to hosting and infrastructure differences. Verify outputs for critical use cases."*

#### CoT Reasoning (beta) <a href="#cot-reasoning-beta" id="cot-reasoning-beta"></a>

A toggle marked **Deprecated**. It can't be turned on.

* On an agent that never had it on, the toggle is disabled: *"Chain of Thought is deprecated and can no longer be enabled."*
* On an agent that already has it on, you can turn it off: *"Chain of Thought is deprecated. You can turn it off, but once disabled it cannot be re-enabled."* While it is on, **Select Model for CoT** sets the model used for CoT reasoning.

With **Agent Capability** set to **Fast**, the toggle is marked **Not Supported**.

#### Auto-compaction <a href="#auto-compaction" id="auto-compaction"></a>

A toggle: *"Summarize the conversation when it nears the context window."* When on, **Compaction threshold** sets when compaction happens: *"Compact when context usage reaches this share of the window,"* from **50%** to **95%** in steps of 5. Auto-compaction appears only when the agent's executor version supports it.

#### Prompt Sanitization <a href="#enable-prompt-sanitization" id="enable-prompt-sanitization"></a>

A toggle: *"Enable detection of malicious user prompts."* On an agent whose executor version doesn't support it, the toggle is off, unavailable, and marked **Not Supported**, and it is saved as off.

### Fields and obligation <a href="#fields-and-obligation" id="fields-and-obligation"></a>

| Field                | Obligation      | Notes                                                                                        |
| -------------------- | --------------- | -------------------------------------------------------------------------------------------- |
| Autonomy             | Mandatory       | Default `Med`.                                                                               |
| Agent Capability     | Mandatory       | Default `Auto`. Locked while Response Mode is `Flash`.                                       |
| Response Mode        | Mandatory       | `Advanced`, `Balanced`, or `Flash`. Default `Advanced`.                                      |
| Model Family         | Optional        | Filters the model lists. Google and OpenAI in production.                                    |
| Planning Model       | Conditional     | `Advanced` mode with `Auto`, `Intelligent Planner`, or `Fast`. Same pool as Execution Model. |
| Execution Model      | Conditional     | `Advanced` mode. Options and default vary by organization.                                   |
| CoT Reasoning (beta) | Deprecated      | Can only be turned off, on agents that already have it on.                                   |
| Auto-compaction      | Optional toggle | Shown when the executor version supports it. Threshold 50–95%.                               |
| Prompt Sanitization  | Conditional     | Shown as **Not Supported** when the executor version doesn't support it.                     |

### Saving <a href="#saving" id="saving"></a>

The **Save** button activates with unsaved changes. After saving, test the new behavior with **Try Agent**.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

Behavior settings affect the agent's *character* — how it reasons, how it phrases, how confidently it acts. The same instructions executed by `Gemini 3 Flash` and by `GPT 5.4` produce different agents, even when neither configuration has changed otherwise. The Draft Version popover is where you snapshot a behavior configuration that's working, so you can recover it later.

***

{% 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 %}


# Runtime & Versioning

Select, validate, and upgrade the Agent Executor version that runs your agent.

**Runtime & Versioning** controls the Agent Executor version that runs your agent. Executor releases add capabilities, address issues, and can deprecate earlier behavior. Pinning a version keeps runtime behavior predictable while you validate upgrades.

Open **Agent Config → Runtime & Versoning**. The navigation label currently uses `Versoning`.

### Executor Version <a href="#executor-version" id="executor-version"></a>

Use **Executor Version** to select the runtime for this agent.

| Field            | Obligation | Default                                                    | Notes                                                                |
| ---------------- | ---------- | ---------------------------------------------------------- | -------------------------------------------------------------------- |
| Executor Version | Mandatory  | The latest version available to your tenant, such as `1.4` | Switching versions can change agent behavior and available features. |

The dropdown lists versions available to your tenant. New agents use the latest available version by default. Existing agents remain on their current version until you migrate them.

You can also change it from the agent list: in **My Agents**, select **•••** on the agent's row, then **Executor Version**. The current version is ticked, and **1.0** is marked **Deprecated**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-de412ee9f6524c9b4a4d38c8bf15a997a18adfd4%2Fqore_agent-builder_how-to-my-agents-menu_rounded_shadow.png?alt=media" alt="My Agents with the ••• menu open on an agent: Export Agent, Executor Version and Delete Agent, with the Executor Version submenu listing 1.4 (ticked), 1.3, 1.2, 1.1 and 1.0 Deprecated"><figcaption><p>Executor Version, from My Agents.</p></figcaption></figure>

{% hint style="info" %}
Agent Executor v1.4 is available. Migrate agents on earlier versions after validation.
{% endhint %}

### Migrate to v1.4 <a href="#migrate-to-v14" id="migrate-to-v14"></a>

Agent Executor v1.4 is the current documented upgrade target. Migrate when you need its runtime capabilities or support for the current release.

1. In **Executor Version**, select `1.4`.
2. Select **Save**.
3. Test representative conversations, skills, and integrations.

Check expected outputs and execution behavior before you rely on the upgraded agent in production.

{% hint style="warning" %}
An executor upgrade can change agent behavior. Validate the agent before migrating production workloads.
{% endhint %}

See [September 12 release notes](/ai-workbench-qore/release-notes/2026/september-12) for the v1.4 announcement.

### When the executor version matters <a href="#when-the-executor-version-matters" id="when-the-executor-version-matters"></a>

Most agent configuration works across versions. Some capabilities require a newer executor version. For example, PII tokenization can be unavailable when an agent uses an older unsupported version.

If a builder section is unavailable, check the executor version. Upgrade and validate the agent when the feature requires a newer runtime.

### Draft versions and executor versions <a href="#draft-versions-and-executor-versions" id="draft-versions-and-executor-versions"></a>

**Executor Version** selects the platform runtime. **Draft Version** saves a snapshot of the agent configuration.

| Version type         | Scope                    | Use it for                                        |
| -------------------- | ------------------------ | ------------------------------------------------- |
| **Executor Version** | One runtime per agent    | Control runtime behavior and feature availability |
| **Draft Version**    | Many snapshots per agent | Compare or restore agent configuration            |

The settings are independent. Saving a draft doesn't change the executor version. Changing the executor version doesn't save a draft.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

Version pinning makes agent behavior reproducible. Your agent remains on its tested runtime until you choose an upgrade. Use the latest supported version for new agents, then validate it before production use.

***

{% 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 %}


# Execution Plan/Checklist

A checklist is a reusable execution plan automatically generated and refined by the agent over time based on successful runtime plans. It represents a structured sequence of skill executions the agent can reuse when handling similar requests in the future.

Instead of planning every request from scratch, the agent can recognize familiar patterns and follow an existing checklist to execute the workflow more consistently and efficiently. If no suitable checklist exists for an incoming request, the planner dynamically creates a new execution plan at runtime.

Checklists also power the **Flow** tab (formerly **Plan**) on the Builder Canvas. When no checklist exists for the agent, the Flow tab displays **No Plan Found**.

***

## Agent Config → Checklists

Access this section from:

**Agent Config → Checklists**

The page displays all execution checklists currently available to the agent.

***

## The Checklists Table

The right panel contains a table with the following columns:

| Column          | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| **Name**        | The checklist name                                          |
| **When to use** | The type of requests or situations the checklist applies to |
| **Steps**       | Number of execution steps in the workflow                   |
| **Actions**     | Available management actions for the checklist              |

Each row represents one reusable execution workflow available to the agent.

## How Checklists Are Created

Checklists are derived from the agent’s runtime planning behavior.

As the planner executes tasks successfully, recurring execution patterns can be converted into reusable checklists. This allows the agent to standardize workflows that are repeatedly used and improve execution consistency over time.

Rather than manually rebuilding the same workflow repeatedly, the agent can reuse a known execution structure for similar requests.

***

## How Checklists Relate to the Rest of the Agent

### Builder Canvas → Flow Tab

The **Flow** tab visualizes the checklist flow associated with the agent.

When one or more checklists exist, the tab displays the execution sequence and step structure. Without any checklists, the Flow tab shows **No Plan Found**.

***

### Skills & Capabilities

Each checklist step executes a skill attached to the agent.

A checklist can only invoke skills that are currently available within the agent’s configured capabilities.

***

### Triggers

Triggers determine **when the agent starts running**.

Checklists determine **how the agent executes once it starts**.

These systems operate independently:

* A trigger can invoke the agent without matching a checklist
* A checklist can execute regardless of how the agent was triggered

***

## When Checklists Become Useful

Checklists are most valuable when:

* Similar requests are received repeatedly
* The workflow requires multiple skills executed in a specific order
* Runtime planning results have become inconsistent
* Execution paths need to be easier to review, explain, or audit
* Predictable execution is more important than planner flexibility

***

## When Dynamic Planning Is Better

Dynamic planning remains useful when:

* Incoming requests are highly varied
* The agent is still early in adoption and usage patterns are unknown
* Workflows frequently change
* A request type is too infrequent to justify a reusable execution plan

***

## Why This Matters

Checklists help balance flexibility with execution consistency.

The runtime planner is capable of dynamically generating workflows for almost any request, but dynamic plans may vary between runs depending on context and reasoning decisions.

For recurring workflows where the ideal execution path is already known, reusable checklists provide:

* More predictable execution
* Faster runtime planning
* Better operational consistency
* Easier debugging and auditing
* Clearer visibility into how the agent handles common requests

Most agents initially operate well without checklists. Over time, as repeated execution patterns emerge, reusable plans become valuable for stabilizing and scaling agent behavior.

***

{% 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 %}


# Adding a skill to the agent

{% hint style="info" %}
Skills define what an agent can *do* at runtime. While knowledge gives the agent information to reference, skills allow it to take actions—such as calling APIs, executing code, querying databases, interacting with external systems, or invoking other agents.
{% endhint %}

> This flow allows you to attach new capabilities to an agent directly from the Builder Canvas through the **Add Skill to Agent** workflow.

### Understanding skills

Qore has seven kinds of skill. They differ in who provides them, how much you set up, and what they suit. Before adding a skill, find the kind that fits the job.

| Kind                        | Where you add it                                            | Provided by                           | What you set up                        | Use it when                                                                                                    | Details                                                                                                                                                                      |
| --------------------------- | ----------------------------------------------------------- | ------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Built-in skills**         | **Pre-attached Skills** tab                                 | Uptiq, on every agent                 | Nothing. Enable the ones you need      | The agent needs the basics: reasoning, web search, knowledge search, code, files, and documents                | [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills), [Document skills](/ai-workbench-qore/platform-resources/skill-library/document-skills) |
| **Skill Library skills**    | **Skill Library** tab                                       | Uptiq                                 | A form for each skill                  | The agent must reach your own systems or run your own logic: an HTTP API, code, an MCP server, or web crawling | [Skill Library](/ai-workbench-qore/platform-resources/skill-library)                                                                                                         |
| **MCP Marketplace servers** | **MCP Marketplace** tab                                     | Third parties, curated in the catalog | Connect the server                     | A catalog server already does the job, such as market data, SEC filings, search, or scraping                   | [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools)                                                                                                        |
| **Integrations**            | **Add Integrations** on the canvas, and **Apps & Services** | Integration Hub                       | Connect the service                    | The action involves a SaaS product with a pre-built connector, such as Stripe or Twilio                        | [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services)                                                                                          |
| **Custom skills**           | **Custom Skills** tab                                       | You                                   | Upload a folder with a `SKILL.md` file | The agent should follow your own procedure or know-how, such as a house style or a review checklist            | [Custom skills](/ai-workbench-qore/platform-resources/skill-library/custom-skills)                                                                                           |
| **Flows**                   | **Flows** tab                                               | You, built in Flows                   | Choose a flow                          | The job is a fixed, multi-step process that should run as one step                                             | [Use flows with agents](/ai-workbench-qore/console/flows/use-flows-with-agents)                                                                                              |
| **Agents**                  | **Agents** tab                                              | You, as another agent in the project  | Choose an agent                        | Another agent is better suited to part of the job, so this agent hands that part to it                         | [Add another agent](#add-another-agent-as-a-skill)                                                                                                                           |

{% hint style="info" %}
**Start with what already exists.** Enable a built-in skill, or connect a catalog server or integration, before you configure or build your own. Built-in skills and connectors need the least setup.
{% endhint %}

{% hint style="info" %}
If you are unsure where to begin, start with the **Skill Library** tab.
{% endhint %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FrfM2GXJHJeR4kdiM46pv%2Fimage.png?alt=media&amp;token=bad03347-c4dc-4352-9c39-fbf86ba6147f" alt=""><figcaption></figcaption></figure>

### Add a skill to the agent

{% stepper %}
{% step %}

#### Step 1—Open the Add Skill flow

From the Builder Canvas, select **+ Add Skill** in the Skills section below the agent node.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-306259302970ff3c19e4ee1bc8f4c29da69abea7%2Fqore_agent-builder_studio-agent-builder-attach-agent-canvas-add-skill_rounded_shadow.png?alt=media" alt="The Builder Canvas, with the + Add Skill button in the Skills section below the agent node"><figcaption><p>Opening the Add Skill flow from the canvas.</p></figcaption></figure>

This opens the **Add Skill to Agent** dialog.
{% endstep %}

{% step %}

#### Step 2—Choose a skill source

The dialog is organized into multiple tabs to help you discover skills from different sources.

| Tab                     | Description                                                                                                                                                                                                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **All**                 | Every skill from every tab                                                                                                                                                                                                                                                                                                 |
| **Skill Library**       | Skills by Uptiq that you configure for your own systems and logic: MCP Server, API Call, API Call Advanced, JavaScript Code, Python Code, Structured Data Query, Web Crawler, Document Extraction, and Document Summarizer. See [Skill Library](/ai-workbench-qore/platform-resources/skill-library)                       |
| **Flows**               | Flows you can add to the agent as a skill. **+ Create Flow** makes a new one; see [Create a flow](/ai-workbench-qore/task-guides/create-a-flow#create-a-flow-from-an-agent)                                                                                                                                                |
| **Agents**              | Existing agents that you can reuse as sub-agents                                                                                                                                                                                                                                                                           |
| **MCP Marketplace**     | MCP servers, grouped by category. See [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools)                                                                                                                                                                                                                |
| **Custom Skills**       | Upload your own skill, a folder with a `SKILL.md` file and up to 10 supporting files. See [Custom skills](/ai-workbench-qore/platform-resources/skill-library/custom-skills)                                                                                                                                               |
| **Pre-attached Skills** | The built-in General and Document skills, in two lists: **Active Skills**, and **Skills you can add**, each with an **Enable** button. See [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills) and [Document skills](/ai-workbench-qore/platform-resources/skill-library/document-skills) |

Switching tabs automatically filters the available skill list.

#### Add another agent as a skill

The **Agents** tab lists the other agents in the project, each with its name and description. The agent you're editing isn't listed.

{% hint style="warning" %}
**Selecting an agent attaches it straight away.** There is no form or confirmation step. The agent appears in the canvas's **Skills** list as an **Agent** skill, and the skill count goes up by one.
{% endhint %}

The attached agent becomes a sub-agent. Like any skill, it's chosen by its description, so make sure each agent's description says what it's for.
{% endstep %}

{% step %}

#### Step 3—Search for a skill

Use the **Search Skills** field to quickly filter skills by name or capability.

Search results are scoped to the currently selected tab.
{% endstep %}

{% step %}

#### Step 4—Select the skill

Select a skill to open its configuration form.

Each skill card includes:

* Skill name
* Capability summary
* Skill type
* Author or provider attribution

The configuration experience varies depending on the selected skill type.
{% endstep %}

{% step %}

#### Step 5—Configure and save

Configure the selected skill based on its runtime requirements.

Examples:

| Skill                        | What you configure                                                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| API Call                     | URL, method, authorization, headers, query parameters, and input and output schemas. API Call Advanced adds a request body |
| JavaScript Code, Python Code | Name, description, timeout, code, and input and output schemas                                                             |
| MCP Server                   | Connection name and remote server URL, with optional OAuth client credentials and headers                                  |
| Web Crawler                  | A Firecrawl MCP connection. Add your Firecrawl API key, or a `$secret` reference to it, to the pre-filled URL              |
| Agent                        | Agent selection and invocation configuration                                                                               |

For every Skill Library skill, see [Skill Library](/ai-workbench-qore/platform-resources/skill-library#what-each-skill-asks-for).

Secrets and variables can be referenced dynamically using:

* `$secret.{name}`
* `$agent.{name}`

This enables reusable and secure runtime configuration.
{% endstep %}
{% endstepper %}

### What happens after adding a skill

{% hint style="info" %}
Once saved, the skill becomes available to the agent during runtime execution.

The agent planner can now decide when to invoke the skill based on the incoming user request and the agent instructions.

The Builder Canvas and Agent Config views are also updated to reflect the newly attached capability.
{% endhint %}

### Common issues and troubleshooting

#### The agent does not use the skill

Possible causes:

* The agent instructions do not describe when the skill should be used
* The skill description is too generic or unclear
* Another skill is being prioritized by the planner

Improving the skill description and refining agent instructions usually resolves this.

#### The skill fails during runtime

Check:

* Authentication and credentials
* Endpoint configuration
* MCP server availability
* Runtime syntax or dependency errors

Use Monitoring and execution traces to inspect failures in detail.

#### An MCP server won't connect

* **It fails at Next on an OAuth server:** the server may not support dynamic client registration. Enter the **OAuth Client ID** from its OAuth app under **Advanced Settings**.
* **The sign-in pop-up didn't open:** select **Connect to Authorize**.
* **Every tool call fails as unauthorised:** the server may expect client credentials. 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).

#### The required skill cannot be found

Try switching to the **All** tab to search across every source.

If the capability does not exist yet, create it through **Custom Skills** or connect it via MCP integrations.

### Why skills matter

{% hint style="info" %}
Skills are the operational layer of the agent runtime.

Without skills, agents can only generate responses. With skills, agents can execute workflows, retrieve live data, interact with systems, automate tasks, and orchestrate multi-step business actions.

The most effective agents combine:

* Strong knowledge sources
* Well-defined instructions
* Carefully selected runtime skills

This combination enables agents to move beyond conversational responses into real operational execution.
{% endhint %}

***

{% 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 %}


# Skills & Capabilities

{% hint style="info" %}
**Skill & Capabilities** lists the agent's pre-attached skills, the built-in skills every agent has, and lets you choose which ones the agent uses. Skills from other sources, such as Skill Library skills, sub-agents, flows, integrations, and MCP servers, appear on the canvas's **Skills** card instead. See [Where other skills appear](#adding-skills-to-this-list).
{% endhint %}

> Agent Config → Skill & Capabilities, listing the agent's pre-attached skills

Reach this page from **Agent Config → Skill & Capabilities** in the left navigation.

The page is headed **Pre-attached Skills**, with the number of skills, and says "Enable the skills your agent uses to take actions, access data, and complete tasks." It has two lists:

* **Active Skills** — the skills the agent can use now. Each has an **Actions** menu.
* **Skills you can add** — the rest. Select **Enable** to make one active.

### The skill list <a href="#the-skill-list" id="the-skill-list"></a>

Each row shows:

* The skill's icon (varies by type)
* The skill's name (example **Show Message**)
* A one-line description of what the skill does
* An **Actions** menu, for an active skill, or an **Enable** button, for a skill you can add

### Built-in skills <a href="#platform-supplied-pre-attached-skills" id="platform-supplied-pre-attached-skills"></a>

Every agent has the same 26 pre-attached skills: 15 **General** skills and 11 **Document** skills. The General skills you will use most:

| Skill                   | What it does                                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| **Show Message**        | Shows the user a message in markdown. Best for quick updates or progress messages, not for final answers. |
| **AI Reasoning**        | Uses AI to think through complex topics, make decisions, or generate summaries.                           |
| **Web Search**          | Runs a web search through the language model to retrieve up-to-date information.                          |
| **Knowledge Search**    | Searches the knowledge connected to the agent for relevant answers or references.                         |
| **View Uploaded Files** | Lists the files uploaded in the current session, with their names, details, and upload times.             |

For every built-in skill, see [General skills](/ai-workbench-qore/platform-resources/skill-library/general-skills) and [Document skills](/ai-workbench-qore/platform-resources/skill-library/document-skills).

### The row's `⋮` menu <a href="#the-rows-menu" id="the-rows-menu"></a>

The kebab menu on each row exposes the actions available for that skill — open it on any row to see them.

### Where other skills appear <a href="#adding-skills-to-this-list" id="adding-skills-to-this-list"></a>

This page shows only pre-attached skills. Skills you add from the other tabs of [Add Skill](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent), such as Skill Library skills, custom skills, flows, and other agents, and skills registered by connecting an integration or an [MCP server](/ai-workbench-qore/console/agent-builder/build/mcp-tools), appear in the **Skills** card on the Builder Canvas. The card's count includes them. Select the card's **View all&#x20;*****N*****&#x20;Skills** link, where *N* is the count, to see the full list.

### How skills relate to the canvas <a href="#how-skills-relate-to-the-canvas" id="how-skills-relate-to-the-canvas"></a>

The Builder Canvas has a **Skills** card, connected to the agent node. It shows:

* The total number of skills on the agent, from every source.
* The first few skills, each with its type, such as **System Skill** or **Agent**, and its status, such as **Active**.
* A **View all&#x20;*****N*****&#x20;Skills** link to the full list.
* **Add Skills**, which opens [Add Skill](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).

Use this page to choose which pre-attached skills are active. Use the canvas card to see everything the agent can use.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

{% hint style="info" %}
This list is the planner's universe. When a user sends the agent a request, the platform's planner reads the instructions, considers the input, and picks one or more skills from this list to execute. A skill that isn't in the list cannot be used, no matter what the instructions say. A skill in the list whose description doesn't match the kinds of requests users send won't be picked, no matter how capable it is. Auditing this list — does every skill the agent needs appear? does every skill that appears earn its keep? — is the single highest-value review you can do when an agent isn't behaving as expected.
{% endhint %}

***

{% 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 %}


# MCP Tools

{% hint style="info" %}
**MCP Tools** ("Connect custom systems that provide actions your app or agent can use") is the catalog of Model Context Protocol servers the platform makes available to your agent. Each entry is a server that exposes a set of related tools. Connecting a server creates an **MCP connection** for this agent, and the tools you enable become available to the agent at run time. For how MCP works across Qore, see [MCP](/ai-workbench-qore/core-concepts/mcp).
{% endhint %}

> Agent Config → MCP Tools catalog

Reach this page from **Agent Config → Integration Tools & Connectors → MCP Tools** in the left navigation.

### The catalog <a href="#the-catalog-structure" id="the-catalog-structure"></a>

The page lists MCP servers grouped by **category**. Use **Search MCP tools…** to find a server by name.

The same catalog appears in the **MCP Marketplace** tab of [Add Skill](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent). It holds these servers:

| Category                             | Server                           | What it provides                                                                                                                                                      | You enter   |
| ------------------------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Analytics/Warehouses/BI              | **CoinAPI Market Data API**      | Real-time and historical market data: normalized trades, order books, OHLCV, and tick-level history, across multiple exchanges                                        | **Api Key** |
| Analytics/Warehouses/BI              | **Finfeed Stock API**            | T+1 raw stock market data from IEX, Euronext, and more than 20 other stock exchanges, through a REST API                                                              | **Api Key** |
| Analytics/Warehouses/BI              | **Finfeed SEC API**              | Clean, structured, and timely SEC filing data, through a REST API                                                                                                     | **Api Key** |
| Analytics/Warehouses/BI              | **Alpha Vantage API**            | Real-time and historical financial market data, including stocks, forex, crypto, and economic indicators                                                              | **Api Key** |
| Finance & Banking                    | **Core Banking Sandbox API**     | Sandbox banking for testing and integration: account management, customer onboarding, transaction history, balance inquiries, fund transfers, and payment simulations | **Token**   |
| General Search & Knowledge Retrieval | **Tavily**                       | Tavily's search and data extraction, for AI assistants, over the Model Context Protocol                                                                               | **Api Key** |
| General Search & Knowledge Retrieval | **AWS Knowledge Base Retrieval** | Retrieval from an AWS Knowledge Base through the Bedrock Agent Runtime, for retrieval-augmented generation                                                            | Nothing     |
| Web, Browsing & Scraping             | **Firecrawl**                    | Web scraping, crawling, and search for content extraction                                                                                                             | **Api Key** |

{% hint style="warning" %}
**Core Banking Sandbox API returns simulated data.** Use it to build and test an agent, not to reach a real core banking system.
{% endhint %}

To connect a server that isn't in the catalog, use the **MCP Server** skill in the [Skill Library](/ai-workbench-qore/platform-resources/skill-library). It opens the same form, blank.

### Connecting an MCP server <a href="#connecting-an-mcp-server" id="connecting-an-mcp-server"></a>

Select a server to open **Create MCP Connection**. It runs in up to three steps.

{% stepper %}
{% step %}

#### Enter the connection

The form opens with a warning: *This connector hasn't been officially verified by UPTIQ. Make sure you trust it before using it, as you'll be responsible for any actions it performs.* It appears for catalog servers too.

| Field                     | What to enter                                                                                        |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Connection Name**       | Required. Filled in with the server's name                                                           |
| **Remote MCP Server URL** | Required. Filled in with the server's URL                                                            |
| **Api Key** or **Token**  | Required, for servers that need one. See [How catalog fields are used](#how-catalog-fields-are-used) |
| **Advanced Settings**     | Optional. How Qore signs in to the server. See [Advanced Settings](#advanced-settings)               |

To fill the form from a file instead, select **Import Config File**. Then select **Next**. Qore connects to the server to check it.
{% endstep %}

{% step %}

#### Authorize, if the server asks

If the server needs an OAuth sign-in and Qore has no token for it, **Waiting for Authorization** appears and a pop-up opens with the server's sign-in page. Sign in and grant the requested permissions; the dialog continues by itself once you're authorized.

* **Connect to Authorize** opens the pop-up again, for example if your browser blocked it.
* **Cancel** returns to the first step.

Qore skips this step for connections that use M2M, and for server URLs ending in `/sse`.
{% endstep %}

{% step %}

#### Choose tools and settings

**Tools and Settings** lists the server's tools, with a count such as `5 of 5 tools enabled`. Every tool starts enabled, set to **Always Ask Permissions**.

* **Enable All Tools** turns every tool on or off at once. The menu beside it sets the supervision mode for every tool.
* Each tool has its own switch, and its own supervision mode: **Always Ask Permissions** or **Allow Unsupervised**.
* Select the pencil beside a tool's description to rewrite it, then **Save**.
* A warning icon marks a tool whose input schema is invalid: *This tool has an invalid input schema which might not work for all models.*

Select **Create Connection**.
{% endstep %}
{% endstepper %}

#### How catalog fields are used <a href="#how-catalog-fields-are-used" id="how-catalog-fields-are-used"></a>

A catalog server's URL can hold a placeholder, such as `?apikey={{api_key}}`. Qore replaces it with what you enter in **Api Key**, and saves the URL with the value in it. **Core Banking Sandbox API** instead sends its **Token** as an `Authorization: Bearer` header.

{% hint style="warning" %}
**Enter a secret reference, not the key.** [Connectors](/ai-workbench-qore/control-center/govern/connectors) in Control Center shows each connection's URL in full, so a key typed into **Api Key** can be read there. Store the key on [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) and enter its reference, such as `$secret.TAVILY_API_KEY`. The saved URL then holds the reference, and Qore resolves it when the agent runs.
{% endhint %}

#### Import Config File <a href="#import-config-file" id="import-config-file"></a>

**Import Config File** takes a JSON file in the format MCP clients use, with an `mcpServers` object. Qore reads the first server in it:

* its key, as **Connection Name**
* `url`, as **Remote MCP Server URL**
* `headers`, as **Headers**
* `env.CLIENT_ID` and `env.CLIENT_SECRET`, as **OAuth Client ID** and **OAuth Client Secret**

A file without an `mcpServers` object is refused with *Invalid config file: Missing or invalid "mcpServers" configuration*.

### Advanced Settings <a href="#advanced-settings" id="advanced-settings"></a>

**Advanced Settings** holds the credentials Qore presents to the MCP server. Choose by how the server authenticates.

| Setting                                         | What it's for                                                                                                                                                                                                                                                                    |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Register this Redirect URL**                  | For a server that signs people in through OAuth. Copy the URL and, *when creating an OAuth app on your MCP server, add this URL as an allowed redirect URI.* Shown when the agent's executor version supports it and M2M is off.                                                 |
| **OAuth Client ID** and **OAuth Client Secret** | Optional for an OAuth sign-in. If the server's authorization service supports dynamic client registration, Qore registers itself and you can leave them empty. If it doesn't, enter the client ID from the server's OAuth app, or the connection fails. Required when M2M is on. |
| **Authenticate M2M (OAuth client credentials)** | For a server that issues a client ID and secret instead of a sign-in page. See [Connect with client credentials](#connect-with-client-credentials).                                                                                                                              |
| **Headers**                                     | Key and value pairs sent with every request to the server. Select **Add Entry** for each one.                                                                                                                                                                                    |

**References in the form.** `$secret.<name>` and `$agent.<name>` resolve to the agent's [secrets and variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) anywhere in the connection, including the URL and headers. When the agent has [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) turned on, `$auth.token` is also offered in **Api Key**, **OAuth Client ID**, **OAuth Client Secret** and **Headers**; it resolves to the verified token of the person calling the agent.

#### Connect a server with machine credentials (OAuth client credentials) <a href="#connect-with-client-credentials" id="connect-with-client-credentials"></a>

Some MCP servers, often ones hosted by your company or a vendor behind Microsoft Entra ID, Okta, Auth0 or Keycloak, don't show a sign-in page. Instead they issue a client ID and client secret up front, by email, portal or IT ticket, and expect the caller to exchange them for a token. This is the OAuth 2.0 **client credentials** grant, also called machine-to-machine (M2M). The agent authenticates as itself, not as a person.

{% stepper %}
{% step %}

#### Open the connection form

Select the server in the catalog, or choose **MCP Server** in the Skill Library. Enter the server's name and URL.
{% endstep %}

{% step %}

#### Turn on M2M

Expand **Advanced Settings** and select **Authenticate M2M (OAuth client credentials)**.
{% endstep %}

{% step %}

#### Enter the credentials

* **Token URL** — required. The OAuth 2.0 token endpoint your provider gave you.
* **Scope (Optional)** — some providers require it. For Microsoft Entra ID it usually looks like `api://<resource-app-id>/.default`.
* **OAuth Client ID** and **OAuth Client Secret** — both required when M2M is on.
  {% endstep %}

{% step %}

#### Continue

Select **Next**. There's no authorization step: the agent requests its own token each time it connects. Choose the tools, then **Create Connection**.
{% endstep %}
{% endstepper %}

With M2M on, the form hides the Redirect URL, because this grant never redirects anyone. If Token URL, client ID or client secret is missing, the form says which one, for example *Token URL is required for the client credentials grant*, and doesn't continue.

If a server expects client credentials and you connect it without M2M, the connection can look successful while every tool call fails as unauthorised. Turn M2M on and reconnect.

### Managing a connection <a href="#managing-a-connection" id="managing-a-connection"></a>

Open an existing connection to see **MCP Server Connection**: the connection's name and URL, and under **Tools and Settings**, its enabled tools with a count such as `4 tools enabled` and a search box.

| Action                       | What it does                                                                                                                                                                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect** / **Disconnect** | Turns the connection on or off. Disconnecting asks first: *Disconnecting will stop all ongoing sessions using this MCP server.*                                                                                                                    |
| **Remove**                   | After a confirmation, permanently removes the MCP server from the agent.                                                                                                                                                                           |
| **Initialize**               | Shown instead of Connect when the connection has no credentials yet, such as one imported without its MCP configuration. Reopens Create MCP Connection with the name and URL filled in.                                                            |
| Edit (pencil)                | Reopens Create MCP Connection with the saved name, URL, client ID, headers and M2M settings filled in.                                                                                                                                             |
| **Manage Tools**             | Opens **Manage Tools and Settings**: turn tools on or off with **Enable All** or each switch, change supervision modes, rewrite descriptions, and select **Refresh tools** to fetch the server's current list. Then **Save Changes**, or **Back**. |

{% hint style="info" %}
**Re-enter the client secret when you edit.** The secret isn't shown again after saving, so editing a connection that uses one means typing it again.
{% endhint %}

### Exporting and importing <a href="#exporting-and-importing" id="exporting-and-importing"></a>

[Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent) always includes the agent's MCP connections. **Include MCP configuration**, off by default, decides whether their OAuth client ID and secret, headers and tokens go too. Connections exported without it arrive in the other environment needing **Initialize**.

### Where connected MCPs show up <a href="#where-connected-mcps-show-up" id="where-connected-mcps-show-up"></a>

* **The canvas:** each connection appears as a node in the Skills band, labelled with the connection's name.
* [Skills & Capabilities](/ai-workbench-qore/console/agent-builder/build/skills-and-capabilities): the server's enabled tools.
* [Connectors](/ai-workbench-qore/control-center/govern/connectors) › **MCP Servers**, in Control Center: one row per connection in the account, with its project and the agent that uses it.

### MCP Tools compared to Apps & Services <a href="#mcp-tools-compared-to-apps-and-services" id="mcp-tools-compared-to-apps-and-services"></a>

Both add outside capability to the agent, and the catalogs overlap.

* [Apps & Services](/ai-workbench-qore/console/agent-builder/build/apps-and-services) lists SaaS connectors, such as Stripe, Resend and Twilio, connected through the Integrations Hub.
* MCP Tools lists MCP servers, such as market-data, web-scraping and knowledge-retrieval services. The **MCP Server** skill reaches any other MCP server by URL.
* For an HTTP endpoint that isn't an MCP server, use the [API Call](/ai-workbench-qore/platform-resources/skill-library/api-call) skill.

***

{% 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 %}


# Apps & Services

**Apps & Services** is the catalog of pre-built integrations with third-party SaaS products — email senders, payment processors, messaging platforms, and similar. Each entry in the catalog is a ready-to-connect integration: the platform supplies the connector, you supply the credentials, and the agent gains the ability to take actions in that service through skills the connector exposes. Use this page to give the agent reach into systems your business already runs on, rather than authoring an API Call skill from scratch.

Agent Config → Apps & Services catalog

Reach this page from **Agent Config → Integration Tools & Connectors → Apps & Services** in the left navigation.

### The catalog <a href="#the-catalog" id="the-catalog"></a>

The right pane lists the available integrations. Each row carries:

* The service's logo
* The service's name (for example, `Resend Email`, `Stripe`, `Twilio WhatsApp`)
* A one-line description of what connecting will let the agent do
* A `Connect` button revealed on hover, on the far right

The catalog is large and varies by organization — use the search box at the top right of the pane (`Search integrations…`) to find a specific service quickly.

> **Note** The `Connect` button is hidden until you hover over the row. On touch devices without hover, the row itself may need to be tapped to reveal the button. This is worth knowing if you can't find an obvious affordance for adding an integration.

### Connecting an integration <a href="#connecting-an-integration" id="connecting-an-integration"></a>

Hover the row and click **Connect**. The platform initiates the integration flow for that service — typically an OAuth handshake, sometimes a credentials form. Once authorized, the integration becomes available to the agent through whatever skill or capability that connector exposes (some connectors register one skill; some register several).

{% hint style="info" %}
What happens after you select **Connect** depends on the service — some open an OAuth consent screen, others ask for credentials in a form. Follow the prompts for that service; see [How to connect an integration](/ai-workbench-qore/task-guides/how-to-connect-an-integration).
{% endhint %}

### Where connected integrations show up <a href="#where-connected-integrations-show-up" id="where-connected-integrations-show-up"></a>

After connecting an integration, you'll see effects in three places:

* **The Layout canvas** — the integration may appear as a new node in the Skills band, similar to the MCP connector discs.
* **Skills & Capabilities** — the skill (or skills) the integration registers will show in the agent's skill list.
* **The agent's responses** — at runtime, the agent can invoke the connected service through the registered skill.

### Apps & Services compared to MCP Tools <a href="#apps-and-services-compared-to-mcp-tools" id="apps-and-services-compared-to-mcp-tools"></a>

Both **Apps & Services** and **MCP Tools** add external capability to the agent. The distinction:

* **Apps & Services** catalogs pre-built integrations with SaaS products. The connector is supplied by the platform; you supply credentials.
* **MCP Tools** catalogs Model Context Protocol servers — a more general protocol for connecting external tools. Some entries in the MCP catalog are also SaaS connectors; others are data APIs (CoinAPI, Alpha Vantage), search APIs (Tavily), or knowledge-base retrieval (AWS Knowledge Base).

When the action you want to give the agent involves a recognized SaaS product (sending email through Resend, charging through Stripe), check Apps & Services first. When it involves a data API or a more generic tool, MCP Tools is the right catalog.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

Most useful agents need to reach beyond text generation — to send a confirmation email, to log a record in a system of truth, to query a live data source, to message a user on a different channel. Apps & Services makes that reach a configuration step rather than a coding step. Every integration you connect here is one less skill you'd otherwise author yourself, and one less custom auth flow you'd otherwise maintain. The trade-off is that the catalog covers what the catalog covers — for services not in the catalog, the API Call skill type remains the general-purpose escape hatch.

***

{% 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 %}


# Attaching Knowledge to an Agent

Attaching knowledge allows an agent to reference your organization’s documents, files, and external content during runtime. Instead of responding only from general model training, the agent can retrieve information directly from approved knowledge sources to generate more accurate, contextual, and business-specific responses.

Knowledge can be sourced from uploaded files or connected platforms such as Google Drive, Microsoft OneDrive, and Microsoft SharePoint. Once attached, the content becomes available to the agent through the platform’s knowledge retrieval capabilities.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FJzbxSj1NbYtuq1ARHHim%2Fimage.png?alt=media&amp;token=b0b047c8-1581-40ef-b6c7-5503b19bba0b" alt=""><figcaption></figcaption></figure>

***

### What This Enables

With attached knowledge, agents can:

* Answer questions using internal business documents
* Reference policies, guidelines, or product documentation
* Retrieve context from uploaded files and connected repositories
* Deliver more consistent and traceable responses
* Reduce reliance on generic model knowledge

This transforms the agent from a general AI assistant into a domain-aware business agent grounded in your organization’s data.

***

### Before You Begin

Before attaching knowledge, ensure that:

* You have the source content ready for upload or import
* Each file is within the upload size limit for this screen — **10 MB**. Larger files can be added in [Datasets](/ai-workbench-qore/console/knowledge/datasets), which accepts up to 15 MB per file
* Required integrations such as Google Drive, OneDrive, or SharePoint are already connected
* You understand whether preprocessing is required for your content type

Typical supported content includes:

* PDFs
* Documents
* Spreadsheets
* Policy files
* Structured business reference material

***

### How to Attach Knowledge

#### 1. Open the Builder Canvas

From the Agent Builder canvas, select **+ Add Knowledge** within the Knowledge section above the agent node. This opens the **Attach Knowledge** workflow.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-c68ee30174226cfe734331025cf13408ad831f09%2Fqore_agent-builder_studio-agent-builder-attach-agent-canvas-attach-knowledge_rounded_shadow.png?alt=media" alt="The Builder Canvas, with the + Add Knowledge button in the Knowledge section above the agent node"><figcaption><p>Opening the Attach Knowledge workflow from the canvas.</p></figcaption></figure>

***

#### 2. Select a Knowledge Category

Choose the category that best matches the content being attached. Categories help organize knowledge sources and improve downstream retrieval behavior.

Examples include:

* General Documentation
* Financial Services
* Policies & Compliance
* Underwriting Guidelines
* Healthcare
* Legal
* Insurance
* Manufacturing

If no category is an exact match, select the closest applicable category or use a general-purpose option.

***

#### 3. Import or Upload Content

Knowledge can be added through connected integrations or direct upload.

Available import options include:

* Google Drive
* Microsoft OneDrive
* Microsoft SharePoint

You can also drag and drop files directly into the upload area for local uploads.

***

#### 4. Configure the Preprocessing Pipeline

The **Preprocessing Pipeline** determines how the platform prepares content before indexing.

When enabled, the platform can perform:

* Intelligent document chunking
* OCR for scanned PDFs
* Layout-aware extraction
* Table and structured data parsing

**Recommended Usage**

| Content Type                        | Recommendation                       |
| ----------------------------------- | ------------------------------------ |
| Clean text-based documents          | Leave preprocessing disabled         |
| Scanned PDFs                        | Enable preprocessing                 |
| Table-heavy or structured documents | Enable preprocessing                 |
| Retrieval quality issues            | Re-import with preprocessing enabled |

***

#### 5. Complete the Attachment

Once at least one file has been imported or uploaded, select **Done** to attach the knowledge source to the agent.

The knowledge source then appears as a node within the Knowledge section of the Builder Canvas.

***

### Build knowledge from the Agent Builder chat <a href="#build-knowledge-from-the-agent-builder-chat" id="build-knowledge-from-the-agent-builder-chat"></a>

The agent that builds your agent in the Agent Builder chat now has knowledge skills that follow the Knowledge Builder's process. You can set up the agent's knowledge in the same conversation where you build the agent, without switching to **Knowledge**. To find knowledge the account already has, ask the builder about it in your own words, for example *"Do we have anything on our 2026 fee schedule?"* The builder searches the account's knowledge and tells you what it found. Then ask it to attach that knowledge to the agent, and it's added to the agent as a new knowledge source, from the chat alone.

The builder can:

* **Reuse what exists.** List the account's knowledge bases and datasets, and see which knowledge the agent already has, so it reuses an existing one instead of creating a duplicate.
* **Create and organize.** Create a knowledge base or a dataset, and rename a knowledge base or rewrite its description.
* **Add files.** Add the files you attach to the chat to a dataset, list a dataset's files, and tell you why a file failed to process.
* **Make files searchable.** Sync a dataset into a knowledge base. This runs in the background, and the builder reports the result for each dataset. A dataset whose files are still processing has to wait.
* **Connect knowledge to the agent.** Attach an existing knowledge base to the agent, or detach it.
* **Add flash knowledge.** Put attached files straight into the agent's context on every run. They're usable at once, with no dataset and no wait. Use this for a few small reference files, not a large set of documents.

Some of these changes reach beyond the agent you're building:

* **Detaching** a knowledge base only removes it from this agent. The knowledge base, its datasets, and its files stay available to every other agent that uses them.
* **Deleting** a file from a dataset, or deleting a knowledge base, affects every agent that uses it. The builder asks you to confirm the item by name first.

The builder adds files that you attach to the chat.

***

### Attaching a governed graph <a href="#attaching-a-governed-graph" id="attaching-a-governed-graph"></a>

A [governed graph](/ai-workbench-qore/control-center/govern/governed-graph) is an institution's knowledge graph, uploaded in **Control Center → Govern → Governed Graph**. Once the upload completes, the graph becomes knowledge in the account, and you attach it to the agent like any existing knowledge.

{% stepper %}
{% step %}

#### Open Use Existing Knowledge

On the Builder Canvas, select **+ Add Knowledge** in the Knowledge section. The **Use Existing Knowledge** dialog opens on its **Knowledge** tab.
{% endstep %}

{% step %}

#### Select the graph

Find the graph by name, using **Search knowledge** if the list is long, and tick it. Pick the entry marked **Completed**: a graph whose upload failed is listed too, with **Failed**, but holds no data. Knowledge already attached to the agent isn't listed.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-74e47dbcea0744f3258962c72be8e6abc974def9%2Fqore_agent-builder_use-existing-knowledge-governed-graph_rounded_shadow.png?alt=media" alt="The Use Existing Knowledge dialog on the Knowledge tab, listing CCU Governed Graph as Completed above failed entries, with a search box, a Create Knowledge button and the Add button"><figcaption><p>Selecting a completed governed graph.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Add it

Select **Add**. The graph appears in the canvas's Knowledge section as a **Knowledge Store** node marked **Active**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a5a8ad82eea9d7d7f4b0227dcf776a57256ddbcb%2Fqore_agent-builder_canvas-governed-graph-attached_rounded_shadow.png?alt=media" alt="The Builder Canvas with CCU Governed Graph attached in the Knowledge section as an active Knowledge Store, connected to the agent"><figcaption><p>The governed graph attached to the agent.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

To detach it, open the node's `⋯` menu and select **Unlink**.

* The agent queries the graph with the **Knowledge Graph Search** skill, for structured questions such as which documents a product requires, rather than searching it as text.
* Attaching the graph needs the **Attach a govern graph to an agent** capability: Developer, Account Admin or Org Admin.
* You can't create a governed graph by attaching its package JSON in the Agent Builder chat, or through the dialog's **Flash Knowledge** tab. Upload it in Control Center first.

***

### Runtime Behavior

After attachment:

* The content is indexed and made available to the agent
* The agent can retrieve relevant passages during conversations
* Responses become grounded in attached business content
* The platform uses retrieval workflows to fetch the most relevant information dynamically

If attached knowledge does not sufficiently answer a query, the agent can still fall back to general model reasoning or request clarification.

***

### Common Issues and Troubleshooting

#### Done Button Remains Disabled

Cause:\
No file or external content has been selected yet.

Resolution:\
Upload a file or import content from a connected source.

***

#### Agent Is Not Using Attached Knowledge

Possible reasons:

* The knowledge retrieval capability is not attached to the agent
* Agent instructions do not explicitly guide the agent to consult knowledge sources
* The uploaded content does not contain relevant information
* The file was updated but not synced. Agents answer from the latest synced version of a knowledge base, so a new file version reaches the agent only once it shows **Synced**. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions)

Recommended checks:

* Verify the knowledge retrieval skill is enabled
* Review agent instructions and retrieval behavior
* Validate the uploaded source content

***

#### Retrieval Quality Is Poor

For scanned or complex documents:

* Re-import the content with preprocessing enabled
* Ensure the source document is readable and structured properly
* Avoid low-quality scans where possible

Preprocessing generally improves retrieval accuracy for OCR-heavy and layout-complex documents.

***

### Why Knowledge Attachment Matters

Knowledge attachment is foundational to building reliable enterprise agents.

It enables:

* Business-grounded responses
* Consistent answers across users
* Reduced hallucination risk
* Better compliance and traceability
* Domain-specific intelligence

Instead of relying solely on generalized training data, the agent retrieves information from approved organizational sources, making outputs more trustworthy, explainable, and operationally useful.

***

{% 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 %}


# Triggers

{% hint style="info" %}
**Triggers** are the events that cause the agent to run. Each trigger is a named condition — described in prose — that the platform watches for; when the condition is met, the agent is invoked with that trigger's context. Triggers are how an agent moves from a passive chatbot (answering when asked) into an active automation (running on its own when something noteworthy happens in the host application).
{% endhint %}

> Agent Config → Triggers list

Reach this page from **Agent Config → Triggers** in the left navigation. It's titled **Agent Triggers**: "Control what events trigger your agent to run." An agent with no triggers shows **No triggers created** and an **Add New Trigger** button.

{% hint style="info" %}
**Agent triggers aren't flow triggers.** These triggers start an agent. A flow has its own triggers, set in the flow builder. See [Flows](/ai-workbench-qore/console/flows/build-a-flow#choose-a-trigger).
{% endhint %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-7d082459201093a48add653939e79b851b555495%2Fqore_agent-builder_studio-agent-builder-attach-agent-canvas-add-triggers_rounded_shadow.png?alt=media" alt="The Builder Canvas, with the Triggers chip showing the configured trigger count"><figcaption><p>The Triggers chip on the Builder Canvas.</p></figcaption></figure>

### The trigger list <a href="#the-trigger-list" id="the-trigger-list"></a>

The right pane shows every trigger configured on the agent. Each row carries:

* A trigger icon
* The trigger's name
* A type pill, such as **Schedule**
* A truncated description of the condition
* A `⋮` overflow menu on the right

<details>

<summary>Expanded trigger editor</summary>

**Note** The expanded trigger editor — reached by clicking a row — opens a wider modal with a list pane on the left and an editable detail pane on the right. The wider modal also exposes a **`+ Add New Trigger`** action that's not present in the inline view. The creating a trigger page walks through that flow.

</details>

### Trigger types <a href="#trigger-types" id="trigger-types"></a>

Each trigger has a **Trigger Source** — the type of event that fires it. The Trigger Source is a required field on the trigger detail form. Triggers belong to the agent. The canvas's **Triggers** card lists them with their type, such as **Schedule**.

{% hint style="info" %}
The sources available in the dropdown depend on how the agent is set up. If the source you expect is not listed, check the agent's configuration with your platform administrator.
{% endhint %}

### What's in a trigger <a href="#whats-in-a-trigger" id="whats-in-a-trigger"></a>

A trigger is the combination of three things:

| Field          | Obligation | Notes                                                                                                                                           |
| -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Trigger Source | Mandatory  | What causes the trigger to fire. The sources available depend on the agent's setup.                                                             |
| Trigger Name   | Mandatory  | A unique identifier. The platform treats this as the trigger's primary key.                                                                     |
| Description    | Mandatory  | Prose that explains when the trigger fires. **This is read by the planner at runtime to decide whether the trigger matches an incoming event.** |

{% hint style="warning" %}
The Description field carries most of the weight. The platform does not parse the description as a rules expression — it is fed to a language model that decides whether an incoming event matches the description. This means:

* **Anchor conditions to specific values.** "When the business's cash reserves fall below 15% of the average monthly operating cost" is interpretable. "When cash is low" is not.
* **Avoid qualitative judgments.** "When something concerning happens" matches everything; "when a transaction exceeds the historical average for that category by 50% or more" matches the specific event you want.
* **One condition per trigger.** A trigger with three or-conditions is harder for the runtime to match cleanly than three triggers with one condition each. Multiple triggers also give you finer control over what happens after each one fires.
  {% endhint %}

### Editing or removing a trigger <a href="#editing-or-removing-a-trigger" id="editing-or-removing-a-trigger"></a>

{% hint style="info" %}
Click any row to open the detail editor (the **Custom Trigger** panel on the right of the expanded modal). The detail editor lets you change the Trigger Source, the name, and the description, then save with **Update Trigger** or discard with **Cancel**.

The row's `⋮` menu surfaces per-row actions (likely duplicate / delete / inspect).
{% endhint %}

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

{% hint style="info" %}
A well-authored trigger is the difference between an agent that runs *when it should* and one that runs *when something vaguely related happens*. Because the description is interpreted by a model at runtime, vague language produces unreliable firing — false positives in some weeks, false negatives in others, with no obvious pattern. Spend the time to anchor each trigger description to concrete, measurable conditions. The downstream consequence is an agent whose alerts can be trusted, which is the whole point of triggering an agent rather than scheduling it.
{% endhint %}

***

{% 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 %}


# Secrets & Variables

Manage encrypted secrets and runtime variables used throughout your agent.

**Secrets & Variables** is the agent's keychain and configuration store. The page holds two parallel tables: **Secrets** (API keys, tokens, credentials — encrypted when **Secured** is on) and **Variables** (general-purpose values like base URLs, IDs, default parameters — stored in clear). Everywhere else in the builder that needs a value the agent will resolve at runtime — a skill's API endpoint, a credential in an instruction, an integration's auth header — references the value from this page through a `$secret.` or `$agent.` reference rather than pasting the value inline. Reach this page from **Agent Config → Secrets & Variables** in the left navigation.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-b5ae29009dd5f1842074b367d8b84e6276479be2%2Fqore_agent-builder_manage-agent-secrets-and-variables_rounded_shadow.png?alt=media" alt="The Secrets and Variables page in Agent Config, with the Secrets table and its Text or JSON type menu open, the Variables table, and the Built-in section"><figcaption><p>Secrets &#x26; Variables.</p></figcaption></figure>

### Secrets <a href="#secrets" id="secrets"></a>

Secrets hold sensitive values. Turn on **Secured** to store a secret in encrypted format. Leave it on for any value that would be a problem if it leaked.

> Store API keys and sensitive credentials.

**Usage syntax:** `$secret.{variable_name}` — for example, `$secret.API_URL`, `$secret.STRIPE_SECRET_KEY`.

Reference a secret by its `$secret.{name}` form anywhere the platform accepts dynamic values: skill configurations, trigger descriptions, instructions, integration settings.

<table><thead><tr><th width="229.99993896484375">Field</th><th>What it holds</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>The identifier you reference. Becomes <code>$secret.{name}</code>.</td></tr><tr><td><strong>Type</strong></td><td><strong>Text</strong> or <strong>JSON</strong>. A Text value can't contain spaces; a JSON value must be valid JSON.</td></tr><tr><td><strong>Value</strong></td><td>The secret's value.</td></tr><tr><td><strong>Secured</strong></td><td>When ticked, the value is stored encrypted and shows as <code>******</code> after you save. Off by default, so tick it for anything sensitive.</td></tr></tbody></table>

To add a secret, select **+ Add Secret**, fill in the row, and select **Save**.

A secret's name can't be changed once it's saved; delete the row and add it again under the new name. A secured value can't be edited in place either. To change one, untick **Secured** (this clears the value), enter the new value, tick **Secured** again, and save.

### Variables <a href="#variables" id="variables"></a>

Variables are non-sensitive values that change between environments or use cases, but don't need encryption.

> Store general purpose variables for execution context.

**Usage syntax:** `$agent.{variable_name}` — for example, `$agent.BASE_URL`, `$agent.DEFAULT_REGION`.

<table><thead><tr><th width="225.20001220703125">Field</th><th>What it holds</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>The identifier you reference. Becomes <code>$agent.{name}</code>.</td></tr><tr><td><strong>Description</strong></td><td>A short note on what the variable is for. Useful when another team member opens the agent later.</td></tr><tr><td><strong>Default Value</strong></td><td>The variable's stored value. It can be left empty.</td></tr></tbody></table>

To add a variable, select **+ Add Variable**.

Select **Save** to keep your changes to either table.

### Rules for both tables <a href="#obligation-across-the-two-tables" id="obligation-across-the-two-tables"></a>

| Field                  | Obligation | Notes                                                  |
| ---------------------- | ---------- | ------------------------------------------------------ |
| Secret Name            | Mandatory  | See the naming rules below.                            |
| Secret Type            | Mandatory  | **Text** (no spaces) or **JSON** (must be valid JSON). |
| Secret Value           | Mandatory  |                                                        |
| Secret Secured         | Optional   | Off by default. Tick it for anything sensitive.        |
| Variable Name          | Mandatory  | See the naming rules below.                            |
| Variable Description   | Optional   | Recommended.                                           |
| Variable Default Value | Optional   |                                                        |

**Naming rules.** A name starts with a letter or an underscore and contains only letters, numbers and underscores, so no spaces. Two secrets, or two variables, can't share a name.

### When to use a secret versus a variable <a href="#when-to-use-a-secret-versus-a-variable" id="when-to-use-a-secret-versus-a-variable"></a>

{% columns %}
{% column %}
Use a **secret** for anything that would be a problem if it leaked: API keys, OAuth client secrets, database passwords, internal endpoints not meant for public exposure.
{% endcolumn %}

{% column %}
Use a **variable** for anything that's safe to expose but useful to centralize: base URLs that differ between staging and production, default region or locale codes, identifiers that other parts of the agent reference repeatedly.
{% endcolumn %}
{% endcolumns %}

A useful rule: if you'd hesitate to paste the value into a public Slack channel, it belongs in Secrets. If you wouldn't hesitate, it belongs in Variables.

### How references resolve at runtime <a href="#how-references-resolve-at-runtime" id="how-references-resolve-at-runtime"></a>

When the agent runs, the platform resolves `$secret.{name}` and `$agent.{name}` references to their stored values before passing the substituted content to skills or to the model. The reference syntax stays in the *stored* configuration; only the runtime sees the resolved value.

This means:

* A skill configuration that references `$secret.STRIPE_SECRET_KEY` shows the literal `$secret.STRIPE_SECRET_KEY` in the configuration form, not the actual key.
* The same reference resolves to the real key when the skill executes.
* Updating the secret's value updates every skill that references it, immediately, without re-editing each skill.

This is the main reason secrets and variables belong on a single page rather than scattered through the skills that use them: one place to rotate a key when it changes.

### Built-in values <a href="#built-in-values" id="built-in-values"></a>

The **Built-in** section lists values the platform provides at run time. There's nothing to store for them.

* `$auth.token`: the verified caller's token, once the agent has [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) turned on. It resolves **only in MCP connection configurations**; skills don't receive it. When a request carries no token, it resolves empty.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

{% hint style="info" %}
This page is the boundary between *configuration* (what the agent's been told to do) and *credentials* (what the agent needs to actually do it). Keeping that boundary clean — every credential here, every reference elsewhere — gives you three things the alternative doesn't. First, secrets don't appear in Instructions, trigger descriptions, or skill configs that may be visible in traces or shared with other team members. Second, rotating a credential is a one-row edit rather than a scavenger hunt. Third, the same agent can be promoted across environments by changing the values here without touching anything else. Treat this page as the canonical source for anything the agent needs to authenticate or address an external system.
{% endhint %}

***

{% 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 %}


# Test

Validate the agent before anyone depends on it.

**Test** is where you find out whether the agent actually does what you intended — before it reaches real users.

Testing an agent is not like testing ordinary software. The same input can produce different output, so a single successful run proves very little. What you need is a scored dataset of representative cases, run repeatedly as you change instructions, skills, and behavior settings, so you can see whether a change improved the agent or merely moved the problem.

* [Evals](/ai-workbench-qore/console/agent-builder/test/evals) — Test the agent against scored datasets before release.

You can also exercise the agent interactively with **Try Agent** in the builder, and open the execution trace to see how it interpreted your instructions, which skills it called, and how long each step took. Use interactive testing to explore and evals to prove.

***

When the agent performs on your test cases, move on to [Deploy](/ai-workbench-qore/console/agent-builder/deploy). After release, [Monitor](/ai-workbench-qore/console/agent-builder/monitor) tells you how it behaves on traffic your test set never anticipated.

***

{% 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 %}


# Evals

Test agent responses against scored datasets with automated LLM grading.

Evals is an evaluation framework for systematically testing agent quality on the Uptiq Platform. It allows teams to create datasets of test cases — read from an uploaded document, generated by an LLM, or added manually — run those test cases against a live agent, score each response on a 0–10 scale using an LLM scorer, and receive AI-generated suggestions for improving the agent.

{% hint style="info" %}
Use [Evals](/ai-workbench-qore/console/agent-builder/test/evals) before release, [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval) after release, and [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) to carry reviewed feedback forward.
{% endhint %}

| Capability           | Description                                                                                                                  | Limit                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Dataset management   | Create, rename, delete datasets; import test cases from an uploaded document, or generate them from the agent's instructions | 100 per agent                                     |
| Test case management | Question, expected answer, optional document context and attachments                                                         | 50 per AI generation; up to 500 from one document |
| Evaluation runs      | Trigger, monitor progress in real-time, cancel, view results                                                                 | 100 per agent                                     |
| LLM scoring          | 0–10 scale with reasoning, 7+ = pass threshold                                                                               | —                                                 |
| Suggested changes    | AI-generated improvement recommendations with one-click apply                                                                | —                                                 |
| Document support     | Auto-generated DOCX/XLSX/PDF test documents with preview                                                                     | —                                                 |

Evals is accessed from the **Cognition & Control** section in the Agent Builder's **Agent Config** sidebar.

## Workflow

{% tabs %}
{% tab title="Datasets" %}
Manage [datasets](#datasets) and [test cases](#test-cases).
{% endtab %}

{% tab title="Runs" %}
View [runs](#runs), [scoring](#scoring), and [suggested changes](#suggested-changes).
{% endtab %}
{% endtabs %}

{% stepper %}
{% step %}

### Build a dataset

Create a [dataset](#datasets) from an uploaded document, generate one with AI, or add test cases manually.
{% endstep %}

{% step %}

### Run the evaluation

Execute the dataset against the live agent in [Runs](#runs).
{% endstep %}

{% step %}

### Review and improve

Inspect [scores](#scoring), review failures, and apply [suggested changes](#suggested-changes).
{% endstep %}
{% endstepper %}

***

## Datasets

A dataset is a collection of test cases for evaluating an agent. Each agent can have up to **100 datasets**.

### Generate Dataset

Select **Generate Dataset** on the **Datasets** tab. The **Add test data & cases** page opens in place of the list, in two steps.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-218581c7e546a8df60d977e4353e75104650c179%2Fqore_agent-builder_manage-agent-evals-datasets_rounded_shadow.png?alt=media" alt="The Evals page in Agent Config on the Datasets tab, listing datasets with their status, test case count and creation time, and the Generate Dataset button"><figcaption><p>The Datasets tab, with the Generate Dataset button.</p></figcaption></figure>

{% stepper %}
{% step %}

#### Test Data & Cases

Choose where the test cases come from.

{% tabs %}
{% tab title="Upload file" %}
Upload a document, and the test cases are read out of it for you. The document can list the test cases, or describe the scenarios to cover; from a description, the cases are derived from the rules and constraints it states.

* **File types:** `.pdf`, `.xlsx`, `.xls`, `.md`
* **Size:** up to 10 MB
* **Test cases:** decided by the document, up to 500

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-e49f6ef0996439358936c2b899251be6d3512e51%2Fqore_agent-builder_manage-agent-evals-upload-file_rounded_shadow.png?alt=media" alt="Step 1 of Add test data and cases, on the Upload file tab, with a drop zone that accepts pdf, xlsx, xls and md files up to 10 MB"><figcaption><p>Uploading a document of test cases.</p></figcaption></figure>
{% endtab %}

{% tab title="Generate with AI" %}
Have test cases written for you from the agent's instructions.

| Field                       | Required | Description                                    |
| --------------------------- | -------- | ---------------------------------------------- |
| **Number of Test Cases**    | Yes      | 1–50, defaults to 10                           |
| **Additional Instructions** | No       | e.g., "Focus on edge cases related to pricing" |

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-67d595647e34e9d723dc5101a39829c26183e8b6%2Fqore_agent-builder_manage-agent-evals-generate-with-ai_rounded_shadow.png?alt=media" alt="Step 1 of Add test data and cases, on the Generate with AI tab, with the Number of Test Cases and Additional Instructions fields"><figcaption><p>Generating test cases from the agent's instructions.</p></figcaption></figure>

**Generation steps:**

1. The system reads the agent's system prompt (instructions)
2. Sends it to an LLM (Gemini 3 Flash) to generate test cases
3. For each test case, the LLM creates: question, expected answer, and optional document content
4. Document content is converted to actual files (DOCX, XLSX, or PDF) and uploaded to storage
5. Test case records are created with document references
   {% endtab %}
   {% endtabs %}
   {% endstep %}

{% step %}

#### Review & Generate

Check the details, then generate the dataset.

| Field                | Description                                                             |
| -------------------- | ----------------------------------------------------------------------- |
| **Dataset name**     | Required, up to 120 characters.                                         |
| **Test case source** | **Uploaded file** (with the file name) or **Generated with AI**.        |
| **Test cases**       | The number you asked for, or **Decided by the document** for an upload. |

The new dataset's details page opens. Reading an uploaded document takes a while, so the dataset shows **Extracting** until its test cases are ready. You can leave the page in the meantime.
{% endstep %}
{% endstepper %}

#### Add test cases manually

Create manual test cases one at a time in an existing dataset.

Each manual test case can include:

* `question`
* `expected answer`
* optional documents

Use `POST /:agentId/eval/datasets/:datasetId/items` to create the test case.

Use **Test Case Search** to filter by question, expected answer, or document context.

<details>

<summary>How document format selection works</summary>

Document format selection is automatic.

| Format | Content Type             | Examples                      |
| ------ | ------------------------ | ----------------------------- |
| XLSX   | Tabular/spreadsheet data | Budgets, financial tables     |
| DOCX   | Narrative prose          | Memos, policies, contracts    |
| PDF    | Professional documents   | Invoices, resumes, statements |

</details>

### Dataset Views

**List view** displays all datasets for the agent:

* **Name** — Dataset name
* **Status** — See the table below
* **Test Cases** — How many test cases the dataset holds
* **Created** — Creation timestamp
* **Actions** — Rename (pencil icon), Delete

| Status         | Meaning                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Extracting** | The uploaded document is still being read. The list refreshes on its own until it settles.                                           |
| **Ready**      | The test cases are in place and the dataset can be run.                                                                              |
| **Failed**     | No test cases could be read from the document. Hover over the badge for the reason, then upload a revised document as a new dataset. |

Empty state: "No evaluation datasets yet. Generate one to get started."

**Details view** shows the dataset name as header with a **"Run Evaluation"** button (disabled if no [test cases](#test-cases)), plus the list of all [test cases](#test-cases).

***

### Test Cases

Each test case contains:

* **Question** — The input prompt sent to the agent
* **Expected Answer** — The ground truth / ideal response
* **Document Context** (optional) — Description of attached documents (e.g., "Excel budget sheet")
* **Documents** (optional) — Attached files (DOCX, XLSX, PDF) shown as clickable chips

#### Document Preview

Clicking a document chip opens a preview modal:

| File Type                  | Viewer                                  |
| -------------------------- | --------------------------------------- |
| PDF                        | Native document viewer                  |
| Google Docs / Office files | Embedded Google or Office Online viewer |
| Excel                      | Office Online viewer                    |

{% hint style="info" %}
Toggle between "Show preview" and "Show context" if document context is available. Use the "Open file" button for external download.
{% endhint %}

***

## Runs

#### Starting a Run

{% tabs %}
{% tab title="Start a run" %}

1. Navigate to a dataset with at least one test case
2. Click **"Run Evaluation"**
3. The system creates an eval run with status `Pending`
4. Background processing starts
5. Success toast: "Evaluation run started"
   {% endtab %}

{% tab title="Monitor a run" %}
Use the **Runs** tab to track:

* current status
* progress
* scores
* suggestions

Each run is a card showing the dataset name, its status, when it started, and its **Passed**, **Failed** and **Avg score** figures. Use **Search runs** to find one, and select a card to open the **Evaluation Run** page with its summary and per-test-case [results](#scoring).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2c9137f8bfa2784b392bb85c5cac0853741d56d2%2Fqore_agent-builder_manage-agent-evals-runs_rounded_shadow.png?alt=media" alt="The Evals page on the Runs tab, with a search box and two completed run cards showing passed and failed counts and an average score"><figcaption><p>The Runs tab.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

#### Run Execution

For each test case in the dataset:

1. Resolve document references to signed URLs
2. Trigger the agent via the Agent Executor (`/agents/{agentId}/trigger`)
3. Pass the question + documents to the agent
4. Extract the agent's actual answer from the response
5. Score the response using an LLM scorer (Gemini 3 Flash)
6. Record the result (score, reasoning, correctness, duration)
7. Update run progress counters

{% hint style="info" %}
Up to **3 test cases** execute concurrently during a run.
{% endhint %}

#### Run Status

<details>

<summary>Status lifecycle</summary>

```
Pending → Running → Completed
                 → Failed
                 → Stopped (user-stopped)
```

</details>

| Status        | Indicator        | Details Shown                               | Available Actions                                     |
| ------------- | ---------------- | ------------------------------------------- | ----------------------------------------------------- |
| **Pending**   | Warning badge    | Waiting to start                            | —                                                     |
| **Running**   | Animated spinner | Progress bar (completedItems / totalItems)  | Stop                                                  |
| **Completed** | Green badge      | Pass/fail counts, [average score](#scoring) | View results, Apply [suggestions](#suggested-changes) |
| **Failed**    | Red badge        | Error message                               | —                                                     |
| **Stopped**   | Red badge        | Partial [results](#scoring)                 | View partial [results](#scoring)                      |

{% hint style="info" %}
A **Stop** button appears during in-progress runs. Stopping preserves already-completed results. The UI polls every **3 seconds** while a run is in progress, stopping automatically when the run completes.
{% endhint %}

***

## Scoring

**Score Scale:** Each test case response is scored by an LLM (Gemini 3 Flash):

| Score    | Verdict           | Description                                          | Result |
| -------- | ----------------- | ---------------------------------------------------- | ------ |
| **0–3**  | Incorrect         | Response is wrong or irrelevant                      | Fail   |
| **4–6**  | Partially correct | Some relevant content but incomplete or inaccurate   | Fail   |
| **7–8**  | Correct           | Meets the expected answer criteria                   | Pass   |
| **9–10** | Comprehensive     | Exceeds expectations with additional relevant detail | Pass   |

{% hint style="warning" %}
**Pass threshold:** A score of 7 or above marks the test case as passed.
{% endhint %}

**Result Card** — each completed test case displays:

* **Status Badge** — Pass (green), Fail (red), or Error (red)
* **Score** — "Score: X/10"
* **Duration** — Execution time
* **Question** — Original input
* **Expected Answer** — Ground truth (muted, scrollable)
* **Actual Answer** — Agent's response (or error message)
* **Scorer Reasoning** — LLM's explanation of the score

Results appear progressively as each test case completes.

{% hint style="success" %}
Completed runs display **pass count** (green), **fail count** (red), **average score** (0–10), and an LLM-generated **summary** of evaluation results.
{% endhint %}

<details>

<summary>What a failing run usually means</summary>

A failing run does not always mean the agent is broken.

Common causes include:

* incomplete instructions
* missing skills or knowledge
* answers that are directionally correct but below the pass threshold

</details>

***

## Suggested Changes

{% hint style="info" %}
Suggestions are generated automatically when a run completes with failures or an average score below 7.
{% endhint %}

Each suggestion contains:

* **Title** — Short description (max 200 characters)
* **Category** — Instructions, Skills, Knowledge, Guardrails, or Other
* **Description** — Detailed recommendation (max 2,000 characters)

Suggestions can modify: agent instructions, skills, knowledge, and guardrails.

#### Applying Suggestions

{% stepper %}
{% step %}

### Open suggestions

Click **"Apply to Agent"** on a completed run with suggestions.
{% endstep %}

{% step %}

### Review selections

A dialog opens with all suggestions and checkboxes.

Edit titles, categories, or descriptions as needed.
{% endstep %}

{% step %}

### Apply changes

Select the suggestions to apply and click **Apply**.

Toast: "Builder agent is applying your changes — watch the chat panel on the left"
{% endstep %}

{% step %}

### Continue in chat

The agent config modal closes and the Builder Agent executes the changes in the chat panel.
{% endstep %}
{% endstepper %}

### Related sections

* [Monitoring](/ai-workbench-qore/console/agent-builder/monitor) — Watch runtime behavior after the agent is live.
* [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval) — Score live conversations in production.
* [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) — Review and approve learning cases from real usage.

***

{% 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 %}


# Deploy

Ship the agent into your product, safely.

**Deploy** is where the agent leaves the builder and becomes something your users can reach — embedded in an app, called from your backend, or packaged for another environment.

The pages here fall into two halves that belong together: how the agent gets *out* to your product, and the controls that decide what it may do once it is there. A deployed agent is reachable by people who never saw the builder, so the credential, domain, PII, and guardrail settings on this page are the boundary between "the agent can act" and "the agent can only act the way you intended."

## Getting the agent out

* [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent) — Package an agent for reuse across environments.
* [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration) — Embed or call the agent from your product.

## Controlling what it can do

* [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication) — Create access keys and choose where the widget may run.
* [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) — Verify who is calling the agent through your identity provider.
* [PII Tokenization](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking) — Protect sensitive user and business data.
* [Guardrails (Beta)](/ai-workbench-qore/console/agent-builder/deploy/guardrails) — Define safety and compliance controls.

***

Once the agent is live, [Monitor](/ai-workbench-qore/console/agent-builder/monitor) is where you watch it and feed corrections back into [Build](/ai-workbench-qore/console/agent-builder/build).

***

{% 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 %}


# Export Agent

Bundle an agent's full configuration into a portable, reusable package.

**Export Agent Package** bundles this agent's logic, configuration, tools, and contextual data into a single portable package for reuse or deployment in another environment. Open it with **Export Agent**, the export icon in the header above the canvas, between **Integrate Agent** (`</>`) and **Agent Config**. You need the **Export Agent** capability; without it the button is disabled.

{% hint style="info" %}
Looking to run the agent live inside your own app instead of exporting it? See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration).
{% endhint %}

You can also open it from the agent list: in **My Agents**, select **•••** on the agent's row, then **Export Agent**. It opens the same dialog.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-747fb7b94642d29435df007d3b534debaf895025%2Fqore_agent-builder_how-to-canvas-header_rounded_shadow.png?alt=media" alt="The canvas header: the Overview and Flow tabs, credits and cost, the Draft Version selector, the Integrate Agent and Export Agent icons, Agent Config, and Try Agent"><figcaption><p>Export Agent is the export icon in the canvas header, between Integrate Agent and Agent Config.</p></figcaption></figure>

## What gets exported

The bundle is a complete snapshot of the agent's setup, so it can be rebuilt exactly as-is somewhere else. It includes the agent's:

* Identity and instructions
* Attached skills and knowledge
* Integration skills
* Triggers and checklists
* Guardrails
* Runtime settings

That makes it useful whenever the agent needs to leave its current home:

* Move it between environments (development → staging → production)
* Share it with another team or tenant
* Keep a portable backup outside the platform

## Knowledge in the package

Knowledge attached to the agent always travels with it. No export option turns it off. The package holds each knowledge base attached to the agent, together with its files.

When you import the package, Qore restores each knowledge base, with its files, into the importing project as that project's own copy, and attaches it to the imported agent. Each restored knowledge base gets a new version labelled *Imported*.

* **Re-importing** the same package updates the project's existing copy instead of making a second one. Other agents in that project that use the same knowledge base see the update too.
* **Knowledge that another project already holds** is imported as a new copy. The original isn't changed.
* **An import replaces the agent's knowledge rather than adding to it.** Knowledge the agent already had in the target project, but that isn't in the package, is detached. Governed graphs stay attached.
* **Governed graphs aren't imported.** The import lists them in a warning: *N attached knowledge graph(s) will not be imported*, followed by their names.
* **Older multimodal knowledge comes back as text.** Files that were ingested as multimodal are imported and processed as text only. The import warns you how many are affected.

## Export options

Before you export, three checkboxes decide how much sensitive or connected material travels inside the bundle. All three are unchecked by default.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-73daf3367727e4e43e6a457e38227c67dd85f625%2Fqore_agent-builder_how-to-export-agent-package_rounded_shadow.png?alt=media" alt="The Export Agent Package dialog: Export this agent&#x27;s logic, configuration, tools, and contextual data into a single portable package, with Include secrets, Include MCP configuration and Include integration skills checkboxes, and Cancel and Export Package buttons"><figcaption><p>The Export Agent Package dialog.</p></figcaption></figure>

| Option                         | Default   | What it includes                                                                                |
| ------------------------------ | --------- | ----------------------------------------------------------------------------------------------- |
| **Include secrets**            | Unchecked | API keys, tokens, and credentials — not just references to them.                                |
| **Include MCP configuration**  | Unchecked | Each MCP connection's credentials and settings: OAuth client ID and secret, headers and tokens. |
| **Include integration skills** | Unchecked | The agent's connected Apps & Services / integration-backed skills and their setup.              |

Ticking any of the three shows a warning: *Exporting secrets, MCP configuration, or integration skills may expose sensitive credentials, internal tools, or privileged access.*

**MCP connections are exported either way.** With **Include MCP configuration** on, each connection travels with its credentials and settings, ready to use. With it off, each connection travels without its OAuth client ID and secret, headers and tokens, and is marked not initialized. After import, such a connection shows **Initialize** in the agent: select it to re-enter the connection's credentials. See [MCP](/ai-workbench-qore/core-concepts/mcp#managing-a-connection).

{% hint style="warning" %}
**Include secrets exports credential values in plaintext form inside the package.** Leave it off unless the destination environment genuinely needs the same credentials and the package will be handled securely. When it is off, secrets export as references and you supply the values again in the target environment via **Secrets & Variables**.
{% endhint %}

## Exporting the package

With your options chosen, the export itself is a single step. Select **Export Agent** in the header, set **Include secrets**, **Include MCP configuration**, and **Include integration skills** as needed, then select **Export Package** (or **Cancel** to dismiss).

The package isn't downloaded in your browser. Qore builds it in the background, so a large agent can't time out while you wait, and shows *Agent export is in progress. You will receive an email with the download link shortly.*

When the package is ready, you get an email titled *Your agent export "‹agent name›" is ready!* Select **Download** in the email to get the package, the one portable file you import into another environment. If the export raised any warnings, the same email lists them after *Please note:*.

The download link expires. How long it lasts depends on where your deployment stores files. Exporting the agent again sends a new email with a new link.

If the export fails, Qore retries it automatically. If it still fails, you get an email titled *Your agent export failed* that gives the reason, and a **View Agent** button that opens the agent. The email ends with *If the issue persists, please contact support*, followed by a reference ID to share when one is available.

Both emails go to the email address of the user who started the export.

## Troubleshooting

<details>

<summary>I selected Export Package but no email has arrived</summary>

The email is sent only when the package has finished building. It goes to the email address of the user who started the export. If the export fails, that address gets a *Your agent export failed* email instead.

</details>

<details>

<summary>The Download link in the email doesn't work</summary>

The download link expires, and how long it lasts depends on where your deployment stores files. Exporting the agent again sends a new email with a new link.

</details>

<details>

<summary>An imported agent's MCP server shows Initialize</summary>

The package was exported without **Include MCP configuration**, so the connection has no credentials. Open it, select **Initialize**, and enter them. See [Managing a connection](/ai-workbench-qore/console/agent-builder/build/mcp-tools#managing-a-connection).

</details>

<details>

<summary>I got a “Your agent export failed” email</summary>

Qore sends this email after retrying the export automatically. The email gives the reason the export failed, and **View Agent** opens the agent. The email ends with *If the issue persists, please contact support*, followed by a reference ID to share when one is available.

</details>

<details>

<summary>The imported agent has lost knowledge it had before</summary>

An import replaces the agent's knowledge rather than adding to it. Knowledge the agent had in this project that isn't in the package is detached. The knowledge base itself isn't deleted, so you can attach it again. See [Attaching Knowledge to an Agent](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent).

</details>

<details>

<summary>Another agent's knowledge changed after I imported a package</summary>

Re-importing a package updates this project's copy of each knowledge base in it, and every agent in the project that uses that knowledge base sees the update.

</details>

<details>

<summary>A governed graph is missing from the imported agent</summary>

Governed graphs aren't imported. The import lists them in a warning that starts *N attached knowledge graph(s) will not be imported*. Upload the graph in the target environment's [Governed Graph](/ai-workbench-qore/control-center/govern/governed-graph), then attach it to the agent. See [Attaching a governed graph](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent#attaching-a-governed-graph).

</details>

<details>

<summary>Images in the imported knowledge are missing</summary>

Knowledge that was ingested as multimodal comes back as text only, because multimodal ingestion has been removed. The import warns you how many files are affected.

</details>

## FAQs

<details>

<summary>Can I download the package straight from the browser?</summary>

No. The package is always built in the background and delivered by email, so a large agent can't time out while you wait.

</details>

<details>

<summary>Is the agent's knowledge included in the package?</summary>

Yes, always. Each knowledge base attached to the agent travels with it, together with its files, and no export option turns this off. See [Knowledge in the package](#knowledge-in-the-package).

</details>

<details>

<summary>Will re-importing the same package create duplicate knowledge?</summary>

No. Re-importing updates the project's existing copy of each knowledge base. Knowledge that another project already holds is imported as a new copy, and the original isn't changed.

</details>

<details>

<summary>Are secrets included?</summary>

Only when you turn on **Include secrets**, which is off by default, and then their values are in the package in plaintext. Otherwise secrets export as references, and you enter the values again in the target environment's **Secrets & Variables**. See [Export options](#export-options).

</details>

<details>

<summary>Are MCP connections included?</summary>

Yes, always. **Include MCP configuration**, off by default, decides whether each connection's OAuth client ID and secret, headers and tokens go too. Without them, the connections arrive needing **Initialize**. See [MCP Tools](/ai-workbench-qore/console/agent-builder/build/mcp-tools#exporting-and-importing).

</details>

<details>

<summary>Who receives the export emails?</summary>

The user who started the export, at their account's email address. Both the ready email and the failure email go there.

</details>

### Related sections

* [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration) — Run the agent live in your product instead of packaging it.
* [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) — Recreate or rotate secret values in the target environment.
* [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning) — Match runtime settings after import.

***

{% 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 %}


# Integrate Agent

Embed, call, or drive your agent from your own applications.

If you want people to use this agent outside the platform — in your own app, product, or website — set it up here. Pick **Agent API** to call it from your backend, or **Embedded Chat** to drop a ready-made chat widget into your site. Find it under **Agent Config → Integrate Agent**, under *Credentials & access*; it opens as a side panel with two tabs, **Embedded Chat** and **Agent API**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-75c5226d4f2af344c407ea985f812e367cda8852%2Fqore_agent-builder_manage-agent-integrate-agent-embedded-chat_rounded_shadow.png?alt=media" alt="The Integrate Agent panel on the Embedded Chat tab, at step 1 Widget key, with Use existing key and Generate new key options"><figcaption><p>Integrate Agent, with the Embedded Chat and Agent API tabs.</p></figcaption></figure>

{% hint style="info" %}
**Versions are per agent.** Read the SDK version and Executor version from your own agent's **Agent Config Panel**, and use those in your app and API calls. The values shown in the samples on this page are placeholders.
{% endhint %}

{% hint style="warning" %}
**`<BASE_URL>` in every sample on this page** is a placeholder for the Qore API host your organization uses. Confirm your production host with your Uptiq contact or your platform administrator before you ship — it differs by deployment, and a sample host will not work against your environment. (The panel's own "Download as MD" export shows a real host for your environment — copy the sample from there once you've confirmed it's the right one for where you're shipping.)
{% endhint %}

## Choosing an integration

Start by matching the tab to where your agent runs and how much of the interface you want to own.

| If you want to…                                          | Use                                      | Runtime                       |
| -------------------------------------------------------- | ---------------------------------------- | ----------------------------- |
| Drop a chat onto a web page with no UI to build          | **Embedded Chat**                        | Browser (prebuilt UI)         |
| Call the agent from a backend, service, or scheduled job | **Agent API** — Client: `raw (HTTP)`     | Server-to-server (no browser) |
| Build your own custom chat UI in the browser             | **Agent API** — Client: `TypeScript SDK` | Browser (your UI)             |

**Shared prerequisites.** Both tabs connect using credentials and domain rules configured on the agent:

| Requirement            | Where                                | Applies to                                                                              |
| ---------------------- | ------------------------------------ | --------------------------------------------------------------------------------------- |
| **Widget Key**         | Agent Config → **Access & Security** | Embedded Chat, TypeScript SDK client (and optionally the API)                           |
| **API Key + Secret**   | Agent Config → **Access & Security** | Agent API, raw HTTP client (server-to-server)                                           |
| **Whitelisted domain** | Agent Config → **Access & Security** | Embedded Chat, TypeScript SDK client — add the full URL or hostname, no trailing spaces |

To obtain a **Widget Key**: open your agent's **Access & Security** page, then generate and copy the key — the same **Widget key** step the Embedded Chat wizard walks you through below. To **whitelist a domain**: on the same page, add and save your domain under **Allowed Domains**.

Set up [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication) first. It holds both the Access Keys and the Allowed Domains list.

{% hint style="warning" %}
Wherever you supply a `user` object, it must represent a **trusted, authenticated identity** from your own auth system — the user currently logged into your application and verified by your auth system. Never populate it from query parameters or untrusted input, which can be manipulated.
{% endhint %}

## Embedded Chat

Embedded Chat is the quickest path — a prebuilt chat UI you drop onto a page, with no interface to build yourself. The panel walks you through it as three steps.

### Step 1 — Widget key

Choose **Use existing key** to reuse a key already issued for this agent, or **Generate new key**. A public key lets the widget talk to this agent from the browser — safe to ship in client code. Select **Generate key**, then **Continue**.

### Step 2 — Whitelist domains

Only these origins may load the widget; requests from anywhere else are rejected. Add each domain your widget will run on (for example `app.yourdomain.com`), then **Continue**. The domains go on the same **Allowed Domains** list as [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication#allowed-domains).

### Step 3 — Install widget

Install the React SDK and mount the widget in your app:

```bash
npm install @uptiqai/widgets-sdk@1.295.0
```

```tsx
import { ChatWidget } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';

export default function App() {
  return (
    <ChatWidget
      config={{
        serverUrl: '<BASE_URL>',
        agentId: '<agent-id>',
        widgetKey: '<your-widget-key>',
        agentExecutorVersion: '1.4',
      }}
      user={{ uid: 'user_123', firstName: 'John', email: 'john@example.com' }}
    />
  );
}
```

{% hint style="info" %}
**The widget SDK version above is the one released alongside this agent's executor version** — pinning it keeps the widget and the executor in step. Upgrade the agent's executor version first if you need a newer widget.
{% endhint %}

That's enough to get a working chat widget live. The rest of this section is reference material for going further: the framework-agnostic HTML web component, the Full Screen layout, theming, and the headless JS SDK for a fully custom UI.

### Reference: widget variants

The **Embed Agent** widget is a drop-in chat interface backed by `@uptiqai/widgets-sdk`. Beyond the React `ChatWidget` shown above, it also comes as a framework-agnostic **HTML web component**, and each offers a compact **Chat Widget** (floating popover) or an immersive **Full Screen** layout with sidebar navigation. The widget handles conversation state, history, and messaging for you.

**Install**

```bash
npm install @uptiqai/widgets-sdk@1.295.0
# or
pnpm add @uptiqai/widgets-sdk@1.295.0
```

Import the stylesheet once in your application entry point:

```js
import '@uptiqai/widgets-sdk/dist/style.css';
```

**Chat Widget vs. Full Screen** — both share the same `config`, `user`, `theme`, `instanceId`, and ref API. Full Screen adds a `hideTrigger` / `hide-trigger` option to hide the default launcher and open via your own button. Expand the variant you need:

<details>

<summary>React — Chat Widget (popover)</summary>

```tsx
import { ChatWidget } from '@uptiqai/widgets-sdk';
import type { ChatWidgetRef } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';
import { useRef } from 'react';

function App() {
  const currentUser = useAuth(); // your auth hook
  return (
    <ChatWidget
      config={{
        serverUrl: '<BASE_URL>',
        agentId: '<agent-id>',
        widgetKey: '<your-widget-key>',
        agentExecutorVersion: '1.4',
      }}
      user={{
        uid: currentUser.id,
        firstName: currentUser.firstName,
        lastName: currentUser.lastName,
        email: currentUser.email,
      }}
    />
  );
}
```

</details>

<details>

<summary>React — Full Screen</summary>

Use `FullScreenChatWidget` / `FullScreenChatWidgetRef`. Add `hideTrigger` when driving visibility from your own button:

```tsx
import { FullScreenChatWidget } from '@uptiqai/widgets-sdk';
import type { FullScreenChatWidgetRef } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';
import { useRef } from 'react';

function App() {
  const widgetRef = useRef<FullScreenChatWidgetRef>(null);
  const currentUser = useAuth();
  return (
    <FullScreenChatWidget
      config={{
        serverUrl: '<BASE_URL>',
        agentId: '<agent-id>',
        widgetKey: '<your-widget-key>',
        agentExecutorVersion: '1.4',
      }}
      user={{
        uid: currentUser.id,
        firstName: currentUser.firstName,
        lastName: currentUser.lastName,
        email: currentUser.email,
      }}
      hideTrigger={true}
      widgetRef={widgetRef}
    />
  );
}
```

</details>

<details>

<summary>HTML — Chat Widget (popover)</summary>

Add the widget script to your page `<head>`, then use the custom element:

```html
<uptiq-chat-widget
  id="chat-widget"
  config='{
    "serverUrl": "<BASE_URL>",
    "agentId": "<agent-id>",
    "widgetKey": "<your-widget-key>",
    "agentExecutorVersion": "1.4"
  }'
  user='{
    "uid": "auth0|<user-id>",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@company.com"
  }'
></uptiq-chat-widget>
```

</details>

<details>

<summary>HTML — Full Screen</summary>

Use `<uptiq-full-screen-chat-widget>` and add `hide-trigger="true"` to hide the default launcher:

```html
<uptiq-full-screen-chat-widget
  id="chat-widget"
  hide-trigger="true"
  config='{
    "serverUrl": "<BASE_URL>",
    "agentId": "<agent-id>",
    "widgetKey": "<your-widget-key>",
    "agentExecutorVersion": "1.4"
  }'
  user='{
    "uid": "auth0|<user-id>",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@company.com"
  }'
></uptiq-full-screen-chat-widget>
```

</details>

### Props / attributes reference

React uses **props** (objects); the HTML web component uses **attributes** (JSON-stringified objects, kebab-case names). Otherwise they map 1:1.

| React prop           | HTML attribute         | Required | Type                     | Description                                                                                                                                                                                                             |
| -------------------- | ---------------------- | -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`             | `config`               | Yes      | `WidgetConfig`           | Backend/agent config — see below.                                                                                                                                                                                       |
| `user`               | `user`                 | Yes      | `WidgetUser`             | Authenticated user — see below.                                                                                                                                                                                         |
| `instanceId`         | `instance-id`          | No       | string                   | Unique ID when rendering multiple widgets on one page. Default: auto-generated.                                                                                                                                         |
| `theme`              | `theme`                | No       | `WidgetTheme`            | Palette overrides — see **Theme customization**.                                                                                                                                                                        |
| `defaultExecutionId` | `default-execution-id` | No       | string                   | Start with a specific conversation/execution loaded (continue a previous chat).                                                                                                                                         |
| `onExecutionChange`  | —                      | No       | `(executionId?) => void` | Fires when the current conversation changes.                                                                                                                                                                            |
| `defaultOpen`        | `default-open`         | No       | boolean                  | Open on mount. Default `false`.                                                                                                                                                                                         |
| `hideTrigger`        | `hide-trigger`         | No       | boolean                  | *(Full Screen)* Hide the default launcher; open via your own button + ref. Default `false`.                                                                                                                             |
| `onClose`            | —                      | No       | `() => void`             | Fires when the user closes the widget.                                                                                                                                                                                  |
| `widgetRef`          | —                      | No       | `React.Ref<…Ref>`        | Programmatic `open()` / `close()` control.                                                                                                                                                                              |
| `authToken`          | `auth-token`           | No       | string                   | The signed-in user's identity token, for an agent with [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) on. Sent with every message, held in memory only.                             |
| `allowDeveloperMode` | `allow-developer-mode` | No       | boolean                  | *Available on request.* Shows a **Developer Mode** switch in the sidebar, which reveals [Setup Identity Token](/ai-workbench-qore/console/agent-builder/deploy/authentication-1#setup-identity-token). Default `false`. |

**`config` (required)** — `WidgetConfig`:

```ts
{
  serverUrl: '<BASE_URL>',    // your Qore API host - see the note at the top of this page
  agentId: '<agent-id>',      // the agent's ID, from its Agent Config Panel
  widgetKey: string,          // from Access & Security
  agentExecutorVersion?: string, // Executor version from agent config (optional)
}
```

**`user` (required)** — `WidgetUser`:

```ts
{
  uid: string;        // Unique identifier for the user in your system
  firstName: string;  // User's first name
  lastName?: string;  // User's last name (optional)
  email: string;      // User's email address
}
```

{% hint style="warning" %}
**Security:** populate `user` from your authenticated session — e.g. `const currentUser = useAuth();` — never from query params, form input, or other untrusted sources.
{% endhint %}

<details>

<summary>widgetRef — programmatic open/close control</summary>

```ts
// React.Ref<ChatWidgetRef> | React.Ref<FullScreenChatWidgetRef>
{
  open: () => void;   // Opens the widget
  close: () => void;  // Closes the widget
}
```

```tsx
const widgetRef = useRef<FullScreenChatWidgetRef>(null);

const handleOpenChat = () => widgetRef.current?.open();
const handleCloseChat = () => widgetRef.current?.close();
```

</details>

### Theme customization

Pass a `theme` (React object / HTML JSON string) to match your design system:

```tsx
theme={{
  palette: {
    primary: '#3b82f6',
    primaryForeground: '#ffffff',
    background: '#ffffff',
    foreground: '#0f172a',
    border: '#e2e8f0',
    success: '#10b981',
    destructive: '#ef4444',
  },
}}
```

<details>

<summary>Full palette reference (WidgetTheme)</summary>

```ts
{
  palette?: {
    // Primary shades
    primary00?; primary100?; primary200?; primary300?; primary400?; primary500?;
    // Secondary shades
    secondary300?; secondary500?; secondary700?;
    // Background shades (00 lightest → 900 darkest)
    background00?; background100?; background200?; background300?; background800?; background900?;
    // Foreground / text
    foreground00?; foreground200?; foreground600?; foreground800?; foreground900?;
    // Borders
    border100?; border200?; border300?; border400?;
    // Semantic
    primary?; primaryForeground?;
    secondary?; secondaryForeground?;
    background?; foreground?;
    border?; input?;
    success?; successForeground?;
    warning?; warningForeground?;
    destructive?; destructiveForeground?;
    sidebar?; sidebarForeground?;
    ring?;
    // all values are string (optional)
  }
}
```

</details>

### Examples

<details>

<summary>Example 1 — Basic implementation</summary>

```tsx
import { FullScreenChatWidget } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';

function App() {
  const currentUser = useAuth();
  return (
    <div>
      <h1>My Application</h1>
      <FullScreenChatWidget
        config={{ serverUrl: '<BASE_URL>', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.4' }}
        user={{ uid: currentUser.id, firstName: currentUser.firstName, lastName: currentUser.lastName, email: currentUser.email }}
      />
    </div>
  );
}
```

</details>

<details>

<summary>Example 2 — Custom trigger with ref control</summary>

```tsx
import { FullScreenChatWidget } from '@uptiqai/widgets-sdk';
import type { FullScreenChatWidgetRef } from '@uptiqai/widgets-sdk';
import '@uptiqai/widgets-sdk/dist/style.css';
import { useRef } from 'react';

function App() {
  const widgetRef = useRef<FullScreenChatWidgetRef>(null);
  const currentUser = useAuth();
  return (
    <div>
      <button onClick={() => widgetRef.current?.open()}>💬 Chat with AI Assistant</button>
      <FullScreenChatWidget
        config={{ serverUrl: '<BASE_URL>', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.4' }}
        user={{ uid: currentUser.id, firstName: currentUser.firstName, lastName: currentUser.lastName, email: currentUser.email }}
        hideTrigger={true}
        widgetRef={widgetRef}
      />
    </div>
  );
}
```

For the **popover** `ChatWidget`, the same pattern applies with both open and close buttons (`widgetRef.current?.open()` / `.close()`).

</details>

<details>

<summary>Example 3 — Theme customization</summary>

```tsx
const customTheme = {
  palette: {
    primary: '#6366f1', primaryForeground: '#ffffff',
    background: '#f8fafc', foreground: '#1e293b', border: '#cbd5e1',
    sidebar: '#ffffff', sidebarForeground: '#475569',
    success: '#22c55e', warning: '#f59e0b', destructive: '#ef4444',
  },
};

<FullScreenChatWidget config={/* … */} user={/* … */} theme={customTheme} />
```

</details>

<details>

<summary>Example 4 — Tracking conversations</summary>

```tsx
import { useState } from 'react';

function App() {
  const currentUser = useAuth();
  const [currentExecutionId, setCurrentExecutionId] = useState<string>();

  const handleExecutionChange = (executionId?: string) => {
    setCurrentExecutionId(executionId);
    if (executionId) localStorage.setItem('lastExecutionId', executionId);
    analytics.track('conversation_changed', { executionId });
  };

  const lastExecutionId = localStorage.getItem('lastExecutionId') || undefined;

  return (
    <FullScreenChatWidget
      config={{ serverUrl: '<BASE_URL>', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.4' }}
      user={{ uid: currentUser.id, firstName: currentUser.firstName, lastName: currentUser.lastName, email: currentUser.email }}
      defaultExecutionId={lastExecutionId}
      onExecutionChange={handleExecutionChange}
      onClose={() => console.log('Widget closed with execution:', currentExecutionId)}
    />
  );
}
```

</details>

<details>

<summary>Example 5 — Multiple widgets on the same page</summary>

Give each widget a distinct `instanceId` (React) / `instance-id` (HTML):

```tsx
<FullScreenChatWidget instanceId="sales-agent" config={{ /* sales agentId + widgetKey */ }} user={/* … */} />
<FullScreenChatWidget instanceId="support-agent" config={{ /* support agentId + widgetKey */ }} user={/* … */} />
```

</details>

### Features

* Chat interface (floating popover or full-screen) with responsive design
* Conversation sidebar for managing multiple chats
* New chat creation for starting fresh conversations
* Message history persistence across sessions
* Real-time messaging with the AI agent
* Agent avatar display in the trigger button
* Customizable theming to match your brand
* TypeScript support with full type definitions

### Browser support

All modern browsers: Chrome/Edge (latest), Firefox (latest), Safari (latest), and mobile browsers (iOS Safari, Chrome Mobile).

### Troubleshooting

* **Widget not appearing** — ensure you imported the CSS (`import '@uptiqai/widgets-sdk/dist/style.css';`), that both required props (`config` and `user`) are provided, and that your Widget Key is correct and active.
* **"Unauthorized" errors** — confirm your application's domain is whitelisted exactly (full URL with protocol or hostname only, no trailing spaces).

## Agent API

When you'd rather drive the agent from your own code than a prebuilt UI, use the **Agent API** tab. It generates one code sample from three selectors:

| Selector    | Options                                      | Notes                                                                                                                                                                                                                                   |
| ----------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client**  | `raw (HTTP)`, `TypeScript SDK`, `Python SDK` | Python SDK is **Coming soon**.                                                                                                                                                                                                          |
| **Mode**    | `Sync`, `Async`, `Realtime`                  | This page documents Sync and Async in full. **Realtime** appears as a selector on screen; its request/response shape isn't documented yet — check back or ask your Uptiq contact before building against it.                            |
| **Dialect** | `Native`, `OpenAI`                           | **Native** is Qore's own request/response shape, documented below. **OpenAI** exposes an OpenAI-compatible surface (chat completions-style requests); it isn't documented on this page yet — the selector is live, the reference isn't. |

The credentials panel above the generated sample reads: *"Every request needs both the API key below (sent as the `x-api-key` header, always visible here) and its matching API secret (sent as `x-api-key-secret`, shown only once when generated). Keep both server-side — never expose them in the browser."* Generate the key pair from the panel, or from **Access & Security**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a499d7cffd683816349fb10209983ae1475a10a3%2Fqore_agent-builder_manage-agent-integrate-agent-api_rounded_shadow.png?alt=media" alt="The Agent API tab of Integrate Agent, with the API credentials panel reading No API key yet, the Generate new secret key button, and the Client, Mode and Dialect selectors"><figcaption><p>The Agent API tab, before an API key exists.</p></figcaption></figure>

* **Generate new secret key** creates a new API key and secret, and shows the secret once. Copy it straight away. It adds a key and doesn't deactivate any existing one; deactivate keys you no longer use on [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication#renaming-or-deactivating-a-key).
* If the agent already has an API key, the panel shows it. Its secret can't be shown again, so if you didn't save it, generate a new pair.

#### Download as MD

**Copy** copies the generated sample. **Download as MD** opens a preview of the exact Markdown file you'll download: the agent's name, executor version and base URL, the credentials guidance, and the sample for the Client, Mode and Dialect you chose. Embedded Chat has the same button on its **Install widget** step.

On the Agent API tab, the dialog has an **Include secrets** option. Tick it to write the agent's API key and its secret into the file, so the file works as-is. It needs an API key to exist.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-4cdbb671de8d9b99be0bb90011270a9999de598e%2Fqore_agent-builder_manage-agent-integrate-agent-download-md_rounded_shadow.png?alt=media" alt="The Download as MD dialog for Agent API over HTTP, previewing the integration spec Markdown, with the Include secrets checkbox and the Download .md button"><figcaption><p>Download as MD, with Include secrets.</p></figcaption></figure>

{% hint style="warning" %}
**A file downloaded with Include secrets is a credential.** Anyone who has it can call the agent. Keep it out of shared drives, tickets and repositories, and deactivate the key on Access & Security if the file leaks.
{% endhint %}

The rest of this section documents the **Native** dialect for the **raw (HTTP)** client — Sync and Async modes — plus the **TypeScript SDK** client. Both run server-to-server or in the browser respectively; pick based on where your integration runs:

### Native dialect, raw HTTP client

The **Headless Agent Trigger API** invokes an agent over HTTP — no UI or browser. Use it for backend services, scheduled jobs, or any workflow that starts the agent from your own systems.

* **Base URL:** `<BASE_URL>` · **Format:** JSON

#### Authentication

Every request must include exactly one of the following header sets.

<details>

<summary>Option 1 — API Key + Secret (server-to-server)</summary>

Best for backend and service-to-service integrations.

```http
x-api-key: YOUR_AGENT_API_KEY
x-api-key-secret: YOUR_AGENT_API_KEY_SECRET
Content-Type: application/json
```

Create and copy both from **Access & Security**.

</details>

<details>

<summary>Option 2 — Widget Key</summary>

Best for first-party platform integrations.

```http
x-widget-key: YOUR_AGENT_WIDGET_KEY
Content-Type: application/json
```

Create and copy it from **Access & Security**.

</details>

#### Trigger an agent

```
POST /agent-executor/1.4/agents/:agentId/trigger
```

Starts a new agent execution or resumes a paused one.

**Path parameters**

| Name      | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `agentId` | string | Yes      | The unique identifier of the agent to run. |

**Request body** — provide either `message` or `resumeData`; all other fields are optional.

| Field            | Type   | Description                                                                                                                                                                                                    |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`        | string | The instruction sent to the agent. Required for new executions.                                                                                                                                                |
| `payload`        | object | Structured data sent alongside `message` for programmatic inputs.                                                                                                                                              |
| `documents`      | array  | File attachments. See **Document handling**.                                                                                                                                                                   |
| `executionId`    | string | Specific execution ID. Auto-generated if omitted.                                                                                                                                                              |
| `executionMode`  | string | `async` (default) or `sync`. Use `sync` only when you need an immediate response.                                                                                                                              |
| `responseFormat` | string | `Markdown` (default) or `Json`.                                                                                                                                                                                |
| `webhooks`       | array  | Webhook URLs to receive execution updates. See **Webhooks**.                                                                                                                                                   |
| `token`          | string | The caller's identity token, for an agent with [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) on. Optional: a run without it still proceeds, with no authenticated caller. |

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the latest sales report"}'
```

Success response: `{ "executionId": "exec_123" }`

That is an acknowledgement, not an answer — executions default to async. Poll the execution or receive a webhook to turn an `executionId` into a result.

#### Document handling

Attaching documents is a two-step process: upload the file, then reference it in the trigger request.

<details>

<summary>Step 1 — Get a signed upload URL</summary>

```
POST /agent-executor/1.4/agents/:agentId/uploads/signed-urls
```

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/uploads/signed-urls" \
  -H "x-widget-key: YOUR_AGENT_WIDGET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 1 }'
```

| Field         | Type   | Required | Description                                     |
| ------------- | ------ | -------- | ----------------------------------------------- |
| `count`       | number | No       | Number of signed URLs to generate. Default `1`. |
| `executionId` | string | No       | Execution ID to associate the upload with.      |

Response:

```json
{
  "message": "Signed URL generated successfully.",
  "data": [
    { "id": "document-id", "url": "https://storage.googleapis.com/.../uploads/...", "agentId": "agent-id" }
  ]
}
```

`PUT` your file to the returned `url`, then use the `id` when triggering the agent.

{% hint style="warning" %}
The previous endpoint `POST /agent-executor/1.4/agents/:agentId/documents/presigned-url` is **deprecated** and will be removed — migrate to `uploads/signed-urls`.
{% endhint %}

</details>

<details>

<summary>Step 2 — Attach the document to the trigger request</summary>

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze financial risk",
    "documents": [
      { "id": "<document-id>", "fileName": "balance-sheet.pdf", "mimeType": "application/pdf" }
    ]
  }'
```

| Field       | Type   | Description                                                  |
| ----------- | ------ | ------------------------------------------------------------ |
| `id`        | string | Document ID returned from the upload endpoint.               |
| `signedUrl` | string | Alternative to `id` — the signed URL of the uploaded file.   |
| `fileName`  | string | Original filename. Recommended for better agent context.     |
| `mimeType`  | string | MIME type of the file. Recommended for better agent context. |

</details>

#### Passing variables and a business ID

Two more fields on the trigger request, alongside `message` and `documents`:

| Field        | Type   | Description                                                                                                                                                                                   |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid`        | string | The calling user's ID in your system — the same identity concept as the widget's `user.uid`.                                                                                                  |
| `variables`  | object | Key/value pairs the agent's instructions can reference. **Every key must already be declared** in the agent's **Agent Variables** section under Agent Config — an undeclared key is rejected. |
| `businessId` | string | Attributes this run to a business or tenant of your own. Accepted on every trigger request.                                                                                                   |

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Compare a 15-year and 30-year fixed mortgage.",
    "executionMode": "sync",
    "uid": "user_123",
    "variables": { "customerName": "John", "region": "US" },
    "businessId": "<businessId>"
  }'
```

#### Checking and managing a running execution

Once an execution is triggered, four more endpoints let you check on it or stop it — all under the same `:agentId` path used to trigger it.

<details>

<summary>Check where an execution sits in the queue</summary>

```
GET /agent-executor/1.4/agents/:agentId/executions/:executionId/queue-status
```

Messages sent to the same `executionId` are processed serially — one item shows `Executing`, the rest `Pending`.

```bash
curl "<BASE_URL>/agent-executor/1.4/agents/:agentId/executions/:executionId/queue-status" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET"
```

Response: `{ "data": [{ "state": "Executing", "content": { "messageId": "<messageId>" } } ] }`

For a **sync** call, the reply instead blocks until done, with the result in `result.content`: `{ "executionId": "exec_123", "result": { "type": "done", "content": "..." } }`.

</details>

<details>

<summary>Cancel a message that is still Pending</summary>

```bash
curl -X DELETE "<BASE_URL>/agent-executor/1.4/agents/:agentId/executions/:executionId/queue/:messageId" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET"
```

</details>

<details>

<summary>Abort a running execution</summary>

```
POST /agent-executor/1.4/agents/:agentId/executions/:executionId/abort
```

The agent stops and emits a terminal `done` event.

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/executions/:executionId/abort" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET"
```

</details>

#### Listing and inspecting conversations

<details>

<summary>List this agent's conversations</summary>

```
GET /agent-executor/1.4/agents/:agentId/conversations
```

Returns titles and metadata only, not transcripts. Add `?initiatedBy=user_123` to filter to one user's conversations.

```bash
curl "<BASE_URL>/agent-executor/1.4/agents/:agentId/conversations" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET"
```

</details>

<details>

<summary>Fetch a single conversation's transcript by executionId</summary>

```bash
curl "<BASE_URL>/agent-executor/1.4/agents/:agentId/conversation/:executionId" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET"
```

</details>

#### Webhooks

{% hint style="info" %}
Webhooks are available on **Agent Executor Version 1.2 and onwards**.
{% endhint %}

Register webhooks in the trigger request to receive real-time updates when an execution completes or needs input:

```json
{
  "webhooks": [
    { "url": "https://your-service.com/webhook", "metadata": "optional-context-id" }
  ]
}
```

Your endpoint receives:

```json
{
  "executionId": "exec_123",
  "success": true,
  "result": { "message": "Agent response..." },
  "error": null,
  "metadata": "optional-context-id"
}
```

<details>

<summary>Verify the webhook signature</summary>

Each webhook includes an `X-Webhook-Signature` header — a hex-encoded RSA-SHA256 signature of the raw JSON body. Verify it against the platform's public key (available on the agent's Agent API screen):

```js
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHex, publicKey) {
  const signature = Buffer.from(signatureHex, 'hex');
  return crypto.verify('RSA-SHA256', Buffer.from(rawBody), publicKey, signature);
}
```

</details>

#### Common examples

<details>

<summary>Send structured data with a message</summary>

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Generate quarterly report", "payload": { "quarter": "Q4", "year": 2024 } }'
```

</details>

<details>

<summary>Resume a paused execution</summary>

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "executionId": "exec_123", "resumeData": { "lastStep": "analysis" } }'
```

</details>

<details>

<summary>Pin a specific reasoning model (advanced)</summary>

By default the platform picks the reasoning model. To override:

```json
{ "message": "Analyze this contract", "agentStrategy": { "reasoningModelId": "your-model-id" } }
```

</details>

#### Error responses

| Status | Meaning         | Example                                                          |
| ------ | --------------- | ---------------------------------------------------------------- |
| `400`  | Invalid request | `{ "error": "Message or resume data is required" }`              |
| `401`  | Bad credentials | `{ "error": "Invalid or missing agent API key" }`                |
| `403`  | Forbidden       | `{ "message": "You're not authorized to perform this action." }` |
| `500`  | Server error    | `{ "message": "Something went wrong. Please try again later." }` |

{% hint style="info" %}
Executions default to **async** — use `sync` only when you must block on the result. The trigger endpoint is **not idempotent**: each call starts a new execution unless you pass an existing `executionId`.
{% endhint %}

### TypeScript SDK client

Select **TypeScript SDK** as the Client to drive the agent from your own code instead of raw HTTP. The **Headless Agent JS SDK** lets you build a custom chat interface while it handles the socket connection, real-time agent events, and file uploads automatically. Runs in the browser (React, Vue, or vanilla JS). Entry point: `createHeadlessAgentInstance(params)`, which returns an instance with `emit()`, `on()`, and `cleanup()` methods.

**Install & import**

```bash
npm install @uptiqai/widgets-sdk@1.295.0
```

```ts
import { createHeadlessAgentInstance } from '@uptiqai/widgets-sdk';
// TypeScript projects also import the types:
import type { HeadlessAgentInstance, AgentInterruptEvent } from '@uptiqai/widgets-sdk';
```

Authentication uses the **Widget Key**; your application's domain must be whitelisted (see **Shared prerequisites** above).

#### Create an instance

```ts
const instance = createHeadlessAgentInstance({
  config: { serverUrl: '<BASE_URL>', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.4' },
  user: { uid: 'user-123', firstName: 'Jane', lastName: 'User', email: 'jane@example.com' },
  instanceId: 'my-chat-instance',
});
```

| Parameter    | Type           | Required | Description                                                                                                                                   |
| ------------ | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`     | `WidgetConfig` | Yes      | `serverUrl`, `agentId`, `widgetKey`, optional `agentExecutorVersion`.                                                                         |
| `user`       | `WidgetUser`   | Yes      | `uid`, `firstName`, `email` (required); `lastName` (optional).                                                                                |
| `instanceId` | string         | Yes      | Unique identifier used for socket scoping.                                                                                                    |
| `authToken`  | string         | No       | The signed-in user's identity token, for an agent with [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1) on. |

#### Instance API

| Method         | Signature                                           | Description                                                                                        |
| -------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `emit`         | `(event: 'query', payload: QueryPayload) => void`   | Send a query to the agent, optionally with file attachments.                                       |
| `on`           | `(event: 'agent-interrupt', handler) => () => void` | Subscribe to agent events. Returns an unsubscribe function.                                        |
| `cleanup`      | `() => void`                                        | Remove listeners and disconnect the socket (call on unmount).                                      |
| `setAuthToken` | `(token?: string) => void`                          | Replace the identity token sent with every later message, for example after your app refreshes it. |

<details>

<summary>Sending messages — emit('query', payload)</summary>

| Property      | Type     | Required | Description                                                  |
| ------------- | -------- | -------- | ------------------------------------------------------------ |
| `content`     | string   | Yes      | The user's message text (use `' '` when sending only files). |
| `executionId` | string   | No       | Existing execution ID to continue a conversation.            |
| `files`       | `File[]` | No       | Browser `File` objects to upload and attach.                 |

The SDK obtains presigned upload URLs, uploads each file to cloud storage, and attaches the metadata to the message automatically — just pass the `File` objects.

```ts
// New conversation
instance.emit('query', { content: 'Hello, can you help me?' });

// With attachments
instance.emit('query', { content: 'Analyze these documents', files: [file1, file2] });

// Continue an existing conversation
instance.emit('query', { content: 'Tell me more', executionId: 'existing-execution-uuid' });

// Files only (no text)
instance.emit('query', { content: ' ', files: [selectedFile] });
```

</details>

<details>

<summary>Receiving events — on('agent-interrupt', handler)</summary>

The handler receives an `AgentInterruptEvent`; branch on its `type`:

| Event `type`    | Description                  | Key fields           |
| --------------- | ---------------------------- | -------------------- |
| `agent_message` | Agent text response          | `content`, `subtype` |
| `status_update` | Progress indicator           | `status`             |
| `done`          | Execution completed          | `content` (optional) |
| `error`         | Error occurred               | `error`              |
| `tool_call`     | Agent is calling a tool      | tool details         |
| `tool_result`   | Tool call completed          | tool result          |
| `plan_update`   | Agent created/updated a plan | plan details         |

`agent_message` events carry a `subtype`: `intermediate` (streaming), `final` (complete), `question` (needs user response), `final_stream`, `output_files`, `ask_permission`.

{% hint style="warning" %}
**Don't filter only by `subtype === 'final'`** or you'll miss agent questions and streamed replies — handle `final`, `question`, and `final_stream` at minimum.
{% endhint %}

```ts
const unsubscribe = instance.on('agent-interrupt', event => {
  switch (event.type) {
    case 'agent_message':
      if (['final', 'question', 'final_stream'].includes(event.subtype) && event.content) {
        displayMessage({ role: 'agent', content: event.content });
      }
      break;
    case 'error':
      displayMessage({ role: 'system', content: event.error ?? 'An error occurred' });
      break;
    case 'status_update':
    case 'done':
    case 'tool_call':
    case 'tool_result':
    case 'plan_update':
      // optional UI handling
      break;
    default:
      console.log('Unknown event type:', event.type);
  }
});
```

</details>

<details>

<summary>Cleanup</summary>

Always call `cleanup()` (and the unsubscribe function) when you're done — e.g. on component unmount:

```ts
unsubscribe();
instance.cleanup();
```

</details>

#### React integration example

```tsx
import { createHeadlessAgentInstance } from '@uptiqai/widgets-sdk';
import type { HeadlessAgentInstance, AgentInterruptEvent } from '@uptiqai/widgets-sdk';
import { useEffect, useRef, useState } from 'react';

const config = { serverUrl: '<BASE_URL>', agentId: '<agent-id>', widgetKey: '<your-widget-key>', agentExecutorVersion: '1.4' };
const user = { uid: 'user-123', firstName: 'Jane', lastName: 'User', email: 'jane@example.com' };

export const ChatComponent = () => {
  const [messages, setMessages] = useState<Array<{ role: 'user' | 'agent'; content: string }>>([]);
  const instanceRef = useRef<HeadlessAgentInstance | null>(null);

  useEffect(() => {
    const instance = createHeadlessAgentInstance({ config, user, instanceId: 'my-chat-instance' });
    instanceRef.current = instance;

    const unsubscribe = instance.on('agent-interrupt', (event: AgentInterruptEvent) => {
      if (event.type === 'agent_message'
          && ['final', 'question', 'final_stream'].includes(event.subtype ?? '')
          && event.content) {
        setMessages(prev => [...prev, { role: 'agent', content: event.content! }]);
      }
    });

    return () => { unsubscribe(); instance.cleanup(); };
  }, []);

  const sendMessage = (text: string, files?: File[]) => {
    setMessages(prev => [...prev, { role: 'user', content: text }]);
    instanceRef.current?.emit('query', { content: text, files });
  };

  return <div>{messages.map((m, i) => <div key={i}>{m.role}: {m.content}</div>)}</div>;
};
```

<details>

<summary>TypeScript types</summary>

```ts
import type {
  HeadlessAgentInstance,
  QueryPayload,
  AgentInterruptEvent,
  CreateHeadlessAgentInstanceParams,
} from '@uptiqai/widgets-sdk';

type HeadlessAgentInstance = {
  emit: (event: 'query', payload: QueryPayload) => void;
  on: (event: 'agent-interrupt', handler: (event: AgentInterruptEvent) => void) => () => void;
  cleanup: () => void;
};

type QueryPayload = { content: string; executionId?: string; files?: File[] };
```

</details>

#### Best practices

* **Single instance** — create one instance per chat context and reuse it for the whole conversation.
* **Subscribe before sending** — attach your `on('agent-interrupt', …)` handler before the first `emit` so no responses are missed.
* **Handle multiple subtypes** — capture `final`, `question`, and `final_stream`, not just `final`.
* **Always clean up** — call `cleanup()` on unmount to prevent memory leaks.
* **Persist `executionId`** — store and pass it to continue a conversation across page reloads.
* **Let the SDK handle uploads** — pass `File` objects; presigned-URL upload is automatic.

{% hint style="info" %}
The SDK manages socket connections and reconnection automatically, and shares the socket across instances that use the same `user` and `config`. For server-side or backend-only execution with no browser, use the **raw (HTTP)** client instead.
{% endhint %}

## How this relates to the agent's other settings

Whichever integration you choose, a few other settings shape how it behaves:

* [**Access & Security**](/ai-workbench-qore/console/agent-builder/deploy/authentication) — the Access Keys are the credentials your Embedded Chat widget, TypeScript SDK client, or Agent API integration uses; the Allowed Domains list governs where the widget and TypeScript SDK client can run.
* [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables) — the credentials and values the agent uses at runtime; the widget, SDK, and API all invoke the agent against these same configured secrets.

Tighten these before you publish embeds or share API credentials — once a widget is live on a page, every visitor reaches the agent through whatever auth and domain rules you have set.

{% hint style="info" %}
To export the agent's full configuration as a portable package instead of running it live, see [Export Agent](/ai-workbench-qore/console/agent-builder/deploy/export-agent).
{% endhint %}

***

{% 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 %}


# Access & Security

Issue the keys that let applications call the agent, and limit where its widget may run.

**Access & Security** controls how the agent is reached from outside the platform. It has two sections:

* **Access Keys**: the API keys and widget keys that applications use to call the agent.
* **Allowed Domains**: the web origins where the agent's embedded widget may run.

The keys and domains set here are the same ones the [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration) panel uses, so you can manage them from either place.

To open it, go to **Agent Config** and select **Access & Security** under *Credentials & access*.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-65405dddbef0788cdba754bc9c170147f9dba5a6%2Fqore_agent-builder_manage-agent-access-and-security_rounded_shadow.png?alt=media" alt="The Access and Security page in Agent Config, with the Access Keys table showing one active widget key and the Allowed Domains list below it"><figcaption><p>Access &#x26; Security, with Access Keys above and Allowed Domains below.</p></figcaption></figure>

### Access Keys <a href="#access-keys" id="access-keys"></a>

The **Access Keys** table lists the agent's credentials.

| Column     | What it holds                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| **Name**   | A friendly name for the key, for example `Default`, `Production Widget` or `Mobile API`.                         |
| **Key**    | The credential value, displayed masked as `********`. Select the copy icon beside it to copy the unmasked value. |
| **Type**   | **API Key** or **Widget Key**. See [Key types](#key-types).                                                      |
| **Status** | **Active**, or deactivated (the row is dimmed). A deactivated key is no longer accepted.                         |

Each row has a `⋯` menu with **Rename** and **Deactivate**.

### Key types <a href="#key-types" id="key-types"></a>

The type of key you create depends on how the agent will be called.

* **Widget Key**: used by the Embedded Chat widget and the TypeScript SDK client from [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration). It's safe to ship in browser code, because a widget key works only from the platform itself and the domains on the [Allowed Domains](#allowed-domains) list.
* **API Key**: a key and secret pair for server-to-server calls to the Agent API. The key is sent as `x-api-key`, and the secret as `x-api-key-secret`.

{% hint style="warning" %}
**The API secret is shown once, when the pair is generated.** The Access Keys table shows the key, never the secret. If you didn't record it, create a new API key and switch your integration to it. Keep both values server-side; the widget key is the only credential here that may ship in browser code.

One exception: **Download as MD** on the Agent API tab of Integrate Agent has an **Include secrets** option that writes the agent's API key and secret into the downloaded file. Treat that file as a credential.
{% endhint %}

### Working with keys <a href="#working-with-keys" id="working-with-keys"></a>

#### Adding a key <a href="#adding-a-key" id="adding-a-key"></a>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-c0c452c197b1ba4ac5c997e3705c0e518caacaef%2Fqore_agent-builder_manage-agent-access-and-security-add-key_rounded_shadow.png?alt=media" alt="The Add New Key dialog, with a Key Name field, a Key Type choice of API Key or Widget Key, and the Generate Key button"><figcaption><p>The Add New Key dialog.</p></figcaption></figure>

1. Select **+ Add Key**.
2. Enter a **Key Name**.
3. Choose the **Key Type**: **API Key** or **Widget Key**.
4. Select **Generate Key**.

The dialog then shows the new key, and for an API key, its **API Secret**. Copy both before you close the dialog: for security reasons, they can't be retrieved later.

#### Copying a key <a href="#copying-a-key" id="copying-a-key"></a>

Select the copy icon next to the masked key in the **Key** column. The platform places the unmasked value on your clipboard. The display stays masked.

#### Renaming or deactivating a key <a href="#renaming-or-deactivating-a-key" id="renaming-or-deactivating-a-key"></a>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-69ab1e50b75ddc378996cec6020e9089ddffe849%2Fqore_agent-builder_manage-agent-access-and-security-key-menu_rounded_shadow.png?alt=media" alt="The Access Keys table with a row&#x27;s menu open, showing Rename and Deactivate"><figcaption><p>Each key's menu.</p></figcaption></figure>

Open the `⋯` menu on the row:

* **Rename** changes the key's name. The key value doesn't change.
* **Deactivate** stops the key from being accepted. **This can't be undone**: a deactivated key can't be used again.

There's no rotate action. To replace a key, add a new one, move your integrations to it, then deactivate the old one.

> **Important** Treat the unmasked key as a secret. Anywhere the key is pasted (application code, environment variables, configuration files) should follow the same handling rules as any other credential. Do **not** paste it into Instructions or commit it to a public repository.

### Allowed Domains <a href="#allowed-domains" id="allowed-domains"></a>

**Allowed Domains** lists the web origins where the agent's embedded widget may run. A request made with a widget key is accepted only when the page it comes from is on this list, or is the platform's own domain. Anything else is refused. This is what stops your agent, and the data and quota behind it, from being embedded on a site you didn't authorize.

* **With the list empty, the widget runs nowhere outside the platform.** Add every domain where you embed it.
* **The list applies to widget keys only.** API-key calls are server-to-server and have no web origin, so they're checked by the key and secret alone.

#### Adding and removing domains <a href="#adding-and-removing-domains" id="adding-and-removing-domains"></a>

1. Select **+ Add New Domain**. A new row appears.
2. Enter the URL or domain in the **Enter URL** field.
3. To remove an entry, select the trash icon on its row.
4. Select **Save**. Changes take effect only after you save.

The **Whitelist domains** step of the Embedded Chat setup on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration#embedded-chat) adds to the same list.

{% hint style="warning" %}
Enter each domain exactly as the browser sends it, and test it against your intended origin before you rely on it in production. A mismatch in protocol, subdomain or port is refused like any other unlisted origin.
{% endhint %}

For each environment where the widget is embedded, add its specific origin:

* `https://app.example.com`: production app
* `https://staging.example.com`: staging environment
* `http://localhost:3000`: local development. Remove it before the agent goes to production.

### Security considerations <a href="#security-considerations" id="security-considerations"></a>

Three settings together govern how the agent is reached from outside:

* **Access Keys** on this page: which credentials are valid.
* **Allowed Domains** on this page: which web origins the widget may run on.
* [**Authentication**](/ai-workbench-qore/console/agent-builder/deploy/authentication-1): which person is calling, verified against your identity provider.

What kinds of integration you expose is set up on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration). A tight key list with a tight domain list produces an agent that's hard to call from anywhere you didn't intend. Loosening either one, by sharing one long-lived key everywhere or adding domains you don't need, widens the agent's exposure.

### Why this matters <a href="#why-this-matters" id="why-this-matters"></a>

Keys are how an integration introduces itself to the agent at runtime. A leaked key (pasted into a public repo, exposed in a client-side bundle, or caught in a screenshot) is effectively the right to call the agent on your behalf. Name keys descriptively so you know which to replace when something goes wrong, and give each integration its own key. Sharing one key across all of them means deactivating it takes every integration down at once. Audit the domain list the way you'd audit a firewall rule: add origins deliberately and remove the ones you no longer need.

***

{% 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 %}


# Authentication

Verify agent callers through your identity provider and pass their identity to MCP connections.

Authentication verifies a caller's Microsoft Entra ID or Google token before an agent run. Verified tokens are available to MCP connections as `$auth.token`, so downstream tools can apply the caller's permissions and audit trail.

Use Authentication with [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication).

* Authentication identifies the person.
* Access & Security authorizes the calling application.

{% hint style="warning" %}
Authentication does not require a token. Requests without one still run, but `$auth.token` is unavailable. Requests with an invalid token are rejected.
{% endhint %}

### Configure authentication

Register an application with your identity provider before you begin:

* **Microsoft Entra ID** — Register an application in your Entra directory.
* **Google** — Create an OAuth client in your Google Cloud project.

{% stepper %}
{% step %}

#### Enable authentication

Turn on **Enable Authentication**.
{% endstep %}

{% step %}

#### Select a provider

Choose a provider from **Authentication Provider**. The available fields update for that provider.
{% endstep %}

{% step %}

#### Enter provider details

Enter the required identifiers. See [provider requirements](#provider-requirements).
{% endstep %}

{% step %}

#### Save changes

Select **Save**. The control becomes available after a change.
{% endstep %}
{% endstepper %}

Turning Authentication off retains your provider details. The agent does not use them until you enable Authentication again.

### Provider requirements

{% tabs %}
{% tab title="Microsoft Entra ID" %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-bb544e5791b5e4327000f9824dbce153b365a1c9%2Fqore_agent-builder_manage-agent-authentication-entra_rounded_shadow.png?alt=media" alt="Authentication configured with Microsoft Entra ID, showing the Directory tenant ID and Application client ID fields."><figcaption><p>Authentication configured for Microsoft Entra ID.</p></figcaption></figure>

| Required value              | Where to find it                                      |
| --------------------------- | ----------------------------------------------------- |
| **Directory (tenant) ID**   | The **Overview** page for the Entra app registration. |
| **Application (client) ID** | The same **Overview** page.                           |

Qore accepts a token only when it is:

* Signed by your Entra directory.
* Issued by that directory's v2.0 endpoint.
* Intended for the configured application client ID.
  {% endtab %}

{% tab title="Google" %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2bd48db653d1394a849a1eb9e9a0bcb104507373%2Fqore_agent-builder_manage-agent-authentication-google_rounded_shadow.png?alt=media" alt="Authentication configured with Google, showing the OAuth client ID field."><figcaption><p>Authentication configured for Google.</p></figcaption></figure>

| Required value      | Where to find it                                                                         |
| ------------------- | ---------------------------------------------------------------------------------------- |
| **OAuth client ID** | The OAuth client in your Google Cloud project. It ends in `.apps.googleusercontent.com`. |

Send the Google OAuth access token from the user's sign-in. Qore verifies that Google issued it for the configured OAuth client ID.
{% endtab %}
{% endtabs %}

### Send the caller token

Send the caller's token with every agent request. Qore verifies it and exposes it to MCP connections as `$auth.token`.

{% tabs %}
{% tab title="Agent API" %}
Add `token` beside `message` in the trigger request body.

```bash
curl -X POST "<BASE_URL>/agent-executor/1.4/agents/:agentId/trigger" \
  -H "x-api-key: YOUR_AGENT_API_KEY" \
  -H "x-api-key-secret: YOUR_AGENT_API_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"message": "List my open approvals", "token": "<the caller'\''s identity token>"}'
```

{% endtab %}

{% tab title="Embedded Chat widget" %}
Pass the signed-in user's token using `authToken` in React or `auth-token` in HTML.

The widget sends it with new chats, follow-up turns, and permission or credential requests. A headless instance supports `setAuthToken()` for refreshed tokens.
{% endtab %}
{% endtabs %}

#### Setup Identity Token <a href="#setup-identity-token" id="setup-identity-token"></a>

{% hint style="warning" %}
**Available on request.** Setup Identity Token is switched on only for the clients who have asked for it. If your widget doesn't show **Developer Mode**, it isn't enabled for you.
{% endhint %}

Setup Identity Token lets you try an agent as a specific signed-in person by pasting their token by hand. When a widget is created with `allowDeveloperMode`, its sidebar shows a **Developer Mode** switch. Switch it on and, for an agent with authentication enabled, a **Setup Identity Token** action appears under **Start New Chat**. Paste a token there to try the agent as that person.

* The token lasts for the session and is never stored.
* A token passed as `authToken` replaces one entered by hand.
* In the Agent Playground, Developer Mode is not available in production.

#### Use the token in MCP connections

Reference `$auth.token` in an MCP connection configuration where the downstream server expects a user credential. Qore replaces it with the verified token during the run.

> `$auth.token` works only in MCP connection configurations. Skills and agent instructions cannot access it.

{% hint style="info" %}
If a request has no token, `$auth.token` resolves to an empty value. The downstream server receives an anonymous request.
{% endhint %}

Use `$auth.token` like the `$secret.` and `$agent.` values described in [Secrets & Variables](/ai-workbench-qore/console/agent-builder/build/secrets-and-variables). Ensure every caller sends a token when the downstream system requires a signed-in user.

### Request outcomes and token security

| Authentication                       | Token                                                | Result                                                                                              |
| ------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Off                                  | Any, or none                                         | The run proceeds. Qore ignores the token.                                                           |
| On                                   | None                                                 | The run proceeds without `$auth.token`.                                                             |
| On                                   | Valid                                                | The run proceeds. `$auth.token` contains the token.                                                 |
| On                                   | Invalid, or issued for another application or client | Rejected with `AGENT_AUTHENTICATION_FAILED`.                                                        |
| On                                   | Expired Microsoft Entra ID token                     | Rejected with `TOKEN_EXPIRED`.                                                                      |
| On                                   | Expired Google token                                 | Rejected with `AGENT_AUTHENTICATION_FAILED`. Google reports expired and invalid tokens identically. |
| On, with incomplete provider details | Any token                                            | Rejected with `AGENT_AUTHENTICATION_CONFIG_INVALID`. Update the agent configuration.                |
| On, when Google is unavailable       | Any token                                            | Fails with `GOOGLE_IDENTITY_SERVICE_UNAVAILABLE` and HTTP `503`. Retry the request.                 |

If Microsoft Entra ID is unavailable, Qore rejects the request with `AGENT_AUTHENTICATION_FAILED`.

#### Token security

* Qore encrypts the token before queuing the run.
* Qore decrypts it only to verify the token.
* Qore never stores the raw token.
* Execution-status responses exclude the raw token.
* The embedded widget keeps the token only in session memory.

{% hint style="warning" %}
Send tokens only from your application's authenticated session. Do not accept tokens from URLs, form fields, or other user-controlled inputs.
{% endhint %}

***

{% 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 %}


# Guardrails

Protect agent runs with PII masking, tool approval, and model policies.

Guardrails are the safety controls that protect your agent at every stage of a run — masking sensitive data before it reaches the model, pausing risky tool calls for human approval, and holding the agent to an approved set of language models. Find them at **Agent Config → Guardrails**, under *Cognition & Control*.

{% hint style="info" %}
**Beta.** Guardrails is a Beta feature — controls and labels may change.
{% endhint %}

### Configure guardrails

Use these pages to configure the guardrails that you manage per agent:

* [PII masking](/ai-workbench-qore/console/agent-builder/deploy/guardrails/pii-masking) — choose a detection provider, entity rules, and tokenization coverage.
* [Tool execution approval](/ai-workbench-qore/console/agent-builder/deploy/guardrails/tool-execution) — require a user’s approval before selected skills run.

## How guardrails work

Open the page from **Agent Config → Guardrails**. You'll see a single list of guardrails, each with a **Name**, a **Type**, and a **Status**. The header summarizes the set — for example, *"4 guardrails · 2 enforced by the AI Gateway."*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-4046e7a081a78fb1cc2cc0bba9378325af488b40%2Fqore_agent-builder_agent-builder-guardrail-tool-permission_rounded_shadow.png?alt=media" alt="The Guardrails list, with Name, Type, and Status columns for each guardrail"><figcaption><p>The Guardrails page, listing all four guardrails.</p></figcaption></figure>

The Status column holds two kinds of control:

* **Toggle** — you turn the guardrail on or off for this agent. *Sensitive Data Masking* and *Tool Execution Approval* work this way.
* **Always enforced** — the guardrail is locked on and can't be turned off here. *Allowed LLM Families* and *Allowed LLM Providers* work this way; they're enforced centrally by the [AI Gateway](/ai-workbench-qore/control-center/ai-gateway) — the platform layer every model request passes through — and set by your organization, not per agent.

To change what a toggleable guardrail covers, use the **gear** at the end of its row. That opens the guardrail's own configuration screen — the entity list for masking, or the skills list for tool approval.

| Guardrail               | Type              | Configurable here?                     |
| ----------------------- | ----------------- | -------------------------------------- |
| Sensitive Data Masking  | `Pii Masking`     | Yes — toggle + gear                    |
| Tool Execution Approval | `Tool Permission` | Yes — toggle + gear                    |
| Allowed LLM Families    | `Model Policy`    | No — always enforced by the AI Gateway |
| Allowed LLM Providers   | `Model Policy`    | No — always enforced by the AI Gateway |

## Model policy guardrails

*Allowed LLM Families* and *Allowed LLM Providers* are both `Model Policy` guardrails. They show as **Always enforced** — locked on and applied by the [AI Gateway](/ai-workbench-qore/control-center/ai-gateway) to every model request, so they can't be toggled off per agent. The approved sets are configured by your organization in the AI Gateway, not on this page.

### Allowed LLM Families

Restricts the agent to an approved set of model *families* — a family is a group of related models (for example, GPT or Claude). The agent can only use models from families your organization has approved.

### Allowed LLM Providers

Restricts the agent to an approved set of *providers* — the vendors that host the models (for example, OpenAI, Anthropic, AWS Bedrock, or Azure OpenAI). The agent can only route requests to providers your organization has approved.

## Guardrails page controls

<details>

<summary>UI inventory — the Guardrails page</summary>

| Element                   | Description                                                                                                  | When to use it                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| Header summary            | Count of guardrails and how many are gateway-enforced (e.g. *"4 guardrails · 2 enforced by the AI Gateway"*) | Read to confirm how many controls are active                        |
| **Name** column           | The guardrail's name                                                                                         | Identify the guardrail                                              |
| **Type** column           | The guardrail's category — `Pii Masking`, `Tool Permission`, or `Model Policy`                               | Tells you what the guardrail acts on                                |
| **Status** toggle         | Turns a toggleable guardrail on or off for this agent                                                        | Enable or disable Sensitive Data Masking or Tool Execution Approval |
| **Always enforced** badge | Marks a guardrail that is locked on by the AI Gateway                                                        | Signals a Model Policy guardrail you can't change here              |
| **Gear**                  | Opens the guardrail's configuration screen                                                                   | Configure the masking entities or the approval skills list          |

</details>

## Why this matters

* Guardrails catch problems at the earliest point they're detectable — before the model sees data, before a tool runs, before a disallowed model is used.
* Masking, tool approval, and model policy each protect a different stage of a run.
* The safe defaults (mask common PII, no forced approval, org-approved models) fit almost every agent.

## Related

{% content-ref url="/pages/zH9Bsg8FxRdLqitlHI8J" %}
[Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning)
{% endcontent-ref %}

{% content-ref url="/pages/rGXmqmGrFNaJnqEn7wCA" %}
[Monitor](/ai-workbench-qore/console/agent-builder/monitor)
{% endcontent-ref %}

{% content-ref url="/pages/I59HzEvpXa0tjAaqrtTo" %}
[Glossary](/ai-workbench-qore/start-here/glossary)
{% endcontent-ref %}

***

{% 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 %}


# PII masking

PII masking protects sensitive data before it reaches a model. The guardrail detects selected entity types and replaces their values with opaque tokens.

To configure it, open **Agent Config → Guardrails**. Turn on **Sensitive Data Masking**, then select the **gear** in that row.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-6a69a2869a5051ee5dcf2a8e22cc7149c2fcdc0e%2Fqore_agent-builder_guardrails-pii-tokenization_rounded_shadow.png?alt=media" alt="The Sensitive Data Masking guardrail toggled on in the Guardrails list, with the gear to open its configuration"><figcaption><p>Turning on Sensitive Data Masking.</p></figcaption></figure>

{% hint style="warning" %}
When this guardrail is off, content reaches the model unmasked. Enable it whenever the agent handles PII.
{% endhint %}

## Choose a masking provider

A provider detects PII in agent content. Choose one based on its coverage, accuracy, and latency.

| Provider                 | What it does                                    | Use it when                                                               |
| ------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------- |
| **AWS Comprehend**       | Managed ML detection with broad entity coverage | You need the widest catalog and can use a managed ML service              |
| **Azure Text Analytics** | Managed ML detection with EU identifiers        | You need EU-specific identifiers                                          |
| **Google Cloud DLP**     | Managed inspection with custom infoTypes        | You need a large catalog or custom infoTypes                              |
| **Regex**                | Pattern matching without ML                     | You need low latency for structured values, such as SSNs and card numbers |
| **Off**                  | Does not mask content                           | No PII flows through the agent                                            |

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-0874210598c54a6b6e8085c7e86e067b88132a88%2Fqore_agent-builder_guardrails-pii-tokenization-configure_rounded_shadow.png?alt=media" alt="The PII masking configuration screen, with a provider dropdown"><figcaption><p>Choosing a masking provider.</p></figcaption></figure>

The selected provider controls the available entity types. **Regex** exposes six types. **Google Cloud DLP** exposes 133 types. Managed-provider coverage reflects your tenant configuration.

## Set the entity rule

Use **Entity rule** to choose which detected entities are masked.

* **Deny list** masks only selected entity types. Add each type that needs protection.
* **Allow list** passes selected entity types through unchanged. It masks every other detected type.

Use **Select all** or **Clear** to update every entity. Use **Clear group** to reset one group. The page shows how many entity types are masked.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-1e762ee4d86c9050bbff13e3e20b77445e488a93%2Fqore_agent-builder_guardrails-pii-tokenization-configure-configure_rounded_shadow.png?alt=media" alt="The entity rule screen, with deny/allow list selection and entity groups"><figcaption><p>Setting the entity rule and selecting entity types.</p></figcaption></figure>

### Entity groups

Entity groups vary by provider. Use **Search** to find a specific type.

{% tabs %}
{% tab title="Regex (6 entities)" %}

* **Identity**: US SSN (`SSN`) and Passport (`PASSPORT_NUMBER`)
* **Contact**: Email (`EMAIL`) and Phone (`PHONE`)
* **Financial**: Bank account (`BANK_ACCOUNT_NUMBER`) and Card number (`CREDIT_DEBIT_NUMBER`)
  {% endtab %}

{% tab title="Google Cloud DLP (133 entities)" %}
Examples include:

* **Technical**: IP address (`IP_ADDRESS`)
* **Other**: Age (`AGE`) and Auth Token (`AUTH_TOKEN`)
* **Country-specific identifiers**: Argentina DNI, Australia Medicare, and Australia Tax File Number
  {% endtab %}
  {% endtabs %}

Select **Save** to apply provider or entity-selection changes.

## Understand tokenization

PII masking uses tokenization. The platform replaces a detected value with an opaque token before a model receives the content. The mapping is stored in a secure vault. A permitted downstream step can restore the original value when needed.

Selected entities are tokenized. Unselected entities bypass tokenization and reach the model unchanged. Tokenize all detected entities unless a clear requirement needs the original value.

Exclude an entity type only when:

* A downstream system requires the original value.
* A secure downstream step de-tokenizes the response.
* Detection for that type obscures required context.

{% hint style="info" %}
Tokenization requires a compatible executor version. When the agent uses an unsupported version, the entity list is read-only. Update the executor version in **Runtime & Versioning**.
{% endhint %}

## Review your configuration

Review the entity list when the agent’s responsibilities change. Every excluded type reaches the model in clear text.

For the parent-level overview, see [Guardrails](/ai-workbench-qore/console/agent-builder/deploy/guardrails).

***

{% 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 %}


# Tool execution

Tool Execution Approval adds human approval before an agent runs selected skills. A tool is a skill available to the agent.

To configure approval, open **Agent Config → Guardrails**. Turn on **Tool Execution Approval**, then select the **gear** in that row.

## Choose tools that need approval

The **Edit Tool Permission** screen lists every skill available to the agent. Each skill has its own approval toggle. A counter shows the number selected, such as *“18 of 19 skills selected.”*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2f1c10776ca70574ca470b3c7613deecee7f0412%2Fqore_agent-builder_guardrails-tool-execution-approval_rounded_shadow.png?alt=media" alt="The Edit Tool Permission screen, listing skills with per-skill approval toggles"><figcaption><p>The Edit Tool Permission screen.</p></figcaption></figure>

* **Enable for all skills** requires approval for every current and future skill. It overrides individual toggles.
* **Per-skill toggles** require approval for selected skills only.
* **Search skills** filters a large skill list by name.

The list includes built-in and added skills. Built-in examples include AI Reasoning, Web Search, Knowledge Search, Generate Custom Skill, and Extract Document Data (Legacy). The available set varies by agent.

Custom skills appear automatically. With **Enable for all skills** on, newly added skills inherit the approval requirement.

Select **Update Tool Permission** to save changes. Select **Cancel** to discard them.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-65c5e5fd47d559323a4bd3fb6d06f2a5ee0dfed1%2Fqore_agent-builder_guardrails-tool-execution-approval-update-permission_rounded_shadow.png?alt=media" alt="The Update Tool Permission and Cancel buttons on the Edit Tool Permission screen"><figcaption><p>Saving changes with Update Tool Permission.</p></figcaption></figure>

## What users see

When the agent reaches an approved tool, it pauses before the call. The chat shows guardrail activity, such as *“Running tool-permission guardrail for ‘Web Search’.”* It then asks the user whether the tool should proceed.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-921186e0e8556c8e764816cc7c20df85152c9379%2Fqore_agent-builder_guardrails-tool-execution-approval-web-search-prompt_rounded_shadow.png?alt=media" alt="The chat pausing on a Web Search tool call, asking the user to Allow or Deny"><figcaption><p>The runtime approval prompt for a paused tool call.</p></figcaption></figure>

* **Allow** runs the tool and continues the agent run.
* **Deny** blocks the tool call. The agent continues without it.

## Choose an approval strategy

Require approval for tools that take external actions or access sensitive data. Individual approvals work well when only a few skills need review.

Use **Enable for all skills** when every tool call requires confirmation. This setting also protects skills added after initial configuration.

For the parent-level overview, see [Guardrails](/ai-workbench-qore/console/agent-builder/deploy/guardrails).

***

{% 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 %}


# Monitor

Watch the agent in production and improve it from what you learn.

**Monitor** is where a live agent reveals what testing missed. Users ask unexpected questions. They use unfamiliar wording. Their data changes after you build the agent.

Use Monitor to inspect individual executions, score live conversations, and turn reviewed corrections into learning cases. Apply what you learn in [Build](/ai-workbench-qore/console/agent-builder/build), such as clearer instructions, a missing skill, or a knowledge gap.

### Review executions

Monitoring lists the agent's execution history. Each row represents one invocation, whether from the embedded widget, an API call, or a trigger.

Open **Control Center → Runs & Traces** to inspect an agent's production activity (see [Runs & Traces](/ai-workbench-qore/control-center/observe/runs-and-traces)). It used to be the **Monitoring** tab in Agent Config, which has been removed. The table includes stable identifiers for each execution and its conversation.

| Column              | What it shows                                                                             |
| ------------------- | ----------------------------------------------------------------------------------------- |
| **Execution ID**    | A unique run identifier. Select the copy icon to copy its full value.                     |
| **Agent Name**      | The agent that ran.                                                                       |
| **Conversation ID** | The conversation containing the execution. A conversation can include several executions. |
| **Created At**      | When the execution started.                                                               |

Use the agent filter above the table to inspect another agent in your tenant. This helps trace executions when one agent calls another.

#### Inspect an execution

Select a table row to open its execution trace. Review these details:

* **Skill selection** — Confirm the planner selected skills that match the request.
* **Skill results** — Find authentication errors, timeouts, and schema mismatches.
* **Guardrail results** — See which guardrail handled the execution and why.
* **Step timing** — Identify slow skill calls that increase agent latency.

Sample executions regularly to confirm expected behavior. When someone reports an unexpected response, use the Execution ID or Conversation ID to locate the exact trace.

### Improve production behavior

* [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval) — Score live conversations after release.
* [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) — Turn reviewed production feedback into reusable learning cases.

{% hint style="info" %}
Learning cases do not enter agent memory automatically. Each one is reviewed and approved by a person first — auto-approval is intentionally disabled, so a bad or malicious input cannot quietly teach the agent the wrong thing.
{% endhint %}

***

Validate improvements with [Evals](/ai-workbench-qore/console/agent-builder/test/evals) before rolling them out more broadly.

### Use account-wide governance

Monitor focuses on one agent's runs. Use [Governance](/ai-workbench-qore/control-center/governance) and [Control Center](/ai-workbench-qore/start-here/control-center) to investigate activity across your account.

* [Observe](/ai-workbench-qore/control-center/observe) — Review conversation volume, duration, and outcomes.
* [Evals](/ai-workbench-qore/control-center/evals) — Monitor quality scores and review low-confidence results.
* [Controls & Audit](/ai-workbench-qore/control-center/controls-and-audit) — Review guardrail results, emergency controls, and account changes.
* [Observe › logs](/ai-workbench-qore/control-center/observe) — Trace model calls, API requests, and database operations.

***

{% 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 %}


# Online-Eval

Score every live conversation automatically, in the background, without affecting end users.

Online Evals is the production-side evaluation system on the Uptiq Platform. Once an agent is deployed, it runs by itself on real conversations, without anyone asking it to. The grading happens off to the side — not in the path of the actual response. If the grading itself fails for any reason — a timeout, an error — that failure gets logged and retried, but it never touches the live conversation. The user never sees it, never feels it.

| Capability              | Description                                                                  |
| ----------------------- | ---------------------------------------------------------------------------- |
| Background scoring      | Runs automatically on completed conversations, off the critical path         |
| Configurable scorers    | Define which quality dimensions are evaluated, with custom prompts           |
| Performance dashboard   | Current scores, trends over time, and drill-down to specific conversations   |
| Threshold alerting      | Get alerted when quality drops past a threshold you've set                   |
| Feedback loop           | Production problems feed back into the next round of building, done manually |
| Failure isolation       | Grading failures are logged and retried — never touch the live conversation  |
| Model-provider agnostic | Works regardless of which LLM powers the agent or the grader                 |

{% hint style="info" %}
Online Evals is the runtime counterpart to [Evals](/ai-workbench-qore/console/agent-builder/test/evals). Use Evals to validate quality before deployment, Online Evals to score live traffic after deployment, and [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) to turn reviewed feedback into approved learning cases.
{% endhint %}

Online Evals is accessed from the **Cognition & Control** section in the Agent Builder's "Agent Config" modal sidebar. The interface has two tabs:

* **Scorers** — Configure which quality dimensions are evaluated
* **Runs** — View evaluation run history and results

***

## How It Works

Once the agent is live, Online Evals takes over automatically:

1. End users invoke the agent in real conversations
2. Online eval runs in the background — non-intrusive
3. Performance results stream to the Maintainer's dashboard
4. Maintainer tracks agent performance over time
5. **Performance drift or regression?**
   * **No** → Keep watching
   * **Yes** → Iterate and refine the agent — feeds back to the builder

If something's drifted, that loops back to whoever built the agent, so production problems actually feed back into the next round of building — not just into a report nobody reads.

***

## Dashboard

What comes out of Online Evals lands on a dashboard for whoever's maintaining the agent:

* **Current performance** — How the agent is scoring right now
* **Threshold suggestions** — If quality drops past a threshold score, suggestions pop up
* **Drill-down** — Click into a metric and see exactly which real conversations are dragging the score down

***

## Guardrails and Governance

Who can do what is enforced at the platform level — it's a permission boundary, not a process people are trusted to follow. Builders get the offline/testing side, Maintainers get the live monitoring side.

Whatever real conversation data feeds the online evals still respects tenant isolation and PII rules — it's not an open pipe into live data.

Online Evals works the same regardless of which LLM provider is behind either the agent or the grader.

### Related sections

* [Monitoring](/ai-workbench-qore/console/agent-builder/monitor) — Track production health and investigate runtime issues.
* [Evals](/ai-workbench-qore/console/agent-builder/test/evals) — Validate changes against test datasets before rollout.
* [Reinforcement Learnings](/ai-workbench-qore/console/agent-builder/monitor/reinforcement-learnings) — Review approved corrections from real conversations.

***

{% 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 %}


# Reinforcement Learnings

Turn reviewed production feedback into approved learning cases.

Reinforcement Learnings closes the loop between production behavior and future agent performance. It captures reviewed corrections from real usage and turns approved feedback into reusable learning cases.

### What it does

Use Reinforcement Learnings to improve the agent from its own history. It helps teams collect issues found in production, review what the correct behavior should have been, and preserve approved corrections for future use.

This gives you a structured path from observed misses to durable improvements.

### Approval flow

Learning cases do not enter memory automatically. Each case must be reviewed and approved before it is added.

{% hint style="warning" %}
Approval is manual. Auto-approval is intentionally disabled.
{% endhint %}

### How it fits with the rest of Agent Config

Use [Monitoring](/ai-workbench-qore/console/agent-builder/monitor) and [Online-Eval](/ai-workbench-qore/console/agent-builder/monitor/online-eval) to find misses in production. Use [Evals](/ai-workbench-qore/console/agent-builder/test/evals) to validate improvements before you roll them out more broadly.

Reinforcement Learnings connects those steps. It carries reviewed feedback forward so the agent improves from real outcomes, not just isolated test runs.

***

{% 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 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).

</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).

</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).

</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#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).

</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#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#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#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).

</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#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#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#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#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#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).

</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#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#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#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).

</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#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#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).

</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#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#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).

</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#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#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#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#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#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#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#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#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#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).

</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#troubleshooting).

</details>

### Related

* [Get Started](/ai-workbench-qore/console/agent-builder/get-started), [The Canvas](/ai-workbench-qore/console/agent-builder/the-canvas), [Build](/ai-workbench-qore/console/agent-builder/build), [Deploy](/ai-workbench-qore/console/agent-builder/deploy), and [Monitor](/ai-workbench-qore/console/agent-builder/monitor)
* [Create an agent](/ai-workbench-qore/task-guides/create-an-agent) and [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent): 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 %}


# App Builder

Build, test, publish, secure, and monitor applications in Qore Console.

App Builder is where you create applications in Qore Console. Start from a prompt, an existing codebase, or your own IDE. Then build, preview, test, secure, and publish the app in one live workspace.

Build the interface users touch, and connect agents from [Agent Builder](/ai-workbench-qore/console/agent-builder) behind it. Attach requirements or screenshots, connect data, and refine the app as you work.

App Builder is part of **Console**. Use Console to build and run apps. Use **Control Center** to monitor and govern running apps across your account.

## Start an app

You can start in two ways:

* **Create a new app** — Describe the app in plain language, or start with a template.
* **Bring in an existing app** — Import a Platform package, a Git repository, or a project from another builder. You can also connect your IDE over MCP.

Both paths open the [App Workspace](/ai-workbench-qore/console/app-builder/app-workspace), where you do the rest of the work.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-0faac31e0306735da5540c50ca46f907c6eb3522%2Fqore_console_console-app-builder-apps-list_rounded_shadow.png?alt=media" alt="The App Builder landing screen, with the Create New App prompt and a My Apps list showing draft apps"><figcaption><p>The App Builder landing screen.</p></figcaption></figure>

Below the prompt, **My Apps** lists your apps, each with its status (**Draft** or **Published**) and when it was last updated. Narrow the list with **Search apps…** and the **All**, **Published**, and **Draft** filter. Both are kept in the page address, so reloading the page or sharing its link opens the same filtered list.

Each app's **•••** menu has **Export App**, which opens the same **Export App Package** dialog as the app workspace, and **Delete App**, which deletes the app.

## Build an app

{% stepper %}
{% step %}

#### Describe your idea

Describe the app in plain language. Use **Plan Mode** to align on logic before code changes.
{% endstep %}

{% step %}

#### Configure components

Set up the front end, back end, and agents that power the app.
{% endstep %}

{% step %}

#### Connect services

Link services, databases, and APIs.
{% endstep %}

{% step %}

#### Test and refine

Test functionality, review responses, and address gaps.
{% endstep %}

{% step %}

#### Publish and monitor

Publish the app, then track its usage and cost.
{% endstep %}
{% endstepper %}

Use [Plan](/ai-workbench-qore/console/app-builder/plan) to define the blueprint. Use [Build](/ai-workbench-qore/console/app-builder/build) to generate and extend the app. Use [Test](/ai-workbench-qore/console/app-builder/test), [Deploy](/ai-workbench-qore/console/app-builder/deploy), and [Operate](/ai-workbench-qore/console/app-builder/operate) to take it live and manage it.

{% hint style="info" %}
**Mobile** is a beta app target. **Flow Engine** is a preview area of Console.

**Mobile backend support and store-ready packaging:** Build mobile apps with backend integration. Generate Android packages that are closer to Google Play publishing requirements.
{% endhint %}

## Explore App Builder

{% content-ref url="/pages/db6b18a9a31d8092c1e9b584cdbb9931cc4fea13" %}
[Importing apps](/ai-workbench-qore/console/app-builder/creating-and-importing-apps)
{% endcontent-ref %}

{% content-ref url="/pages/bc7662d99efc00ab94438c3b32248b84a7af247f" %}
[App Workspace](/ai-workbench-qore/console/app-builder/app-workspace)
{% endcontent-ref %}

{% content-ref url="/pages/6de8c0921a81fc6dc038359c161a4825e5e9aa3e" %}
[App Config](/ai-workbench-qore/console/app-builder/build/app-config)
{% endcontent-ref %}

{% content-ref url="/pages/fadca3113941216b965e532881dffdc606cd4f86" %}
[DB Explorer](/ai-workbench-qore/console/app-builder/build/db-explorer)
{% endcontent-ref %}

{% content-ref url="/pages/4844ee4b9bc46117ccc5a5bc36b61b43cb4a3936" %}
[Data Flow](/ai-workbench-qore/console/app-builder/build/data-flow)
{% endcontent-ref %}

{% content-ref url="/pages/c10eed6161aadb656ac4137fce98a06ced6ec452" %}
[Testing](/ai-workbench-qore/console/app-builder/testing)
{% endcontent-ref %}

{% content-ref url="/pages/9006766511be37fb1fe542c48dd782896979a34b" %}
[Security Scans](/ai-workbench-qore/console/app-builder/security-scans)
{% endcontent-ref %}

{% content-ref url="/pages/8702fcc339f8f48ebac028fe6ea122c072838cf2" %}
[Analytics](/ai-workbench-qore/console/app-builder/analytics)
{% endcontent-ref %}

For common questions and fixes, see [App Builder: FAQs & Troubleshooting](/ai-workbench-qore/console/app-builder/app-builder-faqs-and-troubleshooting).

***

{% 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 %}


# Importing apps

Create apps from prompts, packages, repositories, or your own IDE.

There are four ways to get an app into App Builder:

* Describe a new one from a prompt
* Import a project you already have
* Bring in a Git repository
* Connect your own IDE

This page covers each.

## Create a new app from a prompt

On the App Builder home, describe the app you want to build in the **Describe the app you want to create…** box, choose what kind of app it is, pick the model that builds it, and start the build. Qore opens the [app workspace](/ai-workbench-qore/console/app-builder/app-workspace) and works through your request. If you'd rather not start from scratch, pick one of the starter templates offered beneath the prompt.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-097424e10a66f71a5b21aae357602ac2049cef70%2Fqore_app-builder_studio-app-builder-import-an-existing-app-new-app_rounded_shadow.png?alt=media" alt="The app creation prompt box, with Web/Mobile target and model selection"><figcaption><p>Describing a new app and choosing its target and model.</p></figcaption></figure>

The app type menu, which reads **Web App** by default, offers three types:

* **Web App** — Traditional web app with pages, data and a backend.
* **Website** — Landing pages, marketing websites, SEO friendly.
* **Mobile (Beta)** — Native mobile app for Android and iOS.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-cc4275ef342e83a402bc88d0eab39ce5abf69917%2Fqore_app-builder_how-to-target-menu_rounded_shadow.png?alt=media" alt="The app type menu open, listing Web App, Website, and Mobile (Beta), each with a one-line description"><figcaption><p>The three app types.</p></figcaption></figure>

To change the model, open the model menu beside the app type, which shows the current model, such as **Gemini 3 Flash Preview**. Each model carries its provider's logo: Claude for Anthropic, Gemini for Google, and OpenAI. A model from any other provider shows a generic sparkle icon. When the list holds more than six models, a **Search models** box at the top lets you type part of a name to narrow it. The current model is ticked.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-45937a64677f46c12ffd405a642f9f40bcc517d3%2Fqore_app-builder_create-new-app-model-search_rounded_shadow.png?alt=media" alt="The Create New App prompt with the model menu open: a Search models box above a list of models, each with its provider&#x27;s logo, and Gemini 3 Flash Preview ticked"><figcaption><p>Search the model menu, and see each model's provider at a glance.</p></figcaption></figure>

## Import an existing app

Choose **Import an existing app** to bring in an app you already have. You can supply it three ways:

* **Upload a package or project** — drag in, or select, a ZIP file up to 500 MB.
* **GitHub** — import a repository.
* **GitLab** — import a project.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2213490a2da56f85fc7a37ceb5dbf7f2e3f5f8fd%2Fqore_app-builder_studio-app-builder-import-an-existing-app_rounded_shadow.png?alt=media" alt="The Import an existing app dialog, with Upload, GitHub, and GitLab options"><figcaption><p>The three ways to import an existing app.</p></figcaption></figure>

{% hint style="info" %}
A Qore **Platform package** is restored as-is — it comes back exactly as it was. Anything else — a Git repository, or a project exported from Lovable, v0, Bolt, or Figma Make — is **converted** into a Platform app. Expect a conversion step, not a byte-for-byte restore, for non-Platform sources.
{% endhint %}

### Import from GitHub

Choose **GitHub**, then:

{% stepper %}
{% step %}

#### Pick the connected account

{% endstep %}

{% step %}

#### Choose a Repository

{% endstep %}

{% step %}

#### Choose a Branch

This only becomes available once you've selected a repository.
{% endstep %}

{% step %}

#### Select Continue

Import that repository and branch.
{% endstep %}
{% endstepper %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-28adf5eaaaed370cdf69174f6f72eae92a1de911%2Fqore_app-builder_studio-import-an-existing-app_rounded_shadow.png?alt=media" alt="The App Builder home, with the app creation prompt and the option to import an existing app"><figcaption><p>Starting a new app or importing an existing one from App Builder's home.</p></figcaption></figure>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-dcdfc72d151e089f0f9d39905fc224626ee7e09e%2Fqore_app-builder_studio-app-builder-import-an-existing-app-git-hub_rounded_shadow.png?alt=media" alt="The GitHub import flow, with account, repository, and branch selection"><figcaption><p>Importing a repository from GitHub.</p></figcaption></figure>

### Import from GitLab

Choose **GitLab**. If your GitLab account isn't connected yet, select **Connect GitLab** first, authorize Qore, and return to the tab to browse your projects.

{% hint style="info" %}
GitHub lets you select a repository and branch right away. GitLab requires an account connection before you can browse projects.
{% endhint %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-4fd5e01ff9cb15a33754a7717649001ca4430aa8%2Fqore_app-builder_studio-app-builder-import-an-existing-app-git-lab_rounded_shadow.png?alt=media" alt="The GitLab import flow, with project selection"><figcaption><p>Importing a project from GitLab.</p></figcaption></figure>

{% hint style="info" %}
Connecting GitHub or GitLab grants Qore access to your source account. Connect only the account you intend to import from.
{% endhint %}

## Build from your IDE

Choose **Build from your IDE** to connect an app to an MCP-capable coding agent — for example Claude Code or Cursor — so you can build it from your own editor.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-103184cd55ae1c4f8ff77280d951e80b16aef91e%2Fqore_app-builder_how-to-build-from-your-ide_rounded_shadow.png?alt=media" alt="The Build from your IDE dialog: an example claude mcp add command for Claude Code with the server address blurred, the required x-platform-key header, and an API keys section with Add Key and No keys yet"><figcaption><p>The Build from your IDE dialog.</p></figcaption></figure>

{% stepper %}
{% step %}

#### Create an API key

In the **Build from your IDE** dialog, under **API keys**, select **+ Add Key** and name it. The key connects your editor to this app. Each key shows its **Name**, a masked value, and a **Status**, and can be revoked at any time with **Revoke**. Before you've made one, the list reads *No keys yet.*
{% endstep %}

{% step %}

#### Add the App Builder MCP server to your editor

Copy the connection command and run it in your coding agent, replacing `<YOUR_API_KEY>` with the key you created. The endpoint is `<BASE_URL>/app-builder/api/v1/mcp` and every request must carry the header `x-platform-key`. Replace `<BASE_URL>` with the Qore API host your organization uses — confirm it with your platform administrator, as it differs by deployment.

{% code title="Add the App Builder MCP server (Claude Code)" overflow="wrap" %}

```bash
claude mcp add --transport http app-builder <BASE_URL>/app-builder/api/v1/mcp \
  --header "x-platform-key: <YOUR_API_KEY>"
```

{% endcode %}
{% endstep %}

{% step %}

#### Build from your editor

With the server connected, your coding agent can build this app directly from your IDE.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
An API key is a credential — it grants an external tool access to build this app. Store it securely, and **Revoke** any key you no longer use.
{% endhint %}

## Why this matters

* You can start an app however suits you — a prompt, a package, a repository, or your own editor.
* What you import determines what you get: a Platform package restores exactly; everything else is converted.

## Related

{% content-ref url="/pages/bc7662d99efc00ab94438c3b32248b84a7af247f" %}
[App Workspace](/ai-workbench-qore/console/app-builder/app-workspace)
{% endcontent-ref %}

***

{% 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 %}


# App Workspace

Build, preview, inspect, test, version, and share your app.

The app workspace is where you build, inspect, test, and share an app. Describe a change, review the live preview, then move through the App Builder workflow.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-af73c769ef5a758d0be029d8ed48258e46258bd8%2Fqore_app-builder_studio-import-an-existing-app-example_rounded_shadow.png?alt=media" alt="The app workspace, with the build conversation, live preview, and workspace panels"><figcaption><p>The app workspace.</p></figcaption></figure>

<table data-view="cards"><thead><tr><th>Next step</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td>Set up data, domains, and integrations</td><td><a href="/ai-workbench-qore/console/app-builder/build/app-config">App Config</a></td></tr><tr><td>Validate the app before release</td><td><a href="/ai-workbench-qore/console/app-builder/testing">Testing</a></td></tr><tr><td>Publish the current version</td><td><a href="/ai-workbench-qore/console/app-builder/deploy">Deploy</a></td></tr></tbody></table>

### Describe and build

Use the conversation to describe the change you want. Qore plans the work, waits for your approval, builds the app, and confirms when **Live preview is ready**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-50b60905dafa474b902a8b656f6761bc1a5ab7a6%2Fqore_app-builder_studio-app-builder-building-by-chatting_rounded_shadow.png?alt=media" alt="The build conversation, describing a change and showing the plan/approve/build flow"><figcaption><p>Describing a change in the build conversation.</p></figcaption></figure>

Each turn shows its work time and token usage. Open the token total for model-level input and output usage.

While the build agent works, the conversation shows **Working…** and each step it takes, such as finding, reading, or running files, with a tick when each is done. Select **Stop** to stop it.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a97c8e1d9322749f8dc7a61f95b790cac52b3363%2Fqore_app-builder_how-to-build-agent-working_rounded_shadow.png?alt=media" alt="The build conversation with the agent Working, listing its steps with ticks, and a Stop button above the Describe the changes you want box"><figcaption><p>The build agent at work, with Stop.</p></figcaption></figure>

A single request can run for up to 45 minutes. If it runs longer, Qore stops it, saves the work done so far, and replies: *This request ran too long and was stopped. The work done so far is saved — send a follow-up to continue, or split the request into smaller steps.* If code generation fails, the reply reads *We are currently experiencing an issue with code generation. Please try again or switch to a different model.*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-5414d627a0eb7c928e1a7610b3b577c47fa8a2c5%2Fqore_app-builder_studio-import-an-existing-app-token-usage_rounded_shadow.png?alt=media" alt="The token usage breakdown for a build turn, showing model-level input and output usage"><figcaption><p>Model-level token usage for a build turn.</p></figcaption></figure>

#### Fix errors

Forward a preview error to the build agent. When the preview hits an error, a bar at the bottom of the build conversation shows it — for example `UNHANDLED_REJECTION` — with **Fix with AI**. Select **Fix with AI** to send it. The request includes the error type and message. Qore fixes the app and rebuilds the preview.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-463a070e45de3fa2fdb0ae83fca36205f8ef3906%2Fqore_app-builder_how-to-error-bar-fix-with-ai_rounded_shadow.png?alt=media" alt="The build conversation ending with a summary of changes, Live preview is ready, Upgrade your app with Add an AI Agent, and a red error bar reading UNHANDLED_REJECTION with a Fix with AI button"><figcaption><p>A preview error, with Fix with AI.</p></figcaption></figure>

{% hint style="info" %}
Fixing an error is another conversation turn. Describe or forward the error, then review the rebuilt preview.
{% endhint %}

{% hint style="info" %}
**Fix with AI** sends the reported issue to Qore's build agent. Review the rebuilt preview before you continue.
{% endhint %}

### Continue building

Choose a suggested next step, or enter another request. **Upgrade your app** can add a database for persistent data or an AI agent for app intelligence — for example **Add an AI Agent** (*Connect intelligence to your app*).

{% hint style="info" %}
Each round follows the same flow: plan, approve, and build. Nothing is built before you approve the plan.
{% endhint %}

### Preview

Use the live preview after every change. The toolbar above it has reload and full-screen icons, and desktop, tablet, and mobile widths to check responsiveness. Each preview includes a **Built with QORE** badge.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-742aacd258d719f3f56dc1468fd251cf7d4ad01b%2Fqore_app-builder_how-to-preview-toolbar_rounded_shadow.png?alt=media" alt="The Preview tab showing a running app, with reload, full-screen, and desktop, tablet and mobile icons above it, and a Built with QORE badge"><figcaption><p>The live preview.</p></figcaption></figure>

### Explore the workspace

Switch the centre panel between **Preview**, **Code**, and **Agents**.

#### Code

* Inspect the generated source in the file tree. It includes the frontend, tests, project configuration, `app.run.json`, and `APPLICATION_PLAN.md`.
* Select a file to read it, edit it, download it, or connect its repository to GitHub. To edit, select **Edit**, make your changes, then select **Save**. Saving an edit creates a new version.
* Use the build conversation for most app changes.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2dd359973434e54b175c7b7f97f6915d7a1fc201%2Fqore_app-builder_studio-app-builder-code-edit_rounded_shadow.png?alt=media" alt="The Code panel, showing the generated file tree and an open source file"><figcaption><p>Inspecting and editing generated source in the Code panel.</p></figcaption></figure>

#### Agents

* Use **Agents** to add automation, data processing, and logic.
* Select **Build an Agent** for a new agent, or **Attach Agents** for an existing one.
* For attachment steps, see [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-26aef8aadd88fb89c9bf6b17c8a0f723b59715b7%2Fqore_app-builder_studio-app-builder-agents-attach-agents_rounded_shadow.png?alt=media" alt="The Attach Agents dialog, listing existing agents to attach to the app"><figcaption><p>Attaching an existing agent to the app.</p></figcaption></figure>

### Credits

The Credits meter shows what this app has consumed—the Credits used, the Cost, and when the figure was last synced. Building an app spends credits, so keep an eye on it as you iterate. For account-wide usage and limits, see [Billing](/ai-workbench-qore/control-center/cost-control).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-cbaea4971b83d7524e46d3967d5decf8ef2d0648%2Fqore_app-builder_studio-import-an-existing-app-example-credits-usage_rounded_shadow.png?alt=media" alt="The Credits meter, showing credits used, cost, and last synced time"><figcaption><p>The Credits meter.</p></figcaption></figure>

### Versions and publishing

The version selector lists builds newest first. **Latest** marks the newest build. **Published** marks the version users see. *Uncommitted changes* marks work outside a version.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-eeb65a4b742e2c0c55d8c41c2fdf8bb1c7f714c1%2Fqore_app-builder_studio-import-an-existing-app-example-version_rounded_shadow.png?alt=media" alt="The version selector, listing builds newest first with Latest and Published markers"><figcaption><p>The version selector.</p></figcaption></figure>

Select a version in the selector. **Preview Version** opens for it, for example: *You are about to view Version 5.0.0 from Sep 11, 2026, 9:50 PM. This will temporarily load the selected version. Your current version will remain unchanged.* Choose one:

* **View Version** (for example **View Version 5.0.0**) — loads that version temporarily.
* **Revert to Version** (for example **Revert to Version 5.0.0**) — reverts the app to that version.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-6a6a2a5fb631324f8e6194d88920f634f682f61c%2Fqore_app-builder_how-to-version-preview-dialog_rounded_shadow.png?alt=media" alt="The Preview Version 5.0.0 dialog: you are about to view Version 5.0.0 from Sep 11, 2026, 9:50 PM; this will temporarily load the selected version and your current version will remain unchanged; Revert to Version 5.0.0 and View Version 5.0.0 buttons"><figcaption><p>Preview Version.</p></figcaption></figure>

While you view an older version, a bar reads **Viewing Version** with the version number, for example **Viewing Version 5.0.0**. Select **Back to Latest** to return to the newest version, or **Revert to Version** to revert to the one you're viewing.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-ee43eddf3e3398f3e6042df8b1b5ce3a96519b7a%2Fqore_app-builder_how-to-version-viewing-bar_rounded_shadow.png?alt=media" alt="A bar reading Viewing Version 5.0.0, with Back to Latest and Revert to Version 5.0.0 buttons"><figcaption><p>Viewing an older version.</p></figcaption></figure>

To make a version live, follow [Deploy an app](/ai-workbench-qore/console/app-builder/deploy).

### Share

Select **Share**, beside the version selector, to share the app.

### Export

Select the export icon in the workspace top bar, beside **Share**, to bundle the app into one package: its frontend, backend, AI agent logic, database schema, and cloud storage configuration. You need the **Export App** capability; without it the button is disabled. It isn't shown while the app is still in its initial plan.

In the **Export App Package** dialog, tick **Include chat history in package** if you want the build conversation in the package (it's off by default), then select **Export Package**. The package isn't downloaded in your browser. Qore shows *Export started. You will receive an email when it is ready.*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-0574ffa93330ec60348a2711e373e0c461285a5f%2Fqore_app-builder_how-to-export-app-package_rounded_shadow.png?alt=media" alt="The Export App Package dialog, with the Include chat history in package checkbox and Cancel and Export Package buttons"><figcaption><p>Export App Package.</p></figcaption></figure>

### More

The **More** menu reflects the selected build version. Use it to inspect:

* [Analytics](/ai-workbench-qore/console/app-builder/analytics) for published-app engagement
* [DB Explorer](/ai-workbench-qore/console/app-builder/build/db-explorer) and [Data Flow](/ai-workbench-qore/console/app-builder/build/data-flow) for app data and architecture
* [Testing](/ai-workbench-qore/console/app-builder/testing) and [Security Scans](/ai-workbench-qore/console/app-builder/security-scans) before release

***

{% 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 %}


# Plan

Define requirements and architecture before generating app code.

Building a great financial app starts with a solid blueprint. This phase establishes core logic, team alignment, and architectural integrity **before** generating code.

* **Objective**: Define application requirements and vet logic using **Plan Mode**.
* **Outcome**: An accurate blueprint that eliminates technical guesswork and reduces technical debt.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FaEPTi5AlV5EL5lkemINw%2Fimage.png?alt=media&amp;token=8d3fa412-bfab-434b-b650-df9cebf234ff" alt=""><figcaption><p>The Platform Planner proposing a structured architecture for a Subscription Management Hub.</p></figcaption></figure>

{% hint style="info" %}
Planning is optional. **Build Mode** is the default, and for a small or well-understood app you can prompt straight into [Build](/ai-workbench-qore/console/app-builder/build). Switch to Plan Mode from the header dropdown when the logic is complex, regulated, or needs sign-off before code exists.
{% endhint %}

## Plan Mode

Think of **Plan Mode** as your strategic sandbox for talking through the "why" and "how" of your application.

* **Logic Mapping**: Map out complex workflows, such as loan eligibility or KYC processes, before committing to a build.
* **Transparency**: Toggle the **"Thought"** dropdown to view the AI's reasoning and ensure alignment with business goals.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FrYx0RRPW6HWhtZtgQe6A%2Fimage.png?alt=media&amp;token=51e2c411-749a-473a-836d-bb69d5ce022d" alt=""><figcaption><p>Reviewing proposed logic and "Extra Ideas" generated by the AI System Planner.</p></figcaption></figure>

{% hint style="warning" %}
The **Publish** action is unavailable while in Plan Mode. To share early work with stakeholders, add them as collaborators from **Share** instead — see [Collaboration](#collaboration) below.
{% endhint %}

## Iterative building

Refine and adjust your requirements in real time using the chat with the Planner.

* Use **"Revise plan"** to add features or modify logic (e.g., "Add a masked payment method column").
* Experiment with different data models or structures without overwriting a working build.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FQo9GIxrEKaWsgkyQDP7E%2Fimage.png?alt=media&amp;token=32eeb5e6-2d6f-4411-b98a-e16729bec4bd" alt=""><figcaption><p>Using the chat and 'Revise plan' to iteratively update the blueprint before the build phase.</p></figcaption></figure>

## Template Marketplace

Use industry-standard templates to bypass boilerplate setup and establish a functional baseline.

* Select a financial template (e.g., Budget Tracker) from the dashboard.
* Templates come with pre-configured layouts and common components, so you can focus your energy on your unique proprietary logic.
* Once you load a template, you can use **Plan Mode** to strip it down, add new features, or completely rebrand it to match your bank's identity.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FOhi15Zu1iqBojNdXHXgh%2FBudgetTrackerTemplate.png?alt=media&amp;token=f22c0d8f-fbda-45f0-a8a6-2d809498464d" alt=""><figcaption><p>Create New App from the Template Marketplace</p></figcaption></figure>

## Version history

Manage project iterations and eliminate the risk of failed experiments during the design phase.

* Access the **Version** dropdown to view previous prompts and architectural states.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2F807mEwc7bJJSdSWB8SeN%2Fimage.png?alt=media&amp;token=a8ea24a2-f555-4074-bdf3-7736828926b9" alt=""><figcaption><p>Rollback to a previous version.</p></figcaption></figure>

* Choose to either **View Version** to load it temporarily, or **Revert to Version** to restore it. While you view a version, **Back to Latest** returns you to the newest one. See [App Workspace › Versions and publishing](/ai-workbench-qore/console/app-builder/app-workspace#versions-and-publishing).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FLp9obdDGVYyBmIHTfRFd%2Fimage.png?alt=media&amp;token=a1ac67a6-0bc3-448f-98dc-863dd5e44265" alt=""><figcaption><p>View or Revert to a version</p></figcaption></figure>

## Collaboration

Shipping enterprise apps requires input from multiple experts to vet compliance and UI design.

* Use **Share** to bring in developers, risk officers, or co-founders via email.

{% hint style="warning" %}
**Sharing grants access at the account level.** Inviting someone by email adds them to the account as a collaborator, which lets them open, edit and publish apps across that account — not only the one you shared. Per-app access levels and public view-only links are not available today. Check with your platform administrator before sharing an app that contains sensitive material.
{% endhint %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FT4chneGfEz2f5PolfXnW%2Fimage.png?alt=media&amp;token=b4b8ac54-42ae-4a2c-87e8-a6420f9439c1" alt=""><figcaption><p>Share Project where owners can manage collaborator emails and access levels.</p></figcaption></figure>

***

When the blueprint is right, click **Start building** — or read [Build](/ai-workbench-qore/console/app-builder/build) first.

***

{% 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 %}


# Build

Generate, customize, and connect production-ready apps from your requirements.

**Build** is where the App Builder converts your blueprint into a functional, production-ready React application, and where you shape how it looks and what it can reach.

**Build Mode is the default.** Every prompt you send initializes active code execution rather than strategic discussion — you do not need to turn it on. Switch to [Plan Mode](/ai-workbench-qore/console/app-builder/plan) from the header dropdown only when you want to align on logic before executing changes.

## Initialising the build

Transitioning from a concept to a functional React application depends on whether you are starting fresh or iterating on a saved project.

* **New Apps**: Enter your intent into the dashboard prompt bar and select **Build** to trigger immediate generative execution.
* **Existing Apps**: Locate the project in the **My Apps** section of your dashboard. Clicking the app restores the workspace for further iterative shaping.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FE8w5sINrjCzJpCQPlboY%2FSmartBudgetTrackerBuild1.png?alt=media&amp;token=62aafc90-7b42-42f9-8d0e-2ae76ba3849a" alt=""><figcaption><p>A successfully initialized personal finance tracker showing the live functional prototype, transaction logging, and implemented visual analytics.</p></figcaption></figure>

### What generation does

* **Prompt-Driven Development:** Describe what you need — for example, *"Build a loan calculator that adjusts interest rates based on credit score inputs."*
* **High-Velocity Infrastructure:** The engine writes the frontend React components, structures application state management, and implements persistent `localStorage` out of the box.
* **Real-Time Preview:** Production-ready code compiles into an interactive mockup side by side with your chat timeline. If something isn't right, send a follow-up prompt to tweak the layout or logic.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Ftjs00imKU5funVc0ZH1x%2FAppBldBuildDashboard.png?alt=media&amp;token=08d657a1-e4d0-4ccf-b292-d45014fe3ce0" alt=""><figcaption><p>The default Build Mode executing text instructions into full-stack code instantly</p></figcaption></figure>

{% hint style="info" %}
**Fix with AI** sends the reported issue to Qore's build agent. Review the rebuilt preview before you continue.
{% endhint %}

## Attach assets

Sometimes a text prompt isn't enough. Provide deep context by attaching business documentation or visual references directly into your workspace.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FhkxMYNviddwwEjCL318I%2FAttachAssets.png?alt=media&amp;token=135f0898-6e3f-42ac-8bea-41919e69dcb7" alt=""><figcaption><p>Utilizing the Attach Assets dropdown within the prompt bar to attach reference documentation or import standalone application packages.</p></figcaption></figure>

Clicking the **Plus (+)** icon in the prompt bar reveals:

* **Attach File**: Upload custom data layers, spreadsheets, or wireframes to serve as an explicit structural guide for the layout.
* **Import App Package:** Upload whole legacy project files, to iterate on previously compiled builds without starting from zero.

What the builder does with them:

* **PRD Integration**: Upload your Product Requirements Document. The builder analyses your technical specs — such as lending compliance rules — and ensures the app's logic adheres to every requirement.
* **Visual Reference Mapping**: Attach a screenshot of a dashboard you admire. The builder uses it as a wireframe to map out where buttons, charts, and data tables live.
* **Natural Language Synergy:** Combine text with attachments — *"Use the logic in the attached PRD, but follow the layout of this screenshot."*

## Design-aware generation

In the financial sector, brand consistency isn't optional — it's trust. **Design-Aware Generation** ensures your new app looks like your internal design team built it from day one.

Clicking the **Color Palette (Branding)** icon in the prompt box opens **Design and Branding Preferences**: *Customize the visual style, branding and appearances of your app.* Choose a design from **Choose from project designs** or **Create new project design**, pick a **Visual Style** such as **Auto (Recommended)**, **Minimal**, or **Modern SaaS**, upload **Brand Logos** (**Full Logo**, **Small Logo**, **Favicon**), then select **Apply**. Changes here apply to this app only; the saved project design stays unchanged. In an existing app, the same settings are in [App Config › Brand Guidelines](/ai-workbench-qore/console/app-builder/build/app-config#brand-guidelines).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-c95a22f861f98618c08f04c7f638e3bba944c460%2Fqore_app-builder_how-to-design-and-branding_rounded_shadow.png?alt=media" alt="The Design and Branding Preferences dialog: Choose from project designs and Create new project design tabs, a Project design dropdown set to Calm Neutral, Visual Style cards, Brand Logos upload fields, and Reset Changes and Apply buttons"><figcaption><p>Design and Branding Preferences.</p></figcaption></figure>

### Image mapping and asset uploads

Upload your core visual identity markers. The App Builder extracts and scales your design language across logos, favicons, and primary and secondary colours.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fq5ZNYiTgEcWyIiXyK4TS%2FBranding1LightMode.png?alt=media&amp;token=f0b20a15-b07d-48c2-bc5b-28cdf0bfd400" alt=""><figcaption><p>The 'Set Your Branding' workspace in Light Mode, featuring asset upload inputs, primary color configurations, and a live user interface preview canvas.</p></figcaption></figure>

**Originality at scale:** Because the builder understands the generalized visual style rather than a static layout template, it generates original pages that remain on-brand through every structural expansion.

### Dual-theme optimization

The platform supports native theme switching directly inside the configuration panel.

* **Light Mode Framework**: Optimizes high-contrast visibility using light background fields (`#ffffff`) paired with soft neutral borders and inputs.
* **Dark Mode Architecture:** Restructures container logic to use dark, eye-strain-reducing panels (`#27272a`) while preserving your defined Primary Brand Color highlights.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fm1PrHFu6avWq5GD0V3Rz%2FBrandingDarkMode.png?alt=media&amp;token=d11921da-40d5-4f34-84b5-173a505cdb9a" alt=""><figcaption><p>Toggling the native Dark Theme configuration selector to preview the adaptive behaviors of branding colors on dark system layers.</p></figcaption></figure>

### Advanced customization

In **Design and Branding Preferences**, expand **Advanced Customization** to set individual colours: **Primary Foreground**, **Secondary Foreground**, **Background**, **Foreground**, **Border**, **Input**, **Muted**, **Muted Foreground**, **Accent**, **Accent Foreground**, **Sidebar**, and **Sidebar Foreground**. Each takes a colour, as a swatch or a hex value. Select **Hide Advanced Customization** to collapse it. **Create new project design** has the same fields.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2e08af13ac0723dcb3e58910d49c1d23a42e2c65%2Fqore_app-builder_how-to-advanced-customization_rounded_shadow.png?alt=media" alt="Design and Branding Preferences with Advanced Customization expanded: Hide Advanced Customization, then Primary Foreground, Secondary Foreground, Background, Foreground and Border, each with a colour swatch and hex value"><figcaption><p>Advanced Customization.</p></figcaption></figure>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-0fc830f633a70d8c7c2dd4b269533a257b60d745%2Fqore_app-builder_how-to-advanced-customization-more_rounded_shadow.png?alt=media" alt="Further Advanced Customization fields: Muted, Muted Foreground, Accent, Accent Foreground, Sidebar and Sidebar Foreground, each with a colour swatch and hex value"><figcaption><p>More Advanced Customization fields.</p></figcaption></figure>

## Building for mobile

Select **Mobile (Beta)** in the app type menu **before** generation, and the engine targets touch-optimized environments.

* **Responsive Initialization:** The engine prioritizes touch-friendly components, such as bottom-sheet menus and thumb-optimized button placement.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FsYzhnCqk8j7jcKFtv5Jy%2FMobile1.png?alt=media&amp;token=e2f335da-e668-4b0e-bf2a-2877adbc8584" alt=""><figcaption><p>Defining a mobile-first project by selecting the Mobile (Beta) platform before initializing the generative prompt.</p></figcaption></figure>

* **Mobile-Enriched Codebase:** Mobile-first generation produces a codebase optimized for smaller devices, including responsive breakpoints and efficient data-fetching patterns.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FgMPneKwesKbGruwgB0sQ%2FMobile2.png?alt=media&amp;token=6397d201-d199-4916-ad0d-e76a97f305e2" alt=""><figcaption><p>The generative engine prioritizing mobile-enriched code (e.g., <code>expense.data.ts</code>) based on the project’s platform parameters.</p></figcaption></figure>

Validating a mobile build on a real handset is covered in [Test](/ai-workbench-qore/console/app-builder/test).

## Service extensions

A polished interface needs a secure data layer and operational intelligence to do useful work. Once your build initializes, the context panel exposes quick-action extension buttons.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2F4X7cgW0ZcRvKVAAIZwDe%2FConnectDbaseAgents.png?alt=media&amp;token=2e9c847d-4dd4-400f-9500-d838be1f018b" alt=""><figcaption><p>A sample chat interface log showing successful initialization of the base application with direct execution links to connect infrastructure and attach automated agents.</p></figcaption></figure>

### Database integration

To move from a static mock state to permanent persistence, the platform integrates with **Supabase**, giving your application an enterprise-grade PostgreSQL backend.

* **Zero-Config Connection**: Click **Connect Supabase** in the workspace log panel to open the modal manager.
* **Bring Your Own Key (BYOK) Linking**: Authenticate your organization layer, connect to your workspace environments, and map your database URL and Anon Keys without writing manual API endpoints or SQL schemas.
* **Granular Record Control:** Capture, isolate, and read financial data records — transaction histories, loan status modifications — directly through the compiled frontend.
* **Real-Time PostgreSQL Sync**: Updates made by users are immediately reflected across admin dashboards and analytics charts.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FAlDbPUBrmo9Gjxn3tB37%2FConnectDbase.png?alt=media&amp;token=fa88f28e-fa38-4013-8eab-9f0092a8baef" alt=""><figcaption><p>The database configuration window, guiding users through organization setup and project connection parameters to initialize the Supabase data mapping layer.</p></figcaption></figure>

### Autonomous workspace agents

Beyond storage, attach task-specific agents to monitor compliance, validate parameters, or review strategic goals within your build.

* **Modular Intelligence Assignment:** Click **Attach Agent(s)** to access the agent workspace marketplace.
* **Specialized System Handlers:** Check the agents you want, to deploy oversight directly onto your app's processing loop.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FKP7xXdFJJ5dFnqwq8kGV%2FAttachAgents.png?alt=media&amp;token=83041964-2b8d-43b7-8501-55637dd1afb5" alt=""><figcaption><p>The Attach Agent(s) selection modal displaying custom, pre-built autonomous assistants available to deploy onto the compiled application instance.</p></figcaption></figure>

Agents attached here are built and configured in the [Agent Builder](/ai-workbench-qore/console/agent-builder), and they travel with the app when you export it — see [Deploy](/ai-workbench-qore/console/app-builder/deploy).

***

When the app does what you intended, validate it on a real device in [Test](/ai-workbench-qore/console/app-builder/test).

***

{% 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 %}


# App Config

Configure identity, data, domains, branding, integrations, and app preferences.

App Config holds an app's settings — its identity, its database, its domains and branding, its environment variables and integrations, and developer and notification preferences. Open it with **App Config** in the workspace action bar.

App Config has eight sections: Basic Config, Database, Domains, Brand Guidelines, Environment Variables, Integrations, Developer Tools, and Preferences. Several settings distinguish the **Preview** build from the **Published** one — so check which scope you're editing.

## Basic Config

Set the app's **App Name** (required — the app can't be saved without it) and its **App Description**, then **Save**. The name is how the app is identified across Console.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a040042be0177ba3499939fd1442b384ef4e81db%2Fqore_app-builder_how-to-app-config-basic_rounded_shadow.png?alt=media" alt="App Config open at Basic Config, with the section list on the left and the App Name and App Description fields and a Save button"><figcaption><p>Basic Config.</p></figcaption></figure>

## Database

Choose the database the app uses. Qore offers **Uptiq Managed DB** — a managed PostgreSQL database — which shows as **Connected** when in use, with a **•••** menu beside it, and **Supabase** (Postgres plus auth and APIs) as an alternative.

To connect the database and choose its schema when you publish, see [Deploy › Connect the database](/ai-workbench-qore/console/app-builder/deploy#connect-the-database).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-c94de2a986f075ca42d03cfb0d61cc5d9e9a24da%2Fqore_app-builder_how-to-app-config-database_rounded_shadow.png?alt=media" alt="The Database section, with Uptiq Managed DB (Managed PostgreSQL database) Connected with a menu beside it, and Supabase (Postgres + auth + APIs)"><figcaption><p>Choosing the app's database.</p></figcaption></figure>

{% hint style="info" %}
The managed database is the simplest path — Qore runs it for you. Connect Supabase instead when you need its auth and API features.
{% endhint %}

## Domains

Under **Connected Domains**, use **Connect New Domain** to attach a domain from a third-party provider, so the published app serves from your own domain rather than the default Qore URL.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2c33314291049761ff2d0acf8970e5d8f96c6992%2Fqore_app-builder_how-to-app-config-domains_rounded_shadow.png?alt=media" alt="The Domains section: Connected Domains, Connect a domain from a third party provider, and Connect New Domain"><figcaption><p>Connecting a custom domain.</p></figcaption></figure>

## Brand Guidelines

Set the app's visual style and branding in **Design and Branding Preferences**. Three tabs set where the design comes from:

* **Current app design** — the design this app uses now.
* **Choose from project designs** — a saved design from the project.
* **Create new project design** — a new design.
* **Visual Style** — choose the design language: **Auto (Recommended)** lets Qore pick, or select one of **Minimal**, **Modern SaaS**, **Neumorphism**, **Glassmorphism**, **Enterprise**, **Dark Mode**, **Bold & Colorful**, or **Fintech / Banking**.
* **Brand Logos** — upload a **Full Logo** (headers and branding), a **Small Logo** (compact spaces), and a **Favicon** (browser-tab icon, best at 32×32 or 64×64 px).
* **Brand colors** — set the **Primary Brand Color** and **Secondary Brand Color** (for example, `#2b7fff` and `#f4f4f5`), with **Advanced Customization** for finer control.
* **Advanced Customization** — expand it to set **Primary Foreground**, **Secondary Foreground**, **Background**, **Foreground**, **Border**, **Input**, **Muted**, **Muted Foreground**, **Accent**, **Accent Foreground**, **Sidebar**, and **Sidebar Foreground**. Each takes a colour, as a swatch or a hex value. Select **Hide Advanced Customization** to collapse it.

**Create new project design** has the same fields.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a12e1b680619d3616184465992dc13d4000f892c%2Fqore_app-builder_how-to-app-config-brand-guidelines_rounded_shadow.png?alt=media" alt="The Brand Guidelines section: Design and Branding Preferences with the Current app design, Choose from project designs and Create new project design tabs, Visual Style cards, Brand Logos uploads, and Reset Changes and Apply"><figcaption><p>Brand Guidelines.</p></figcaption></figure>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2e08af13ac0723dcb3e58910d49c1d23a42e2c65%2Fqore_app-builder_how-to-advanced-customization_rounded_shadow.png?alt=media" alt="Design and Branding Preferences with Advanced Customization expanded: Hide Advanced Customization, then Primary Foreground, Secondary Foreground, Background, Foreground and Border, each with a colour swatch and hex value"><figcaption><p>Advanced Customization.</p></figcaption></figure>

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-0fc830f633a70d8c7c2dd4b269533a257b60d745%2Fqore_app-builder_how-to-advanced-customization-more_rounded_shadow.png?alt=media" alt="Further Advanced Customization fields: Muted, Muted Foreground, Accent, Accent Foreground, Sidebar and Sidebar Foreground, each with a colour swatch and hex value"><figcaption><p>More Advanced Customization fields.</p></figcaption></figure>

Use **Apply** to save, or **Reset Changes** to discard.

## Environment Variables

Store the API keys, tokens, and credentials your app's integrations need. Values are **encrypted** and injected as environment variables at runtime. Add each as a **Key** and **Value** with **+ Add Variable**, then select **Save**. A **Preview / Publish** toggle lets you set different values for the preview build and the published build.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-516e739088f7d9367502d9ab3ffa7c39aff00fc3%2Fqore_app-builder_how-to-app-config-environment-variables_rounded_shadow.png?alt=media" alt="The Environment Variables section, with Preview and Publish tabs, a Key and Value table, Add Variable, and Save"><figcaption><p>Environment Variables.</p></figcaption></figure>

{% hint style="warning" %}
Environment variables hold secrets. They're encrypted at rest and only injected at runtime, but treat the values as sensitive — set them here rather than hard-coding them into the app.
{% endhint %}

## Integrations

Connect the app to outside tools and platforms. The catalog holds 73 connectors across categories such as Storage, Authentication, LLM, Payments, CRM, Accountancy, Email Notification, Messaging, and Banking — for example Airtable, Confluence, DocuSign, the Google Workspace apps, and the Microsoft 365 apps. Search or narrow by category, then **Connect** the ones you need.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-5a22a52d473e2a209accba0952bf23c79f24ec2a%2Fqore_app-builder_studio-import-an-existing-app-integrations_rounded_shadow.png?alt=media" alt="The Integrations section, with a searchable connector catalog"><figcaption><p>The Integrations catalog.</p></figcaption></figure>

{% hint style="info" %}
Connecting an integration grants the app access to that service. Connect only what the app actually uses.
{% endhint %}

## Developer Tools

Turn on **Enable Developer Tools** to inspect the app's runtime behavior in the preview — useful while debugging, off by default. Select **Save** to keep the change.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2241f7ec83c3575f35fb65dbf29cee42836a794f%2Fqore_app-builder_how-to-app-config-developer-tools_rounded_shadow.png?alt=media" alt="The Developer Tools section, with the Enable Developer Tools toggle and Save"><figcaption><p>Developer Tools.</p></figcaption></figure>

## Preferences

Turn on **Build Notifications** to be notified when a project build completes, so you don't have to watch the workspace to know a build finished. Select **Save** to keep the change.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-59e0cbd2e35423a40e394b783d27441902364a91%2Fqore_app-builder_how-to-app-config-preferences_rounded_shadow.png?alt=media" alt="The Preferences section, with the Build Notifications toggle and Save"><figcaption><p>Preferences.</p></figcaption></figure>

## App Config sections

| Element                   | Description                                           | When to use it                                                 |
| ------------------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| **Basic Config**          | The app's name and description                        | Rename the app or update its description; App Name is required |
| **Database**              | The connected database (Uptiq Managed DB or Supabase) | Choose or switch the app's database                            |
| **Domains**               | Custom domains for the published app                  | Serve the app from your own domain                             |
| **Brand Guidelines**      | Visual style, logos, and brand colors                 | Set the app's look and branding                                |
| **Environment Variables** | Encrypted secrets injected at runtime                 | Store API keys and credentials; set per Preview/Publish        |
| **Integrations**          | The 73-connector catalog                              | Connect the tools the app uses                                 |
| **Developer Tools**       | Runtime inspection in the preview                     | Turn on while debugging                                        |
| **Preferences**           | Build-completion notifications                        | Get notified when a build finishes                             |

## Why this matters

* App Config is where an app's identity, data, connections, and look are all set.
* Several settings differ between the **Preview** and **Published** builds — confirm the scope before you change one.
* The database, domain, integration, and environment-variable sections grant access or hold secrets; treat them with more care than the cosmetic ones.

## Related

{% content-ref url="/pages/bc7662d99efc00ab94438c3b32248b84a7af247f" %}
[App Workspace](/ai-workbench-qore/console/app-builder/app-workspace)
{% endcontent-ref %}

{% content-ref url="/pages/6CB3ux2H16RPihpNE3qg" %}
[Integrations Hub](/ai-workbench-qore/console/integrations-hub)
{% endcontent-ref %}

***

{% 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 %}


# DB Explorer

Inspect schemas, review queries, and query app databases safely.

DB Explorer lets you inspect an app's database — see its schema as a diagram, review the queries that ran, and run your own. Open it from the app workspace's **More** menu → **DB Explorer**.

## Choose the database and schema

DB Explorer can inspect either of the app's databases: pick **Preview DB** or **Publish DB** depending on whether you want the build you're previewing or the one that's live, and choose the schema. The tables in the chosen schema are listed for you to open.

{% hint style="info" %}
Preview and Publish are separate databases. Confirm which one you've selected before you read a value or run a query — they can hold different data.
{% endhint %}

## Visualizer

The **Visualizer** draws the schema as a set of linked tables. Each column shows its name and type, marked for **primary key**, **nullable**, and **foreign key**, with relationship lines between tables — for example a one-to-many link from a `User` table to a `UserIdentity` table. It's the fastest way to understand the app's data model at a glance.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-aaa367a0686184ea89be6bb5effe7dcaa1d12732%2Fqore_app-builder_studio-import-an-existing-app-more-db-explorer-preview-db_rounded_shadow.png?alt=media" alt="The DB Explorer Visualizer, showing linked tables with column types and relationship lines"><figcaption><p>The Visualizer, viewing the Preview DB schema.</p></figcaption></figure>

## Console

The **Console** shows the queries Qore has run against the database, each with its SQL, its parameters, and whether it succeeded — useful for seeing what the app is actually doing to its data.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-8a576872e2e4bcb79647de38f539c2d0a8437439%2Fqore_app-builder_studio-import-an-existing-app-more-db-explorer-preview-db-console_rounded_shadow.png?alt=media" alt="The DB Explorer Console, listing queries with their SQL, parameters, and result"><figcaption><p>The Console, showing queries run against the database.</p></figcaption></figure>

## SQL

The **SQL** editor lets you run your own queries against the selected database.

{% hint style="warning" %}
The SQL editor runs real queries against the app's database. Be careful running anything that changes data, and confirm you're pointed at the intended database — **Preview DB** or **Publish DB** — first.
{% endhint %}

## Why this matters

* DB Explorer shows what an app stores and what it's doing to its data, without leaving the workspace.
* Which database you're on — **Preview** or **Publish** — governs everything here; the same schema can differ between them.

## Related

{% content-ref url="/pages/6de8c0921a81fc6dc038359c161a4825e5e9aa3e" %}
[App Config](/ai-workbench-qore/console/app-builder/build/app-config)
{% endcontent-ref %}

{% content-ref url="/pages/4844ee4b9bc46117ccc5a5bc36b61b43cb4a3936" %}
[Data Flow](/ai-workbench-qore/console/app-builder/build/data-flow)
{% endcontent-ref %}

***

{% 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 %}


# Data Flow

Visualize app components, data stores, and connections across your architecture.

Data Flow is an architecture diagram of how an app works — its pages, services, integrations, external systems, and data stores, and the connections between them. Qore generates it from the app as you build. Open it from the app workspace's **More** menu → **Data Flow**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-b219634fb23dc5332857dcb05149f9c99903c607%2Fqore_app-builder_studio-import-an-existing-app-more-data-flow-mermaid_rounded_shadow.png?alt=media" alt="The Data Flow diagram, showing pages, services, integrations, and data stores with labelled connections"><figcaption><p>The Data Flow diagram.</p></figcaption></figure>

## What it shows

Each component in the diagram is typed — a **Page**, a **Backend** service, an **Integration**, an **External** system, a **Database**, or the **User** — and each connection is labelled with what it does. For example, an authentication flow might run from the user, to a login page, to a Google OAuth integration, out to Google's identity service, back to a backend auth service, and into a Postgres database, with each arrow labelled ("redirects to Google", "callback to backend", "saves/updates user", and so on).

An **Overview** panel summarizes the app in plain language — what it does and what it's built with. Select any component or connection to see what that part does.

{% hint style="info" %}
The diagram is generated from the app and reflects the selected build version, so it updates as the app changes. It's a map for understanding the app, not an editor — you change the architecture by changing the app in the build conversation.
{% endhint %}

## Why this matters

* Data Flow is the fastest way to understand, explain, or review how an app is put together.
* It stays in sync with the app because Qore regenerates it as the app changes.

## Related

{% content-ref url="/pages/6CB3ux2H16RPihpNE3qg" %}
[Integrations Hub](/ai-workbench-qore/console/integrations-hub)
{% endcontent-ref %}

{% content-ref url="/pages/bc7662d99efc00ab94438c3b32248b84a7af247f" %}
[App Workspace](/ai-workbench-qore/console/app-builder/app-workspace)
{% endcontent-ref %}

***

{% 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 %}


# Testing

Review automated test results for every app build version.

Testing shows you whether each build of an app passed its automated tests. Qore runs the tests on every build, keeps the result per version, and lets you open a full report. Open it from the app workspace's **More** menu → **Testing**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-fe9bd59fc81848a2beaf9b26c76ecd30bfa7448a%2Fqore_app-builder_studio-import-an-existing-app-more-testing_rounded_shadow.png?alt=media" alt="The Testing screen, listing build versions with pass/fail results and case counts"><figcaption><p>Testing, listing test runs per build version.</p></figcaption></figure>

## The test runs

Each build version is listed newest-first with its **result** (passed or failed), a summary of how many cases ran (for example, *14 Passed · Total 14 Cases*), and when it ran. The most recent build is marked **Latest**. Select **View Report** to open the full report for that version.

## The test report

The report opens with the app name and the **Version**, the **Commit** it ran against, the **Trigger** (for example, *OnBuild*), when it was **Generated**, and the overall **Result** (for example, *PASSED*), followed by a summary of **Total**, **Passed**, **Failed**, **Skipped**, and **Duration**.

Below the summary, the results are broken out by suite — for example a **frontend** suite and a **backend** suite — each listing every test with its result, the file it lives in, the test name, and how long it took (for example, `tests/App.test.tsx › renders without crashing`, or `app routes › GET /health returns 200 OK`). Use **Download** to save the report.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-27e04d02661471e78be4349b9136982ca782aa1e%2Fqore_app-builder_studio-import-an-existing-app-more-testing-report_rounded_shadow.png?alt=media" alt="A test report, with summary counts and results broken out by frontend and backend suite"><figcaption><p>A full test report.</p></figcaption></figure>

{% hint style="info" %}
Tests are tied to a **build version** and its commit and rerun on each build, so a report reflects a point-in-time version. Check the version before reading a result.
{% endhint %}

## If a build fails its tests

A run's result can be **failed** as well as passed. When it is, open **View Report** to see which suites and tests failed and where, then fix the app in the [App Workspace](/ai-workbench-qore/console/app-builder/app-workspace) — describe the fix, or forward a failing test to the build agent — and rebuild. A new build produces a new version with its own test run.

{% hint style="warning" %}
Don't publish a version whose tests failed — the published version is what your users get. Fix the failures, rebuild, and publish the passing version.
{% endhint %}

## Why this matters

* Testing tells you whether a version is safe to publish before you deploy it.
* Results are per build version, so you can confirm the exact version you're about to publish.

## Related

{% content-ref url="/pages/9006766511be37fb1fe542c48dd782896979a34b" %}
[Security Scans](/ai-workbench-qore/console/app-builder/security-scans)
{% endcontent-ref %}

{% content-ref url="/pages/bc7662d99efc00ab94438c3b32248b84a7af247f" %}
[App Workspace](/ai-workbench-qore/console/app-builder/app-workspace)
{% endcontent-ref %}

***

{% 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 %}


# Security Scans

Find, review, and remediate dependency vulnerabilities in each app build.

Security scans an app's dependencies for known vulnerabilities on each build, keeps the result per version, and lets you review each finding and remediate it. Open it from the app workspace's **More** menu → **Security**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-b20f76f3892ef4cb03dbe013c8989bd83ae3f565%2Fqore_app-builder_studio-import-an-existing-app-more-security_rounded_shadow.png?alt=media" alt="The Security screen, listing build versions with findings by severity"><figcaption><p>Security, listing scans per build version.</p></figcaption></figure>

## The scans

Each build version is listed with a **Completed** status, the **commit** it scanned, and a summary of findings by severity (for example, *High 6 · Medium 5 · Low 1*). Open a scan to see its findings in full.

## Scan details

A scan opens with a severity summary — **Critical**, **High**, **Medium**, **Low**, and **Info** with counts — plus the commit and how long the scan took. You can **Show suppressed** findings, narrow by severity, **Bulk update** findings, remediate with **Fix with AI**, or export a **Report**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2b0e8d122935a57e2f3b1fe32c56b36c84e723d4%2Fqore_app-builder_studio-import-an-existing-app-more-security-scan-details_rounded_shadow.png?alt=media" alt="A security scan&#x27;s detail view, with severity summary and a list of findings"><figcaption><p>Scan details, with findings by severity.</p></figcaption></figure>

Each finding is one row showing its **severity**, a title, the scanner (**Trivy**), that it's a **Dependency** issue, the lockfile it was found in (for example, `frontend/pnpm-lock.yaml`), the package, and the advisory id (a **CVE** or **GHSA** number).

<details>

<summary>Details</summary>

Read the finding's description, any available patches, and a **Remediation** — for example, *Upgrade fast-uri to 2.4.3, 3.1.4, 4.1.1 or later*.

</details>

While **Fix with AI** is working, the button is greyed out. Its fix arrives as a new version — for example, *Version 2.0.0 (Latest): Fix the actionable security issues detected by security scan…* in the version selector.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2e08cf92fd58dd80656fb43669717f08b456abf4%2Fqore_app-builder_how-to-version-selector_rounded_shadow.png?alt=media" alt="The version selector open beside the Security scans list, with Version 2.0.0 (Latest), Fix the actionable security issues detected by security scan, above Version 1.0.0"><figcaption><p>A Fix with AI remediation, as a new version.</p></figcaption></figure>

{% hint style="warning" %}
**Fix with AI** changes the app to remediate a finding — it edits the app's dependencies through the build agent, not just the report. Review the change it makes, and re-check the tests and scan afterward.
{% endhint %}

## Why this matters

* Security tells you what vulnerabilities a build carries before you publish it.
* Findings are dependency issues from the app's lockfiles; remediation usually means upgrading a package to a patched version.
* Scans are per build version, so you can confirm the exact version you're about to ship.

## Related

{% content-ref url="/pages/c10eed6161aadb656ac4137fce98a06ced6ec452" %}
[Testing](/ai-workbench-qore/console/app-builder/testing)
{% endcontent-ref %}

{% content-ref url="/pages/KDQL1trGEyacZ7JGRO4O" %}
[Deploy](/ai-workbench-qore/console/app-builder/deploy)
{% endcontent-ref %}

***

{% 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 %}


# Deploy

Publish tested app versions with required production configuration.

Deploy an app when its current version is ready for users. Review the live preview and test results first.

## Publish an app

{% hint style="warning" %}
Configure the database first. Without a database, the app can't be published. See [Connect the database](#connect-the-database).
{% endhint %}

{% stepper %}
{% step %}

### Confirm you want to publish

Select **Publish** in the app workspace. **Publish your Application** asks you to review your connected services and confirm you are ready to go live. Once published, your latest changes are deployed to your users.

Select **Publish App** to continue, or **Cancel**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-96d03c602661cbd6e058a6d8ff93b06ad5f46482%2Fqore_app-builder_how-to-publish-confirm_rounded_shadow.png?alt=media" alt="The Publish your Application dialog, with Cancel and Publish App buttons"><figcaption><p>Publish your Application.</p></figcaption></figure>
{% endstep %}

{% step %}

### Choose where each service runs

**Publish App - Deployment** lists each service of the app under **Deployment** — for example **Web** and **API** — with a menu beside each, such as **Google Kubernetes Engine**. Choose where each one runs, then select **Continue**.

You can change this later. Republishing redeploys the affected services.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-250bf35d8c91b6d6fbac4d5049c5914adf67fb3d%2Fqore_app-builder_how-to-publish-deployment_rounded_shadow.png?alt=media" alt="The Publish App - Deployment dialog, with Web and API each set to Google Kubernetes Engine, and a Continue button"><figcaption><p>Choosing where each service runs.</p></figcaption></figure>
{% endstep %}

{% step %}

### Complete the publish checklist

The **Publish Checklist** lists the configurations you connected in preview. The published app needs them to work correctly. You can update them later in app settings.

* **Database** — **Required**. When its status is **Not Configured**, select **Connect**. See [Connect the database](#connect-the-database).
* **External Services Used** — each service, for **Preview** and **Publish**. With none, it reads *No external services connected.*
* **Environment Variables** — each variable, for **Preview** and **Publish**. With none, it reads *No environment variables configured.*

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-7376d7a3fdca6674e4ad13ee58fd8a27d10de080%2Fqore_app-builder_how-to-publish-checklist-not-configured_rounded_shadow.png?alt=media" alt="The Publish Checklist: Database (Required) with Uptiq Managed DB Not Configured and a Connect action, and External Services Used with no services connected"><figcaption><p>The publish checklist, before the database is connected.</p></figcaption></figure>

When the database is connected, its status reads **Configured** and the action changes to **Manage**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-079667529002a6b39ee6181172923b64abedf704%2Fqore_app-builder_how-to-publish-checklist-configured_rounded_shadow.png?alt=media" alt="The Publish Checklist with Uptiq Managed DB Configured and a Manage action"><figcaption><p>The publish checklist, with the database configured.</p></figcaption></figure>

To change the database, domains, integrations, or environment variables, use [App Config](/ai-workbench-qore/console/app-builder/build/app-config).
{% endstep %}

{% step %}

### Publish

Select **Publish**. **Publishing App** shows each service — such as **API** and **Web** — as **In Progress**, and the **Publish** button reads **Publishing**. The process may take a few minutes. You're notified as soon as the app is published and ready to use.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-f868da70d1a776481eba402b5969b10ad705927d%2Fqore_app-builder_how-to-publishing-progress_rounded_shadow.png?alt=media" alt="The Publishing App dialog, with API and Web In Progress, and the Publish button reading Publishing"><figcaption><p>Publishing in progress.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Publish a new version

When the app has been published before, **Publish** opens a panel with the last published version, its date, and the live URL. Open or copy the URL, or select **Manage Domains** to manage its domain. Review the checklist, then select **Publish Changes**. The platform deploys the current version and updates the live URL.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-525909dfba2bfdf0627eb0aa2676c8aee8492ae0%2Fqore_app-builder_studio-import-an-existing-app-more-publish-new-version_rounded_shadow.png?alt=media" alt="The publish panel, showing the last published version, its date, and the live URL"><figcaption><p>The publish panel for an app that has been published before.</p></figcaption></figure>

### Connect the database

{% stepper %}
{% step %}

#### Open Manage Database

In the publish checklist, select **Connect** beside the database. **Manage Database** lists the available databases, such as **App DB** and **Preview Database**, each with **Connect**.

To add one, type a name in **Database name** and select **+ Add Database**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-8044fb96edb2c46a41dddae76af8d74b758a4240%2Fqore_app-builder_how-to-manage-database_rounded_shadow.png?alt=media" alt="The Manage Database dialog, listing App DB and Preview Database with Connect buttons, and a Database name field with Add Database"><figcaption><p>Manage Database.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Choose a database

Select **Connect** beside the database. **Select Schema** opens, with the database name beneath the title.
{% endstep %}

{% step %}

#### Create a schema, or connect an existing one

* **Create New Schema** — type a name, such as *sales*, and select **Create & Connect**. You're assigned as the **Root User**, with full ownership of the schema.
* **Existing Schemas** — each schema shows its status, such as **In Use**, and its owner app. Choose an access level — **Standard (Read & Write)** or **Read Only** — then select **Connect**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-79fb47ee72815072234023b62fdd489a00af9fc4%2Fqore_app-builder_how-to-select-schema-access_rounded_shadow.png?alt=media" alt="The Select Schema dialog for Preview Database: Create New Schema with a Create and Connect button, and two existing schemas, each In Use, with an access menu open showing Standard (Read and Write) and Read Only"><figcaption><p>Select Schema, with the access level menu open.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

Once connected, **Manage Database** shows the database as **Connected**, with its schema name and a **Manage** button.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-c8f067e804af4fb30b83e14fe55f0ec07cd575a1%2Fqore_app-builder_how-to-manage-database-connected_rounded_shadow.png?alt=media" alt="Manage Database with the Design database Connected, its schema name, and a Manage button"><figcaption><p>A connected database.</p></figcaption></figure>

Select **Manage** to return to **Select Schema**. A connected schema shows **Connected** and its owner, with a user menu, such as **Root User**, and **Update User**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-00b2ba36ca3deea35ec59b578b2e145f107ceb2c%2Fqore_app-builder_how-to-select-schema-connected_rounded_shadow.png?alt=media" alt="Select Schema for the Design database, with the sales schema Connected, owned by ToDo List App, a Root User menu and an Update User button"><figcaption><p>A connected schema.</p></figcaption></figure>

### Resolve a failed publish

When publishing fails, **Publishing Failed** reads: *An error occurred while publishing your application. Please try again or use the "Fix with AI" option to attempt an automatic resolution of the issue.* Select one of these actions:

* **Try Again** to retry the publish
* **Fix with AI** to send the failure to the build agent
* **Close** to dismiss the notification

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-87addcffa9546ae4d9e8e7dac0332726e3bf8658%2Fqore_app-builder_how-to-publish-failed_rounded_shadow.png?alt=media" alt="The Publishing Failed dialog, with View Error Details, and Close, Fix with AI and Try Again buttons"><figcaption><p>A failed publish, with recovery actions.</p></figcaption></figure>

{% hint style="info" %}
**Fix with AI** sends the reported issue to Qore's build agent. Review the rebuilt preview before you continue.
{% endhint %}

With **Fix with AI**, the build agent works on the failure in the build conversation. It shows **Working…** and each step it takes. Select **Stop** to stop it. When it finishes, it summarizes the changes and shows **Live preview is ready**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a97c8e1d9322749f8dc7a61f95b790cac52b3363%2Fqore_app-builder_how-to-build-agent-working_rounded_shadow.png?alt=media" alt="The build conversation with the request Fix the publish failure, the agent Working and listing its steps, and a Stop button"><figcaption><p>The build agent working on a publish failure.</p></figcaption></figure>

Select **View Error Details** to open the deploy log. It shows numbered build steps and the underlying error. Use the log to fix the issue, then select **Try Again**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-8c11c3105f5067411d1c0af848425ef869d1b2b2%2Fqore_app-builder_studio-import-an-existing-app-more-publish-failed-error-details_rounded_shadow.png?alt=media" alt="The deploy log, with numbered build steps and the underlying error"><figcaption><p>The deploy log's error details.</p></figcaption></figure>

For example, a missing `package.json` appears as an `npm install` failure with error code `ENOENT`.

## Versions

The version selector lists builds newest first. **Latest** marks the newest build. **Published** marks the live version. *Uncommitted changes* marks work outside a version.

Select a version to review or return to it. The published version can differ from the latest build.

## What ships

After testing, the platform packages the project as one deployment unit:

* **Frontend code** — UI components, state managers, and inline styles compile for production
* **Infrastructure settings** — connected database variables, storage links, and custom routing stay mapped to the container
* **Attached agents** — prompts, compliance skills, and reasoning logic travel with the app export package

## Enterprise publishing

The publishing engine supports high-concurrency environments and automates server configuration.

* **High-traffic infrastructure** — the pipeline manages concurrent enterprise publishing requests
* **Request queuing** — deployments process sequentially to prevent stuck states during peak periods
* **Zero-downtime rollouts** — infrastructure updates migrate in the background
* **Production stability** — backward-compatible upgrades preserve published apps through platform updates

## Staging and governance

* **Isolated staging controls** — deploy privately for compliance, risk, and security review
* **Performance-ready clusters** — published apps run on multi-region nodes optimized for sub-second load times

{% hint style="warning" %}
**Publish** is unavailable in **Plan Mode**. To gather feedback before compiling code, add reviewers as collaborators from **Share**. See [Plan](/ai-workbench-qore/console/app-builder/plan#collaboration).
{% endhint %}

***

After publishing, use [Operate](/ai-workbench-qore/console/app-builder/operate) to track costs and acquisition.

***

{% 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 %}


# Operate

Monitor costs, acquisition, analytics, and app health after launch.

Deploying a financial application is the first step, not the last. Once it's live, the priority shifts from development to governance, fiscal transparency, and scale. **Operate** is the administrative control tower for your ecosystem of AI-driven tools.

In a production banking environment, every interaction carries a cost and every user journey requires attribution.

For account-wide governance and monitoring, use the [Control Center](/ai-workbench-qore/start-here/control-center).

## Usage and cost control

The **Usage & Cost Control** dashboard gives a high-fidelity view of how AI resources are consumed across your digital ecosystem — from a single Commercial Loan Portal to a suite of internal Compliance Agents.

**App build-time cost visibility.** App build-time cost visibility has been added, so you know what you're spending before you even publish.

For account-wide credit usage, spending limits, and alerts, use [Cost Control](/ai-workbench-qore/control-center/cost-control) in Control Center.

### Resource tracking

Live telemetry on credit and token consumption, rather than retrospective reporting.

* **Token-Level Visibility**: Monitor LLM token usage across providers (e.g., Vertex AI, Claude) to understand the exact cost of each automated interaction.
* **Credit Management:** Track platform credits in real time, whether you're on Pay-As-You-Go or a pre-allocated enterprise plan.
* **Automated Institutional Invoicing:** Detailed invoices break usage down so you can reconcile expenses or re-allocate costs to departments or branch locations.

{% hint style="info" %}
**Auto-unpublish on Dev/QA environments after 5 hours**

In line with our ongoing cost-control efforts, apps on Dev and QA environments will now auto-unpublish after 5 hours of inactivity.
{% endhint %}

### Budget optimization

Attribute costs to specific business outcomes.

* **Identify High-Consumption Assets:** See which apps or agents are most resource-intensive. If a Wealth Management Chatbot consumes more tokens than expected, refine its prompt or switch it to **Flash Mode** to improve unit economics.
* **Departmental Allocation:** Attribute usage to business units, enabling charge-back models where Commercial Lending and Retail Banking are billed only for the AI logic they use.
* **Budget Guardrails:** Set proactive alerts and thresholds so a pilot project stays within its quarterly budget — you're notified before usage hits critical levels.

## Analytics and referrals

Understanding where a high-value lead came from is essential for optimizing marketing spend and managing partner relationships. **Referral Tracking** monitors user acquisition with granular precision.

For unified engagement data across published apps, use [Observe](/ai-workbench-qore/control-center/observe) in Control Center. For one app's traffic, use [Analytics](/ai-workbench-qore/console/app-builder/analytics).

* **UTM-Based Referrals:** Track which campaigns, emails, or digital ads convert into active users.
* **Partner Link Attribution:** Assign unique referral codes to external partners — mortgage brokers, insurance agents, branch locations. When a user onboards via a partner link, the acquisition is permanently attributed to the correct source.
* **Conversion Insights:** Identify which referral channels drive the highest quality applications by tracking the path from click to submitted loan application.
* **Performance Auditing:** Review acquisition data to ensure marketing budget goes to the highest-performing channels.
* **Seamless Integration:** Referral data is captured at the point of entry and can be passed into your CRM or internal reporting systems through an agent's [API Call](/ai-workbench-qore/platform-resources/skill-library/api-call) skill.

## System health

Maintain visibility into platform stability and response times to ensure your deployment delivers the experience your brand promises.

For organization-wide dashboards across every app and agent, see [Monitoring & Performance Dashboards](/ai-workbench-qore/control-center/observe) under Governance. For a single agent's runtime behavior, see [Monitor](/ai-workbench-qore/console/agent-builder/monitor) in the Agent Builder.

For account-wide activity, model calls, and API requests, use [Observe](/ai-workbench-qore/control-center/observe) in Control Center.

***

{% 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 %}


# Analytics

Track published app visitors, traffic trends, and audience characteristics.

Analytics shows you who is using a published app and where they come from. Open it from the app workspace's **More** menu → **Analytics**.

**In-app and unified app analytics:** In-app analytics is available alongside a unified view in the [Control Center](/ai-workbench-qore/start-here/control-center).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-3e578a7e841b7732e8ce6fa39ba08575c5689a75%2Fqore_app-builder_studio-import-an-existing-app-more-analytics_rounded_shadow.png?alt=media" alt="The Analytics screen, showing unique visitors trend, top browsers, devices, countries, and pages"><figcaption><p>Analytics for a published app.</p></figcaption></figure>

## What it shows

Analytics reports **Unique Visitors** as a trend over a period you choose — for example the last 30 days — so you can see how traffic moves day to day. Alongside the trend, it breaks visitors down by:

* **Top browsers** — which browsers your visitors used.
* **Top devices** — desktop, mobile, and so on.
* **Top countries** — where visitors came from.
* **Top pages** — which pages drew the most visits.

{% hint style="info" %}
Analytics covers the app's **published** URLs, so a version you haven't published yet won't appear here. The account-wide view across all apps lives in [Control Center's Observe](/ai-workbench-qore/control-center/observe).
{% endhint %}

## Why this matters

* Analytics tells you whether a published app is actually being used, and by whom.
* It's scoped to one app; publish a version to start collecting data for it.

## Related

{% content-ref url="/pages/807cab861e090edd0ce825909db3db1b28f73799" %}
[Control Center](/ai-workbench-qore/start-here/control-center)
{% endcontent-ref %}

{% content-ref url="/pages/4023fee41d519b1fbe13cbf03c9027c75b45de1a" %}
[Observe](/ai-workbench-qore/control-center/observe)
{% endcontent-ref %}

***

{% 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 %}


# mobile render test

Verify mobile apps on real devices before publishing.

Building an enterprise-grade financial app is only half the battle. **Test** is your operational safety net — a sandbox to test, tweak, and verify your financial logic before going live.

The **Mobile & Local Sandbox** mimics your live production environment. It bypasses app store approval pipelines, putting your compiled React Native code straight onto a physical handset for real-world testing.

## Why a real device

* **Interactive Sandboxing:** Test custom components — a loan calculator, a transaction dashboard — under realistic conditions. Enter real numbers, tap buttons, and confirm the logic behaves as intended before pushing changes live.
* **Touch-Optimized Edge Case Hunting:** Standard browser emulators miss real touch gestures. A live handset shows whether floating buttons, swipe elements, and input fields stay thumb-friendly across screen sizes.
* **Instant Iterative Tuning:** Spot a UI glitch or logic flaw on the device, jump back into the builder prompt, send a follow-up instruction, and watch the rebuild refresh on your screen.
* **Stakeholder Sandboxing:** Preview environments are isolated from internal active system files, so clients and compliance officers can review logic safely without exposing backend data.

## The mobile handshake

Connecting your browser-based workspace to a physical device:

1. **Platform Selection:** Ensure your project target is toggled to **Mobile (beta)** in the header before generating — see [Build](/ai-workbench-qore/console/app-builder/build#building-for-mobile).
2. **QR Generation:** Once generation completes, the platform exposes a secure, project-specific QR code in the workspace preview dashboard.
3. **Expo Go Connection:** Scan the QR code with your phone's camera via the free, third-party **Expo Go** app. This mounts and renders your full application bundle on the phone in seconds.

{% columns %}
{% column %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FcFfjIxsdQ7iCBc5gHQIb%2FMobile3.1.png?alt=media&amp;token=66bee917-346d-47b6-8b9d-ece491814152" alt=""><figcaption><p>Bridging the gap between design and physical testing via Expo Go for real-device validation.</p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2FCkFZ3DRBbROzyKKsuSrZ%2FMobile4.jpeg?alt=media&amp;token=71719cfd-5f79-446b-aeff-f34fde76fdc6" alt="" width="360"><figcaption><p>Final high-fidelity prototype featuring thumb-optimized navigation and touch-friendly interface components.</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

You can also use the mobile previewer inside the builder to validate logic and branding on a simulated handset without leaving the workspace. Use the simulator to iterate quickly; use a real device before you publish.

{% hint style="info" %}
**Fix with AI** sends the reported issue to Qore's build agent. Review the rebuilt preview before you continue.
{% endhint %}

***

When the app holds up on a real device, move to [Deploy](/ai-workbench-qore/console/app-builder/deploy).

***

{% 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 %}


# App Builder: FAQs & Troubleshooting

Answers to common App Builder questions, and fixes for stalled builds, preview errors, failed tests, and failed publishes.

This page answers common questions about building, importing, versioning, and publishing apps. Use the troubleshooting entries when a build stalls, the preview errors, tests fail, or a publish doesn't go through.

## FAQs

### Building

<details>

<summary>Who can build and publish apps?</summary>

Every standard role can view apps. Building, importing, exporting, publishing, sharing, versions, Git, custom domains, and attaching agents need Developer, Account Admin, or Organisation Admin. See [Roles](/ai-workbench-qore/control-center/admin/roles).

</details>

<details>

<summary>What's the difference between Plan Mode and Build Mode?</summary>

**Build Mode**, the default, builds on every prompt. **Plan Mode** lets you talk through the requirements first, and nothing is built until you switch back. **Publish** is unavailable in Plan Mode. See [Plan](/ai-workbench-qore/console/app-builder/plan#plan-mode).

</details>

<details>

<summary>Which kinds of app can I build?</summary>

**Web App**, the default, with pages, data, and a backend; **Website**, for landing pages and marketing sites; and **Mobile (Beta)**, a native app for Android and iOS. See [Create a new app from a prompt](/ai-workbench-qore/console/app-builder/creating-and-importing-apps#create-a-new-app-from-a-prompt).

</details>

<details>

<summary>How long can one request run?</summary>

Up to 45 minutes. A longer request is stopped, and the work done so far is saved. See [Describe and build](/ai-workbench-qore/console/app-builder/app-workspace#describe-and-build).

</details>

<details>

<summary>Can I edit the generated code myself?</summary>

Yes. In **Code**, select a file, select **Edit**, make your changes, and select **Save**. Saving an edit creates a new version. See [Code](/ai-workbench-qore/console/app-builder/app-workspace#code).

</details>

<details>

<summary>Does building an app use credits?</summary>

Yes. The workspace's Credits meter shows what the app has consumed: credits used, cost, and when the figure was last synced. See [Credits](/ai-workbench-qore/console/app-builder/app-workspace#credits).

</details>

### Importing, versions, and export

<details>

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

A ZIP package or project up to 500 MB, a GitHub repository, or a GitLab project. A Qore Platform package is restored as it was; anything else, such as a Git repository or a project from another builder, is converted into a Platform app. See [Import an existing app](/ai-workbench-qore/console/app-builder/creating-and-importing-apps#import-an-existing-app).

</details>

<details>

<summary>What's the difference between View Version and Revert to Version?</summary>

**View Version** loads an older version temporarily; your current version stays unchanged. **Revert to Version** reverts the app to it. **Published** marks the version users see. See [Versions and publishing](/ai-workbench-qore/console/app-builder/app-workspace#versions-and-publishing).

</details>

<details>

<summary>Where does an app export go?</summary>

To your email. The package isn't downloaded in the browser; Qore shows *Export started. You will receive an email when it is ready.* Chat history is left out unless you tick **Include chat history in package**. See [Export](/ai-workbench-qore/console/app-builder/app-workspace#export).

</details>

### Publishing

<details>

<summary>Does an app need a database to publish?</summary>

Yes. The database is **Required** on the publish checklist; without one, the app can't be published. See [Connect the database](/ai-workbench-qore/console/app-builder/deploy#connect-the-database).

</details>

<details>

<summary>Can I change where each service runs after publishing?</summary>

Yes. Republishing redeploys the affected services. See [Choose where each service runs](/ai-workbench-qore/console/app-builder/deploy#choose-where-each-service-runs).

</details>

<details>

<summary>What happens when I publish a new version?</summary>

**Publish** shows the last published version, its date, and the live URL. Review the checklist and select **Publish Changes**; the platform deploys the current version and updates the live URL. See [Publish a new version](/ai-workbench-qore/console/app-builder/deploy#publish-a-new-version).

</details>

## Troubleshooting

### Building

<details>

<summary>My app started building before I finished planning</summary>

Build Mode builds on every prompt. Switch to Plan Mode first. See [Plan](/ai-workbench-qore/console/app-builder/plan#plan-mode).

</details>

<details>

<summary>The build seems stuck</summary>

Check the build conversation for an **Agent is waiting for your input** step, such as choosing a provider. Make a choice, or select **Skip**. See [Create an app](/ai-workbench-qore/task-guides/create-an-app#common-issues).

</details>

<details>

<summary>"This request ran too long and was stopped"</summary>

A single request can run for up to 45 minutes. The work done so far is saved. Send a follow-up to continue, or split the request into smaller steps. See [Describe and build](/ai-workbench-qore/console/app-builder/app-workspace#describe-and-build).

</details>

<details>

<summary>"We are currently experiencing an issue with code generation"</summary>

Code generation failed. Try again, or switch to a different model. See [Describe and build](/ai-workbench-qore/console/app-builder/app-workspace#describe-and-build).

</details>

<details>

<summary>The preview shows an error</summary>

A bar at the bottom of the build conversation shows the error, for example `UNHANDLED_REJECTION`, with **Fix with AI**. Select it to send the error type and message to the build agent, which fixes the app and rebuilds the preview. See [Fix errors](/ai-workbench-qore/console/app-builder/app-workspace#fix-errors).

</details>

<details>

<summary>Fix with AI is greyed out in Security</summary>

Fix with AI is already working. Wait for it to finish. See [Security Scans](/ai-workbench-qore/console/app-builder/security-scans).

</details>

<details>

<summary>Proceed is greyed out in Attach Agent(s)</summary>

Tick at least one agent. See [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent).

</details>

<details>

<summary>The Export icon is disabled or missing</summary>

Exporting needs the **Export App** capability. The icon isn't shown while the app is still in its initial plan. See [Export](/ai-workbench-qore/console/app-builder/app-workspace#export).

</details>

### Tests and publishing

<details>

<summary>A build failed its tests</summary>

Open **View Report** to see which suites and tests failed. Fix the app in the workspace, by describing the fix or forwarding a failing test to the build agent, then rebuild; the new build gets its own test run. See [If a build fails its tests](/ai-workbench-qore/console/app-builder/testing#if-a-build-fails-its-tests).

</details>

<details>

<summary>Publish is unavailable</summary>

**Publish** is unavailable in Plan Mode, and publishing needs the **Publish an app** capability. Without it, hovering shows *You don't have access to publish apps*. See [Plan](/ai-workbench-qore/console/app-builder/plan#plan-mode) and [Roles](/ai-workbench-qore/control-center/admin/roles).

</details>

<details>

<summary>The checklist shows the database as Not Configured</summary>

Select **Connect** beside the database, choose a database, then create a schema or connect an existing one. See [Connect the database](/ai-workbench-qore/console/app-builder/deploy#connect-the-database).

</details>

<details>

<summary>"Publishing Failed"</summary>

Select **Try Again**, or **Fix with AI** to send the failure to the build agent. **View Error Details** opens the deploy log, with numbered build steps and the underlying error. See [Resolve a failed publish](/ai-workbench-qore/console/app-builder/deploy#resolve-a-failed-publish).

</details>

<details>

<summary>Import from GitLab shows no projects</summary>

GitLab needs an account connection first. Select **Connect GitLab**, authorize Qore, and return to the tab. See [Import from GitLab](/ai-workbench-qore/console/app-builder/creating-and-importing-apps#import-from-gitlab).

</details>

### Related

* [App Workspace](/ai-workbench-qore/console/app-builder/app-workspace), [Importing apps](/ai-workbench-qore/console/app-builder/creating-and-importing-apps), [Testing](/ai-workbench-qore/console/app-builder/testing), [Security Scans](/ai-workbench-qore/console/app-builder/security-scans), and [Deploy](/ai-workbench-qore/console/app-builder/deploy)
* [Create an app](/ai-workbench-qore/task-guides/create-an-app): every App 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 %}


# Knowledge

Build queryable knowledge from your documents, then attach it to agents and apps.

Knowledge turns source documents into queryable content for agents. Qore creates a table of contents, tags, and embeddings that agents retrieve during conversations.

Select **Knowledge** in the Console sidebar. Create knowledge at the top of the page and manage project knowledge bases below it. Select **All Datasets** to manage source files. For every task in one place, see [Create a knowledge base](/ai-workbench-qore/task-guides/create-a-knowledge).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-3b39c294803ab40a8f0025e242f2c6df9170791a%2F020_knowledge_landing_cards.png?alt=media" alt="The Knowledge page: Create New Knowledge with a Describe what this knowledge should hold… prompt, a + button and a Datasets selector, three suggestion chips, and MY KNOWLEDGE below as a grid of cards, each with a name, description, Last updated time, a play button and a ⋮ menu; All Datasets sits top right"><figcaption><p>Knowledge opens on the creation prompt, with every knowledge base in the project below it.</p></figcaption></figure>

## At a glance

| Task                                   | Start with                                 | Result                                                               |
| -------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------- |
| Build knowledge from a description     | The **Create New Knowledge** prompt        | A configured knowledge base                                          |
| Group source files                     | **All Datasets**                           | A named dataset that tracks ingestion                                |
| Bring changed files into the knowledge | A knowledge base → **Datasets** → **Sync** | A new knowledge version that agents answer from                      |
| Inspect what was extracted             | A knowledge base → **Content**             | The table of contents, tags, raw extraction and summary per document |
| Use what you built                     | **Try Knowledge**, or attach it            | Grounded answers, in the playground or in an agent                   |

Two concepts work together:

{% columns %}
{% column %}

#### Dataset

A named grouping of source files. It tracks ingestion but does not interpret content.

See [Datasets](/ai-workbench-qore/console/knowledge/datasets).
{% endcolumn %}

{% column %}

#### Knowledge base

Qore builds it from datasets or attached files. It contains a table of contents, tags, and embeddings that agents can query.
{% endcolumn %}
{% endcolumns %}

A knowledge base only changes when you **sync** it. Updating a file in a dataset does nothing to the knowledge base until that file is synced, and each file that syncs creates a new knowledge version. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

## Create knowledge

Describe what the knowledge should hold. Qore sets up the knowledge base from your description.

Ready-to-use templates provide starting descriptions for common knowledge types. Select a template, then edit its description before you send it.

Choose a source while you create the knowledge:

{% tabs %}
{% tab title="Attach files" %}
Use **+** to attach files from your computer, a cloud drive, or a website. When you give several website URLs, Qore creates a dataset for each.
{% endtab %}

{% tab title="Use datasets" %}
Use **Datasets** to select existing datasets. The selector includes **Search datasets…** and **+ Create Dataset**.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
You do not have to have a dataset first. Describing the knowledge and attaching files in one step is the normal path; datasets matter when you want to reuse the same source files across several knowledge bases, or when you are crawling a website.
{% endhint %}

You can also build knowledge from the **Agent Builder** chat. The agent that builds your agent follows the same process as the Knowledge Builder: it can create a knowledge base, add the files you attach to a dataset, sync it, and attach the result to the agent you're building. See [Build knowledge from the Agent Builder chat](/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent#build-knowledge-from-the-agent-builder-chat).

## Find your knowledge

**MY KNOWLEDGE** lists the project's knowledge bases. Each card shows its name, description, and last update time. Select a card to open it.

| Control               | What it does                                                                                                                                                          |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search knowledge…** | Filters by name and description. It does not search document contents. Query a knowledge base in [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge). |
| List and grid icons   | Switch between row and card views.                                                                                                                                    |
| **▷**                 | Opens [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge) for that knowledge base.                                                                    |
| **⋮**                 | Opens item actions, including delete.                                                                                                                                 |

{% hint style="danger" %}
**Deleting a knowledge base cannot be undone here.** It removes the generated structure — the table of contents, tags, and embeddings. The source files stay in their datasets, so you can build a new knowledge base from them, but the deleted one does not come back.
{% endhint %}

Knowledge created from a website crawl is named after its source.

**All Datasets** in the top right opens [Datasets](/ai-workbench-qore/console/knowledge/datasets).

{% hint style="info" %}
**Share a knowledge base.** Each knowledge base has its own URL. Anyone opening it needs access to the same project.
{% endhint %}

## Work on one knowledge base

Open a knowledge base to refine its scope, manage source files, and inspect processing.

* Select the knowledge base name to switch knowledge bases.
* Use chat to add sources or change the knowledge scope. Each reply shows its credit usage.

{% tabs %}
{% tab title="Datasets" %}
This tab lists the datasets and files that the knowledge base uses. It shows each file's version and status. Sync files, upload new versions, and resolve items needing attention here.

See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).
{% endtab %}

{% tab title="Content" %}
This tab lists processed documents. Select a document to review its **Content**, **Tags**, **Raw extraction**, and **Summary**.

See [Document processing](/ai-workbench-qore/console/knowledge/document-processing).
{% endtab %}
{% endtabs %}

* Select **vN ▾** to view each knowledge version and what created it.
* Select **+ Attach** to add files from your computer, a cloud drive, or a website. See [Add files](/ai-workbench-qore/console/knowledge/datasets#add-files).
* Select **▷ Try Knowledge** to query the knowledge base and inspect the chunks behind each answer. See [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge).

{% hint style="info" %}
**Detach is different from delete.** **Detach dataset** and **Detach from knowledge** remove sources from this knowledge base. The source files remain in the dataset. **Delete from dataset** removes the file from the dataset.
{% endhint %}

## When processing fails

Processing runs through ingestion, table-of-contents generation, tagging, and embeddings. Failures identify the stage that stopped.

Provider throttling commonly stops table-of-contents generation:

> **The provider rate limited the request.**\
> **Failed stage: TOC\_GENERATION**

Failed files show **Sync failed** in **Datasets** and a warning in **Content** → **Documents**. Select the file to view its error and failed stage.

Select **Retry** to process the file again. Qore also retries automatically within two hours. Retries are limited. After all retries are exhausted, **Retry** is unavailable. Correct the source file, then provide a new version. Common issues include scanned PDFs without text and password-protected files.

{% hint style="warning" %}
**Wait before retrying.** An immediate retry usually meets the same rate limit, and every attempt consumes provider quota. Repeated failures across knowledge bases usually mean a tenant-wide throttle rather than a problem with your files — check with your administrator before continuing.
{% endhint %}

A file contributes only after it shows **Synced**. To retry several failed files, select the dataset's **⋮** → **Retry failed files only**. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions#sync-files).

## Retired options

**Legacy Dataset** and **Legacy Knowledge** no longer appear in Knowledge. Use datasets and knowledge bases instead.

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Datasets</strong></td><td>Group source files, add them from uploads, drives, or a website crawl.</td><td><a href="/ai-workbench-qore/console/knowledge/datasets">Datasets</a></td></tr><tr><td><strong>Sync &#x26; versions</strong></td><td>How file updates reach agents through sync and knowledge versions.</td><td><a href="/ai-workbench-qore/console/knowledge/sync-and-versions">Sync &amp; versions</a></td></tr><tr><td><strong>Try Knowledge</strong></td><td>Query any version and see the chunks behind each answer.</td><td><a href="/ai-workbench-qore/console/knowledge/try-knowledge">Try Knowledge</a></td></tr><tr><td><strong>Knowledge FAQs</strong></td><td>Short answers about knowledge bases, files, sync and versions.</td><td><a href="/ai-workbench-qore/console/knowledge/faqs">Knowledge: FAQs &amp; Troubleshooting</a></td></tr><tr><td><strong>Document processing</strong></td><td>The table of contents, tags, raw extraction and summary Qore produces.</td><td><a href="/ai-workbench-qore/console/knowledge/document-processing">Document processing</a></td></tr><tr><td><strong>Attaching Knowledge to an Agent</strong></td><td>Give an agent access to a knowledge base.</td><td><a href="/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent">Attaching Knowledge to an Agent</a></td></tr><tr><td><strong>Knowledge &#x26; Context</strong></td><td>The concept behind retrieval, and when to reach for it.</td><td><a href="/ai-workbench-qore/core-concepts/knowledge-and-context">Knowledge &amp; Context</a></td></tr></tbody></table>

***

{% 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 %}


# Datasets

Group source files from uploads, cloud drives, or a website crawl.

A dataset groups source files for reuse. It tracks ingestion and accepts new files. Create a knowledge base to process and query the content.

{% hint style="info" %}
Use a dataset when several knowledge bases need the same files. You can also create knowledge directly from attached files.
{% endhint %}

### At a glance

| Task             | Start with                    | Result                            |
| ---------------- | ----------------------------- | --------------------------------- |
| Create a dataset | **Create Dataset**            | A reusable source-file group      |
| Add files        | **Attach Files**              | Files ready to sync               |
| Crawl a site     | **Website** → **Start crawl** | Website content added as one file |
| Replace a file   | **Upload new version**        | The next version of that file     |

{% columns %}
{% column %}

#### Dataset

A named source-file group. It tracks files and their ingestion.
{% endcolumn %}

{% column %}

#### Knowledge base

Processed, queryable content built from datasets or attached files.
{% endcolumn %}
{% endcolumns %}

Inside a knowledge base, **Datasets** shows source files, versions, and sync status. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

### Create a dataset

Select **Create Dataset**, then provide the following details:

* **Name** is required. It identifies the dataset.
* **Description** is optional. Use it to distinguish similar datasets.
* **Source Assets** are optional. Add them now or later.

{% tabs %}
{% tab title="Upload" %}
Add files from your computer. Each file can be up to `15 MB`. Add up to `25` files at once.
{% endtab %}

{% tab title="Cloud storage" %}
Add files from **Google Drive**, **OneDrive**, or **SharePoint**. Google Drive uses Google OAuth. OneDrive and SharePoint use Microsoft OAuth.
{% endtab %}

{% tab title="Website" %}
Crawl a public website and add its content to the dataset.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Datasets support `.pdf`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.tiff`, `.bmp`, and other image formats. Google Drive supports the same formats. Files attached from the agent canvas have a `10 MB` limit.
{% endhint %}

### Add files

To add files later, select **Upload files to dataset** for the dataset. Use **Attach Files** to upload, select a cloud provider, or add a website.

New files show **Ready to sync**. They remain outside knowledge-base answers until you sync them. With automatic sync enabled, syncing begins automatically. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions#sync-files).

### Add a website

Use **Website** to crawl public pages without downloading them first.

| Setting           | Default | Range     | Effect                                                        |
| ----------------- | ------- | --------- | ------------------------------------------------------------- |
| **Website URL**   | —       | Valid URL | The crawl starting point                                      |
| **Maximum pages** | `25`    | `1`–`200` | Maximum pages ingested                                        |
| **Link depth**    | `2`     | `1`–`10`  | Link levels followed; `1` includes directly linked pages only |

Select **Start crawl**. Crawling runs in the background. The crawled site is added as one file, so it syncs, versions, and detaches as one unit.

{% hint style="warning" %}
Set the page limit before starting. A crawl that reaches its limit contains only part of the site.
{% endhint %}

### Review files and track ingestion

Each dataset lists a file's name, type, size, and ingestion status. Within a knowledge base, files also show their version and sync status. See [File status](/ai-workbench-qore/console/knowledge/sync-and-versions#understand-statuses).

#### File actions

| Action                     | Result                                                                                                                                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **View document**          | Opens the file                                                                                                                                                                                            |
| **Upload new version**     | Adds the next file version under the same name, from your computer, a cloud drive, or a website. See [File versions](/ai-workbench-qore/console/knowledge/sync-and-versions#knowledge-and-file-versions). |
| **Version history**        | Lists earlier versions                                                                                                                                                                                    |
| **View extracted content** | Shows processed content. See [Document processing](/ai-workbench-qore/console/knowledge/document-processing).                                                                                             |
| **Download original**      | Downloads the uploaded file                                                                                                                                                                               |
| **Detach from knowledge**  | Removes the file from this knowledge base only                                                                                                                                                            |
| **Delete from dataset**    | Removes the file from the dataset                                                                                                                                                                         |

| Status        | Meaning                                                     |
| ------------- | ----------------------------------------------------------- |
| **Completed** | Processing finished. The file can contribute after syncing. |
| `in-progress` | Processing is underway.                                     |
| `queued`      | Processing is waiting to start.                             |
| `failed`      | Processing did not finish.                                  |

Wait for **Completed** before syncing. If processing does not complete, wait a few minutes and refresh. Contact your administrator if the issue persists.

### Search and discovery

* Dataset and file search match names and descriptions.
* Search does not inspect document content.
* Use [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge) to query processed content.

Files are also indexed for semantic discovery. **Preparing for discovery** means indexing is underway. **Discoverable** means indexing is complete. Discovery and sync are independent, so a discoverable file can still be **Ready to sync**.

Discovery searches your data sources by meaning, not by name. Use it to find which dataset holds what you need, for example which one covers this year's rate card:

* On a dataset's page, use **Search this dataset**.
* In the Knowledge Builder chat or the Agent Builder chat, ask for it in your own words.

Only **Discoverable** files are found. A file still **Preparing for discovery** doesn't appear in results yet.

{% hint style="info" %}
**Detaching is not deleting.** Detaching a dataset or file removes it from one knowledge base. Deleting a file removes it from the dataset.
{% endhint %}

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Knowledge</strong></td><td>Build queryable knowledge from source files.</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td><strong>Sync &#x26; versions</strong></td><td>Bring file updates into a knowledge base.</td><td><a href="/ai-workbench-qore/console/knowledge/sync-and-versions">Sync &amp; versions</a></td></tr><tr><td><strong>Document processing</strong></td><td>Review processed document content.</td><td><a href="/ai-workbench-qore/console/knowledge/document-processing">Document processing</a></td></tr><tr><td><strong>Knowledge FAQs</strong></td><td>Find answers about datasets, sync, and versions.</td><td><a href="/ai-workbench-qore/console/knowledge/faqs">Knowledge: FAQs &amp; Troubleshooting</a></td></tr></tbody></table>

***

{% 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 %}


# Sync & versions

How file updates reach agents through sync and knowledge versions.

A knowledge base uses files from its datasets. Update a file, then sync it to create a knowledge version. Agents use the latest completed version, so sync provides a controlled way to update their source knowledge.

Open a knowledge base and select **Datasets** to manage file updates and sync status.

### At a glance

| Goal                   | Action                                   | Result                                               |
| ---------------------- | ---------------------------------------- | ---------------------------------------------------- |
| Update knowledge       | Upload a new file version, then sync it. | Agents use the updated content after sync completes. |
| Review changes         | Open the knowledge version menu.         | See versions and the change that created each one.   |
| Keep a dataset current | Enable auto sync.                        | Eligible new files sync automatically.               |
| Resolve an issue       | Filter for items needing attention.      | Find failed and stale files.                         |

### How updates reach agents

**File → dataset → sync → knowledge version → agents**

A dataset holds source files. Adding or replacing a file does not update a knowledge base immediately. The file remains **Ready to sync** until you sync it.

{% hint style="info" %}
**A completed sync is live.** There is no draft or publish stage. Validate important updates in [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge), then compare answers with the previous version when needed.
{% endhint %}

{% columns %}
{% column %}

#### Before sync

* A new file version remains outside the knowledge base.
* Agents continue using the previous knowledge version.
* You can review the replacement before it becomes active.
  {% endcolumn %}

{% column %}

#### After sync

* Each synced file creates a knowledge version.
* Agents use the latest completed version.
* The file status changes to **Synced**.
  {% endcolumn %}
  {% endcolumns %}

### Knowledge and file versions

Knowledge versions record how the knowledge base changed. The version history shows the latest version first, including:

* The file that a sync added.
* A dataset attachment.
* The initial knowledge-base version.

Each completed file sync creates a separate knowledge version. Version numbers only increase. Earlier versions remain available for queries in [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge), but you cannot make an earlier version current.

To update a file, select **⋮** → **Upload new version**, then choose the replacement from your computer, Google Drive, OneDrive, SharePoint, or a website. The file retains its name and receives the next file version number. Use **Version history** to review earlier file versions.

{% hint style="warning" %}
Cloud-source changes do not sync automatically. When a source changes in Google Drive, OneDrive, or SharePoint, upload the new version before you sync it.
{% endhint %}

### Sync files

Choose the scope that matches your change:

{% tabs %}
{% tab title="All ready files" %}
Select **Sync ready files** to sync every ready file across the knowledge base. This option is unavailable when no files are ready.
{% endtab %}

{% tab title="One dataset" %}
Select **Sync N ready** on a dataset to sync only that dataset's ready files. Use **Re-sync all** when no files are ready but the dataset needs syncing again.
{% endtab %}

{% tab title="Dataset actions" %}
Use the dataset menu for targeted actions:

| Action                          | Use it when                                           |
| ------------------------------- | ----------------------------------------------------- |
| **Sync all preprocessed files** | All processed files in the dataset should be current. |
| **Force re-sync everything**    | You need to rebuild this dataset's contribution.      |
| **Retry failed files only**     | Only failed files need another attempt.               |
| **Upload files to dataset**     | You have new source material.                         |
| **Detach dataset**              | This knowledge base should no longer use the dataset. |
| {% endtab %}                    |                                                       |
| {% endtabs %}                   |                                                       |

{% hint style="warning" %}
**Force re-sync everything** processes every file again. Each synced file creates a version. Use **Retry failed files only** when failures are isolated.
{% endhint %}

#### Auto sync

Enable **Auto sync** from the dataset menu when new files should sync without manual action. Use manual sync for content that requires review before agents use it, such as policies or rate information.

### Understand statuses

Dataset status shows whether its files are available to the knowledge base. The status summary tracks attached files, fully synced datasets, ready files, files in progress, and failed files.

| Dataset status       | Meaning                                               |
| -------------------- | ----------------------------------------------------- |
| **Not synced**       | No files from this dataset are in the knowledge base. |
| **Partially synced** | Some files are synced and others are not.             |
| **Auto sync**        | New eligible files sync automatically.                |

Each file has independent discovery and sync statuses.

{% columns %}
{% column %}

#### Discovery status

| Status                      | Meaning                 |
| --------------------------- | ----------------------- |
| **Discoverable**            | Indexed and searchable. |
| **Preparing for discovery** | Being indexed.          |
| {% endcolumn %}             |                         |

{% column %}

#### Sync status

| Status                    | Action                        |
| ------------------------- | ----------------------------- |
| **Ready to sync**         | Sync the file.                |
| **Syncing**               | Wait for completion.          |
| **Synced**                | No action is needed.          |
| **New version available** | Sync the newer file version.  |
| **Sync failed**           | Retry the file.               |
| **Not eligible**          | Wait for discovery to finish. |
| {% endcolumn %}           |                               |
| {% endcolumns %}          |                               |

A file can be **Discoverable** and **Ready to sync**. It is searchable as a source, but agents do not yet answer from it.

### Resolve items needing attention

Items need attention when a file failed or a newer file version is available. Select **Review** to see those items, or filter by **All**, **Needs attention**, **Ready to sync**, **Processing**, or **Synced**. Search by dataset or file name to find a specific item.

For failed processing, retry the file after addressing the source issue. See [When processing fails](/ai-workbench-qore/console/knowledge#when-processing-fails) for common causes and retry guidance.

{% hint style="info" %}
One dataset can support several knowledge bases. Syncing it in one knowledge base does not update the others. Each knowledge base maintains its own sync statuses and knowledge versions.
{% endhint %}

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Knowledge</strong></td><td>Create knowledge bases and work with them.</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td><strong>Datasets</strong></td><td>Add files from uploads, cloud drives or a website.</td><td><a href="/ai-workbench-qore/console/knowledge/datasets">Datasets</a></td></tr><tr><td><strong>Try Knowledge</strong></td><td>Query any version and see the chunks behind each answer.</td><td><a href="/ai-workbench-qore/console/knowledge/try-knowledge">Try Knowledge</a></td></tr><tr><td><strong>Knowledge FAQs</strong></td><td>Short answers about sync, versions and files.</td><td><a href="/ai-workbench-qore/console/knowledge/faqs">Knowledge: FAQs &amp; Troubleshooting</a></td></tr></tbody></table>

***

{% 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 %}


# Try Knowledge

Query a knowledge base, any version, and inspect the chunks behind each answer.

**Try Knowledge** lets you test a knowledge base before an agent uses it. Ask real user questions, inspect the retrieved chunks, and compare knowledge versions after a sync.

Open a knowledge base in **Console → Knowledge**, then select **Try Knowledge**.

{% hint style="info" %}
Try Knowledge answers from the selected knowledge version only. It does not use agent instructions, tools, or other knowledge.
{% endhint %}

### What you can do

{% columns %}
{% column %}

#### Test coverage

Ask questions your users will ask. A missing answer identifies content that needs syncing or improvement.
{% endcolumn %}

{% column %}

#### Verify retrieval

Inspect the chunks behind an answer. This shows whether the expected content was found and ranked well.
{% endcolumn %}
{% endcolumns %}

| Action                    | Use it to                                             |
| ------------------------- | ----------------------------------------------------- |
| Ask a question            | Check answer quality and knowledge coverage.          |
| View the execution report | Review retrieved chunks and citations.                |
| Select a version          | Compare the latest knowledge with an earlier version. |
| Refresh                   | Clear the conversation and begin a new test.          |

### Test a knowledge base

{% stepper %}
{% step %}

#### Ask a representative question

Enter a question and send it. Use the wording your users would use.
{% endstep %}

{% step %}

#### Review the answer

An answer based on missing context signals a coverage or sync issue.
{% endstep %}

{% step %}

#### Check the evidence

Open **Execution Report**, then select the answer's **Evaluation Report** to inspect its retrieved chunks.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
Test questions that reflect real tasks. An agent using this knowledge base can only retrieve what the knowledge base contains.
{% endhint %}

### Inspect retrieved chunks

The execution report lists the chunks for the selected answer, most relevant first.

{% tabs %}
{% tab title="What each chunk shows" %}

* **Rank and title** identify the source section. A chunk can have no title.
* **Score** shows match strength from `0` to `1`. Higher scores indicate closer matches.
* **Tags** identify document attributes created during processing.

See [Document processing](/ai-workbench-qore/console/knowledge/document-processing) for processing details.
{% endtab %}

{% tab title="How to investigate an answer" %}

* If the expected section is absent, retrieval did not find it.
* If it ranks low, compare its tags and wording with the question.
* Check the source file and its processing before rewriting the question.
  {% endtab %}
  {% endtabs %}

### Compare knowledge versions

Select a version, then ask the same question. The selected version affects only this test. Agents always use the latest version.

| Compare                     | Check                                                  |
| --------------------------- | ------------------------------------------------------ |
| Latest and previous version | Whether the answer changed as expected.                |
| Retrieved chunks            | Whether the expected source is present and ranks well. |

See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions) to learn how updates create knowledge versions.

{% hint style="warning" %}
Only synced content can answer questions. Files that are ready to sync or failed to sync do not contribute. Check file status in the **Datasets** tab when recently uploaded content is missing.
{% endhint %}

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Sync &#x26; versions</strong></td><td>Learn how file updates become knowledge versions.</td><td><a href="/ai-workbench-qore/console/knowledge/sync-and-versions">Sync &amp; versions</a></td></tr><tr><td><strong>Document processing</strong></td><td>Review the content, tags, extraction, and summary behind each document.</td><td><a href="/ai-workbench-qore/console/knowledge/document-processing">Document processing</a></td></tr><tr><td><strong>Attaching Knowledge to an Agent</strong></td><td>Give an agent access to a knowledge base.</td><td><a href="/ai-workbench-qore/console/agent-builder/build/attaching-knowledge-to-an-agent">Attaching Knowledge to an Agent</a></td></tr><tr><td><strong>Knowledge FAQs</strong></td><td>Get answers about knowledge bases, datasets, sync, and versions.</td><td><a href="/ai-workbench-qore/console/knowledge/faqs">Knowledge: FAQs &amp; Troubleshooting</a></td></tr></tbody></table>

***

{% 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 %}


# Document processing

Review how Qore extracts, structures, tags, and summarizes each document.

Qore extracts text, identifies sections, applies tags, and creates a summary for each document. Review these results to confirm that agents can retrieve the right information.

Use document processing when an answer is incomplete or inaccurate. Check it before syncing important files.

### Inspect a document

Open a knowledge base and select a document. Then choose an inspection view.

{% hint style="info" %}
**Review before sync.** A warning indicator identifies a document that needs attention, such as a failed sync.
{% endhint %}

* Select **Content** to review sections and chunks.
* Select **Tags**, **Raw extraction**, or **Summary** to investigate a specific issue.
* Open a dataset file with **⋮** → **View extracted content**.

{% columns %}
{% column %}
**Check structure**

Review **Content** and **Tags** when answers miss or confuse a topic.
{% endcolumn %}

{% column %}
**Check source text**

Review **Raw extraction** when the file itself was read incorrectly.
{% endcolumn %}
{% endcolumns %}

{% tabs %}
{% tab title="Content" %}

### Content

**Content** lists the sections Qore found in document order. Each section shows its chunk count. Select a section to review its extracted text and tags.

Retrieval uses this structure to locate relevant content. Clear, complete sections produce more accurate answers.

{% hint style="warning" %}
If an expected section is missing, or topics are merged, retrieval cannot recover them. Upload a corrected file, then sync it.
{% endhint %}
{% endtab %}

{% tab title="Tags" %}

### Tags

**Tags** label the document and its sections. They use the format `NAMESPACE:VALUE`. The namespace identifies the type of information.

| Namespace       | What it identifies                 |
| --------------- | ---------------------------------- |
| `DOCUMENT_TYPE` | The whole document                 |
| `SECTION_TYPE`  | A chunk's location in the document |
| `CONTENT_TYPE`  | What a chunk contains              |
| `FORMAT_TYPE`   | How content is organized           |
| `TIME_PERIOD`   | The time span a chunk references   |

Tags apply to individual chunks, not only to the document. A chunk can carry several tags that describe its document, position, meaning, and format.

* `SECTION_TYPE` identifies where a chunk appears in the document.
* `CONTENT_TYPE` identifies what a chunk is about.

Hover over a truncated tag to view its full value. You cannot add or edit tags in these views. Qore regenerates them during sync.

{% hint style="info" %}
The available namespaces vary by document type. The table describes common namespaces, not a fixed set.
{% endhint %}
{% endtab %}

{% tab title="Raw extraction" %}

### Raw extraction

**Raw extraction** contains the plain text Qore read before it created sections. Page breaks appear as `[PAGE 1]`. Select **Download** to save the extracted text.

Use this view when text is garbled, a scanned page has no text, or a table lost its structure. Problems here affect every later stage. Upload a better source file, then sync it. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions).

{% hint style="info" %}
Use **Raw extraction** for this review. The **Preprocessed Files** view is no longer available.
{% endhint %}
{% endtab %}

{% tab title="Summary" %}

### Summary

**Summary** provides a short description of the whole document. Use it as a quick check that Qore processed the expected content.

If the summary covers the wrong subject or omits part of the file, confirm the source in **Raw extraction**.
{% endtab %}
{% endtabs %}

### When you sync again

Qore regenerates the table of contents, tags, and summary during sync. **Force re-sync everything** replaces existing processing results. It does not merge them.

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Knowledge</strong></td><td>Create knowledge bases, query them, and attach them.</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td><strong>Knowledge Datasets</strong></td><td>Manage the source files Qore processes.</td><td><a href="/ai-workbench-qore/console/knowledge/datasets">Datasets</a></td></tr><tr><td><strong>Sync &#x26; versions</strong></td><td>Sync file updates and review knowledge versions.</td><td><a href="/ai-workbench-qore/console/knowledge/sync-and-versions">Sync &amp; versions</a></td></tr><tr><td><strong>Try Knowledge</strong></td><td>Inspect the chunks and tags behind an answer.</td><td><a href="/ai-workbench-qore/console/knowledge/try-knowledge">Try Knowledge</a></td></tr><tr><td><strong>Knowledge &#x26; Context</strong></td><td>Why agents search your knowledge instead of reading all of it.</td><td><a href="/ai-workbench-qore/core-concepts/knowledge-and-context">Knowledge &amp; Context</a></td></tr></tbody></table>

***

{% 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 %}


# Knowledge: FAQs & Troubleshooting

Short answers about knowledge bases, datasets, sync, versions and Try Knowledge.

Short answers to the questions people ask most about Knowledge. Each one links to the page that covers it in full.

## Knowledge bases

<details>

<summary>Why doesn't Knowledge expand in the sidebar?</summary>

It has no submenu. Selecting **Knowledge** opens one page: a prompt to create knowledge at the top, and every knowledge base in the project below it as cards. Open a knowledge base by selecting its card. See [Knowledge](/ai-workbench-qore/console/knowledge).

</details>

<details>

<summary>Where are my datasets?</summary>

Select **All Datasets** in the top right of the Knowledge page. It lists every dataset in the project with its description, number of sources and when it last changed. The datasets a particular knowledge base uses are on that knowledge base's **Datasets** tab. See [Datasets](/ai-workbench-qore/console/knowledge/datasets).

</details>

<details>

<summary>What is the difference between a dataset and a knowledge base?</summary>

A **dataset** holds source files and tracks their processing. It does not interpret them. A **knowledge base** is what Qore builds from the files in one or more datasets: a table of contents, tags and embeddings that an agent can search. You attach a knowledge base to an agent, not a dataset. See [Knowledge](/ai-workbench-qore/console/knowledge).

</details>

<details>

<summary>Do I need a dataset before I create a knowledge base?</summary>

No. Describe the knowledge base and attach files in the same step, and Qore sets up what it needs. Create datasets first when you want to reuse the same files across several knowledge bases. See [Create knowledge](/ai-workbench-qore/console/knowledge#create-knowledge).

</details>

<details>

<summary>Can I share a knowledge base with a colleague?</summary>

Yes, by link. Each knowledge base has its own URL. The person you share it with needs access to the same project.

</details>

<details>

<summary>What happens when I delete a knowledge base?</summary>

The knowledge base and everything Qore generated for it are removed: the table of contents, tags and embeddings. This cannot be undone. The source files stay in their datasets, so you can build a new knowledge base from them. See [Find your knowledge](/ai-workbench-qore/console/knowledge#find-your-knowledge).

</details>

## Datasets and files

<details>

<summary>Which file types and sizes can I add?</summary>

`.pdf`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.tiff`, `.bmp` and other image formats, up to `15 MB` per file and `25` files per upload. The same formats apply to files from Google Drive. The Agent Builder canvas has a lower limit of `10 MB` per file. See [Create a dataset](/ai-workbench-qore/console/knowledge/datasets#create-a-dataset).

</details>

<details>

<summary>Why does Google Drive, OneDrive or SharePoint ask me to sign in?</summary>

Cloud sources need your permission before Qore can read your files, so the first time you pick one you authorize Qore with your Google or Microsoft account. If your administrator manages those permissions, ask them before you start.

</details>

<details>

<summary>What do I get when I crawl a website?</summary>

One file, added to the dataset you crawled from, holding every page the crawl reached. The crawl runs in the background. **Maximum pages** (default `25`, up to `200`) caps how much of the site you get, so raise it before you crawl a large site. See [Add a website](/ai-workbench-qore/console/knowledge/datasets#add-a-website).

</details>

<details>

<summary>What is the difference between Detach and Delete?</summary>

**Detach from knowledge** and **Detach dataset** remove a file or a dataset from one knowledge base. The files stay in the dataset, and other knowledge bases that use them are unaffected. **Delete from dataset** removes the file from the dataset itself. See [File actions](/ai-workbench-qore/console/knowledge/datasets#file-actions).

</details>

<details>

<summary>Can I download a file I uploaded?</summary>

Yes. In the knowledge base's **Datasets** tab, open the file's **⋮** menu and select **Download original**. To download the text Qore extracted from it instead, open the document's **Raw extraction** tab and select **Download**. See [Document processing](/ai-workbench-qore/console/knowledge/document-processing).

</details>

## Sync and versions

<details>

<summary>I uploaded a new version of a file. Why is the agent still giving the old answer?</summary>

Uploading changes the dataset, not the knowledge base. The file waits as **Ready to sync**, and agents keep answering from the last synced version until you sync it. Sync the file, wait for **Synced**, and the agent answers from the new version. See [How updates reach agents](/ai-workbench-qore/console/knowledge/sync-and-versions#how-updates-reach-agents).

</details>

<details>

<summary>What creates a new knowledge version?</summary>

Each file that finishes syncing creates one version, and so does attaching a dataset. Syncing five files gives you five new versions, each named after the file it added. The **vN ▾** menu lists them all. See [Knowledge and file versions](/ai-workbench-qore/console/knowledge/sync-and-versions#knowledge-and-file-versions).

</details>

<details>

<summary>What is the difference between Ready to sync and Synced?</summary>

**Ready to sync** means the file is processed and in the dataset, but not yet in the knowledge base. **Synced** means the knowledge base answers from it. See [Sync status](/ai-workbench-qore/console/knowledge/sync-and-versions#sync-status).

</details>

<details>

<summary>Can I upload a new version from a cloud drive or a website?</summary>

Yes. **Upload new version** takes the replacement from your computer, Google Drive, OneDrive, SharePoint, or a website. The file keeps its name and gets the next version number. Sync it to bring it into the knowledge base. See [Sync & versions](/ai-workbench-qore/console/knowledge/sync-and-versions#knowledge-and-file-versions).

</details>

<details>

<summary>What does New version available mean?</summary>

The knowledge base holds an older version of the file than the dataset does. The file counts as *stale* in the **Needs attention** banner. Sync it to bring the knowledge base up to date.

</details>

<details>

<summary>What does auto sync do?</summary>

With **Enable auto sync** on a dataset, files added to it start syncing into the knowledge base without you selecting **Sync**. The dataset shows an **Auto sync** badge. Leave it off where you want to check a file before agents use it. See [Auto sync](/ai-workbench-qore/console/knowledge/sync-and-versions#auto-sync).

</details>

<details>

<summary>When should I use Force re-sync everything instead of Retry failed files only?</summary>

Use **Retry failed files only** when some files show **Sync failed**. It leaves the rest alone. Use **Force re-sync everything** only when the whole dataset looks wrong in the knowledge base. It syncs every file again, which takes longer and creates a version for each file. See [Sync files](/ai-workbench-qore/console/knowledge/sync-and-versions#sync-files).

</details>

<details>

<summary>Can I edit knowledge content directly?</summary>

No. To change what a knowledge base says, upload a corrected version of the source file and sync it. Even a one-word fix goes through the file. See [Knowledge and file versions](/ai-workbench-qore/console/knowledge/sync-and-versions#knowledge-and-file-versions).

</details>

<details>

<summary>Can I roll a knowledge base back to an earlier version?</summary>

No. Earlier versions stay in the **vN ▾** menu, and you can still query them in Try Knowledge, but you cannot make one current again. To undo a change, upload the earlier file as a new version and sync it.

</details>

## Try Knowledge

<details>

<summary>Can I test an older version of the knowledge base?</summary>

Yes. In Try Knowledge, pick the version from the **vN ▾** picker and ask your question. This only affects Try Knowledge. Agents always answer from the latest version. See [Compare knowledge versions](/ai-workbench-qore/console/knowledge/try-knowledge#compare-knowledge-versions).

</details>

<details>

<summary>What does the Score on a chunk mean?</summary>

How closely that chunk matched your question, from `0` to `1`. Higher is closer. Chunks are listed from the highest score down. See [Inspect retrieved chunks](/ai-workbench-qore/console/knowledge/try-knowledge#inspect-retrieved-chunks).

</details>

<details>

<summary>What are Execution Report and Evaluation Report?</summary>

**Execution Report**, top right, opens the **Knowledge Chunks and Citations** panel. **Evaluation Report**, under each question, picks which answer the panel shows. A green dot marks the selected answer.

</details>

<details>

<summary>Why does Try Knowledge answer differently from my agent?</summary>

Try Knowledge answers from the knowledge base alone. An agent also follows its instructions and can use its tools and other knowledge, so its answer can differ even from the same chunks.

</details>

## Discovery and search

<details>

<summary>What does Discoverable mean?</summary>

The file is indexed for semantic search over your data sources. While indexing runs, it shows **Preparing for discovery**. Discovery is separate from sync: a **Discoverable** file can still be **Ready to sync**. See [Search and discovery](/ai-workbench-qore/console/knowledge/datasets#search-and-discovery).

</details>

<details>

<summary>How do I find which dataset has the information I need?</summary>

Use discovery, which searches your data sources by meaning. On a dataset's page, use **Search this dataset**. Or ask in the Knowledge Builder or Agent Builder chat, in your own words. Only **Discoverable** files are found. See [Search and discovery](/ai-workbench-qore/console/knowledge/datasets#search-and-discovery).

</details>

<details>

<summary>Why doesn't searching find text inside my documents?</summary>

**Search knowledge…** and dataset search match names and descriptions only. To search what documents say, ask the knowledge base in [Try Knowledge](/ai-workbench-qore/console/knowledge/try-knowledge).

</details>

## Troubleshooting

<details>

<summary>A file shows Sync failed. What should I do?</summary>

Open the **Content** tab and select the file in **Documents** to see the error and the stage it failed at. Then retry: one file from its row, or several with the dataset's **⋮** → **Retry failed files only**. If retries keep failing, the file itself is usually the problem, for example a scanned PDF with no text. Upload a better copy as a new version. See [When processing fails](/ai-workbench-qore/console/knowledge#when-processing-fails).

</details>

<details>

<summary>What does "3 files need attention — 2 failed, 1 stale" mean?</summary>

Two files failed to sync, and one is out of date in the knowledge base because a newer version exists in the dataset. Select **Review**, or set the filter to **Needs attention**, to see them. See [Resolve items needing attention](/ai-workbench-qore/console/knowledge/sync-and-versions#resolve-items-needing-attention).

</details>

<details>

<summary>Processing failed with "The provider rate limited the request". Should I retry right away?</summary>

No. An immediate retry usually meets the same limit and uses more quota. The product retries on its own within two hours. If several knowledge bases fail the same way, the limit is probably tenant-wide, so check with your administrator. See [When processing fails](/ai-workbench-qore/console/knowledge#when-processing-fails).

</details>

<details>

<summary>A file has been Preparing for discovery or Syncing for a long time. What now?</summary>

Wait a few minutes and refresh. While a file is **Preparing for discovery** it shows **Not eligible** for sync, and that clears on its own. Long delays across many files are usually platform-wide, so raise them with your administrator.

</details>

<details>

<summary>Where did Legacy Dataset and Legacy Knowledge go?</summary>

They have been retired and no longer appear in Knowledge. Use datasets and knowledge bases instead. See [Datasets](/ai-workbench-qore/console/knowledge/datasets).

</details>

### Related

<table data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Knowledge</strong></td><td>Create knowledge bases and work with them.</td><td><a href="/ai-workbench-qore/console/knowledge">Knowledge</a></td></tr><tr><td><strong>Sync &#x26; versions</strong></td><td>How file updates reach agents.</td><td><a href="/ai-workbench-qore/console/knowledge/sync-and-versions">Sync &amp; versions</a></td></tr><tr><td><strong>Datasets</strong></td><td>Add files from uploads, cloud drives or a website.</td><td><a href="/ai-workbench-qore/console/knowledge/datasets">Datasets</a></td></tr><tr><td><strong>Try Knowledge</strong></td><td>Query any version and see the chunks behind each answer.</td><td><a href="/ai-workbench-qore/console/knowledge/try-knowledge">Try Knowledge</a></td></tr></tbody></table>

***

{% 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 %}


# Flows

Describe an automation in chat, and Qore builds a flow to run it. Test it, publish it, and use it from an agent.

A **flow** is an automation of connected tasks. A trigger starts the flow, and each task passes results onward.

Describe the automation in chat. Qore creates a draft for you to configure, test, and publish.

Flows are project-scoped. A flow is available only in its project.

{% hint style="info" %}
**Flows are in preview.** The experience may change.
{% endhint %}

## Get started

In **Console**, select a project, then select **Flows**. **Create New Flow** reads *Describe the automation. I'll build the flow to run it.* Describe a new automation in **Describe the flow you want to build…**, or select a template chip, such as **Fraud Investigation**, **Loan Approval Flow**, or **KYC Verification Flow**.

**My Flows** lists your flows. Use **Search flows…** to find one by name, and switch between the list and grid layouts. To open a flow, select **•••** on its row, then **Edit**.

You can also create a flow from an agent's **Add Skill to Agent** dialog: **Flows** tab › **+ Create Flow**. See [Build a flow](/ai-workbench-qore/console/flows/build-a-flow#create-a-blank-flow-from-an-agent).

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-025510f7e6e6c82b8ab61d9e2ed634355e84b205%2Fqore_flows_how-to-flows-home_rounded_shadow.png?alt=media" alt="The Flows page: Create New Flow with a prompt box, template chips such as Fraud Investigation, Loan Approval Flow and KYC Verification Flow, and a My Flows list with Search flows and list and grid icons"><figcaption><p>Create a flow or open an existing one.</p></figcaption></figure>

For every task in one place, see [Create a flow](/ai-workbench-qore/task-guides/create-a-flow).

<table data-view="cards"><thead><tr><th>Topic</th><th data-card-target data-type="content-ref">Learn more</th></tr></thead><tbody><tr><td>Create drafts, choose triggers, and configure tasks.</td><td><a href="/ai-workbench-qore/console/flows/build-a-flow">Build a flow</a></td></tr><tr><td>Define schemas and share data securely across tasks.</td><td><a href="/ai-workbench-qore/console/flows/flow-inputs-outputs-and-variables">Flow inputs, outputs, and variables</a></td></tr><tr><td>Validate drafts, publish versions, and inspect past runs.</td><td><a href="/ai-workbench-qore/console/flows/test-and-publish-flows">Test and publish flows</a></td></tr><tr><td>Use a flow as an agent skill and review permissions.</td><td><a href="/ai-workbench-qore/console/flows/use-flows-with-agents">Use flows with agents</a></td></tr><tr><td>Find answers to common questions and resolve known flow issues.</td><td><a href="/ai-workbench-qore/console/flows/flows-faqs-and-troubleshooting">Flows: FAQs &amp; Troubleshooting</a></td></tr></tbody></table>

### Related resources

{% content-ref url="/pages/U2DLXxsJzqrUQ7hsS9ti" %}
[Projects](/ai-workbench-qore/console/projects)
{% endcontent-ref %}

{% content-ref url="/pages/8bBmw8K6OWJO25M5na0a" %}
[Skill Library](/ai-workbench-qore/platform-resources/skill-library)
{% endcontent-ref %}

***

{% 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 %}


# Build a flow

Create a draft flow from a chat prompt, then configure its trigger and tasks.

Flows turn a described automation into connected tasks. Build a draft, review its design, and configure each task before testing it.

{% hint style="info" %}
**Flows are in preview.** The experience may change as the feature develops.
{% endhint %}

## Create a draft

{% stepper %}
{% step %}

#### Describe the automation

In **Flows**, enter what the flow receives, what it should do, and what it returns.
{% endstep %}

{% step %}

#### Send the prompt

Qore creates a draft and opens it in the builder. The chat summarizes the flow's name, tasks, input, output, and trigger.
{% endstep %}

{% step %}

#### Refine the draft

Continue the conversation to request changes, or edit the flow directly. Review **Agent Reasoning** for the design rationale.
{% endstep %}
{% endstepper %}

Ready-to-use templates provide a starting description for common automations. Select one when its scenario matches your goal, then tailor the generated draft.

## Create a blank flow from an agent

In an agent's **Add Skill to Agent** dialog, select the **Flows** tab, then **+ Create Flow**. In **Create New Flow** (*Create a reusable flow as a Skill to extend your AI…*), enter a **Flow Name** and a **Description**, both required, and select **Save**. To set the flow's image, select **Upload** and choose an image up to 2 MB; **Remove** clears it.

The flow opens in the builder with an empty canvas, and the chat reads *Workflow "‹name›" created. How can I help to build your workflow?* It also appears in **My Flows** on the Flows page.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-a2bd4e17539704b90986c028c7c2f74cf76c4a24%2Fqore_flows_how-to-create-new-flow-dialog_rounded_shadow.png?alt=media" alt="The Create New Flow dialog: an avatar with Upload and Remove buttons, required Flow Name and Description fields, and Cancel and Save buttons"><figcaption><p>Create New Flow, from an agent.</p></figcaption></figure>

## The builder

The chat is on the left, and the canvas is on the right. Above the canvas: *All changes saved in cloud*, the **Editor** and **Try Out** tabs, **Flow I/O**, and **Publish**. The rail on the left holds the flow canvas, **Variables**, **Version History**, **Execution History**, and help (**?**). Zoom controls sit at the bottom. To rename the flow, select its name at the top of the chat, then **Rename Flow**.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-857bb5a4422b26b8386c42201647f02e3640fd3b%2Fqore_flows_how-to-builder-empty_rounded_shadow.png?alt=media" alt="The flow builder: All changes saved in cloud, the Editor and Try Out tabs, Flow I/O and Publish, a rail of icons on the left, Start of Flow with an Add Trigger button in the canvas, and zoom controls at the bottom"><figcaption><p>A new flow in the builder.</p></figcaption></figure>

## Configure the flow

### Choose a trigger

A trigger starts the flow. In a new flow, select **+ Add Trigger** under **Start of Flow**. In a drafted flow, select the trigger in the canvas. Then choose one.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-d1d9e47399ccaf0438dd5ca0f9c500bc092df45e%2Fqore_flows_how-to-add-trigger-menu_rounded_shadow.png?alt=media" alt="The Add Trigger menu: A trigger is what starts your workflow, with Start manually, Start through Agent and Start via trigger, each with a description"><figcaption><p>The trigger options.</p></figcaption></figure>

| Trigger                 | Starts the flow                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| **Start manually**      | When a user launches it. Use it for testing or simple setups.                                |
| **Start through Agent** | When an AI agent runs the flow.                                                              |
| **Start via trigger**   | When an external event occurs, such as a Slack message. This option is still in development. |

{% hint style="info" %}
**Flow triggers differ from agent triggers.** A flow trigger starts a flow. Configure an agent's own triggers in [Triggers](/ai-workbench-qore/console/agent-builder/build/triggers).
{% endhint %}

### Add and configure tasks

Each task performs one job. Select **Select Task**, or the **+** after a task. Search by task name, then select a task to configure it.

| Task              | Purpose                                                    |
| ----------------- | ---------------------------------------------------------- |
| **Agent**         | Runs an agent as a flow step.                              |
| **Prompt**        | Sends a prompt to an AI model.                             |
| **Dataset**       | Reads from or writes to a dataset.                         |
| **Pass Through**  | Passes data to the next task.                              |
| **Sticky Note**   | Documents the flow in the canvas.                          |
| **User Approval** | Waits for a user's approval before continuing. In preview. |
| **Knowledge**     | Pushes data to a knowledge store. In preview.              |

Required settings have an asterisk. A red warning icon means a required setting is missing. Complete it before publishing.

### Task settings

{% tabs %}
{% tab title="Prompt" %}

| Setting                     | Purpose                                                                         |
| --------------------------- | ------------------------------------------------------------------------------- |
| **Model**                   | Selects the model that runs the prompt.                                         |
| **Instructions for the AI** | Required. Defines the model's task.                                             |
| **Query**                   | Required. Supplies the message or data.                                         |
| **Tools**                   | Makes tools, such as `web_search`, available to the model.                      |
| **Document ID**             | Supplies one or more document IDs, or a flow input such as `$input.documentId`. |
| {% endtab %}                |                                                                                 |

{% tab title="Agent" %}

| Setting              | Purpose                                      |
| -------------------- | -------------------------------------------- |
| **Agent**            | Required. Selects the agent to run.          |
| **Use Context**      | Passes the flow context. Enabled by default. |
| **Use Chat History** | Passes chat history. Disabled by default.    |
| **Document ID**      | Supplies one or more document IDs.           |
| {% endtab %}         |                                              |

{% tab title="Knowledge and approval" %}

| Task              | Settings                                               |
| ----------------- | ------------------------------------------------------ |
| **Knowledge**     | Select a knowledge store and the document IDs to push. |
| **User Approval** | Enter the required message shown to the approver.      |
| **Sticky Note**   | Add text that documents the flow.                      |
| **Pass Through**  | Use global and output variables to pass data onward.   |
| {% endtab %}      |                                                        |
| {% endtabs %}     |                                                        |

Open **Advance** to assign task inputs from global variables and map output fields to output variables.

***

{% 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 %}


# Flow inputs, outputs, and variables

Define the data a flow accepts, returns, and shares across tasks.

Flow I/O defines a flow's contract. Variables supply shared values and protect credentials used during a run.

## Define inputs and outputs

Open **Flow I/O** to configure the schemas: the request parameters and the expected response format.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-dc30638f52954103e064b08d779de3e7f171ee4d%2Fqore_flows_how-to-flow-io-input_rounded_shadow.png?alt=media" alt="The Flow I/O dialog on the Input Schema tab, with Basic and Advanced modes, a Key, Type, Description and Required table with an Add button, and Save"><figcaption><p>Flow I/O, on the Input Schema tab.</p></figcaption></figure>

| Schema            | Defines                                  | Example                             |
| ----------------- | ---------------------------------------- | ----------------------------------- |
| **Input Schema**  | Values supplied when the flow starts.    | `documentId`, text, required.       |
| **Output Schema** | Values returned when the flow completes. | `extracted_data`, object, required. |

Choose an editing mode:

{% columns %}
{% column %}

#### Basic

Add fields in a table. Set **Key**, **Type**, **Description**, and **Required**.

Supported types: **Text**, **Number**, **Boolean**, **Object**, **Array**, and **Dropdown**.
{% endcolumn %}

{% column %}

#### Advanced

Edit the schema as JSON Schema. Use this mode when you need direct schema control.
{% endcolumn %}
{% endcolumns %}

Select **Save** after editing. Input fields also appear on the **Global Variables** tab as read-only entries.

## Use variables

Variables declared in a flow are available to all tasks. Open them with **Variables** on the builder's rail.

| Type                 | Use for                                            | Reference                 |
| -------------------- | -------------------------------------------------- | ------------------------- |
| **Secrets**          | API keys, tokens, and other credentials.           | `$secret.{variable_name}` |
| **Global Variables** | Values shared across tasks, such as a document ID. | `$global.{variable_name}` |

### Add a secret

1. Select **Add Secret**.
2. Enter a required **Name** and **Value**.
3. Choose **String** or **JSON** for **Type**.
4. Select **Secured** when appropriate, then select **Save**.

{% hint style="warning" %}
**Store credentials as secrets.** Reference `$secret.CRM_TOKEN` in task settings. Do not enter credentials directly in a task.
{% endhint %}

### Add a global variable

1. Select **Add Variable**.
2. Enter a required **Key**.
3. Choose a type and add a description.
4. Select **Required** when the flow cannot run without it.
5. Select **Save**.

Task configuration can map a global variable to an input. It can also map a task output to an output variable.

***

{% 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 %}


# Test and publish flows

Run a flow with test data, respond to approvals, and publish a verified version.

Test a draft before publishing it. Review each task's result, resolve configuration issues, and then make the version available.

## Test a flow

{% stepper %}
{% step %}

#### Open Try Out

Switch from **Editor** to **Try Out**.
{% endstep %}

{% step %}

#### Provide input

Enter a value for every field in the input schema. Use **JSON Grid** for one field per row: select **+ Add Entry**, enter a **Key** and **Value**, then select **✓**. Or use **Raw** for JSON input.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-0035b30d888cf06852646af3c70598ea10f5dbcd%2Fqore_flows_how-to-try-out-add-entry_rounded_shadow.png?alt=media" alt="The Input panel in JSON Grid mode, with Key and Value fields, confirm and discard buttons, and Run and Cancel"><figcaption><p>Adding an input entry in JSON Grid.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Run and inspect

Select **Run**. The **Execution Log** records each task and its result. Before the first run, it reads *No execution logs available*.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-981917f380cd334de811cc609d2caa466b224995%2Fqore_flows_how-to-try-out_rounded_shadow.png?alt=media" alt="Try Out: the Input panel in Raw mode showing an empty JSON object with Run and Cancel, and the Execution Log reading No execution logs available"><figcaption><p>Try Out.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Respond to an approval request

A **User Approval** task pauses the run. Enter the requested `answer`, such as `approve`, then select **Continue**. Select **Cancel** to stop the run.

## Publish a flow

Changes remain in a draft until you select **Publish**. Publishing makes the draft the current published version.

{% hint style="info" %}
**Validate before publishing.** Complete all required task settings and review the Execution Log for expected results.
{% endhint %}

## Manage versions and runs

| Area                     | Use it to                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------- |
| **Version History**      | Review the draft, current published version, and earlier saved versions.           |
| **Revert Draft Changes** | Discard the draft and restore the published version.                               |
| **Execution History**    | Review every run by date, time, and status. Select a run to inspect task outcomes. |

***

{% 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 %}


# Use flows with agents

Make a flow available to an agent and understand flow permissions.

Every flow becomes a skill with the same name and description. Add it to an agent when the agent needs to run that automation.

## Connect a flow to an agent

Choose the approach that fits your flow:

* **Add the flow as a skill.** In the agent's **Add Skill** dialog, select the flow on the **Flows** tab. With no flows yet, the tab reads *No skills found*; select **+ Create Flow** to make one. A flow made here also appears in **My Flows** on the Flows page. The agent can run it when a request needs it. See [Adding a skill to the agent](/ai-workbench-qore/console/agent-builder/build/adding-a-skill-to-the-agent).
* **Allow the agent to start the flow.** Configure the flow with the **Start through Agent** trigger.

## Permissions

Your role determines what you can do with flows. See [Roles](/ai-workbench-qore/control-center/admin/roles) for complete role capabilities.

| Action                             | Roles                                           |
| ---------------------------------- | ----------------------------------------------- |
| View or trigger a flow             | Every role                                      |
| Build, publish, or manage versions | Developer, Account Admin, or Organisation Admin |
| Attach an agent to a flow          | Developer                                       |

***

{% 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 %}


# Flows: FAQs & Troubleshooting

Find answers to common flow questions and resolve known configuration and test issues.

This page answers common questions about building and running flows. Use the troubleshooting steps when the product shows a specific status or warning.

## FAQs

<details>

<summary>Where can I use a flow?</summary>

A flow belongs to the project where you create it. It is not available in other projects.

</details>

<details>

<summary>How do I start a flow?</summary>

Choose a trigger:

* **Start manually** starts the flow when a user launches it.
* **Start through Agent** lets an AI agent start the flow.
* **Start via trigger** starts from an external event. This option is still in development.

</details>

<details>

<summary>Can an agent use a flow?</summary>

Yes. Each flow is available as a skill with the flow's name and description. Add it through the agent's **Add Skill** dialog, or use the **Start through Agent** trigger.

</details>

<details>

<summary>How do I provide input to a flow?</summary>

Define fields in **Input Schema**. During **Try Out**, provide a value for each field. You can enter values in **JSON Grid** or as raw JSON.

</details>

<details>

<summary>How do I protect credentials?</summary>

Store API keys, tokens, and other credentials as **Secrets**. Reference them in task settings with `$secret.{variable_name}`.

</details>

<details>

<summary>When do changes become available?</summary>

Changes remain in a draft until you select **Publish**. Publishing makes that draft the current published version.

</details>

## Troubleshooting

<details>

<summary>A task shows a red warning icon</summary>

A required task setting is empty. Select the task, complete the required setting, and test the flow again before publishing.

</details>

<details>

<summary>The flow pauses during a test</summary>

The run may be waiting at a **User Approval** task. Enter the requested `answer`, then select **Continue**. Select **Cancel** to stop the run.

</details>

<details>

<summary>A test result is not what you expected</summary>

Open **Execution Log** after the run. It lists each task and its result. Review the input values and task configuration, then run the test again.

</details>

<details>

<summary>I need to undo draft changes</summary>

Open **Version History** and select **Revert Draft Changes**. This restores the published version.

</details>

{% hint style="info" %}
**Need configuration details?** See [Build a flow](/ai-workbench-qore/console/flows/build-a-flow) and [Test and publish flows](/ai-workbench-qore/console/flows/test-and-publish-flows).
{% endhint %}

***

{% 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 %}


# Store

Browse ready-made agents and apps, then launch a solution that fits your work.

The Store gives you ready-made AI agents and micro-apps on the Qore platform. It helps you start with a working solution rather than build one from scratch.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2F7liw42Zd9YdpK7lfGXBF%2Fuptiq-qore_store_agents-tab_rounded_shadow_1.png?alt=media&amp;token=0da58762-dfd0-41ac-9ab7-67a2dc19dc0e" alt="The Store page displaying ready-made AI agents and micro-apps."><figcaption><p>Browse ready-made agents and apps in the Store.</p></figcaption></figure>

### Find and launch a solution

Open **Console** → **Store**. Use the **Agents** and **Apps** tabs, or search with **Search store**.

{% columns %}
{% column %}

#### Agents

Agents handle task-specific or multi-task AI work. Select **Chat Now** to start a conversation.
{% endcolumn %}

{% column %}

#### Apps

Apps are small, purpose-built applications. Select **Launch** to open an app.
{% endcolumn %}
{% endcolumns %}

{% hint style="info" %}
Store solutions are tenant-scoped. They’re available across every project and account in your tenant.
{% endhint %}

### Explore Store guidance

<table data-view="cards"><thead><tr><th>Topic</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td>Browse agents and apps<br><br>Learn what cards show and review detail-panel examples.</td><td><a href="/ai-workbench-qore/console/store/browse-agents-and-apps">Browse agents and apps</a></td></tr><tr><td>Store catalog<br><br>Review the captured agents, apps, and their category scopes.</td><td><a href="/ai-workbench-qore/console/store/store-catalog">Store catalog</a></td></tr></tbody></table>

### Store and design systems

Store solutions are available throughout your tenant. A [Design Systems](/ai-workbench-qore/console/design-systems) applies to one project.

For common questions and fixes, see [Store: FAQs & Troubleshooting](/ai-workbench-qore/console/store/store-faqs-and-troubleshooting).

***

{% 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 %}


# Browse agents and apps

Learn how Store cards, tabs, and detail panels help you select a ready-made solution.

The Store groups ready-made agents and micro-apps in separate tabs. Use card details to compare capabilities and outcomes before you launch a solution.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-2419ab94e12c741be54fb9a643d8c73e854b300e%2Fqore_console_console-store-agents-tab_rounded_shadow.png?alt=media" alt="The Store catalog&#x27;s Agents tab, showing rows of agent cards with category tags, accuracy percentages, and Chat Now buttons"><figcaption><p>Use Store tabs and cards to compare ready-made agents and apps.</p></figcaption></figure>

### Choose a solution type

{% tabs %}
{% tab title="Agents" %}
Agents handle task-specific or multi-task AI work. Each card shows category tags, an accuracy percentage, a short description, and **Chat Now**.

Select a card to review its details. Select **Chat Now** to start a chat.
{% endtab %}

{% tab title="Apps" %}
Apps are small, purpose-built applications. Each card shows category tags, a short description, and **Launch**.

Select a card to review its details. Select **Launch** to open the app. Apps don't show an accuracy percentage.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-8b1b0ae497216c73fc1548177bac4ca6491a1e79%2Fqore_console_console-store-apps-tab_rounded_shadow.png?alt=media" alt="The Store catalog&#x27;s Apps tab, showing app cards with category tags and Launch buttons"><figcaption><p>The Apps tab.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

### Review card details

Select any card to open its detail panel. The panel tabs scroll to sections in one continuous view. They don't replace the panel content.

| Section            | What it shows                      |
| ------------------ | ---------------------------------- |
| **Overview**       | A summary of the agent or app.     |
| **How it works**   | The actions it carries out.        |
| **What you get**   | The outputs you receive.           |
| **Why it matters** | The business outcomes it supports. |

Each panel ends with **Last updated**, which shows when the listing last changed.

{% hint style="info" %}
Review the panel before you launch a solution. It shows the expected workflow, outputs, and outcomes.
{% endhint %}

### Examples

#### Agent detail panel

The **Abandoned Application Follow-Up** agent has the *Distribution* and *Onboarding* tags. Its accuracy indicator is *96%*.

| Section            | Example content                                                                                                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**       | Re-engages applicants who left an account-opening or loan application. It checks consent, personalizes approved SMS and email, and provides a resume path.                       |
| **How it works**   | It processes application-status events, queues abandoned applications, checks consent and opt-outs, sends approved messages, and records each contact in the core system or CRM. |
| **What you get**   | You receive a queued outreach list, consent-checked messages with delivery status, personalized resume links, staff context, and an auditable communications trail.              |
| **Why it matters** | It helps recover abandoned applications, respond within minutes, support TCPA/CAN-SPAM compliance, and retain an opt-out audit trail.                                            |

#### App detail panel

The **Deposit Account Opening Solution** app has the *Onboarding* tag.

| Section            | Example content                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**       | It automates document collection, verification, and eligibility checks during customer onboarding.                                                          |
| **How it works**   | Customers upload documents. AI extracts applicant information, flags missing details, performs compliance checks, and prepares an onboarding summary.       |
| **What you get**   | You receive customer profiles, verification statuses, completeness tracking, validation results, risk indicators, review notes, and recommended next steps. |
| **Why it matters** | It helps reduce turnaround time and manual review effort while improving onboarding accuracy and audit readiness.                                           |

***

{% 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 %}


# Store catalog

Review the agents and apps captured in the Store catalog and their category scopes.

This catalog records Store listings at the time of writing. Use it to identify available solution types and category scopes.

{% hint style="warning" %}
The catalog is a snapshot, not a guarantee. Agents and apps can be added, removed, or retagged. Confirm current availability in the Store.
{% endhint %}

### Apps

| App                                      | Scope                            |
| ---------------------------------------- | -------------------------------- |
| Deposit Account Opening Solution         | Onboarding                       |
| Commercial Lending Agentic App           | Onboarding, Service & Support    |
| Credit Card Application Intake           | Retail Banking, Onboarding       |
| Unsecured Personal Loan Intake           | Retail Banking, Onboarding       |
| Financial Spreading & Credit Decisioning | Growth Driver                    |
| Credit Memo Solution                     | Growth Driver                    |
| Cross Document Analysis                  | Retail Banking                   |
| Portfolio Intelligence                   | Service & Support, Growth Driver |
| Business Health Canvas                   | Service & Support, Growth Driver |

### Agents

| Agent                                  | Scope                                |
| -------------------------------------- | ------------------------------------ |
| Business Deposit & Treasury Management | Corporate Banking, Onboarding        |
| Consumer Deposit Account Opening       | Retail Banking, Onboarding           |
| Customer / Member Onboarding           | Onboarding, Retail Banking           |
| New Customer & Member Acquisition      | Distribution, Onboarding             |
| Account Maintenance & Servicing        | Operations, Customer Service         |
| Digital Self-Service Assistant         | Customer Service, Technology         |
| Branch Support & In-Branch Assistance  | Customer Service, Operations         |
| Contact-Center Support (voice/chat)    | Customer Service                     |
| Retention & Win-Back                   | Customer Service, Retail Banking     |
| Pricing & Offer Optimization           | Finance, Retail Banking              |
| Cross-Sell & Relationship Deepening    | Retail Banking, Distribution         |
| Commercial Loan Origination            | Corporate Banking                    |
| SMB Loan Originations                  | Corporate Banking                    |
| Consumer Loan Origination              | Retail Banking                       |
| KYC/KYB Compliance Monitoring          | Legal & Compliance, Technology       |
| M\&A Customer & Account Data           | Legal & Compliance                   |
| Abandoned Application Follow-Up        | Distribution, Onboarding             |
| Business Continuity & Resiliency       | Operations, Technology               |
| Enterprise & Operational Risk          | Operations                           |
| Exam & Audit Management                | Legal & Compliance                   |
| Policy & Procedure Management          | Legal & Compliance                   |
| Internal Audit                         | Legal & Compliance                   |
| Information Security & Cyber Risk      | Technology                           |
| Third-Party / Vendor Risk Management   | Operations                           |
| Complaint Analytics & Surveillance     | Customer Service                     |
| Consumer Compliance / Fair Lending     | Legal & Compliance                   |
| Regulatory Change Management           | Legal & Compliance                   |
| Regulatory Reporting                   | Finance, Legal & Compliance          |
| Model Risk Management                  | Technology                           |
| Loan Review & Credit QA                | Corporate Banking                    |
| Credit Risk Monitoring & Surveillance  | Corporate Banking                    |
| Fraud Detection & Investigation        | Operations                           |
| KYC / CDD / EDD (ongoing)              | Legal & Compliance, Onboarding       |
| Sanctions / OFAC Screening             | Legal & Compliance                   |
| BSA / AML Transaction Monitoring       | Legal & Compliance                   |
| Executive, Strategy & Board Reporting  | Finance                              |
| Data, Analytics & MIS                  | Technology                           |
| IT & InfoSec Operations                | Technology                           |
| Facilities & Corporate Services        | Operations                           |
| Human Resources & Talent               | HR & Talent                          |
| Procurement & Vendor Management        | Operations                           |
| Treasury & ALM                         | Finance, Asset Management            |
| Finance & Accounting                   | Finance                              |
| Item & Check Processing                | Operations                           |
| Branch Operations                      | Operations                           |
| Loan Servicing & Administration        | Operations                           |
| Deposit Operations                     | Operations                           |
| Payments Operations                    | Operations                           |
| Collections & Loss Mitigation          | Operations, Risk & Compliance        |
| Member-Facing Fraud Support            | Customer Service, Risk & Compliance  |
| Complaint Handling & Resolution        | Customer Service, Legal & Compliance |
| Dispute & Chargeback Management        | Operations, Claims                   |
| Payments Support & Exceptions          | Operations, Customer Service         |
| Card Servicing                         | Customer Service, Operations         |

***

{% 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 %}




---

[Next Page](https://docs.uptiq.ai/llms-full.txt/1)