How an app is wired together app-architecture
An LLM App brings your brand’s services into an AI conversation. For example, a customer asks for coffee recommendations, your app finds matching products, and the assistant shows the results.
In this guide: Learn what each part of your app does, where to make changes, and how those parts work together when someone uses the app.
The three parts of an app
One app can group several related actions, such as Browse products, Compare products, and Find a store. Each action has its own settings, handler, and optional widget. Adding an action does not require another pair of repositories.
An app with interactive widgets has three parts: action settings, handler code, and widget code. You manage the settings in LLM Apps. The handler and widget code live in two separate GitHub repositories.
┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
│ 1. LLM Apps UI │ │ 2. Handler repository │ │ 3. Widget repository │
│ │ │ │ │ │
│ Action descriptions │ │ Connects to your APIs │ │ Widget layout │
│ Required information │ │ Runs the task │ │ Branding and styles │
│ When to use an action │ │ Returns results │ │ Interactive controls │
└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
│ │ │
└───────────────────────────┼───────────────────────────┘
▼
┌───────────────────────────────────────┐
│ Your app in an AI conversation │
│ The action runs and the widget │
│ shows the result. │
└───────────────────────────────────────┘
- Action settings describe the task. They tell the assistant when to use an action and what information it needs. For product search, that information might be a category or search term.
- The handler does the work. It gets data from your systems or carries out a task. A product-search handler, for example, retrieves matching products from your catalog.
- The widget presents the result. It controls what the customer sees and interacts with, such as product cards with names, prices, and buttons.
We recommend adding a widget to each action. A widget gives you control over how results look and how customers interact with them, rather than leaving the presentation to the AI assistant. Text-only responses are also supported.
Where to make changes
Keep the three parts consistent. For example, if you change the information a handler returns, update the widget to display the new result.
What happens in a conversation
After deployment, your app has a connection URL called the MCP server URL. Add this URL to a supported AI platform so the assistant can discover and use your app’s actions.
For an app with a product-search action and widget:
- A customer asks the assistant, Show me coffee pods.
- The assistant uses the action’s description to choose the product-search action.
- The handler gets matching products from the catalog.
- The widget displays the products as cards in the conversation.
- The customer explores the results or asks a follow-up question.
The customer stays in the conversation while your app provides the information or service. Widget support depends on the LLM platform.
Apply and test your changes
Publish widget changes and deploy action changes before testing the updated experience. Follow Deploy your app to deploy to Stage and test the app in a supported LLM platform.
Automatically generated actions start with sample data. Connect the handlers to your real systems and test the app before making it available to customers.