> 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/reference/services/ai-chat-service.md).

# IAIChatService

The primary service for performing chat completions. Acts as a thin layer over Microsoft.Extensions.AI, adding Umbraco-specific features like profiles and middleware.

## Namespace

{% code title="Namespace" %}

```csharp
using Umbraco.AI.Core.Chat;
using Umbraco.AI.Core.InlineChat;
using Microsoft.Extensions.AI;
```

{% endcode %}

## Interface

{% code title="IAIChatService" %}

```csharp
public interface IAIChatService
{
    Task<ChatResponse> GetChatResponseAsync(
        Action<AIChatBuilder> configure,
        IEnumerable<ChatMessage> messages,
        CancellationToken cancellationToken = default);

    IAsyncEnumerable<ChatResponseUpdate> StreamChatResponseAsync(
        Action<AIChatBuilder> configure,
        IEnumerable<ChatMessage> messages,
        CancellationToken cancellationToken = default);

    Task<IChatClient> CreateChatClientAsync(
        Action<AIChatBuilder> configure,
        CancellationToken cancellationToken = default);
}
```

{% endcode %}

## AIChatBuilder

All methods accept an `Action<AIChatBuilder>` to configure the request. The builder provides the following fluent methods:

| Method                                                                       | Description                                                   |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `.WithAlias(string alias)`                                                   | **Required.** Sets an alias for auditing and telemetry.       |
| `.WithName(string name)`                                                     | Sets a display name for telemetry purposes.                   |
| `.WithDescription(string? description)`                                      | Sets a description for telemetry purposes.                    |
| `.WithProfile(Guid profileId)`                                               | Selects a profile by ID. Uses default if omitted.             |
| `.WithProfile(string profileAlias)`                                          | Selects a profile by alias.                                   |
| `.WithChatOptions(ChatOptions options)`                                      | Overrides profile defaults for temperature, max tokens, etc.  |
| `.WithGuardrails(params Guid[] guardrailIds)`                                | Applies guardrails by ID.                                     |
| `.WithGuardrails(params string[] guardrailAliases)`                          | Applies guardrails by alias.                                  |
| `.WithContextItems(IEnumerable<AIRequestContextItem> contextItems)`          | Attaches context items to the request.                        |
| `.WithOutputSchema(AIOutputSchema schema)`                                   | Sets a structured output schema for the response.             |
| `.WithAdditionalProperties(IReadOnlyDictionary<string, object?> properties)` | Attaches additional properties to the request.                |
| `.AsPassThrough()`                                                           | Marks the request as pass-through (bypasses some processing). |

{% code title="Builder example" %}

```csharp
var response = await _chatService.GetChatResponseAsync(
    chat => chat
        .WithAlias("my-summarizer")
        .WithProfile("default-chat")
        .WithChatOptions(new ChatOptions { Temperature = 0.7f }),
    messages,
    cancellationToken);
```

{% endcode %}

## Methods

### GetChatResponseAsync

Performs a chat completion and returns the full response.

{% code title="Signature" %}

```csharp
Task<ChatResponse> GetChatResponseAsync(
    Action<AIChatBuilder> configure,
    IEnumerable<ChatMessage> messages,
    CancellationToken cancellationToken = default);
```

{% endcode %}

| Parameter           | Type                       | Description                                         |
| ------------------- | -------------------------- | --------------------------------------------------- |
| `configure`         | `Action<AIChatBuilder>`    | Builder action to set alias, profile, options, etc. |
| `messages`          | `IEnumerable<ChatMessage>` | The conversation messages                           |
| `cancellationToken` | `CancellationToken`        | Cancellation token                                  |

**Returns**: `ChatResponse` with the assistant's message, usage stats, and finish reason.

{% code title="Example" %}

```csharp
var messages = new[]
{
    new ChatMessage(ChatRole.System, "You are a helpful assistant."),
    new ChatMessage(ChatRole.User, "What is Umbraco?")
};

var response = await _chatService.GetChatResponseAsync(
    chat => chat.WithAlias("my-assistant"),
    messages);

Console.WriteLine(response.Message.Text);
Console.WriteLine($"Tokens: {response.Usage?.TotalTokenCount}");
```

{% endcode %}

### StreamChatResponseAsync

Performs a streaming chat completion, yielding updates as they arrive.

{% code title="Signature" %}

```csharp
IAsyncEnumerable<ChatResponseUpdate> StreamChatResponseAsync(
    Action<AIChatBuilder> configure,
    IEnumerable<ChatMessage> messages,
    CancellationToken cancellationToken = default);
```

{% endcode %}

| Parameter           | Type                       | Description                                         |
| ------------------- | -------------------------- | --------------------------------------------------- |
| `configure`         | `Action<AIChatBuilder>`    | Builder action to set alias, profile, options, etc. |
| `messages`          | `IEnumerable<ChatMessage>` | The conversation messages                           |
| `cancellationToken` | `CancellationToken`        | Cancellation token                                  |

**Returns**: `IAsyncEnumerable<ChatResponseUpdate>` yielding content chunks.

{% code title="Example" %}

```csharp
var messages = new[]
{
    new ChatMessage(ChatRole.User, "Write a story about a robot.")
};

await foreach (var update in _chatService.StreamChatResponseAsync(
    chat => chat.WithAlias("story-writer"),
    messages))
{
    Console.Write(update.Text);
}
```

{% endcode %}

### CreateChatClientAsync

Creates a configured `IChatClient` for advanced scenarios.

{% code title="Signature" %}

```csharp
Task<IChatClient> CreateChatClientAsync(
    Action<AIChatBuilder> configure,
    CancellationToken cancellationToken = default);
```

{% endcode %}

| Parameter           | Type                    | Description                                         |
| ------------------- | ----------------------- | --------------------------------------------------- |
| `configure`         | `Action<AIChatBuilder>` | Builder action to set alias, profile, options, etc. |
| `cancellationToken` | `CancellationToken`     | Cancellation token                                  |

**Returns**: Configured `IChatClient` with middleware applied.

{% code title="Example" %}

```csharp
// Create client for advanced usage
var client = await _chatService.CreateChatClientAsync(
    chat => chat.WithAlias("advanced-client").WithProfile("default-chat"));

// Use M.E.AI methods directly
var response = await client.GetResponseAsync(
    messages,
    new ChatOptions { Temperature = 0.5f });
```

{% endcode %}

## ChatOptions

Profile settings can be overridden via `ChatOptions`:

{% code title="ChatOptions" %}

```csharp
var options = new ChatOptions
{
    Temperature = 0.7f,
    MaxOutputTokens = 2000,
    StopSequences = new[] { "END" }
};

var response = await _chatService.GetChatResponseAsync(
    chat => chat
        .WithAlias("creative-chat")
        .WithChatOptions(options),
    messages);
```

{% endcode %}

## Related Types

* `ChatMessage` - Message in a conversation (M.E.AI)
* `ChatResponse` - Completion response (M.E.AI)
* `ChatResponseUpdate` - Streaming chunk (M.E.AI)
* `ChatOptions` - Request options (M.E.AI)


---

# 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/reference/services/ai-chat-service.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.