> 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/19.latest/add-ons/agent/api/stream-agui.md).

# Stream (AG-UI)

Stream AG-UI protocol events as Server-Sent Events.

Runs an agent and streams events using the [AG-UI protocol](https://docs.ag-ui.com/) over Server-Sent Events (SSE). This endpoint is designed for AG-UI-compatible clients such as CopilotKit.

Use [Stream Agent](/ai-in-umbraco/19.latest/add-ons/agent/api/stream.md) if you need a simpler Microsoft.Extensions.AI stream, or [Run Agent](/ai-in-umbraco/19.latest/add-ons/agent/api/run.md) for a non-streaming JSON response.

## Request

```http
POST /umbraco/ai/management/api/v1/agents/{agentIdOrAlias}/stream-agui
```

### Path Parameters

| Parameter        | Type   | Description                                                            |
| ---------------- | ------ | ---------------------------------------------------------------------- |
| `agentIdOrAlias` | string | Agent GUID, alias, or the special value `auto` for automatic selection |

{% hint style="info" %}
Passing the alias `auto` enables automatic agent selection based on the user's prompt and the provided AG-UI context. When using `auto`, the AG-UI context must include a surface.
{% endhint %}

### Request Body

The request body follows the AG-UI `RunAgentInput` shape:

{% code title="AG-UI Run Request" %}

```json
{
    "threadId": "thread-123",
    "runId": "run-456",
    "messages": [
        {
            "id": "msg-1",
            "role": "user",
            "content": "Help me write a blog post about AI"
        }
    ],
    "tools": [
        {
            "name": "insert_content",
            "description": "Insert content at the cursor",
            "parameters": {
                "type": "object",
                "properties": {
                    "content": { "type": "string" }
                },
                "required": ["content"]
            },
            "metadata": { "scope": "content-write", "isDestructive": false }
        }
    ],
    "context": [
        { "description": "surface", "value": "copilot" }
    ],
    "state": null
}
```

{% endcode %}

### Request Properties

| Property         | Type   | Required | Description                                                                                                                  |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `threadId`       | string | Yes      | The conversation thread identifier                                                                                           |
| `runId`          | string | Yes      | The run identifier                                                                                                           |
| `messages`       | array  | Yes      | Conversation messages in AG-UI format                                                                                        |
| `tools`          | array  | No       | Frontend tool definitions available to the agent. Each tool can carry `metadata` with a `scope` and an `isDestructive` flag. |
| `context`        | array  | No       | AG-UI context items (each has `description` and `value`)                                                                     |
| `state`          | object | No       | Current state as JSON                                                                                                        |
| `resume`         | array  | No       | Resume entries for continuing from interrupts. See [Resume Entries](#resume-entries).                                        |
| `forwardedProps` | object | No       | Additional properties forwarded to the agent                                                                                 |

AG-UI message `role` values are: `user`, `assistant`, `system`, `tool`, or `developer`.

#### Resume Entries

When a run stops for an interrupt, such as a tool call waiting for approval, the next request resumes it. Send one entry in `resume` for each open interrupt:

| Property      | Type   | Required | Description                                                                                                                                                  |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `interruptId` | string | Yes      | The `id` of the interrupt the entry answers                                                                                                                  |
| `status`      | string | Yes      | `resolved` when the user responded, or `cancelled` when they didn't                                                                                          |
| `payload`     | object | No       | The response when `status` is `resolved`. For a tool approval, `{ "approved": true }` or `{ "approved": false }`. For a frontend tool call, the tool result. |

{% code title="Resume after an approval" %}

```json
"resume": [
    {
        "interruptId": "approval:call_123",
        "status": "resolved",
        "payload": { "approved": true }
    }
]
```

{% endcode %}

The server reads resume entries from `resume` only. Entries sent in `forwardedProps.resume` are ignored.

#### Forwarded Properties

`forwardedProps` accepts the following optional property:

| Property          | Type   | Description                                                                                 |
| ----------------- | ------ | ------------------------------------------------------------------------------------------- |
| `previousAgentId` | string | The ID of the agent picked on the previous turn. Only read when `agentIdOrAlias` is `auto`. |

The server treats `previousAgentId` as an untrusted hint. A value that is missing, not a GUID, or not an active, in-scope agent is ignored. An ignored value never causes an error response. Agent selectors receive the resolved agent as `PreviousAgent`. For more information, see [Agent Selection](/ai-in-umbraco/19.latest/extending/agent-selection.md).

## Response

The endpoint returns `Content-Type: text/event-stream`. Each event is emitted as a single SSE `data:` line containing the JSON-serialized event, followed by a blank line. There is no `event:` line - the event type is embedded in the JSON payload as a `type` discriminator:

```
data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-1","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":"Here's a"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-1","delta":" blog post"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-1"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}
```

### Event Types

Event type values are UPPER\_SNAKE\_CASE and match the official AG-UI specification.

| Event type             | Category  | Description                                                |
| ---------------------- | --------- | ---------------------------------------------------------- |
| `RUN_STARTED`          | Lifecycle | Agent run has begun                                        |
| `RUN_FINISHED`         | Lifecycle | Agent run completed successfully                           |
| `RUN_ERROR`            | Lifecycle | Agent run failed                                           |
| `STEP_STARTED`         | Lifecycle | A step within the run has begun                            |
| `STEP_FINISHED`        | Lifecycle | A step within the run has finished                         |
| `TEXT_MESSAGE_START`   | Message   | Beginning of a text message                                |
| `TEXT_MESSAGE_CONTENT` | Message   | Text content delta                                         |
| `TEXT_MESSAGE_END`     | Message   | End of a text message                                      |
| `TEXT_MESSAGE_CHUNK`   | Message   | Combined message chunk                                     |
| `TOOL_CALL_START`      | Tools     | Tool call initiated                                        |
| `TOOL_CALL_ARGS`       | Tools     | Tool arguments delta                                       |
| `TOOL_CALL_END`        | Tools     | Tool call arguments complete                               |
| `TOOL_CALL_RESULT`     | Tools     | Tool result                                                |
| `TOOL_CALL_CHUNK`      | Tools     | Combined tool call chunk                                   |
| `STATE_SNAPSHOT`       | State     | Full state snapshot                                        |
| `STATE_DELTA`          | State     | State change (JSON Patch)                                  |
| `MESSAGES_SNAPSHOT`    | State     | Full messages snapshot                                     |
| `ACTIVITY_SNAPSHOT`    | Activity  | Activity snapshot                                          |
| `ACTIVITY_DELTA`       | Activity  | Activity change                                            |
| `CUSTOM`               | Special   | Custom event (used for e.g. `agent_selected` in auto mode) |
| `RAW`                  | Special   | Passthrough raw event                                      |

### Auto Agent Selection

When `agentIdOrAlias` is `auto`, the stream is prepended with a `CUSTOM` event named `agent_selected` describing which agent was chosen:

```
data: {"type":"CUSTOM","name":"agent_selected","value":{"agentId":"3fa85f64-...","agentName":"Content Assistant","agentAlias":"content-assistant","selectorId":"llm"}}
```

| Field        | Type   | Description                                                                                                  |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------ |
| `agentId`    | string | The selected agent's ID                                                                                      |
| `agentName`  | string | The selected agent's name                                                                                    |
| `agentAlias` | string | The selected agent's alias                                                                                   |
| `selectorId` | string | The selector that picked the agent: `llm`, `sticky`, `only-candidate`, `fallback`, or a custom selector's ID |
| `reason`     | string | The selector's explanation for the pick. Omitted when the selector gave no reason.                           |

To keep track of the previous pick, send the `agentId` back as `forwardedProps.previousAgentId` on the next request.

### Error Responses

HTTP-level errors are returned as problem details (not as SSE). Errors that occur during streaming are emitted as `RUN_ERROR` events in the stream.

{% code title="404 Not Found" %}

```json
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
    "title": "AIAgent not found",
    "status": 404,
    "detail": "The specified agent could not be found."
}
```

{% endcode %}

When the AG-UI context declares a surface, a named agent must be available on it. The agent must be active, list that surface in its `SurfaceIds`, and pass the agent's scope rules. Otherwise the request fails before streaming starts. Requests without a surface skip this check.

{% code title="404 Not Found (agent not available on the surface)" %}

```json
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
    "title": "AIAgent not available in this context",
    "status": 404,
    "detail": "Agent 'content-assistant' is not available in the 'copilot' surface for the current context."
}
```

{% endcode %}

{% code title="400 Bad Request (auto mode without surface)" %}

```json
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Surface is required for auto agent selection",
    "status": 400,
    "detail": "The AG-UI context must include a surface to use 'auto' agent selection."
}
```

{% endcode %}

## Examples

### Consume with cURL

{% code title="cURL" %}

```bash
curl -N -X POST "https://your-site.com/umbraco/ai/management/api/v1/agents/content-assistant/stream-agui" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "threadId": "thread-123",
    "runId": "run-456",
    "messages": [
      { "id": "msg-1", "role": "user", "content": "Help me write a title" }
    ]
  }'
```

{% endcode %}

## Related

* [Run Agent](/ai-in-umbraco/19.latest/add-ons/agent/api/run.md) - Non-streaming JSON response
* [Stream Agent](/ai-in-umbraco/19.latest/add-ons/agent/api/stream.md) - Microsoft.Extensions.AI SSE stream
* [Streaming](/ai-in-umbraco/19.latest/add-ons/agent/streaming.md) - AG-UI event handling details
* [Frontend Tools](/ai-in-umbraco/19.latest/add-ons/agent/frontend-tools.md) - Tool definitions


---

# 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/19.latest/add-ons/agent/api/stream-agui.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.