> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-agentplatform-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Kore Agent Assist
The Kore Agent Assist channel connects an Artemis project to Kore Agent AI, so your deployed agents give contact center agents real-time guidance. Artemis creates the connection, generates its API key, binds it to an environment, and controls traffic through **Pause** and **Resume**. Kore Agent AI keeps calling the existing Agent Assist API, so the external endpoint contract doesn't change.
The setup requires:
1. [Create the connection in Artemis](#create-the-connection-in-artemis)
2. [Configure Kore Agent AI](#configure-kore-agent-ai)
3. [Verify the connection](#verify-the-connection)
After setup, Kore Agent AI routes each Agent Assist session to the agent version active in the environment you select.
**Important considerations**
* **The API key appears only once.** Artemis shows the full key only in the creation dialog. Afterward, only the key prefix stays visible. Copy the key before you select **Done**.
* **Pause and Resume control traffic.** The connection has no separate on or off setting. A paused or inactive connection returns `404` to external requests.
* **Use one connection per environment.** Keep development, staging, and production on separate connections, each with its own key.
* **The key has a narrow scope.** It covers message sending for the owning project only and doesn't grant platform administration access.
* **Output supports text and markdown.** Responses can also carry normalized renderables, actions, and activity events. The channel doesn't accept attachments or deliver channel-native rich media.
## Prerequisites
Confirm the following before you start.
* An Artemis project with an agent version deployed to the target environment. The connection's **Deployment** tab lists it as the **Active Deployment**.
* Access to **Deployments** in the Artemis project.
* Administrator access to Kore Agent AI, including the **Configuration** section.
* A secure location, such as a secrets manager, to store the API key.
***
## Create the connection in Artemis
Create the connection first. Artemis generates the four values that Kore Agent AI needs.
1. In your project, go to **Deployments** -> **Channels**.
2. Select **Kore Agent Assist**.
3. Select **Create Connection**. If the project already has connections, select **New**.
1. In **Display Name**, enter a name that identifies the Agent Assist experience and its environment. The name supports up to 255 characters.
2. In **Environment**, select the environment whose active deployment supplies the entry agent, welcome message, model, and runtime behavior.
3. In **Initial Status**, select **Active** to accept traffic immediately, or select **Inactive** to save the connection and activate it later.
4. Select **Create**.
The **Kore Agent Assist Connection Created** dialog shows four values.
1. Copy **Domain URL**, **Environment**, **App ID**, and **API Key**.
2. Store the API key in your secrets manager.
3. Select **Done**.
After you close the dialog, Artemis can't show the full API key again. If you lose the key, rotate it from the **Overview** tab.
### Connection values
Each value maps to a field of the same name in Kore Agent AI. Copy each one exactly, including case and punctuation.
| Value | Source / Notes |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Domain URL** | The Artemis host that Kore Agent AI calls. Agent AI appends the Agent Assist API route, so don't paste an individual endpoint path. |
| **Environment** | The environment identifier. It can differ from the label in the **Environment** list, so use the value from the dialog. |
| **App ID** | The project ID for the connection. Don't substitute the display name, an agent name, or the **Source ID** from the **Overview** tab. |
| **API Key** | A generated secret with the `abl_` prefix. Agent AI sends it in the `x-api-key` header. Keep it out of browser code, transcripts, client logs, and source control. |
***
## Configure Kore Agent AI
Add the connection as an Agentic Copilot app in Kore Agent AI. For the complete Agent AI procedure, see [Linked Services](https://docs.kore.ai/agentassist/settings/linked-services/).
1. Sign in to [Kore Agent AI](https://agentassist.kore.ai/koreagentassist/).
2. Go to **Configuration** -> **System Setup** -> **Linked Services**.
3. Select **Agentic Configurations**.
4. Select **+ Add Agentic Copilot App**.
Under **App Information**, enter the values from the Artemis connection.
1. In **App Name**, enter a name that agents and administrators recognize. The name supports up to 50 characters.
2. In **Domain URL**, paste the Artemis **Domain URL**.
3. In **Environment**, paste the Artemis **Environment** value.
4. In **App ID**, paste the Artemis **App ID**.
5. In **API Key**, paste the full API key, not the prefix.
Select **Test Connection & Save**. Agent AI checks the values and saves the app when the connection succeeds.
Next, link the app to your Agent AI experience so agents receive guidance at runtime. For details, see [Agentic Copilot](https://docs.kore.ai/agentassist/uncategorized/agentic-copilot/).
### Validation checklist
Review these items before you route live conversations to the connection.
* The Artemis connection shows **Active** status.
* The selected environment has an **Active Deployment**.
* Agent AI holds the exact **Domain URL**, **Environment**, and **App ID** values.
* Agent AI holds the current, full API key.
* **Test Connection & Save** succeeds in Agent AI.
* Every action on the Artemis **Testing** tab returns a successful result.
***
## Verify the connection
The **Testing** tab calls the live Agent Assist API with the connection's saved values. Run it before you add the values to Agent AI, and again after any key rotation.
1. Open the connection, and select the **Testing** tab.
2. Under **Connection**, confirm the **Domain URL**, **Environment**, and **App ID**.
3. In **API Key**, paste the full key you stored at creation. The test actions stay unavailable until you paste a key.
Artemis generates a **sessionReference** for the test session. Run the actions in order so every call uses the same session.
1. Select **Test connection** to check authentication and deployment readiness.
2. Select **Connect (welcome)** to open the session and receive the agent's welcome message.
3. In **Message**, enter a test message, and select **Send message**.
4. Turn on **Stream response (SSE)**, and send another message to check streaming delivery.
5. Select **Terminate** to end the session.
**Results** lists the request, status, duration, and response for each action. To start over with a new session reference, select **New session**.
### Test actions
Each test action calls one Agent Assist API endpoint.
| Action | Endpoint | What it confirms |
| --------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Test connection** | `/test` | The key authenticates, the App ID and environment resolve, and the deployment, entry agent, and model are ready. The call doesn't create a conversation or call the model. |
| **Connect (welcome)** | `/sessions` | The API creates the session and returns the authored welcome message. |
| **Send message** | `/runs/execute` | The agent processes a turn and returns a response. With **Stream response (SSE)** on, the response arrives as a Server-Sent Events stream. |
| **Terminate** | `/sessions/terminate` | The API ends the session and returns a termination response. |
### Verify pause and resume
Confirm that the connection status controls all external traffic.
1. In the connection header, select **Pause**.
2. On the **Testing** tab, select **Test connection**, and confirm the request returns `404`.
3. Select **Resume**, and run **Test connection** again.
***
## Manage the connection
Open a connection from **Deployments** -> **Channels** -> **Kore Agent Assist**. The header shows the display name, environment, and status, plus the **Pause** and delete controls.
| Tab | Use it to |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Overview** | Review the **Connection Summary**, copy the Agent AI values, and rotate the API key. |
| **Configuration** | Change the **Display Name**, and then select **Save Changes**. |
| **Deployment** | Change the environment that handles incoming messages, and review the **Active Deployment** version and deployment time. |
| **Testing** | Run test actions through the live API. |
### Connection summary
The **Overview** tab lists the connection's metadata under **Connection Summary**.
| Field | Description |
| --------------- | ----------------------------------------------------------------------- |
| **Status** | Whether the connection accepts external traffic. |
| **Created** | When you created the connection. |
| **Updated** | When the connection last changed. |
| **Environment** | The environment identifier the connection follows. |
| **Source Type** | The record type. For this channel, the value is **Channel Connection**. |
| **Source ID** | The internal ID of the connection record. Don't use it as the App ID. |
### Change the environment
Changing the environment routes incoming messages to that environment's active deployment.
1. Select the **Deployment** tab.
2. In **Environment**, select the environment.
3. Select **Save Changes**.
4. On the **Overview** tab, check the **Environment** value, and update Agent AI if it differs.
### Rotate the API key
Rotate the key when you lose it or suspect exposure.
1. On the **Overview** tab, select **Rotate** next to **API Key**.
2. Copy the new key. Artemis shows it only once.
3. In Agent AI, replace the **API Key** value, and select **Test Connection & Save**.
Artemis revokes the previous key when it saves the replacement. Agent AI requests fail until you update the key.
### Pause, resume, or delete
Use the header controls to change the connection's availability.
* Select **Pause** to stop external traffic. Requests return `404` until you select **Resume**.
* Select the delete icon to remove the connection. Before you delete it, remove or update the matching app in Agent AI.
***
## API reference
Kore Agent AI calls these endpoints on your behalf. Use this section to build a custom integration or to diagnose failed requests.
### Base path and authentication
All endpoints share one base path built from the connection values.
```text theme={null}
{Domain URL}/api/v2/apps/{App ID}/environments/{Environment}
```
Every request sends `Content-Type: application/json` and the full API key in the `x-api-key` header. Don't send an `Authorization: Bearer` header, a user token, an SDK public key, or the key prefix. The API checks that the key's tenant and project match the resolved App ID and environment, and returns `404` on any mismatch.
### Session lifecycle
Each Agent Assist conversation uses the same session identity across all calls.
| Step | Endpoint | Details |
| --------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Start | `POST /sessions` | Send `sessionIdentity` before the first turn. Set `metadata.isSendWelcomeMessage` to `true` to receive the welcome message. |
| Send turns | `POST /runs/execute` | Send `sessionIdentity` and `input[]`. Reuse the same `sessionReference` for later turns. |
| End | `POST /sessions/terminate` | Send the same session identity when the conversation ends. The API returns a termination response even if the session no longer exists. |
| Check readiness | `/test` | Checks authentication and deployment readiness without creating a conversation or calling the model. |
### Response modes
`/runs/execute` supports three response modes. The request fields decide which mode applies.
| Mode | How to request it | Behavior |
| --------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Synchronous (default) | Leave streaming off, and omit `callbackUrl`. | Returns one completed response on the same HTTP connection. |
| Streaming (SSE) | Set `stream.enable` to `true`, and accept `text/event-stream`. | Streams the response with heartbeats, then sends the final session and run details. Streaming takes precedence over `isAsync`. |
| Async push | Set `isAsync` to `true`, and include `callbackUrl`. | Validates the callback, returns `202` with a processing state, and later delivers the completed or error response to the callback. |
If you set `isAsync` to `true` without a `callbackUrl`, the API falls back to the synchronous response.
For async push, use an approved HTTPS destination, and avoid private and link-local addresses. When callback signing is on, verify the `X-ABL-Signature` header, which signs `timestamp.rawBody`.
### Payload rules
The API normalizes and restricts request content before agent execution.
| Element | Rule |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionIdentity` | Accepts `sessionReference`, `sessionId`, `sessionIdentity`, and `userReference` entries. Include at least one stable `sessionReference`, `sessionId`, or `userReference`, and keep it unchanged across calls. |
| `input[]` | Requires at least one item and supports `text`, `object`, and `tool_input` types. Agent execution needs a `text` item. Each content value allows up to 16,000 characters. |
| `metadata.aa_uamsgs` | Carries Agent Assist conversation history. The API keeps up to 50 messages. |
| Other `metadata` | The API accepts custom keys but strips reserved transport, credential, tenant, project, session, and authorization keys. |
| Output | Text and markdown, plus optional normalized renderables, actions, and activity events. No attachments or channel-native rich media. |
***
## Troubleshoot connection issues
Match the symptom to its likely cause, and apply the recommended action.
| Symptom | Likely cause | Recommended action |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized` | The request carries a missing, partial, or revoked key. | Paste the full current `abl_` key, and confirm every request sends `x-api-key`. |
| `404` app not found | The App ID or Environment doesn't match, the key belongs to another project, or the connection is paused or inactive. | Copy the values again from the **Overview** tab, and confirm the connection shows **Active**. |
| **Test Connection & Save** fails in Agent AI | One or more pasted values differ from the Artemis connection. | Recopy all four values with the copy icons on the **Overview** tab. |
| `/test` reports a deployment resolution failure | The environment has no active deployment, or its entry agent or model configuration isn't valid. | Deploy an agent version to the environment, and check the entry agent and model settings. |
| Streaming returns JSON or stalls | The request doesn't set `stream.enable`, doesn't accept `text/event-stream`, or a proxy buffers the stream. | Set `stream.enable` to `true`, accept `text/event-stream`, turn off proxy buffering, and let heartbeats pass for the full request timeout. |
| Async returns an invalid callback error or never delivers | The callback URL isn't an approved HTTPS destination, or signature checks fail. | Use an approved HTTPS URL outside private and link-local ranges, and verify `X-ABL-Signature` when signing is on. |
| Welcome and follow-up turns land in different sessions | The session identity changes between calls. | Reuse the same `sessionReference`, and keep identity values and their order unchanged between `/sessions` and `/runs/execute`. |
| Test actions stay unavailable | The **Testing** tab has no API key. | Paste the full key, or rotate it from the **Overview** tab and paste the new one. |
## Related topics
Use these pages to continue channel and deployment setup.
* [Channels](/agent-platform/channels)
* [Deployment](/agent-platform/deployment)
* [Linked Services in Kore Agent AI](https://docs.kore.ai/agentassist/settings/linked-services/)