Integrate an agent

Every way to put an agent to work: attach it to a Qore app, embed a chat widget, call the Agent API, or build your own chat UI.

This guide is organized by task. Find what you want to do in the list below, then follow the steps.

Task	Go to
Add an existing agent to an app I built in Qore	Attach to a Qore app
Build a new agent for my Qore app	Build one for the app
Ask the app builder to add an agent	Ask the builder
Choose how to run the agent in my own app	Choose an integration
Open the integration options	Integrate Agent
Create the keys an integration needs	Keys
Allow the domains the widget runs on	Allowed Domains
Drop a chat widget onto my website	Embedded Chat
Use the widget without React, or full screen	Widget variants
Tell the widget who the user is	Pass the user
Call the agent from my backend	Agent API
Generate an API key and secret	API key and secret
Choose the client, mode, and dialect	Code sample
Get the agent's answer	Get the result
Send a document with a request	Send a document
Pass variables, a user ID, or a business ID	Pass variables
Get updates by webhook	Webhooks
Stop a running execution	Abort
List the agent's conversations	Conversations
Understand an error response	Errors
Download the setup as a Markdown file	Download as MD
Build my own chat UI in the browser	TypeScript SDK
Send the signed-in user's identity	Send the token
Pass the caller's identity to an MCP server	$auth.token
Check the integration works	Verify

You need a built and tested agent. If you don't have one yet, see Create an agent.

---

Add an agent to a Qore app

Attach an agent to a Qore app

1

Open the app's Agents tab

Open the app in App Builder, then select the Agents tab in the top bar. It reads Make Your App Smarter with Agents.

The app's Agents tab.

2

Open Attach Agent(s)

Under Attach an Existing Agent, select + Attach Agents. Attach Agent(s) lists your agents, each with its name and description.

3

Select the agents

Tick each agent you want. Select at least one; Proceed stays unavailable until you do.

Attach Agent(s).

4

Proceed

Select Proceed, or Cancel to close without attaching.

You can't attach agents while the app is still generating. If you see Cannot attach agents while application generation is in progress, wait for the build to finish, or Skip the pending build step, then try again.

Build a new agent for the app

On the app's Agents tab, under Build an Agent, select Visit Agent Builder. Build the agent there, then come back and attach it. See Create an agent.

Ask the app builder to add an agent

In the app's build conversation, under Upgrade your app, select Add an AI Agent (Connect intelligence to your app).

---

Run the agent in your own app

Choose an integration

If you want to…	Use	Credential
Drop a chat onto a web page, with no UI to build	Embedded Chat	Widget key, allowed domain
Call the agent from a backend, service, or scheduled job	Agent API with the raw (HTTP) client	API key and secret
Build your own chat UI in the browser	Agent API with the TypeScript SDK client	Widget key, allowed domain

Open Integrate Agent

In the agent's builder, select Integrate Agent (</>) in the canvas header. It opens as a side panel with two tabs: Embedded Chat and Agent API.

Versions are per agent. Use the SDK version and executor version that your own agent's panel shows. In the samples on this page, <BASE_URL> stands for your organization's Qore API host, and 1.4 for the executor version.

Create the keys

Open Agent Config › Access & Security, select + Add Key, name it, choose the type, and select Generate Key:

• Widget Key — for Embedded Chat and the TypeScript SDK. Safe to ship in browser code.
• API Key — a key and secret pair for server-to-server calls. Copy the secret straight away; it's shown only once.

The Embedded Chat and Agent API tabs can also create keys for you. See Create an agent › Create an access key.

Allow your domains

In Access & Security, under Allowed Domains, select + Add New Domain, enter each origin the widget runs on, and select Save. With the list empty, the widget runs nowhere outside the platform. Enter each domain exactly as the browser sends it, such as https://app.example.com.

---

Embedded Chat

Embed a chat widget

1

Widget key

On the Embedded Chat tab, choose Use existing key or Generate new key, then select Continue.

Embedded Chat, step 1.

2

Whitelist domains

Add each domain your widget will run on, such as app.yourdomain.com, then select Continue. The domains go on the agent's Allowed Domains list.

3

Install the widget

Install the React SDK, import its stylesheet, and mount the widget:

Install

npm install @uptiqai/widgets-sdk@<version>

Mount the widget

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: '[email protected]' }}
    />
  );
}

Use the SDK version the panel shows: it's the one released with the agent's executor version.

The widget has a chat popover or full-screen view, a conversation sidebar, new chats, message history that persists across sessions, and theming.

Use the HTML web component or full screen

The widget also comes as a framework-agnostic HTML web component, and each form has a full-screen variant. Both share the same config, user, theme, and instanceId. Full screen adds hideTrigger (or hide-trigger in HTML), so you can open it from your own button. See Integrate Agent › Widget variants.

Pass the signed-in user

Set user to the person signed in to your app: uid, firstName, and email are required, and lastName is optional.

user must come from your own authentication system. Never fill it from query parameters or other input a visitor can change.

---

Agent API

Call the agent from my backend

The Agent API's raw HTTP client triggers the agent with no UI. Send a POST to the trigger endpoint with the API key and secret:

Trigger the agent

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"}'

The request body needs message for a new execution (or resumeData to resume a paused one). Optional fields include payload, documents, executionId, executionMode (async, the default, or sync), responseFormat (Markdown or Json), webhooks, and token.

The trigger endpoint isn't idempotent: each call starts a new execution unless you pass an existing executionId.

Generate an API key and secret

On the Agent API tab, select Generate new secret key. It creates a new key and secret and shows the secret once; copy it straight away. Generating doesn't deactivate any existing key. Keep both values server-side.

The Agent API tab.

Choose the client, mode, and dialect

The Agent API tab builds one code sample from three selectors. Select Copy to copy it.

Selector	Options
Client	raw (HTTP), TypeScript SDK, and Python SDK (marked Coming soon)
Mode	Sync, Async, and Realtime
Dialect	Native (Qore's own request shape) and OpenAI

Get the result

• Async (the default) — the trigger returns { "executionId": "exec_123" }, an acknowledgement, not an answer. Check the execution's queue status, or receive a webhook.
• Sync — the call waits until the agent finishes, and returns the answer in result.content. Use it only when you must wait for the result.

Check an execution with GET /agent-executor/1.4/agents/:agentId/executions/:executionId/queue-status. Messages sent to the same executionId run one at a time: one shows Executing, the rest Pending.

Send a document

1

Get a signed upload URL

POST /agent-executor/1.4/agents/:agentId/uploads/signed-urls, with { "count": 1 }. The response gives an id and a url for each file.

2

Upload the file

PUT the file to the returned url.

3

Attach it to the trigger

Add it to documents in the trigger request, with its id, and preferably its fileName and mimeType.

The older documents/presigned-url endpoint is deprecated.

Pass variables, a user ID, or a business ID

Add these to the trigger request:

• uid — the calling user's ID in your system.
• variables — key/value pairs the agent's instructions can reference. Every key must already be declared in the agent's variables; an undeclared key is rejected.
• businessId — attributes the run to a business or tenant of your own.

Get updates by webhook

Add webhook URLs to webhooks in the trigger request to receive updates when an execution completes or needs input. Webhooks need executor version 1.2 or later.

Each webhook carries an X-Webhook-Signature header: an RSA-SHA256 signature of the raw JSON body. Verify it against the public key shown on the agent's Agent API screen.

Stop a running execution

POST /agent-executor/1.4/agents/:agentId/executions/:executionId/abort. The agent stops and emits a final done event. You can also cancel a message that's still Pending.

List the agent conversations

GET /agent-executor/1.4/agents/:agentId/conversations returns titles and metadata, not transcripts. Add ?initiatedBy=user_123 to filter to one user. You can also fetch one conversation's transcript by its executionId.

Understand an error response

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." }

Download the setup as Markdown

Select Download as MD on the Agent API tab, or on Embedded Chat's Install widget step. A preview shows the file: the agent's name, executor version and base URL, the credentials guidance, and the sample you chose.

On the Agent API tab, Include secrets writes the agent's API key and secret into the file, so it works as-is.

Download as MD.

A file downloaded with Include secrets is a credential. Anyone who has it can call the agent. If it leaks, deactivate the key in Access & Security.

For every endpoint and field, see Integrate Agent › Agent API.

---

Your own chat UI

Build my own chat UI

Choose the TypeScript SDK client on the Agent API tab. The headless SDK handles the connection to the agent while you build the interface. It uses the widget key, and your domain must be on Allowed Domains.

Create an instance

import { createHeadlessAgentInstance } from '@uptiqai/widgets-sdk';

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: '[email protected]' },
  instanceId: 'my-chat-instance',
});

config, user, and instanceId are required; authToken is optional. See Integrate Agent › TypeScript SDK client.

---

Identity

Send the signed-in user token

When the agent has Authentication turned on, send the signed-in user's identity token with each request:

• Agent API — add token beside message in the trigger body.
• Embedded Chat — pass authToken in React, or auth-token in HTML.
• TypeScript SDK — pass authToken when you create the instance. A headless instance also has setAuthToken() for refreshed tokens.

Authentication	Token	Result
Off	Any, or none	The run proceeds; the token is ignored.
On	None	The run proceeds, with no authenticated caller.
On	Valid	The run proceeds, and $auth.token holds the token.
On	Invalid, or for another app	Rejected with AGENT_AUTHENTICATION_FAILED.
On	Expired Microsoft Entra ID	Rejected with TOKEN_EXPIRED.

Send tokens only from your app's authenticated session. Never accept them from URLs, form fields, or other input a visitor controls.

Pass the caller identity to an MCP server

In an MCP connection's configuration, reference $auth.token where the server expects a user credential. Qore replaces it with the verified token during the run, so the server can apply the caller's permissions. $auth.token works only in MCP connection configurations; with no token, it resolves empty. See Authentication.

---

Check and fix

Verify the integration

• A Qore app — preview the app and confirm the agent responds and uses its knowledge and skills.
• Your own app — send a request from your surface and confirm the agent answers. It responds only where your keys and domains allow.
• Runs — find each run in Control Center › Observe › Runs & Traces.

---

Common issues

• "Cannot attach agents while application generation is in progress." Let the app's build finish, or Skip the pending step, then attach.
• Proceed is greyed out in Attach Agent(s). Tick at least one agent.
• The widget doesn't appear. Import the stylesheet, provide both config and user, and check the widget key is correct and active.
• "Unauthorized" errors from the widget. The page's domain isn't on Allowed Domains exactly as the browser sends it, including protocol, subdomain, and port.
• API calls return 401. Check the x-api-key and x-api-key-secret values. If you lost the secret, generate a new pair.
• A request with variables is rejected. Declare every variable key on the agent first.
• No webhook arrives. Webhooks need executor version 1.2 or later.
• Requests with a token are rejected. Check the provider details in Authentication, and that the token was issued for the configured application or client.

---

Related pages

• Integrate Agent, Access & Security, and Authentication
• Build the agent first: Create an agent
• Build the host app: Create an app

---

Maintained by Abhishek Paul AI-assisted, human-approved