> 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/add-ons/agent.md).

# Agent Runtime

Agent Runtime add-on for configuring and running AI agents with streaming responses.

The Agent Runtime add-on (`Umbraco.AI.Agent`) enables you to configure and run AI agents that can interact with users through streaming responses and execute frontend tools.

## Installation

{% code title="Package Manager Console" %}

```powershell
Install-Package Umbraco.AI.Agent
```

{% endcode %}

Or via .NET CLI:

{% code title="Terminal" %}

```bash
dotnet add package Umbraco.AI.Agent
```

{% endcode %}

## Features

* **Standard Agents** - Configure reusable AI agents with instructions and tool permissions
* **Orchestrated Agents** - Compose multiple agents into workflow pipelines
* **Custom Workflows** - Extensible workflow system for multi-agent orchestration
* **AG-UI Protocol** - Stream responses using the AG-UI event protocol
* **Profile Association** - Link agents to specific AI profiles
* **Context Injection** - Include AI Contexts for brand voice (standard agents)
* **Scopes** - Categorize agents for specific purposes (e.g., copilot)
* **Version History** - Track changes with full rollback support
* **Backoffice Management** - Full UI for managing agents
* **Management API** - RESTful API for agent operations

{% hint style="info" %}
For a chat sidebar with frontend tools and Human-in-the-Loop (HITL) approval, install the [Contextual Copilot](/ai-in-umbraco/add-ons/agent-copilot.md) add-on alongside this package. For a full-section, persisted chat experience instead, install [Copilot Workspace](/ai-in-umbraco/add-ons/copilot-workspace.md).
{% endhint %}

## Quick Start

### 1. Create an Agent

In the backoffice, navigate to the **AI** section > **Agents** and create a new agent:

| Field        | Value                                                                        |
| ------------ | ---------------------------------------------------------------------------- |
| Alias        | `content-assistant`                                                          |
| Name         | Content Assistant                                                            |
| Instructions | `You are a helpful content assistant. Help users write and improve content.` |
| Profile      | (select your chat profile)                                                   |

### 2. Run the Agent

{% code title="AgentRunner.cs" %}

```csharp
public class AgentRunner
{
    private readonly IAIAgentService _agentService;

    public AgentRunner(IAIAgentService agentService)
    {
        _agentService = agentService;
    }

    public async Task RunAsync(HttpResponse response, CancellationToken cancellationToken)
    {
        var agent = await _agentService.GetAgentByAliasAsync("content-assistant", cancellationToken);

        response.ContentType = "text/event-stream";

        var request = new AGUIRunRequest
        {
            ThreadId = Guid.NewGuid().ToString(),
            RunId = Guid.NewGuid().ToString(),
            Messages =
            [
                new AGUIMessage
                {
                    Id = Guid.NewGuid().ToString(),
                    Role = AGUIMessageRole.User,
                    Content = "Help me write a blog post about AI"
                }
            ]
        };

        await foreach (var evt in _agentService.StreamAgentAGUIAsync(
            agent!.Id,
            request,
            frontendTools: null,
            cancellationToken))
        {
            // Write as a single SSE data line; the event type is embedded in the JSON payload.
            var json = JsonSerializer.Serialize(evt, typeof(BaseAGUIEvent));
            await response.WriteAsync($"data: {json}\n\n", cancellationToken);
            await response.Body.FlushAsync(cancellationToken);
        }
    }
}
```

{% endcode %}

### 3. Consume in Frontend

{% code title="agent-event-listener.ts" %}

```typescript
// AG-UI events arrive as a single SSE `data:` line each. The event type is
// embedded in the JSON payload as the `type` property.
const eventSource = new EventSource(
    "/umbraco/ai/management/api/v1/agents/content-assistant/stream-agui",
);

eventSource.addEventListener("message", (e) => {
    const evt = JSON.parse(e.data);
    switch (evt.type) {
        case "TEXT_MESSAGE_CONTENT":
            console.log("Content:", evt.delta);
            break;
        case "RUN_FINISHED":
            eventSource.close();
            break;
    }
});
```

{% endcode %}

## AG-UI Protocol

The Agent Runtime uses the AG-UI (Agent UI) protocol for streaming responses. The protocol defines event types for:

* **Lifecycle events** - `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
* **Text streaming** - `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`
* **Tool calls** - `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`
* **State updates** - `STATE_SNAPSHOT`, `STATE_DELTA`

## Documentation

| Section                                                               | Description                               |
| --------------------------------------------------------------------- | ----------------------------------------- |
| [Concepts](/ai-in-umbraco/add-ons/agent/concepts.md)                  | Agent types, architecture, AG-UI protocol |
| [Getting Started](/ai-in-umbraco/add-ons/agent/getting-started.md)    | Step-by-step setup guide                  |
| [Instructions](/ai-in-umbraco/add-ons/agent/instructions.md)          | Standard agent instruction configuration  |
| [Workflows](/ai-in-umbraco/add-ons/agent/workflows.md)                | Orchestrated agent workflows              |
| [Scopes](/ai-in-umbraco/add-ons/agent/scopes.md)                      | Categorizing agents with scopes           |
| [Permissions](/ai-in-umbraco/add-ons/agent/permissions.md)            | Tool permissions and user group overrides |
| [Streaming](/ai-in-umbraco/add-ons/agent/streaming.md)                | SSE streaming and event handling          |
| [Frontend Client](/ai-in-umbraco/add-ons/agent/frontend-client.md)    | UaiAgentClient for custom agent UIs       |
| [API Reference](/ai-in-umbraco/add-ons/agent/api.md)                  | Management API endpoints                  |
| [Service Reference](/ai-in-umbraco/add-ons/agent/ai-agent-service.md) | IAIAgentService                           |

For Contextual Copilot-specific features:

| Section                                                                  | Description                                |
| ------------------------------------------------------------------------ | ------------------------------------------ |
| [Contextual Copilot](/ai-in-umbraco/add-ons/agent-copilot.md)            | Contextual chat sidebar and tool execution |
| [Frontend Tools](/ai-in-umbraco/add-ons/agent-copilot/frontend-tools.md) | Browser-executable tools                   |
| [Usage](/ai-in-umbraco/add-ons/agent-copilot/copilot.md)                 | Using the chat interface                   |

For Copilot Workspace-specific features:

| Section                                                                | Description                                              |
| ---------------------------------------------------------------------- | -------------------------------------------------------- |
| [Copilot Workspace](/ai-in-umbraco/add-ons/copilot-workspace.md)       | Full-section chat, persisted conversations, and projects |
| [Usage](/ai-in-umbraco/add-ons/copilot-workspace/copilot-workspace.md) | Conversations, projects, and the context panel           |

## Related

* [Add-ons Overview](/ai-in-umbraco/add-ons/add-ons.md) - All add-on packages
* [AI Contexts](/ai-in-umbraco/concepts/contexts.md) - Brand voice and guidelines
* [Profiles](/ai-in-umbraco/concepts/profiles.md) - AI configuration


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/ai-in-umbraco/add-ons/agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.