LLM Apps SDK

The client-side SDK for Adobe LLM Apps — brings rich, interactive UI into AI conversations.

Adobe LLM Apps let you expose backend capabilities as MCP tools that AI assistants like ChatGPT can call. But tool responses are just structured data — this SDK is what turns that data into a real UI experience. It runs inside the sandbox iframe the host spins up when your tool is invoked, handles the handshake with the host, delivers the tool result to your widget, and wires up two-way communication so user interactions (button clicks, form submissions) feed back into the conversation as new prompts.

For AEM Edge Delivery Services projects, the SDK ships an <aem-embed> custom element that goes one step further: it fetches your EDS page content, bootstraps the full EDS block pipeline inside the iframe, and passes a connected bridge instance to each block's decorate() function — so EDS developers can build widgets using the same block authoring model they already know.

Installation

The SDK supports two use cases depending on your project type.

AEM Edge Delivery Services (EDS) — no build phase

EDS projects serve files directly without a build step. When you run npm install, a postinstall hook automatically copies the necessary files into your project:

npm install @adobe/llmapps-sdk

This places the following files into scripts/ at your project root, always overwriting to stay in sync with the installed version:

scripts/
├── aem-embed.js     ← custom element that loads EDS blocks inside the host iframe
└── llmapps-sdk.js   ← core SDK

Standard TypeScript / bundler project

npm install @adobe/llmapps-sdk

Import via ES modules as usual. TypeScript definition files (.d.ts) are included for full IDE autocomplete.

import { LLMApp } from '@adobe/llmapps-sdk';

Quick Start

AEM Edge Delivery Services (EDS)

After npm install, the files are already in scripts/. The LLM Apps platform handles the rest — it loads aem-embed.js and renders <aem-embed url="..."> inside the host iframe automatically, pointing at your EDS content URL.

aem-embed.js handles the host iframe handshake, fetches the EDS page content (.plain.html), loads each block's CSS and JS, and calls decorate(block, bridge) on each block. The bridge is a fully connected LLMApp instance — your block just uses it directly, no import needed:

// blocks/my-widget/my-widget.js
export default async function decorate(block, bridge) {
  const { structuredContent } = await bridge.toolResult;
  block.innerHTML = renderProducts(structuredContent);

  block.querySelector('button').addEventListener('click', () => {
    bridge.sendMessage('Show me more details');
  });
}

Standard (bundler / TypeScript)

import { LLMApp } from '@adobe/llmapps-sdk';

const app = new LLMApp({
  appInfo: { name: 'MyWidget', version: '1.0.0' },
});

await app.connect();

// Get the structured data your MCP tool returned
const { structuredContent } = await app.toolResult;

// Render it however you want
document.getElementById('root').innerHTML = renderProducts(structuredContent);

Or use the shorthand:

import { createApp } from '@adobe/llmapps-sdk';

const app = await createApp({
  appInfo: { name: 'MyWidget', version: '1.0.0' },
});
const { structuredContent } = await app.toolResult;

API Reference

Constructor

const app = new LLMApp({
  appInfo: { name: 'MyWidget', version: '1.0.0' },
  appCapabilities: {                              // optional
    availableDisplayModes: ['inline', 'fullscreen'],
  },
});

Connection

| Method | Description | |--------|-------------| | await app.connect() | Connect to the host. Returns the app instance. Safe to call outside an iframe (standalone mode). | | app.isConnected | true after a successful handshake with the host. | | app.isEmbedded | true if running inside an iframe. | | app.host | Detected host name: 'chatgpt', 'claude', 'unknown', or null. | | app.destroy() | Disconnect, clean up listeners and observers. |

Receiving Data

| Property | Description | |----------|-------------| | await app.toolResult | Promise that resolves with the tool's response ({ structuredContent, ... }). | | await app.toolInput | Promise that resolves with the tool's input arguments. | | await app.toolCancelled | Promise that resolves if the tool invocation is cancelled. | | app.onToolInputPartial(callback) | Subscribe to partial/streaming tool input. Returns an unsubscribe function. |

Sending Messages

| Method | Description | |--------|-------------| | app.sendMessage(text) | Send a user message back into the conversation (e.g., from a button click). | | app.callTool(name, args) | Invoke another MCP tool by name. | | app.updateModelContext(text) | Update the model's context with additional information. | | app.openLink(url) | Ask the host to open a URL. | | app.log(level, message) | Send a log message to the host ('info', 'warn', 'error'). |

Host Context & Theming

| Property / Method | Description | |-------------------|-------------| | app.hostContext | Object with theme, styles, locale, displayMode, containerDimensions, etc. | | app.hostCapabilities | What the host supports (openLinks, serverTools, logging, ...). | | app.hostInfo | { name, version } of the host. | | app.applyHostStyles(element?) | Inject the host's CSS variables and fonts into the document (or a specific element). | | app.applyContainerDimensions(element?) | Apply the host's sizing constraints. | | app.onContextChange(callback) | Subscribe to host context changes (e.g., theme switch). Returns an unsubscribe function. |

Display & Sizing

| Method | Description | |--------|-------------| | app.requestDisplayMode(mode) | Request 'inline' or 'fullscreen' display. | | app.reportSize(width, height) | Manually report widget dimensions to the host. | | app.autoResize(element?) | Automatically report size changes via ResizeObserver. Returns a cleanup function. |

Resources

| Method | Description | |--------|-------------| | app.readResource(uri) | Read an MCP resource by URI. |

Vendor Extensions

The SDK auto-detects the host and exposes host-specific APIs when available. These are features that go beyond the MCP standard and are only available in specific hosts.

ChatGPT (app.chatgpt)

Available only when running inside ChatGPT (app.chatgpt is null elsewhere):

if (app.chatgpt) {
  // Persist widget state across conversation turns
  app.chatgpt.setWidgetState({ selectedTab: 2 });
  const saved = app.chatgpt.widgetState;

  // File operations
  const { fileId } = await app.chatgpt.uploadFile(myFile);
  const { url } = await app.chatgpt.getFileDownloadUrl({ fileId });

  // UI operations
  await app.chatgpt.requestModal({ uri: 'modal://settings' });
  app.chatgpt.requestClose();
  app.chatgpt.setOpenInAppUrl({ url: 'https://example.com/order/123' });
}

Examples

The examples below use the standard bundler / TypeScript API (import { LLMApp }). For EDS projects, the same methods are available on the bridge object passed to decorate().

Product Carousel with "Tell me more" Button

import { LLMApp } from '@adobe/llmapps-sdk';

const app = new LLMApp({
  appInfo: { name: 'ProductCarousel', version: '1.0.0' },
});
await app.connect();

const { structuredContent } = await app.toolResult;

structuredContent.products.forEach(product => {
  const card = document.createElement('div');
  card.innerHTML = `
    <img src="${product.image}" alt="${product.name}">
    <h3>${product.name}</h3>
    <p>${product.price}</p>
    <button data-id="${product.id}">Tell me more</button>
  `;

  card.querySelector('button').addEventListener('click', () => {
    app.sendMessage(`Show me details for product ${product.id}`);
  });

  document.getElementById('carousel').appendChild(card);
});

Adapting to Host Theme

const app = new LLMApp({
  appInfo: { name: 'ThemedWidget', version: '1.0.0' },
});
await app.connect();

// Apply host CSS variables and fonts
app.applyHostStyles();

// React to theme changes (e.g., light → dark)
app.onContextChange(ctx => {
  document.body.dataset.theme = ctx.theme;
});

Standalone / Development Mode

The SDK works outside of any host too. When not embedded in an iframe, connect() returns immediately in standalone mode, isConnected is false, and toolResult never resolves. This lets you develop and test your widget in a regular browser:

const app = new LLMApp({
  appInfo: { name: 'MyWidget', version: '1.0.0' },
});
await app.connect();

if (app.isConnected) {
  // Running inside a host — use real data
  const { structuredContent } = await app.toolResult;
  render(structuredContent);
} else {
  // Standalone mode — use mock data for development
  render(mockData);
}

Protocol

The SDK implements the MCP Apps specification using JSON-RPC 2.0 over postMessage. See the OpenAI Apps SDK reference for additional protocol details.

License

Copyright 2026 Adobe. All Rights Reserved.

See LICENSE for details.