# Agent Runtime

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 the **Copilot chat sidebar** with frontend tools and HITL approval, install the [Agent Copilot](/ai-in-umbraco/add-ons/agent-copilot.md) add-on alongside this package.
{% 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 Copilot-specific features:

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

## 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.