> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/17.latest/frontend/frontend.md).

# Overview

Umbraco.AI provides TypeScript APIs for integrating AI capabilities into custom backoffice elements. The frontend APIs work within the Umbraco backoffice context.

## Package

The AI APIs are exported from the Umbraco.AI client package:

{% code title="Import" %}

```typescript
import { UaiChatController, UaiChatMessage, UaiChatResult } from "@umbraco-ai/core";
```

{% endcode %}

## Quick Start

{% code title="Using Chat in a Custom Element" %}

```typescript
import { LitElement, html } from "lit";
import { customElement, state } from "lit/decorators.js";
import { UaiChatController, UaiChatMessage, UaiChatResult } from "@umbraco-ai/core";

@customElement("my-ai-element")
export class MyAIElement extends LitElement {
    #chatController = new UaiChatController(this);

    @state()
    private _response?: string;

    @state()
    private _loading = false;

    async #handleSubmit() {
        this._loading = true;

        const messages: UaiChatMessage[] = [{ role: "user", content: "Hello, can you help me?" }];

        const { data, error } = await this.#chatController.complete(messages);

        if (data) {
            this._response = data.message.content;
        } else {
            console.error("Chat error:", error);
        }

        this._loading = false;
    }

    render() {
        return html`
            <button @click=${this.#handleSubmit} ?disabled=${this._loading}>
                ${this._loading ? "Loading..." : "Ask AI"}
            </button>
            ${this._response ? html`<p>${this._response}</p>` : ""}
        `;
    }
}
```

{% endcode %}

## Key Concepts

### Controller Pattern

`UaiChatController` follows the Umbraco backoffice controller pattern. It requires a controller host (typically the element itself) for lifecycle management:

{% code title="Controller Initialization" %}

```typescript
class MyElement extends LitElement {
    // Controller is created with 'this' as the host
    #chatController = new UaiChatController(this);
}
```

{% endcode %}

The controller handles:

* API communication with the Management API
* Request lifecycle management
* Automatic cleanup on element disconnect

### Profile Selection

Specify which AI profile to use via `profileIdOrAlias`:

{% code title="Profile Selection" %}

```typescript
// Use default chat profile
await controller.complete(messages);

// Use specific profile by alias
await controller.complete(messages, { profileIdOrAlias: "content-assistant" });

// Use specific profile by ID
await controller.complete(messages, { profileIdOrAlias: "3fa85f64-5717-4562-b3fc-2c963f66afa6" });
```

{% endcode %}

### Cancellation

Pass an `AbortSignal` to cancel requests:

{% code title="Cancellation" %}

```typescript
const abortController = new AbortController();

// Start the request
const promise = controller.complete(messages, { signal: abortController.signal });

// Later, to cancel:
abortController.abort();
```

{% endcode %}

## In This Section

{% content-ref url="/pages/d7Qu4WdUPHddT2D4P2c3" %}
[Chat Controller](/ai-in-umbraco/17.latest/frontend/chat-controller.md)
{% endcontent-ref %}

{% content-ref url="/pages/FPbDvdfsrt8RDycDaZ88" %}
[Embeddings Controller](/ai-in-umbraco/17.latest/frontend/embeddings-controller.md)
{% endcontent-ref %}

{% content-ref url="/pages/tDIrWCT24wTWVT0LXozI" %}
[Speech-to-Text Controller](/ai-in-umbraco/17.latest/frontend/speech-to-text-controller.md)
{% endcontent-ref %}

{% content-ref url="/pages/wiRKz5Od5hhOtGdu1VbL" %}
[Tool Controller](/ai-in-umbraco/17.latest/frontend/tool-controller.md)
{% endcontent-ref %}

{% content-ref url="/pages/jWBtkW61GN7UPWhuGCNx" %}
[Chat Repository](/ai-in-umbraco/17.latest/frontend/chat-repository.md)
{% endcontent-ref %}

{% content-ref url="/pages/AJlpWKJOXaASzUGTDdRI" %}
[Types](/ai-in-umbraco/17.latest/frontend/types.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/ai-in-umbraco/17.latest/frontend/frontend.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.