From 6c6729ddeb86768f57f1f1a6aa4c07722aa1dbb1 Mon Sep 17 00:00:00 2001 From: Shruti Kukkar Date: Thu, 2 Jul 2026 11:39:30 +0530 Subject: [PATCH 1/8] ON_START Example --- agent-platform/create-agents.mdx | 33 ++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/agent-platform/create-agents.mdx b/agent-platform/create-agents.mdx index 544c03d2..3cd26f9e 100644 --- a/agent-platform/create-agents.mdx +++ b/agent-platform/create-agents.mdx @@ -193,6 +193,39 @@ ON_START: handoff. If the agent is not being initialized, `ON_START` will not run. +Valid Directives inside `ON_START`: + +| Directive | What it does | +|-----------|--------------| +| `RESPOND:` | Sends an initial message to the user when the session starts. | +| `FORMATS:` | Defines rich content for the initial response without a preceding `RESPOND:` block. | +| `VOICE:` | Defines voice configuration for the initial response without a preceding `RESPOND:` block. | +| `ACTIONS:` | Adds interactive buttons or forms to the initial message. | +| `CALL:` | Invokes a tool when the session starts. | +| `SET:` | Sets a variable using the syntax `SET: field = value`. | +| `DELEGATE:` | Immediately delegate the session to another agent at startup. | +| `MESSAGE_KEY:` | Specifies the internationalization key for the response message. | +| `BRANCHES:` | Defines conditional branching logic. | + +```yaml + +MESSAGES: + welcome_default: "Welcome! How can I help you today?" + +ON_START: + + SET: user_role = session.user.role + BRANCHES: + - IF: user_role == "admin" + RESPOND: "Welcome, Admin! You can manage users, agents, and system settings." + + - IF: user_role == "manager" + RESPOND: "Welcome! You can review reports and manage your team's work." + + - ELSE: + MESSAGE_KEY: welcome_default +``` + ### Supervisor Agents For multi-agent projects, use the `SUPERVISOR` block to define the orchestrating agent. From aeaa361c91296cc845aef75ab238a9244231e9cf Mon Sep 17 00:00:00 2001 From: siddharthmenon-7 Date: Thu, 2 Jul 2026 14:13:19 +0530 Subject: [PATCH 2/8] Content Update --- agent-platform/channels-curl.mdx | 1026 ------------------------------ agent-platform/channels.mdx | 50 +- 2 files changed, 1 insertion(+), 1075 deletions(-) delete mode 100644 agent-platform/channels-curl.mdx diff --git a/agent-platform/channels-curl.mdx b/agent-platform/channels-curl.mdx deleted file mode 100644 index bf85f0f1..00000000 --- a/agent-platform/channels-curl.mdx +++ /dev/null @@ -1,1026 +0,0 @@ ---- -title: "Setup Channels" -sidebarTitle: Channels - CURL ---- - -Channels connect your deployed agents to the surfaces where users interact: websites, messaging apps, and voice calls. The Agent Platform (Artemis) provides channel adapters that handle the protocol-specific details, so a single agent definition works across every channel without modification. - -This guide covers embedding a web chat or voice widget, connecting to Slack, WhatsApp, and voice, and using rich content and file attachments across channels. - -A channel always binds to a deployment in a specific environment. Configure deployments first, then add channels on top. For the deployment lifecycle and the **Deployments** -> **Channels** workspace, see [Deploy Agents](/agent-platform/deployment#channels). - -## How channels connect - -The platform exposes two connection mechanisms. The one you use depends on the surface. - -| Mechanism | Used by | How it works | -| --------- | ------- | ------------ | -| **SDK channel** | Web chat and voice widgets | A public API key (`pk_`) bootstraps a browser session. You embed the Web SDK or the `` web component in your page. | -| **Channel connection** | Slack, WhatsApp, voice, and other messaging adapters | You register the external provider's credentials. The platform returns a webhook URL that the provider calls when a user sends a message. | - -Both mechanisms route to the same agent definition. The adapter normalizes inbound and outbound formats, so your agent doesn't need channel-specific logic for basic conversations. Use rich content when you want to tailor formatting to a specific channel. - -| Surface | Adapter | Connection | -| ------- | ------- | ---------- | -| Web chat and voice | Web SDK, `` | SDK channel (`pk_` key) | -| Slack | Slack adapter | Channel connection | -| WhatsApp | Meta Cloud API, Infobip, Twilio | Channel connection | -| Microsoft Teams | Bot Framework | Channel connection | -| Email | Inbound MIME parsing | Channel connection | -| Telegram | Telegram adapter | Channel connection | -| Voice | Kore Voice Gateway, AudioCodes, Twilio, BYOC SIP | Channel connection | - -## Deploy on Web - -Deploy your agent on a website with the Web SDK. The SDK embeds a chat or voice widget that connects to your deployed agent through a public API key. - -The browser-facing SDK never sends the public `pk_` key directly to the runtime. It exchanges the key for a short-lived SDK session token, then authenticates each request with that token. For the full SDK reference, see [Agent Platform SDKs Overview](/agent-platform/sdks). - -### Create a Public API Key - -The Web SDK authenticates with a public key (`pk_` prefix). Public keys are scoped to a project and are safe to expose in client-side code. - - - - Go to **Project** -> **Settings** -> **API Keys**. - - - Click **Create API key** and select the SDK key type. - - - Add the website origins that are allowed to use the key. The runtime validates the `Origin` header on every SDK request and rejects requests from unlisted origins. - - - Copy the key. It's displayed only once. - - - -### Configure the Web SDK channel - -Bind the channel to a deployment so the widget knows which agents to serve. - -1. Go to **Deployments** -> **Channels**. -2. Add a Web SDK channel and select the target environment or deployment. The channel can follow an environment automatically or pin to a specific deployment version. -3. Associate the public API key you created. - -### Embed the widget - -Add the widget to any page with the web component, or use the SDK directly for full control over the interface. - - - - The `` web component is the fastest way to add a widget. It renders a chat button in the configured position and opens the chat interface when clicked. - - ```html - - - - ``` - - Set `mode` to `chat`, `voice`, or `unified`. Set `position` to `bottom-right`, `bottom-left`, `top-right`, or `top-left`. - - - Use the `AgentSDK` class when you build your own interface. - - ```typescript - import { AgentSDK } from '@agent-platform/web-sdk'; - - const sdk = new AgentSDK({ - projectId: 'your-project-id', - apiKey: 'pk_your-public-key', - endpoint: 'https://agents.kore.ai', - }); - - await sdk.connect(); - - const chat = sdk.chat(); - chat.on('message', (msg) => console.log(msg.content)); - await chat.send('Hello, I need help!'); - ``` - - - Wrap your app in `AgentProvider` and use the `useChat` hook. - - ```tsx - import { AgentProvider, useChat } from '@agent-platform/web-sdk/react'; - - function App() { - return ( - - - - ); - } - - function ChatWidget() { - const { messages, isTyping, sendMessage, isConnected } = useChat(); - return ( -
- {messages.map((msg) => ( -
{msg.content}
- ))} - {isTyping &&
Agent is typing...
} - -
- ); - } - ``` - - - -### Enable Voice - -Set the widget mode to `voice` for a voice-only experience, or `unified` to offer chat and voice together. - -```html - -``` - -When you build your own interface, obtain the voice client with `sdk.voice()` and call `start()` to request microphone access. Voice features require HTTPS in production, because microphone access needs a secure context. For voice states, events, and configuration, see the [VoiceClient reference](/agent-platform/sdks#voiceclient). - -### Restrict to specific origins - -Origin restrictions prevent unauthorized sites from embedding your widget. Set the allowed origins on the public API key under **Project** -> **Settings** -> **API Keys**. - -```json -{ - "allowedOrigins": [ - "https://www.example.com", - "https://app.example.com" - ] -} -``` - -Requests from origins that aren't listed receive a `403 Forbidden` response. - -### Pass user context - -Identify authenticated users by attaching metadata to a message. The metadata is validated server-side and is available to your agent for that turn through `session.messageMetadata`. - -```typescript -const chat = sdk.chat(); - -await chat.send('Look up my account', { - metadata: { - accountId: 'acct_123', - plan: 'premium', - }, -}); -``` - -Use session variables and persistent memory lookups in your agent to act on this context. See [Memory and State](/agent-platform/memory-and-state). - -### Target a specific deployment - -To point the widget at a staging or production deployment, set the channel's binding under **Deployments** -> **Channels**. Pin the channel to a specific deployment version, or let it follow an environment so it always serves the active deployment for that environment. - -### Troubleshooting - -| Symptom | Resolution | -| ------- | ---------- | -| **Widget doesn't appear** | Verify the script URL and that the `api-key` is valid. Check the browser console for errors. | -| **"Invalid or expired API key"** | The key may have been rotated or the channel deactivated. Create a new key under **Project** -> **Settings** -> **API Keys**. | -| **CORS errors** | Add the website's origin to the key's `allowedOrigins` list. | -| **Widget loads but the agent doesn't respond** | Confirm an active deployment exists for the project and the channel is bound to it. | - -## Set up Slack - -Connect your agent to Slack so users can interact with it directly in Slack channels and direct messages. Slack uses a channel connection: you register your Slack app's credentials with the platform, then point Slack's event webhook at the URL the platform returns. - -### Create a Slack app - - - - Go to [api.slack.com/apps](https://api.slack.com/apps) and select **Create New App** -> **From scratch**. Name the app and select the workspace. - - - Under **OAuth & Permissions**, add the bot token scopes your agent needs. - - | Scope | Purpose | - | ----- | ------- | - | `chat:write` | Send messages. | - | `app_mentions:read` | Respond to @mentions. | - | `im:read`, `im:write` | Handle direct messages. | - | `files:read` | Read file attachments, if your agent handles them. | - - - Install the app to your workspace and copy the **Bot User OAuth Token** (`xoxb-...`). Under **Basic Information**, copy the **Signing Secret**. - - - -### Create a channel connection - -Register the Slack app credentials with the platform. The response includes the `webhookUrl`. Copy it for the next step. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "slack", - "display_name": "Production Slack", - "external_identifier": "T12345678:A12345678", - "credentials": { - "bot_token": "xoxb-your-bot-token", - "signing_secret": "your-signing-secret" - }, - "environment": "production" - }' -``` - -### Configure the Slack webhook - - - - In your Slack app settings, go to **Event Subscriptions**, enable events, and paste the `webhookUrl` from the channel connection response. Slack sends a verification challenge, and the platform responds automatically. - - - Under **Subscribe to bot events**, add `message.im` for direct messages and `app_mention` for @mentions in channels. Save your changes. - - - -### Threaded replies - -The Slack adapter supports threaded conversations and enables them by default. When a user mentions the bot in a channel, the agent replies in a thread to keep the channel clean. - -### Slash commands - -Register a custom slash command that routes to your agent. - -1. In your Slack app settings, go to **Slash Commands** and create a command, for example `/ask`. -2. Set the request URL to `https://your-platform/api/v1/channels/slack/slash/{connection-identifier}`. -3. The connection identifier is the external identifier from your channel connection, in the format `team_id:app_id`. - -### Interactive components - -If your agent uses interactive elements such as buttons or select menus, enable interactivity in your Slack app. - -1. Go to **Interactivity & Shortcuts** and toggle it on. -2. Set the request URL to the same webhook URL you used for events. -3. The platform routes interactive payloads, such as button clicks and menu selections, to your agent automatically. - -See [Rich content](#rich-content) for the Slack Block Kit and interactive action syntax. - -### Multi-workspace apps - -To distribute your agent across multiple Slack workspaces, use the generic webhook URL without a connection identifier. The platform extracts the workspace identifier from the event payload. - -``` -https://your-platform/api/v1/channels/slack/webhook -``` - -Create a separate channel connection for each workspace that installs the app. - -### Troubleshooting - -| Symptom | Resolution | -| ------- | ---------- | -| **"Channel not configured for this workspace"** | The connection's external identifier doesn't match the workspace. Verify the `team_id:app_id` matches your Slack app installation. | -| **Bot doesn't respond** | Confirm the Event Subscriptions URL verification succeeded (green checkmark in Slack) and the `bot_token` includes the `chat:write` scope. | -| **Signature verification fails** | The `signing_secret` must match the Signing Secret on the app's Basic Information page. Secrets are case-sensitive. | -| **Duplicate responses** | Slack requires a response within 3 seconds, so the platform queues messages and responds asynchronously. If your app retries events, the platform deduplicates using event IDs. | - -## Set up WhatsApp - -Connect your agent to WhatsApp so users can interact with it through WhatsApp messages. WhatsApp uses a channel connection. You register your WhatsApp Business API credentials with the platform, then point your provider's webhook at the URL the platform returns. - -### Set up a WhatsApp Business API account - -Before connecting to the platform, set up a WhatsApp Business API provider account. The platform supports Meta's Cloud API directly and third-party providers such as Infobip and Twilio. - -For Meta Cloud API: - -1. Go to [developers.facebook.com](https://developers.facebook.com) and create a Meta app with the WhatsApp product enabled. -2. Under **WhatsApp** -> **Getting Started**, note your **Phone Number ID** and **WhatsApp Business Account ID**. -3. Generate a permanent **System User Access Token** with the `whatsapp_business_messaging` permission. -4. Under **Configuration**, note the **App Secret** for webhook signature verification. - -### Create a channel connection - -Register the WhatsApp credentials with the platform. The response includes the `webhookUrl`. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "whatsapp", - "display_name": "Production WhatsApp", - "external_identifier": "your-phone-number-id", - "credentials": { - "access_token": "your-system-user-access-token", - "app_secret": "your-app-secret", - "verify_token": "a-random-string-you-choose" - }, - "config": { - "phoneNumberId": "your-phone-number-id" - }, - "environment": "production" - }' -``` - -### Configure the Meta webhook - -1. In your Meta app settings, go to **WhatsApp** -> **Configuration**. -2. Under **Webhook**, click **Edit** and paste the `webhookUrl`. -3. Enter the same `verify_token` you used when creating the channel connection. -4. Click **Verify and Save**. Meta sends a GET request to verify the webhook. -5. Under **Webhook fields**, subscribe to `messages`. - -### Connect through Infobip - -For WhatsApp through Infobip, use the provider-specific configuration. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "whatsapp", - "display_name": "Infobip WhatsApp", - "external_identifier": "your-sender-number", - "credentials": { - "access_token": "your-infobip-api-key", - "app_secret": "your-webhook-secret", - "verify_token": "unused-for-infobip" - }, - "config": { - "provider": "infobip", - "phoneNumberId": "your-sender-number" - } - }' -``` - -Set the Infobip webhook URL to: - -``` -https://your-platform/api/v1/channels/whatsapp/infobip/webhook -``` - -### Media support - -The WhatsApp adapter receives images, documents, audio, and video from users. The adapter downloads media files and routes them through the attachment pipeline automatically, so no extra configuration is needed. See [File attachments](#file-attachments) for how your agent processes uploaded media. - -### Interactive messages - -Your agent can send interactive WhatsApp messages, such as buttons and lists, through the `WHATSAPP` rich content format. - -```yaml -FLOW: - offer_options: - REASONING: false - RESPOND: "How can I help you today?" - RICH_CONTENT: - WHATSAPP: | - { - "type": "interactive", - "interactive": { - "type": "list", - "body": {"text": "Choose a topic:"}, - "action": { - "button": "Select", - "sections": [ - { - "title": "Support", - "rows": [ - {"id": "billing", "title": "Billing"}, - {"id": "technical", "title": "Technical Issue"} - ] - } - ] - } - } - } - THEN: handle_selection -``` - -### Troubleshooting - -| Symptom | Resolution | -| ------- | ---------- | -| **Webhook verification fails** | The `verify_token` in the channel connection must match the value entered in the Meta webhook configuration. It's a plain string you choose, not a Meta-generated secret. | -| **Messages don't arrive** | Confirm you subscribed to the `messages` webhook field in Meta's configuration, and that the phone number is registered with an active WhatsApp Business account. | -| **Signature verification fails on inbound messages** | The `app_secret` must be the Meta App Secret from Basic Settings, not the system user access token. | -| **Media messages aren't processed** | Large media files can time out during download. Check the attachment processing logs for the session. | - -## Set up Voice - -Set up a voice channel so users can interact with your agent through phone calls. The platform uses speech-to-text and text-to-speech for natural voice conversations, and supports Kore Voice Gateway, AudioCodes, Twilio, and BYOC SIP trunks. Each uses a channel connection. - -### Kore Voice Gateway - -Create a channel connection for Kore Voice Gateway. The response includes a SIP endpoint to point your phone number at. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "korevg", - "display_name": "Voice Support Line", - "external_identifier": "support-line", - "config": { - "provider": "korevg", - "welcomeMessage": "Hello! How can I help you today?", - "voiceConfig": { - "sttProvider": "deepgram", - "sttLanguage": "en-US", - "ttsProvider": "elevenlabs", - "ttsVoice": "rachel" - } - }, - "environment": "production" - }' -``` - -### Twilio Voice - -For Twilio-based voice, create a channel connection with Twilio credentials, then configure the Twilio phone number's webhook to point to the platform's voice endpoint. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "voice_twilio", - "display_name": "Twilio Voice", - "external_identifier": "+15551234567", - "credentials": { - "account_sid": "your-twilio-account-sid", - "auth_token": "your-twilio-auth-token" - }, - "config": { - "phoneNumber": "+15551234567" - }, - "environment": "production" - }' -``` - -### Use caller identity - -For voice sessions, the runtime makes caller identity available through the `session` namespace. Your agent can pass the caller's number or the dialed number into tools without asking the caller to repeat it. - -| Field | Description | -| ----- | ----------- | -| `session.anonymousId` | Normalized caller identity. For phone calls, this is the caller ANI when the gateway provides a valid phone number. | -| `session.sessionPrincipalId` | The recognized session principal used for contact resolution and session ownership checks. | -| `session.calledNumber` | Normalized number the caller dialed, when available. | -| `session.rawCallerId` | Raw caller value before phone normalization. | -| `session.rawFrom` | Raw upstream `From` value before phone normalization. | -| `session.rawCalledNumber` | Raw called value before phone normalization. | -| `session.rawTo` | Raw upstream `To` value before phone normalization. | - -The runtime normalizes phone-like values from the gateway. For example, `sip:+15551234567@example.com` and `+1 (555) 123-4567` both become `+15551234567`. If the first caller value isn't a phone number, the runtime checks trusted SIP identity headers before falling back to the raw identity value. - -Use the normalized fields for most tools: - -```yaml -TOOLS: - lookup_customer(phone: string, called_number?: string) -> object - description: "Find the customer record for a voice caller." - -FLOW: - identify_caller - - identify_caller: - REASONING: false - CALL: lookup_customer - WITH: - phone: session.anonymousId - called_number: session.calledNumber - AS: customer - RESPOND: "Thanks. I found your account." -``` - -Use raw fields only when your integration needs the original gateway value for audit or carrier-specific troubleshooting. - -```yaml -CALL: record_voice_context - WITH: - caller_id: session.anonymousId - raw_from: session.rawFrom - called_number: session.calledNumber - raw_to: session.rawTo - AS: voiceContext -``` - -Caller identity fields can contain phone numbers or carrier-provided identifiers, so treat them as end-user identity data. Don't pass raw fields to external tools unless the tool needs the original gateway value. - -### Add voice-specific responses - -Use `VOICE:` blocks to provide voice-optimized output alongside text. The block accepts `ssml`, `instructions`, and `plain_text` properties. - -```yaml -FLOW: - welcome: - REASONING: false - RESPOND: "Welcome to Acme Support. How can I help?" - VOICE: - instructions: "Use a warm, professional tone. Speak at a moderate pace." - - confirm_booking: - REASONING: false - RESPOND: "Your booking is confirmed. Confirmation number: {{confirmation_id}}." - VOICE: - instructions: "Read the confirmation number slowly and clearly, one character at a time." - ssml: | - - Your booking is confirmed. - Confirmation number: {{confirmation_id}}. - -``` - -### BYOC SIP - -Connect your existing SIP trunk with the bring-your-own-carrier provider. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "korevg", - "display_name": "Enterprise SIP", - "external_identifier": "enterprise-sip", - "config": { - "provider": "byoc_sip", - "sipGateway": "192.168.1.100:5060", - "voiceConfig": { - "sttProvider": "deepgram", - "ttsProvider": "elevenlabs", - "ttsVoice": "rachel" - } - } - }' -``` - -### AudioCodes Voice Gateway - -For AudioCodes VoiceAI Connect integration: - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/channel-connections \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "channel_type": "audiocodes", - "display_name": "AudioCodes Voice", - "external_identifier": "audiocodes-main", - "config": { - "botUrl": "https://your-platform/api/v1/channels/audiocodes/webhook" - } - }' -``` - -### Browser-based Voice - -Generate a Twilio token for browser-based voice calls from your web application. - -```bash -curl -X POST https://your-platform/api/v1/voice/token \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "projectId": "your-project-id", - "identity": "user-123" - }' -``` - -Use the returned token with the Twilio Client SDK in your frontend: - -```typescript -import { Device } from '@twilio/voice-sdk'; - -const device = new Device(token); -await device.register(); - -const call = await device.connect({ - params: { projectId: 'your-project-id' }, -}); -``` - -### Control speech with SSML - -Use SSML for fine-grained control over speech output, such as pauses, emphasis, and pronunciation. - -```yaml -RESPOND: "Your account balance is ${{balance}}." -VOICE: - ssml: | - - Your account balance is - USD{{balance}}. - - Is there anything else I can help with? - -``` - -### Troubleshooting - -| Symptom | Resolution | -| ------- | ---------- | -| **No audio in calls** | Confirm the STT and TTS providers are configured with valid API keys. Check the voice service health endpoint. | -| **Webhook signature validation fails (Twilio)** | The `auth_token` must match the Twilio account's Auth Token. The platform uses it to validate `X-Twilio-Signature` on incoming webhooks. | -| **Voice responses cut off** | Long responses can exceed TTS limits. Keep voice responses concise, or use SSML `` tags to create natural pauses. | -| **SIP registration fails** | For BYOC SIP, verify the SIP gateway IP and port, and confirm the gateway allows connections from the platform's IP range. | - -## Rich Content - -Use rich content to send formatted responses that adapt to each channel's capabilities: Markdown, Adaptive Cards, Slack Block Kit, WhatsApp interactive messages, carousels, and interactive elements. - -Attach a `RICH_CONTENT:` block to any `RESPOND` statement. The runtime selects the format that matches the delivery channel and falls back to the plain text `RESPOND` message when no matching format exists. For the complete reference, see [Rich Content and Expressions](/agent-platform/abl-reference/rich-content-and-expressions). - -| Format | Description | -| ------ | ----------- | -| `MARKDOWN` | Formatted Markdown text. | -| `ADAPTIVE_CARD` | JSON conforming to the Microsoft Adaptive Cards schema. | -| `HTML` | HTML content for web-based channels. | -| `SLACK` | JSON conforming to the Slack Block Kit format. | -| `WHATSAPP` | JSON for WhatsApp interactive messages. | -| `AG_UI` | JSON for AG-UI events. | -| `CAROUSEL` | A scrollable collection of cards. | - -### Add Rich Content to a response - -Provide channel-specific formatting alongside the plain text response. - -```yaml -FLOW: - show_results: - REASONING: false - RESPOND: "Here are your search results." - RICH_CONTENT: - MARKDOWN: | - ## Search Results - - | Hotel | Price | Rating | - |-------|-------|--------| - {{#each hotels}} - | {{name}} | ${{price}} | {{rating}} stars | - {{/each}} -``` - -If you don't provide a channel-specific format, the runtime falls back to the plain text `RESPOND` message. - -### Adaptive Cards for Microsoft Teams - -Send rich interactive cards on Teams with the Adaptive Cards format. - -```yaml -RESPOND: "Your booking summary" -RICH_CONTENT: - ADAPTIVE_CARD: | - { - "type": "AdaptiveCard", - "version": "1.5", - "body": [ - {"type": "TextBlock", "text": "Booking Confirmed", "size": "large", "weight": "bolder"}, - {"type": "FactSet", "facts": [ - {"title": "Hotel", "value": "{{hotel_name}}"}, - {"title": "Dates", "value": "{{checkin}} - {{checkout}}"}, - {"title": "Total", "value": "${{total}}"} - ]} - ] - } -``` - -### Slack Block Kit - -Send formatted messages with Slack blocks. - -```yaml -RESPOND: "Your order status" -RICH_CONTENT: - SLACK: | - { - "blocks": [ - {"type": "header", "text": {"type": "plain_text", "text": "Order Status"}}, - {"type": "section", "fields": [ - {"type": "mrkdwn", "text": "*Order:* #{{order_id}}"}, - {"type": "mrkdwn", "text": "*Status:* {{status}}"} - ]}, - {"type": "divider"}, - {"type": "section", "text": {"type": "mrkdwn", "text": "Estimated delivery: {{delivery_date}}"}} - ] - } -``` - -### WhatsApp Interactive Messages - -Send interactive list or button messages on WhatsApp. - -```yaml -RESPOND: "Select an option" -RICH_CONTENT: - WHATSAPP: | - { - "type": "interactive", - "interactive": { - "type": "button", - "body": {"text": "How would you like to proceed?"}, - "action": { - "buttons": [ - {"type": "reply", "reply": {"id": "modify", "title": "Modify Booking"}}, - {"type": "reply", "reply": {"id": "cancel", "title": "Cancel Booking"}}, - {"type": "reply", "reply": {"id": "info", "title": "More Info"}} - ] - } - } - } -``` - -### Carousel of Cards - -Send a scrollable carousel of cards across supported channels. Each card has a title, an optional subtitle and image, and action buttons. - -```yaml -RESPOND: "Available hotels" -RICH_CONTENT: - CAROUSEL: - - title: "Grand Hotel" - subtitle: "$200/night - 4.5 stars" - imageUrl: "https://example.com/grand-hotel.jpg" - buttons: - - id: book_grand - type: button - label: "Book Now" - value: "grand_hotel" - - title: "City Lodge" - subtitle: "$120/night - 4.0 stars" - imageUrl: "https://example.com/city-lodge.jpg" - buttons: - - id: book_city - type: button - label: "Book Now" - value: "city_lodge" -``` - -### Interactive actions - -Add buttons, select menus, and input fields with an `ACTIONS:` block. Handle the user's interaction with `ON_ACTION`. - -```yaml -FLOW: - offer_actions: - REASONING: false - RESPOND: "What would you like to do?" - ACTIONS: - - id: view_details - type: button - label: "View Details" - - id: select_category - type: select - label: "Category" - options: - - id: billing - label: "Billing" - - id: technical - label: "Technical" - - id: general - label: "General" - ON_ACTION: - view_details: - RESPOND: "Here are the details..." - GOTO: show_details - select_category: - SET: - selected_category = action.value - GOTO: route_to_category -``` - -The `type` property accepts `button`, `select`, or `input`. For `input` elements, set `inputType` to `text`, `number`, `date`, `time`, or `email`, and add a `submitLabel` and `submitId` for the form's submit button. See [Interactive actions](/agent-platform/abl-reference/rich-content-and-expressions#interactive-actions) for the full property list. - -### Multi-channel templates - -Define reusable, named responses in the `TEMPLATES:` block. Templates support `{{}}` interpolation and multi-format variants. Reference a template with `TEMPLATE(name)`. - -```yaml -TEMPLATES: - booking_summary: - DEFAULT: | - Booking Confirmed! - Hotel: {{hotel_name}} - Total: ${{total}} - MARKDOWN: | - ## Booking Confirmed - - | Detail | Value | - |--------|-------| - | **Hotel** | {{hotel_name}} | - | **Total** | ${{total}} | - -FLOW: - confirm: - REASONING: false - RESPOND: TEMPLATE(booking_summary) - THEN: COMPLETE -``` - - - The reference defines `DEFAULT`, `MARKDOWN`, `ADAPTIVE_CARD`, and `ACTIONS` as template variants. The `HTML` and voice template variants from earlier drafts aren't in the reference. Verify with the product team before documenting them. - - -### How the runtime selects a format - -The runtime selects the response format based on the delivery channel and falls back through the priority chain until it finds a defined format. Plain text is always the final fallback. - -| Channel | Priority format | Fallback | -| ------- | --------------- | -------- | -| Web and SDK | `RICH_CONTENT` (Markdown, HTML, AG-UI) | Plain text | -| Mobile | `RICH_CONTENT` (Adaptive Card, Carousel) | Plain text | -| Voice | `VOICE` (SSML, instructions, plain text) | `RESPOND` text | -| Slack | `RICH_CONTENT` (Slack) | Markdown | -| WhatsApp | `RICH_CONTENT` (WhatsApp) | Plain text | - -### Troubleshooting - -| Symptom | Resolution | -| ------- | ---------- | -| **Rich content doesn't render** | The channel may not support the format. Always provide a plain text `RESPOND` fallback. The runtime uses it when no matching rich format exists. | -| **Adaptive Card JSON parse error** | Validate the JSON with the [Adaptive Cards Designer](https://adaptivecards.io/designer/). Template variables resolve before JSON parsing. | -| **Slack blocks rejected by the API** | Slack limits block structure to 50 blocks and 3,000 characters per text element. Validate against Slack's Block Kit Builder. | -| **Interactive action isn't handled** | Confirm each button or select element has an `id` that matches a handler key in the `ON_ACTION` block. | - -## File Attachments - -Handle file attachments so your agent can accept, process, and respond to user-uploaded images, documents, audio, and video. - - - The `ATTACHMENTS` ABL block and the attachments REST API in this section are pending a published reference. Verify block properties, endpoint paths, and field names before publishing. - - -### Declare attachment fields - -Use the `ATTACHMENTS` block in your agent to declare the file types your agent accepts. The runtime prompts the user for each required attachment and validates file type and size before processing. - -```yaml -AGENT: Document_Processor -GOAL: "Process uploaded documents and extract information" - -ATTACHMENTS: - id_document: - prompt: "Please upload a photo of your ID" - category: image - required: true - maxFileSizeMb: 10 - allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"] - ocrEnabled: true - - supporting_document: - prompt: "Upload any supporting documents (optional)" - category: document - required: false - maxFileSizeMb: 20 - allowedMimeTypes: ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"] -``` - -### Upload attachments through the API - -When you build a custom integration, upload files through the attachments API. The response includes an `attachmentId` and a processing `status`. - -```bash -curl -X POST https://your-platform/api/projects/$PROJECT_ID/sessions/$SESSION_ID/attachments \ - -H "Authorization: Bearer $TOKEN" \ - -F "file=@document.pdf" -``` - -For the Web SDK, upload with `chat.uploadAttachment(file)` and send the returned ID with a message. The SDK accepts files up to 25 MB each, with a maximum of 10 files per message. See [Agent Platform SDKs Overview](/agent-platform/sdks#file-uploads). - -### Check processing status - -```bash -curl https://your-platform/api/projects/$PROJECT_ID/sessions/$SESSION_ID/attachments/$ATTACHMENT_ID/status \ - -H "Authorization: Bearer $TOKEN" -``` - -| Field | Description | -| ----- | ----------- | -| `scanStatus` | Malware scan result: pending, clean, or infected. | -| `processingStatus` | Content extraction: pending, processing, or complete. | -| `embeddingStatus` | Embedding generation: pending or complete. | - -### Extract text from images with OCR - -Enable OCR to extract text from images, which is useful for receipts, IDs, and handwritten notes. The extracted text is available in the session as `receipt.extractedText`. - -```yaml -ATTACHMENTS: - receipt: - prompt: "Upload a photo of your receipt" - category: image - required: true - ocrEnabled: true -``` - -### Transcribe audio - -Enable transcription for audio uploads. The transcribed text is available as `voicemail.transcription`. - -```yaml -ATTACHMENTS: - voicemail: - prompt: "Upload the voicemail recording" - category: audio - required: true - transcriptionEnabled: true - allowedMimeTypes: ["audio/mpeg", "audio/wav", "audio/ogg"] -``` - -### Extract key frames from video - -Extract key frames from video for visual analysis. - -```yaml -ATTACHMENTS: - product_video: - prompt: "Upload a video of the defective product" - category: video - required: false - maxFileSizeMb: 50 - keyFrameExtraction: true -``` - -### Request attachments in a flow step - -Request attachments at specific points in a flow. - -```yaml -FLOW: - collect_documents: - REASONING: false - PROMPT: "I need to verify your identity. Please upload a photo of your ID." - GATHER: - FIELDS: - - id_photo - type: attachment - category: image - required: true - THEN: verify_identity - - verify_identity: - REASONING: true - GOAL: "Verify the uploaded ID document" - AVAILABLE_TOOLS: [verify_document, extract_id_data] - EXIT_WHEN: identity_verified IS SET - THEN: proceed -``` - -### Channel-specific handling - -Different channels handle attachments differently. The platform's channel adapters normalize all formats, so no agent-side configuration is needed. - -| Channel | Attachment support | -| ------- | ------------------ | -| Web SDK | Drag-and-drop file upload in the chat widget. | -| Slack | Native file sharing, downloaded automatically. | -| WhatsApp | Image, document, audio, and video through the media API. | -| Teams | File attachments through the Bot Framework. | -| Email | MIME attachments parsed from inbound email. | -| Telegram | Photos, documents, audio, and video messages. | - -### List and retrieve attachments - -The download URL is time-limited (one hour by default) and scoped to the authenticated user. - -```bash -# List all attachments for a session -curl https://your-platform/api/projects/$PROJECT_ID/sessions/$SESSION_ID/attachments \ - -H "Authorization: Bearer $TOKEN" - -# Get a download URL for a specific attachment -curl https://your-platform/api/projects/$PROJECT_ID/sessions/$SESSION_ID/attachments/$ATTACHMENT_ID/url \ - -H "Authorization: Bearer $TOKEN" -``` - -### Troubleshooting - -| Symptom | Resolution | -| ------- | ---------- | -| **"PAYLOAD_TOO_LARGE" on upload** | The file exceeds the maximum size, either the upload endpoint limit or the `maxFileSizeMb` declared in the attachment field. Reduce the file size or adjust the limit. | -| **Processing status stuck on "pending"** | The multimodal processing service may be unavailable. Check service health. | -| **OCR returns empty text** | The image may be too low resolution, or the text isn't clearly visible. Recommend that users upload high-quality images. | -| **Attachment isn't available in session variables** | Wait for `processingStatus` to reach `complete` before accessing extracted content. Use the status endpoint to poll. | - -## Related pages - -- [Deploy Agents](/agent-platform/deployment) -- deployments, environments, and the **Deployments** -> **Channels** workspace. -- [Agent Platform SDKs Overview](/agent-platform/sdks) -- Web SDK and ABL SDK reference. -- [Rich Content and Expressions](/agent-platform/abl-reference/rich-content-and-expressions) -- the full ABL rich content reference. -- [Safety and Guardrails](/agent-platform/safety-and-guardrails) -- rate limiting for SDK channels. -- [Build Your First Agent](/agent-platform/tutorials/build-your-first-agent) -- end-to-end tutorial including web deployment. \ No newline at end of file diff --git a/agent-platform/channels.mdx b/agent-platform/channels.mdx index 73ec1794..abd83690 100644 --- a/agent-platform/channels.mdx +++ b/agent-platform/channels.mdx @@ -7,10 +7,6 @@ Channels connect your deployed agents to the surfaces where users interact. Use Each channel opens a **New \ Connection** dialog. Provider-side setup, creating the app and copying credentials, happens in the provider's console first. You then paste those values into the dialog, and the platform returns a webhook URL to register back with the provider. - - This guide covers the channels currently exposed in the **Deployments** -> **Channels** workspace. The full adapter catalog is owned by the product team. Confirm the authoritative list of supported channels before publishing. - - ## Before you begin Confirm the following before you add a connection: @@ -34,10 +30,6 @@ Every **New Connection** dialog ends with the same three settings. The channel-s Select **Create** to save the connection, or **Cancel** to discard it. - - Use separate connections and credentials for dev, staging, and production. Bind each to its matching environment so a test message never reaches a production audience. - - ## Set up Slack Deploy your agent as a Slack bot for team collaboration in channels and direct messages. @@ -108,10 +100,6 @@ Integrate your agent into Teams channels and chats through an Azure Bot registra Complete the [common connection settings](#common-connection-settings) and select **Create**. - - Attachment ingestion currently supports the **personal chat** scope only. - - ## Set up WhatsApp Connect your agent to WhatsApp Business for customer messaging through Meta's Cloud API. @@ -264,40 +252,4 @@ Choose the authentication mode that fits your setup: - Restrict allowed origins and use separate public keys for dev, staging, and production. -Create a public SDK key before you publish the channel. If the dialog reports **No active public SDK keys found**, create one in **Deploy** -> **Public Keys**. Then copy the embed snippet and add it to your website's `` or before the closing `` tag. For the embed component, SDK reference, and origin restrictions, see [Channels](/agent-platform/channels#deploy-on-web). - -## Set up Realtime LLM Voice - -Run live voice conversations with realtime LLM models, such as OpenAI Realtime and Gemini Live, through the Kore.ai Voice Gateway. - -### Create the connection - -| Field | What to enter | -| ----- | ------------- | -| **Display Name** | A label for the connection. | -| **Connection Name** | A machine-friendly name, for example `realtime-voice-prod`. | - -Complete the [common connection settings](#common-connection-settings) and select **Create**. Then finish the voice setup: - - - - Select a voice provider. The connection defaults to the **Kore.ai Voice Gateway**. - - - Buy a phone number through Twilio in the **Configuration** tab. - - - Choose your realtime LLM model — **OpenAI Realtime** or **Gemini Live**. - - - Select your ASR (speech-to-text) and TTS (text-to-speech) model preferences. - - - Assign the channel to a deployment environment. - - - -## Related pages - -- [Channels](/agent-platform/channels-curl) -- the API method, rich content, and file-attachment handling. -- [Agent Platform SDKs Overview](/agent-platform/sdks) -- Web SDK and ABL SDK reference. \ No newline at end of file +Create a public SDK key before you publish the channel. If the dialog reports **No active public SDK keys found**, create one in **Deploy** -> **Public Keys**. Then copy the embed snippet and add it to your website's `` or before the closing `` tag. For the embed component, SDK reference, and origin restrictions, see [Channels](/agent-platform/channels#deploy-on-web). \ No newline at end of file From dc1a809b70d5b0e757cd6cafd07b70dbf2dd72dd Mon Sep 17 00:00:00 2001 From: siddharthmenon-7 Date: Thu, 2 Jul 2026 14:17:57 +0530 Subject: [PATCH 3/8] Fixed broken link --- agent-platform/channels.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agent-platform/channels.mdx b/agent-platform/channels.mdx index abd83690..b64197aa 100644 --- a/agent-platform/channels.mdx +++ b/agent-platform/channels.mdx @@ -3,7 +3,7 @@ title: "Channels" sidebarTitle: "Channels" --- -Channels connect your deployed agents to the surfaces where users interact. Use the UI when you want to register a provider's credentials and bind the connection to a deployment without writing scripts. For the API method, rich content, and file-attachment handling, see [Channels](/agent-platform/channels-curl). +Channels connect your deployed agents to the surfaces where users interact. Use the UI when you want to register a provider's credentials and bind the connection to a deployment without writing scripts. Each channel opens a **New \ Connection** dialog. Provider-side setup, creating the app and copying credentials, happens in the provider's console first. You then paste those values into the dialog, and the platform returns a webhook URL to register back with the provider. From 20a7aa852a962995044ed7021e918d14958661be Mon Sep 17 00:00:00 2001 From: Prabhat Singh <109069787+prabhat-singh-kore@users.noreply.github.com> Date: Thu, 2 Jul 2026 19:28:32 +0530 Subject: [PATCH 4/8] note in the Channels about on-screen setup instructions --- agent-platform/channels.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/agent-platform/channels.mdx b/agent-platform/channels.mdx index b64197aa..e34b2563 100644 --- a/agent-platform/channels.mdx +++ b/agent-platform/channels.mdx @@ -17,6 +17,8 @@ Confirm the following before you add a connection: **Navigation**: **Project** -> **Deployments** -> **Channels** -> **Add Connection**, then select the channel. +: Read the on-screen Setup instructions for the channel you want to add. Each channel has its own required credentials and setup steps. + ## Common connection settings Every **New Connection** dialog ends with the same three settings. The channel-specific fields differ; these don't. From 36d3b7be4a3fe33af1ce03990ab3e540093cc507 Mon Sep 17 00:00:00 2001 From: Ashish Gupta Date: Thu, 2 Jul 2026 19:36:37 +0530 Subject: [PATCH 5/8] Updating SDK docs - install and import instructions --- .../sdk/sdk-end-to-end-auth-setup.mdx | 2 + agent-platform/sdks.mdx | 116 +++++++++--------- 2 files changed, 58 insertions(+), 60 deletions(-) diff --git a/agent-platform/sdk/sdk-end-to-end-auth-setup.mdx b/agent-platform/sdk/sdk-end-to-end-auth-setup.mdx index 66a37eff..c0e57bbb 100644 --- a/agent-platform/sdk/sdk-end-to-end-auth-setup.mdx +++ b/agent-platform/sdk/sdk-end-to-end-auth-setup.mdx @@ -17,6 +17,8 @@ It covers these scenarios: 3. [Customer-issued shared-secret JWE](#scenario-3-customer-issued-shared-secret-jwe) 4. [Customer-issued public-key JWE with customer-signed payload](#scenario-4-customer-issued-public-key-jwe) +Before you set up E2E auth, [install the Agent Platform SDK](/agent-platform/sdks.mdx#install-web-sdk). + ## Scenario Selection | Scenario | Browser credential | Customer backend responsibility | Runtime responsibility | When to use | diff --git a/agent-platform/sdks.mdx b/agent-platform/sdks.mdx index cd5bfa8d..a3e124d6 100644 --- a/agent-platform/sdks.mdx +++ b/agent-platform/sdks.mdx @@ -3,7 +3,7 @@ title: 'Agent Platform SDKs Overview' sidebarTitle: Web and ABL SDKs --- -The Agent Platform provides two SDKs: the **Web SDK** for embedding agent chat and voice interactions in web applications, and the **ABL SDK** for programmatic access to parse, validate, and compile ABL agent definitions. +The Agent Platform provides two SDKs: the **Web SDK** to embed agent chat and voice interactions in web applications and the **ABL SDK** for programmatic access to parse, validate, and compile ABL agent definitions. {/* AG: Hiding API ref link temporarily @@ -13,31 +13,25 @@ For authentication and error handling conventions, see [API overview](/agent-pla ## Web SDK -The Agent Platform Web SDK (`@agent-platform/web-sdk`) provides a TypeScript/JavaScript library for embedding agent chat and voice interactions in web applications. The SDK supports vanilla JavaScript, React hooks, and a web component for drop-in integration. +The Agent Platform Web SDK (`@koreai/artemis-web-sdk`) provides a TypeScript/JavaScript library for embedding agent chat and voice interactions in web applications. The SDK supports vanilla JavaScript, React hooks, and a web component for drop-in integration. The browser-facing SDK does not send the public `pk_*` key directly to `/ws/sdk`. It first exchanges the key for a short-lived SDK session token on `POST /api/v1/sdk/init`, then authenticates SDK HTTP routes with `X-SDK-Token` and the SDK WebSocket with `Sec-WebSocket-Protocol: sdk-auth,`. -{/* -### Installation + +### Install Web SDK ```bash -npm install @agent-platform/web-sdk +npm i @koreai/artemis-web-sdk ``` +The package includes the core `AgentSDK` constructor, chat and voice clients, React provider/hooks/components, custom elements, rich content renderers, attachment upload, feedback, auth challenge UI, and template utilities. -Or include via script tag: - -```html - -``` -*/} - -### Quick start +### Quick Start #### Vanilla JavaScript ```typescript -import { AgentSDK } from '@agent-platform/web-sdk'; +import { AgentSDK } from '@koreai/artemis-web-sdk'; const sdk = new AgentSDK({ projectId: 'your-project-id', @@ -56,7 +50,7 @@ await chat.send('Hello, I need help!'); #### React ```tsx -import { AgentProvider, useChat, useVoice } from '@agent-platform/web-sdk/react'; +import { AgentProvider, useChat, useVoice } from '@koreai/artemis-web-sdk/react'; function App() { return ( @@ -89,7 +83,7 @@ function ChatWidget() { } ``` -#### Web component +#### Web Component ```html @@ -129,7 +123,7 @@ new AgentSDK(config: SDKConfig) | `isConnected()` | `boolean` | Check if the SDK is connected | | `getSessionId()` | `string | null` | Get the current session ID | -#### Static methods +#### Static Methods | Method | Returns | Description | | ----------------------- | ---------- | -------------------------------------------------------------- | @@ -175,7 +169,7 @@ Handles text messaging with streaming support. Obtained via `sdk.chat()`. | `getIsTyping()` | `boolean` | Check if the agent is currently responding | | `clearMessages()` | `void` | Clear the local message history | -#### send() options +#### send() Options ```typescript interface SendMessageOptions { @@ -249,7 +243,7 @@ chat.on('typing', ({ isTyping }) => { }); ``` -#### Message type +#### Message Type ```typescript interface Message { @@ -264,7 +258,7 @@ interface Message { } ``` -#### RichContent type +#### RichContent Type Multi-format content variants delivered alongside the plain text response: @@ -279,7 +273,7 @@ interface RichContent { } ``` -#### ActionSet type +#### ActionSet Type Interactive action elements the agent sends for user input: @@ -303,7 +297,7 @@ interface ActionElement { } ``` -#### AttachmentRef type +#### AttachmentRef Type ```typescript interface AttachmentRef { @@ -336,13 +330,13 @@ The voice client supports two modes: | `getState()` | `VoiceState` | Get the current voice state | | `getInfo()` | `VoiceInfo` | Get full voice status information | -#### Static methods +#### Static Methods | Method | Returns | Description | | --------------------------- | --------- | -------------------------------------------- | | `VoiceClient.isSupported()` | `boolean` | Check if the browser supports voice features | -#### Voice states +#### Voice States ```typescript type VoiceState = @@ -355,7 +349,7 @@ type VoiceState = | 'error'; // Error state ``` -#### VoiceInfo type +#### VoiceInfo Type ```typescript interface VoiceInfo { @@ -431,7 +425,7 @@ const isMuted = voice.toggleMute(); --- -### React hooks +### React Hooks The React integration provides a context provider and hooks for state management. @@ -440,7 +434,7 @@ The React integration provides a context provider and hooks for state management Wrap your application with `AgentProvider` to initialize the SDK: ```tsx -import { AgentProvider } from '@agent-platform/web-sdk/react'; +import { AgentProvider } from '@koreai/artemis-web-sdk/react'; ``` -#### Widget positions +#### Widget Positions - `bottom-right` (default) - `bottom-left` - `top-right` - `top-left` -#### Widget modes +#### Widget Modes - `chat` -- Text-only chat interface - `voice` -- Voice-only interface @@ -649,11 +643,11 @@ sdk.removeAllListeners(); --- -### WebSocket message types +### WebSocket Message Types The SDK communicates with the platform over WebSocket. These types are used internally but documented for advanced use cases. -#### Server message types +#### Server Message Types | Type | Description | | ---------------- | ------------------------------------------------------------------------- | @@ -666,18 +660,18 @@ The SDK communicates with the platform over WebSocket. These types are used inte --- -### API key management +### API Key Management Public API keys (`pk_` prefix) are scoped to a project and provide limited permissions for SDK usage. They are safe to expose in client-side code. -#### Creating an API key +#### Creating an API Key 1. Go to **Project > Settings > API Keys**. 2. Click **Create API key**. 3. Set the allowed origins (for CORS protection). 4. Copy the key -- it is displayed only once. -#### Origin restrictions +#### Origin Restrictions Configure allowed origins to prevent unauthorized use of your API key: @@ -691,7 +685,7 @@ The runtime validates the `Origin` header on every SDK request and rejects reque --- -### Authentication and verified identity +### Authentication and Verified Identity Public API keys cover anonymous and low-assurance chat. For verified user identity, sensitive-data flows, and customer-issued tokens, configure SDK authentication end to end across Studio, the browser SDK, the customer backend, and the runtime. @@ -699,7 +693,7 @@ Public API keys cover anonymous and low-assurance chat. For verified user identi --- -### Browser compatibility +### Browser Compatibility The SDK requires: @@ -713,6 +707,8 @@ Voice features require HTTPS in production (microphone access requires a secure --- +{/* AG: Requested platform dev for ABL SDK package name - will update after confirmation. + ## ABL SDK The ABL SDK (`@abl/core`) provides programmatic access to parse, validate, and serialize Agent Business Language (ABL) definitions. Use it to build tooling, CI/CD pipelines, and integrations that work with ABL agent specifications. @@ -731,7 +727,7 @@ npm install @abl/compiler --- -### Parsing ABL +### Parse ABL The `parse()` function is the primary entry point. It auto-detects the document type and returns a parsed AST (Abstract Syntax Tree) along with any parse errors. @@ -787,7 +783,7 @@ interface ParseError { } ``` -#### Auto-detection rules +#### Auto-Detection Rules When `type` is not specified, `parse()` detects the document type from the content: @@ -874,7 +870,7 @@ if (result.document) { --- -### Specialized parsers +### Specialized Parsers For advanced use cases, the SDK exposes type-specific parsers: @@ -936,7 +932,7 @@ const isYaml = isYamlFormat(source); // boolean --- -### Expression parsing +### Expression Parsing Parse and work with ABL condition expressions: @@ -974,7 +970,7 @@ const python = expressionToPython(expr); --- -### Lexer utilities +### Lexer Utilities Access the tokenizer for building custom tooling: @@ -1049,7 +1045,7 @@ import { validateFieldReferences } from '@abl/compiler'; const diagnostics = validateFieldReferences(ir); ``` -#### ValidationDiagnostic type +#### ValidationDiagnostic Type ```typescript interface ValidationDiagnostic { @@ -1063,7 +1059,7 @@ interface ValidationDiagnostic { --- -### CI/CD integration example +### CI/CD Integration Example Validate all ABL files in a project before deployment: @@ -1125,13 +1121,13 @@ process.exit(isValid ? 0 : 1); --- -### Working with exported projects +### Working with Exported Projects -{/* AG: Hiding API ref link temporarily +{/* AG: Hiding API ref link temporarily /*} Combine the ABL SDK with the [Project export/import API](/agent-platform/api-reference/knowledge-analytics-export#project-exportimport-api) to programmatically manipulate exported agent files: -/*} + ```typescript import { parse, serialize, validate } from '@abl/core'; @@ -1149,7 +1145,7 @@ if (result.document && result.errors.length === 0) { } ``` -### TypeScript support +### TypeScript Support Both `@abl/core` and `@abl/compiler` ship with full TypeScript type definitions. Key types are exported directly: @@ -1164,9 +1160,9 @@ import type { } from '@abl/compiler'; ``` -{/* AG: Hiding API ref link temporarily +{/* AG: Hiding API ref link temporarily */} -## Next steps +## Next Steps - Channels -- Configure SDK channels and widget settings - [Conversation API](/agent-platform/api-reference/conversation-api) -- REST API for server-side chat integration From 74ac117d94f9227aa2fa769f147137f58ea6b363 Mon Sep 17 00:00:00 2001 From: Ashish Gupta Date: Thu, 2 Jul 2026 19:55:29 +0530 Subject: [PATCH 6/8] Adjusting for Mintlify's lack of support for nested comments --- agent-platform/sdks.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/agent-platform/sdks.mdx b/agent-platform/sdks.mdx index a3e124d6..5f58e5f1 100644 --- a/agent-platform/sdks.mdx +++ b/agent-platform/sdks.mdx @@ -1160,8 +1160,6 @@ import type { } from '@abl/compiler'; ``` -{/* AG: Hiding API ref link temporarily */} - ## Next Steps - Channels -- Configure SDK channels and widget settings From 701d70eba3f2d9fb8f29f440dd6938d94138265d Mon Sep 17 00:00:00 2001 From: Prabhat Singh <109069787+prabhat-singh-kore@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:01:19 +0530 Subject: [PATCH 7/8] Minor edits --- agent-platform/channels.mdx | 32 ++++++++++++++++---------------- agent-platform/deployment.mdx | 33 ++++++++++++++++----------------- 2 files changed, 32 insertions(+), 33 deletions(-) diff --git a/agent-platform/channels.mdx b/agent-platform/channels.mdx index e34b2563..bcd2e67a 100644 --- a/agent-platform/channels.mdx +++ b/agent-platform/channels.mdx @@ -7,7 +7,7 @@ Channels connect your deployed agents to the surfaces where users interact. Use Each channel opens a **New \ Connection** dialog. Provider-side setup, creating the app and copying credentials, happens in the provider's console first. You then paste those values into the dialog, and the platform returns a webhook URL to register back with the provider. -## Before you begin +## Before you Begin Confirm the following before you add a connection: @@ -17,9 +17,9 @@ Confirm the following before you add a connection: **Navigation**: **Project** -> **Deployments** -> **Channels** -> **Add Connection**, then select the channel. -: Read the on-screen Setup instructions for the channel you want to add. Each channel has its own required credentials and setup steps. + Read the on-screen Setup instructions for the channel you want to add. Each channel has its own required credentials and setup steps. -## Common connection settings +## Common Connection Settings Every **New Connection** dialog ends with the same three settings. The channel-specific fields differ; these don't. @@ -36,7 +36,7 @@ Select **Create** to save the connection, or **Cancel** to discard it. Deploy your agent as a Slack bot for team collaboration in channels and direct messages. -### Get Slack credentials +### Get Slack Credentials @@ -53,7 +53,7 @@ Deploy your agent as a Slack bot for team collaboration in channels and direct m -### Create the connection +### Create the Connection In the **New Slack Connection** dialog, you can connect two ways: @@ -73,7 +73,7 @@ For Slack slash commands, point the command's **Request URL** to `/api/v1/channe Integrate your agent into Teams channels and chats through an Azure Bot registration. -### Get Microsoft Teams credentials +### Get Microsoft Teams Credentials @@ -90,7 +90,7 @@ Integrate your agent into Teams channels and chats through an Azure Bot registra -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | @@ -106,7 +106,7 @@ Complete the [common connection settings](#common-connection-settings) and selec Connect your agent to WhatsApp Business for customer messaging through Meta's Cloud API. -### Get WhatsApp credentials +### Get WhatsApp Credentials @@ -120,7 +120,7 @@ Connect your agent to WhatsApp Business for customer messaging through Meta's Cl -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | @@ -137,7 +137,7 @@ Complete the [common connection settings](#common-connection-settings) and selec Connect your agent to a Telegram bot for direct and group conversations. -### Get Telegram credentials +### Get Telegram Credentials @@ -148,7 +148,7 @@ Connect your agent to a Telegram bot for direct and group conversations. -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | @@ -162,7 +162,7 @@ Complete the [common connection settings](#common-connection-settings) and selec Process inbound emails and send agent responses by email. -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | @@ -176,7 +176,7 @@ Configure your email provider to forward or route messages to that address. The Connect your agent to Genesys Cloud as a Bot Connector for contact-center automation. -### Get Genesys credentials +### Get Genesys Credentials @@ -190,7 +190,7 @@ Connect your agent to Genesys Cloud as a Bot Connector for contact-center automa -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | @@ -204,7 +204,7 @@ Complete the [common connection settings](#common-connection-settings) and selec Connect your agent to Kore.ai's Employee Experience (EX) platform for bidirectional messaging. -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | @@ -231,7 +231,7 @@ Complete the [common connection settings](#common-connection-settings) and selec Embed a chat widget in your website with a single script tag. -### Create the connection +### Create the Connection | Field | What to enter | | ----- | ------------- | diff --git a/agent-platform/deployment.mdx b/agent-platform/deployment.mdx index 054bc6c3..1eedfe1e 100644 --- a/agent-platform/deployment.mdx +++ b/agent-platform/deployment.mdx @@ -85,11 +85,11 @@ Go to **Deployments** → **Environments** and click **New Deploy** (upper-right Click **Deploy**. The platform validates your agent ABLs, resolves configuration placeholders, and activates the deployment. If there was a previous dev deployment, it moves to draining — existing sessions finish naturally, new ones go to the new deployment. -## Step 3: Promote to staging +## Step 3: Promote to Staging Don't manually recreate staging deployments. Instead, Promote your dev deployment. This pushes the exact same agent version manifest to staging, so you're testing what you actually built rather than manually re-specifying versions. -## Step 4: Promote staging to production +## Step 4: Promote Staging to Production Once staging is validated, promote it to production the same way, by clicking Promote on the staging deployment. @@ -117,27 +117,26 @@ For external application access, create API Keys. To connect a channel from the **Deployments** -> **Channels** workspace, see [Set up Channels from the UI](/agent-platform/channels), which links each documented channel to its setup steps. +| Channel | Description | +| ------- | ----------- | +| **Slack** | Deploy agents as Slack bots for team collaboration. See the [setup guide](/agent-platform/channels#set-up-slack). | +| **Microsoft Teams** | Integrate agents into Teams channels and chats. See the [setup guide](/agent-platform/channels#set-up-microsoft-teams). | +| **WhatsApp** | Connect agents to WhatsApp Business for customer messaging. See the [setup guide](/agent-platform/channels#set-up-whatsapp). | +| **Telegram** | Connect agents to Telegram bots for messaging and group conversations. See the [setup guide](/agent-platform/channels#set-up-telegram). | +| **Web SDK** | Embed a chat widget in your website with a single script tag. See the [setup guide](/agent-platform/channels#set-up-web-sdk). | +| **Email** | Process inbound emails and send agent responses by email. See the [setup guide](/agent-platform/channels#set-up-email). | +| **Realtime LLM Voice** | Live voice conversations using realtime LLM models, such as OpenAI Realtime and Gemini Live, through the Kore.ai Voice Gateway. See the [setup guide](/agent-platform/channels#set-up-realtime-llm-voice). | +| **Genesys** | Connect agents to Genesys Cloud as a Bot Connector for contact-center automation. See the [setup guide](/agent-platform/channels#set-up-genesys). | +| **AIforWork** | Connect agents to Kore.ai's Employee Experience (EX) platform for bidirectional messaging. See the [setup guide](/agent-platform/channels#set-up-aiforwork). | -| Channel | Description | Setup guide | -| ------- | ----------- | ----------- | -| **Slack** | Deploy agents as Slack bots for team collaboration. | [UI setup](/agent-platform/channels#set-up-slack) | -| **Microsoft Teams** | Integrate agents into Teams channels and chats. | [UI setup](/agent-platform/channels#set-up-microsoft-teams) | -| **WhatsApp** | Connect agents to WhatsApp Business for customer messaging. | [UI setup](/agent-platform/channels#set-up-whatsapp) | -| **Telegram** | Connect agents to Telegram bots for messaging and group conversations. | [UI setup](/agent-platform/channels#set-up-telegram) | -| **Web SDK** | Embed a chat widget in your website with a single script tag. | [UI setup](/agent-platform/channels#set-up-web-sdk) | -| **Email** | Process inbound emails and send agent responses by email. | [UI setup](/agent-platform/channels#set-up-email) | -| **Realtime LLM Voice** | Live voice conversations using realtime LLM models, such as OpenAI Realtime and Gemini Live, through the Kore.ai Voice Gateway. | [UI setup](/agent-platform/channels#set-up-realtime-llm-voice) | -| **Genesys** | Connect agents to Genesys Cloud as a Bot Connector for contact-center automation. | [UI setup](/agent-platform/channels#set-up-genesys) | -| **AIforWork** | Connect agents to Kore.ai's Employee Experience (EX) platform for bidirectional messaging. | [UI setup](/agent-platform/channels#set-up-aiforwork) | - -## Step 6: Rollback if something goes wrong +## Step 6: Rollback if Something Goes Wrong If a production deployment causes issues, go to **Deployments** → **Environments**, find the active deployment, and click **Rollback**. This retires the current deployment and reactivates the previous one in that environment. Users on the bad deployment finish their sessions naturally; new sessions immediately go to the restored version. -## Deployment status reference +## Deployment Status Reference -| Status | What it means | +| Status | What it Means | | -------- | ----------------------------------------------------------------------------------- | | active | Receiving new sessions, serving live requests. | | draining | No new sessions accepted; existing sessions complete naturally. | From 52a6729d09af24b913b09303d2f5f8fc4413826c Mon Sep 17 00:00:00 2001 From: Prabhat Singh <109069787+prabhat-singh-kore@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:05:10 +0530 Subject: [PATCH 8/8] link to channel setup guide in the deployment > Channels table --- agent-platform/deployment.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/agent-platform/deployment.mdx b/agent-platform/deployment.mdx index 1eedfe1e..da1f1145 100644 --- a/agent-platform/deployment.mdx +++ b/agent-platform/deployment.mdx @@ -119,15 +119,15 @@ To connect a channel from the **Deployments** -> **Channels** workspace, see [Se | Channel | Description | | ------- | ----------- | -| **Slack** | Deploy agents as Slack bots for team collaboration. See the [setup guide](/agent-platform/channels#set-up-slack). | -| **Microsoft Teams** | Integrate agents into Teams channels and chats. See the [setup guide](/agent-platform/channels#set-up-microsoft-teams). | -| **WhatsApp** | Connect agents to WhatsApp Business for customer messaging. See the [setup guide](/agent-platform/channels#set-up-whatsapp). | -| **Telegram** | Connect agents to Telegram bots for messaging and group conversations. See the [setup guide](/agent-platform/channels#set-up-telegram). | -| **Web SDK** | Embed a chat widget in your website with a single script tag. See the [setup guide](/agent-platform/channels#set-up-web-sdk). | -| **Email** | Process inbound emails and send agent responses by email. See the [setup guide](/agent-platform/channels#set-up-email). | -| **Realtime LLM Voice** | Live voice conversations using realtime LLM models, such as OpenAI Realtime and Gemini Live, through the Kore.ai Voice Gateway. See the [setup guide](/agent-platform/channels#set-up-realtime-llm-voice). | -| **Genesys** | Connect agents to Genesys Cloud as a Bot Connector for contact-center automation. See the [setup guide](/agent-platform/channels#set-up-genesys). | -| **AIforWork** | Connect agents to Kore.ai's Employee Experience (EX) platform for bidirectional messaging. See the [setup guide](/agent-platform/channels#set-up-aiforwork). | +| **Slack** | Deploy agents as Slack bots for team collaboration. See the [channel setup guide](/agent-platform/channels#set-up-slack). | +| **Microsoft Teams** | Integrate agents into Teams channels and chats. See the [channel setup guide](/agent-platform/channels#set-up-microsoft-teams). | +| **WhatsApp** | Connect agents to WhatsApp Business for customer messaging. See the [channel setup guide](/agent-platform/channels#set-up-whatsapp). | +| **Telegram** | Connect agents to Telegram bots for messaging and group conversations. See the [channel setup guide](/agent-platform/channels#set-up-telegram). | +| **Web SDK** | Embed a chat widget in your website with a single script tag. See the [channel setup guide](/agent-platform/channels#set-up-web-sdk). | +| **Email** | Process inbound emails and send agent responses by email. See the [channel setup guide](/agent-platform/channels#set-up-email). | +| **Realtime LLM Voice** | Live voice conversations using realtime LLM models, such as OpenAI Realtime and Gemini Live, through the Kore.ai Voice Gateway. See the [channel setup guide](/agent-platform/channels#set-up-realtime-llm-voice). | +| **Genesys** | Connect agents to Genesys Cloud as a Bot Connector for contact-center automation. See the [channel setup guide](/agent-platform/channels#set-up-genesys). | +| **AIforWork** | Connect agents to Kore.ai's Employee Experience (EX) platform for bidirectional messaging. See the [channel setup guide](/agent-platform/channels#set-up-aiforwork). | ## Step 6: Rollback if Something Goes Wrong