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.

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)	@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)	@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.

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.

What every way in shares

Credentials, on Access & Security

All ways in use credentials from the agent's Access & Security 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.

Who is calling

Two layers identify the caller:

• The application. Access keys say which integration is calling.
• The person. Authentication, 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.

A request without a token still runs. A request with an invalid token is rejected.

The user object and the identity token must come from your own authenticated session, never from URLs, form fields or other user-controlled input.

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.

Runtime configuration

The widget, the SDKs and the API all run the agent against the same configured Secrets & 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 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 instead packs the agent's configuration into a portable package, to import elsewhere.

Related

• Widget: the prebuilt chat interface
• Integrate Agent: setup steps, samples and endpoints
• Agent SDK: @uptiqai/agent-sdk
• Protocols: how the agent reaches out and how your product reaches in
• Integrate an agent: the task guide

---

Maintained by Abhishek Paul AI-assisted, human-approved