diff --git a/agent-platform/create-agents.mdx b/agent-platform/create-agents.mdx index b192be11..544c03d2 100644 --- a/agent-platform/create-agents.mdx +++ b/agent-platform/create-agents.mdx @@ -965,6 +965,103 @@ TEMPLATES: bienvenida: DEFAULT: "Bienvenido! Como puedo ayudarte hoy?" ``` +## Customize Agent Response + +Agents can respond with more than plain text. Every RESPOND statement supports dynamic variables, reusable templates, rich content, interactive actions, and channel-specific formatting. The platform automatically renders the appropriate response for the active channel. + +### RESPOND + +Use `RESPOND` to return inline text or multi-line messages. Values from variables, memory, and tool outputs can be referenced using `{{ }}` interpolation. + +```yaml +RESPOND: "Hello {{customer_name}}, welcome back!" +``` +For multi-line content, use pipe symbol. + +```yaml + RESPOND: | + Here is your transfer summary: + From: {{source_account}} + To: {{beneficiary_name}} + Amount: {{amount}} {{currency}} +``` +For reusable or channel-specific responses, reference a template instead. + +```yaml +RESPOND: TEMPLATE(welcome_message) +``` + +### Templates + +Use the `TEMPLATES` block to define named, reusable responses that can be referenced throughout the agent using `TEMPLATE(name)`. Templates help eliminate duplication, maintain consistent messaging, and simplify updates by defining a response once and reusing it across multiple flows. + +Templates support: +- Variable interpolation using `{{ }}` to insert dynamic values. +- Conditional blocks and loops for rendering dynamic content. +- Multiple channel-specific variants, allowing the same response to be rendered differently on web, voice, Slack, WhatsApp, Teams, and other supported channels. +- Interactive actions for building rich, interactive experiences. + +The platform automatically selects the appropriate template variant for the active channel. `DEFAULT` is required and serves as the fallback when no channel-specific variant is available. + +| Variant | Purpose | +| -------------------- | ------------------------------ | +| `DEFAULT` | Plain text fallback (required) | +| `MARKDOWN` | Rich Markdown formatting | +| `HTML` | HTML content | +| `VOICE_INSTRUCTIONS` | Text-to-speech guidance | +| `ADAPTIVE_CARD` | Microsoft Teams/Web cards | +| `SLACK` | Slack Block Kit | +| `WHATSAPP` | WhatsApp message format | +| `AG_UI` | AG-UI event format | + +Templates can be referenced from `RESPOND`, `ON_START`, and `COMPLETE` blocks using `TEMPLATE(name)`. + +[Refer to this guide for details and examples](/agent-platform/abl-reference/full-specification#templates-named-response-templates). + +### Interactive Responses + +Add interactive elements to any response using `ACTIONS`. + +Supported actions include: + +- Buttons for predefined choices. +- Select menus for choosing from a list. +- Input fields for collecting user input. +- Forms for grouping multiple inputs with a submit action. + +[Learn More](/agent-platform/abl-reference/full-specification#interactive-actions-). + +### Carousels + +Carousels display a horizontal scrollable collection of cards, each with a title, subtitle, image, and action buttons. Use carousels when presenting multiple options for the user to browse and select from, such as hotel results, product listings, flight options, and similar multi-item responses. + +Define carousels within the `RICH_CONTENT` block using the `CAROUSEL` key. + +```yaml +RICH_CONTENT: + CAROUSEL: + - title: "Economy Class" + subtitle: "$289 - UA 891" + imageUrl: "https://cdn.example.com/economy.jpg" + defaultActionUrl: "https://booking.example.com/ua891" + buttons: + - id: select_economy + type: button + label: "Select" + value: "ua891_economy" + + - title: "Business Class" + subtitle: "$1,249 - UA 891" + imageUrl: "https://cdn.example.com/business.jpg" + buttons: + - id: select_business + type: button + label: "Select" + value: "ua891_business" +``` + +[For the complete list of carousel card properties and additional examples, see Carousel Rich Content](/agent-platform/abl-reference/rich-content-and-expressions#carousels) + ## Customize System Messages 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 960351a3..198029a5 100644 --- a/agent-platform/sdk/sdk-end-to-end-auth-setup.mdx +++ b/agent-platform/sdk/sdk-end-to-end-auth-setup.mdx @@ -1,8 +1,13 @@ --- title: "SDK End-to-End Auth Setup Guide" sidebarTitle: "SDK Auth Setup" +noindex: true --- +[Back to SDKs Overview](/agent-platform/sdks#authentication-and-verified-identity) + +The Agent Platform SDK is a TypeScript/JavaScript library for embedding agent chat and voice interactions in web applications. It supports vanilla JavaScript, React hooks, and a web component for drop-in integration. For the full SDK reference, see the [SDKs Overview](/agent-platform/sdks). + This guide explains how to configure Artemis SDK authentication end to end across Studio, the browser SDK, the customer backend, and deployment/runtime settings. It covers these scenarios: @@ -16,9 +21,9 @@ It covers these scenarios: | Scenario | Browser credential | Customer backend responsibility | Runtime responsibility | When to use | | ---------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| [Public anonymous SDK](#scenario-1-public-anonymous-sdk) | Public SDK API key | None for auth. The app may pass non-sensitive public `userContext`. | Verifies public key, channel, origin, and issues SDK session tokens. | Anonymous or low-assurance website chat where no PHI or verified customer identity is required. | +| [Public anonymous SDK](#scenario-1-public-anonymous-sdk) | Public SDK API key | None for auth. The app may pass non-sensitive public `userContext`. | Verifies public key, channel, origin, and issues SDK session tokens. | Anonymous or low-assurance website chat where no sensitive data or verified customer identity is required. | | [Runtime-signed Hosted Exchange](#scenario-2-runtime-signed-hosted-exchange) | Short-lived `bootstrapToken` returned by customer backend | Authenticates the customer, gathers secure attributes, calls Runtime `POST /api/v1/sdk/customer-sessions` with the channel server secret. | Mints the hosted bootstrap artifact and SDK session token. Applies `sdkTokenEnvelopePolicy`. | Customers accept a server-to-server Runtime call and want Artemis to own signing/encryption. | -| [Customer-issued shared-secret JWE](#scenario-3-customer-issued-shared-secret-jwe) | Short-lived compact JWE returned by customer backend | Authenticates the customer, builds claims, encrypts with the channel JWE shared secret, and returns JWE to the browser. | Decrypts and validates the customer-issued JWE, enforces replay, scope, age, and channel config, then issues SDK session token. | Flow where the customer backend must keep PHI encryption local and avoid the `/customer-sessions` API call. | +| [Customer-issued shared-secret JWE](#scenario-3-customer-issued-shared-secret-jwe) | Short-lived compact JWE returned by customer backend | Authenticates the customer, builds claims, encrypts with the channel JWE shared secret, and returns JWE to the browser. | Decrypts and validates the customer-issued JWE, enforces replay, scope, age, and channel config, then issues SDK session token. | Flow where the customer backend must keep sensitive-data encryption local and avoid the `/customer-sessions` API call. | | [Customer-issued public-key JWE](#scenario-4-customer-issued-public-key-jwe) | Short-lived compact JWE returned by customer backend | Authenticates the customer, signs the payload with the customer private key, encrypts the signed payload with the Runtime channel public key, and returns JWE to the browser. | Decrypts with Runtime private key, verifies customer signature with the configured customer public key, enforces replay, scope, age, and channel config, then issues SDK session token. | Preferred no-API-call flow when security review requires no shared encryption secret on the customer side and explicit issuer authentication. | Public-key customer JWE has two layers: @@ -63,8 +68,8 @@ Important constraints: bootstrap configs. Runtime uses it for SDK init widget display configuration and localization, not as verified identity. - For Hosted Exchange, put verified identity and secure custom attributes in the - customer backend token. Do not send PHI or verified identity directly from the - browser. + customer backend token. Do not send sensitive data or verified identity + directly from the browser. - WebSocket auth should use the one-time `sdk-ticket` flow. The legacy `sdk-auth` protocol is compatibility-only for older bundles. @@ -103,7 +108,7 @@ Origin enforcement happens after Runtime resolves the channel: - Hosted Exchange bootstrap init checks both the channel-config origins and the bound public API key origins after the bootstrap token is verified. - Empty or unset allowed-origin lists behave as unrestricted in code. Production - PHI channels should always configure explicit HTTPS origins. + channels should always configure explicit HTTPS origins. ## Shared Studio Prerequisites @@ -112,7 +117,7 @@ Origin enforcement happens after Runtime resolves the channel: 3. Create or select a public SDK API key for the project. 4. Set allowed origins on the public API key or managed channel key. - Include the exact browser origins that will host the SDK. - - Do not rely on wildcard origins for production PHI flows. + - Do not rely on wildcard origins for production flows. 5. Create an SDK channel and bind it to the deployment or environment. 6. Keep the channel active only after customer backend and browser changes are deployed. @@ -409,11 +414,11 @@ When `sdkTokenEnvelopePolicy` resolves to JWE, `tokenEnvelope` is `"jwe"` and Recommended customer backend controls: - Authenticate the website user before minting a bootstrap token. -- Collect PHI and secure custom attributes server-side only. +- Collect sensitive data and secure custom attributes server-side only. - Keep `verifiedUserId` stable for the customer identity. - Keep the endpoint same-origin or protected by customer auth cookies. - Do not return the channel server secret to the browser. -- Do not log `bootstrapToken`, PHI, or secure custom attributes. +- Do not log `bootstrapToken`, sensitive data, or secure custom attributes. ### Browser SDK Changes @@ -726,7 +731,7 @@ Do not pass `apiKey`, `channelId`, `channelName`, `deploymentSlug`, ## Scenario 4: Customer-Issued Public-Key JWE -This is the preferred no-new-Artemis-API-call option for higher-assurance PHI +This is the preferred no-new-Artemis-API-call option for higher-assurance flows. The customer backend signs the payload, encrypts it to Runtime, and the browser passes only the resulting compact JWE. @@ -1078,12 +1083,12 @@ All Hosted Exchange customer backend endpoints should: 1. Require the customer application's own authenticated session. 2. Derive `verifiedUserId` server-side. -3. Fetch PHI or secure attributes server-side. +3. Fetch sensitive or secure attributes server-side. 4. Put secure attributes under `customAttributes`. 5. Generate unique `jti` values. 6. Use short TTLs. Prefer 5 minutes or less. -7. Avoid logging bootstrap tokens, secure attributes, PHI, server secrets, or - private keys. +7. Avoid logging bootstrap tokens, secure attributes, sensitive data, server + secrets, or private keys. 8. Return only `{ "bootstrapToken": "..." }` and optional non-sensitive expiry metadata to the browser. 9. Rate limit token minting per customer session. @@ -1277,7 +1282,8 @@ Minimum evidence for each selected production scenario: 1. Studio screenshot or API response showing channel auth mode, token envelope policy, customer JWE mode, and active key metadata. -2. Customer backend request/response trace with secrets and PHI redacted. +2. Customer backend request/response trace with secrets and sensitive data + redacted. 3. Runtime init response showing `channelId`, `permissions`, `tokenEnvelope` when present, and `expiresIn`. 4. SDK browser trace showing no channel secret, customer JWE secret, Runtime @@ -1305,7 +1311,7 @@ Minimum evidence for each selected production scenario: ## Security Review Notes -- Public anonymous SDK is not a PHI flow. Treat any browser-provided +- Public anonymous SDK is not a high-assurance flow. Treat any browser-provided `userContext` as unverified. - Runtime-signed Hosted Exchange sends secure attributes to Runtime during `/api/v1/sdk/customer-sessions`. Use it only when that server-to-server API @@ -1317,5 +1323,5 @@ Minimum evidence for each selected production scenario: authentication through the inner JWS. - In all Hosted Exchange modes, Runtime still issues the canonical SDK session token after bootstrap. The customer-issued token is bootstrap-only. -- Do not store PHI in logs, URLs, local storage, WebSocket protocols, or - analytics metadata. +- Do not store sensitive data in logs, URLs, local storage, WebSocket protocols, + or analytics metadata. diff --git a/agent-platform/sdks.mdx b/agent-platform/sdks.mdx index f696fba5..cd5bfa8d 100644 --- a/agent-platform/sdks.mdx +++ b/agent-platform/sdks.mdx @@ -693,7 +693,7 @@ The runtime validates the `Origin` header on every SDK request and rejects reque ### Authentication and verified identity -Public API keys cover anonymous and low-assurance chat. For verified user identity, PHI-safe flows, and customer-issued tokens, configure SDK authentication end to end across Studio, the browser SDK, the customer backend, and the runtime. +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. [Learn more: SDK end-to-end auth setup guide](/agent-platform/sdk/sdk-end-to-end-auth-setup).