> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/ai-workbench-qore/core-concepts/embed-agent.md). # 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.md). ## 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.md)) | `@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.md)) | `@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.md). ### 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//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.md#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.md) 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.md#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.md), 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.md). 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.md). ### 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.md). ## 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.md) 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.md) instead packs the agent's configuration into a portable package, to import elsewhere. ## Related * [Widget](/ai-workbench-qore/core-concepts/widget.md): the prebuilt chat interface * [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md): setup steps, samples and endpoints * [Agent SDK](/ai-workbench-qore/platform-resources/the-agent-development-sdk.md): `@uptiqai/agent-sdk` * [Protocols](/ai-workbench-qore/core-concepts/protocols.md): how the agent reaches out and how your product reaches in * [Integrate an agent](/ai-workbench-qore/task-guides/integrate-an-agent.md): the task guide *** {% columns %} {% column width="83.33333333333334%" %}

Maintained by Abhishek Paul
AI-assisted, human-approved

{% endcolumn %} {% column width="16.666666666666664%" %}
{% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.uptiq.ai/ai-workbench-qore/core-concepts/embed-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.