> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ag-ui.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> Documentation for the protocol types in AGUI.Abstractions

# AGUI.Abstractions Types

`AGUI.Abstractions` contains the protocol model shared by AG-UI .NET clients
and servers. The JSON wire names are camel-case and match the AG-UI protocol.

## RunAgentInput

`RunAgentInput` is the request payload for running an agent. In the HTTP API, it
is the body of the `POST` request.

```csharp theme={null}
using System.Text.Json;
using AGUI.Abstractions;

var input = new RunAgentInput
{
    ThreadId = "thread-1",
    RunId = "run-1",
    Messages =
    [
        new AGUIUserMessage
        {
            Id = "msg-1",
            Content = "Hello!"
        }
    ],
    Tools =
    [
        new AGUITool
        {
            Name = "get_weather",
            Description = "Get the weather for a city",
            Parameters = JsonDocument.Parse("""
                {
                  "type": "object",
                  "properties": {
                    "city": { "type": "string" }
                  },
                  "required": ["city"]
                }
                """).RootElement.Clone()
        }
    ]
};
```

| C# property           | JSON field       | Type                  | Description                                           |
| --------------------- | ---------------- | --------------------- | ----------------------------------------------------- |
| `ThreadId`            | `threadId`       | `string`              | ID of the conversation thread                         |
| `RunId`               | `runId`          | `string`              | ID of the current run                                 |
| `ParentRunId`         | `parentRunId`    | `string?`             | Optional lineage pointer for branching or time travel |
| `Messages`            | `messages`       | `IList<AGUIMessage>`  | Conversation messages                                 |
| `Tools`               | `tools`          | `IList<AGUITool>?`    | Tools available to the agent                          |
| `State`               | `state`          | `JsonElement?`        | Current frontend or agent state                       |
| `Resume`              | `resume`         | `IList<AGUIResume>?`  | Resume payloads for interrupted runs                  |
| `Context`             | `context`        | `IList<AGUIContext>?` | Context objects provided to the agent                 |
| `ForwardedProperties` | `forwardedProps` | `JsonElement`         | Additional properties forwarded by the client         |

## Message Types

Messages form a closed hierarchy rooted at `AGUIMessage`. The base type carries
only the fields shared by every role: `Id` and `Role`. Role-specific properties
such as `content`, `name`, `encryptedValue`, `toolCalls`, and `toolCallId` are
declared on the sealed role classes.

```csharp theme={null}
public abstract class AGUIMessage
{
    public string? Id { get; set; } // "id"
    public abstract string Role { get; } // "role"
}
```

### Roles

The `Role` property returns one of the lowercase constants in `AGUIRoles`:

| Constant              | JSON value  |
| --------------------- | ----------- |
| `AGUIRoles.Developer` | `developer` |
| `AGUIRoles.System`    | `system`    |
| `AGUIRoles.Assistant` | `assistant` |
| `AGUIRoles.User`      | `user`      |
| `AGUIRoles.Tool`      | `tool`      |
| `AGUIRoles.Activity`  | `activity`  |
| `AGUIRoles.Reasoning` | `reasoning` |

### AGUIDeveloperMessage

```csharp theme={null}
var message = new AGUIDeveloperMessage
{
    Id = "dev-1",
    Content = "Prefer concise answers.",
    Name = "policy"
};
```

| C# property      | JSON field       | Type          | Description                     |
| ---------------- | ---------------- | ------------- | ------------------------------- |
| `Id`             | `id`             | `string?`     | Message ID                      |
| `Role`           | `role`           | `"developer"` | Fixed role discriminator        |
| `Content`        | `content`        | `string`      | Developer instruction content   |
| `Name`           | `name`           | `string?`     | Optional sender name            |
| `EncryptedValue` | `encryptedValue` | `string?`     | Optional opaque encrypted value |

### AGUISystemMessage

```csharp theme={null}
var message = new AGUISystemMessage
{
    Id = "sys-1",
    Content = "You are a helpful assistant.",
    Name = "system"
};
```

| C# property      | JSON field       | Type       | Description                     |
| ---------------- | ---------------- | ---------- | ------------------------------- |
| `Id`             | `id`             | `string?`  | Message ID                      |
| `Role`           | `role`           | `"system"` | Fixed role discriminator        |
| `Content`        | `content`        | `string`   | System instruction content      |
| `Name`           | `name`           | `string?`  | Optional sender name            |
| `EncryptedValue` | `encryptedValue` | `string?`  | Optional opaque encrypted value |

### AGUIAssistantMessage

```csharp theme={null}
var message = new AGUIAssistantMessage
{
    Id = "asst-1",
    Content = "I can help with that.",
    ToolCalls =
    [
        new AGUIToolCall
        {
            Id = "call-1",
            Function = new AGUIToolCallFunction
            {
                Name = "get_weather",
                Arguments = """{"city":"Seattle"}"""
            }
        }
    ]
};
```

| C# property      | JSON field       | Type                   | Description                     |
| ---------------- | ---------------- | ---------------------- | ------------------------------- |
| `Id`             | `id`             | `string?`              | Message ID                      |
| `Role`           | `role`           | `"assistant"`          | Fixed role discriminator        |
| `Content`        | `content`        | `string?`              | Optional assistant text         |
| `Name`           | `name`           | `string?`              | Optional assistant name         |
| `EncryptedValue` | `encryptedValue` | `string?`              | Optional opaque encrypted value |
| `ToolCalls`      | `toolCalls`      | `IList<AGUIToolCall>?` | Tool calls made in the message  |

### AGUIUserMessage

`AGUIUserMessage.Content` is an `AGUIUserContent` value. It models the AG-UI
wire union `string | InputContent[]`.

```csharp theme={null}
var textOnly = new AGUIUserMessage
{
    Id = "user-1",
    Content = "Summarize this image."
};

AGUIInputContent textPart = new AGUITextInputContent
{
    Text = "What is shown here?"
};

AGUIInputContent imagePart = new AGUIImageInputContent
{
    Source = new AGUIInputContentUrlSource
    {
        Value = "https://example.com/screen.png",
        MimeType = "image/png"
    }
};

var multimodal = new AGUIUserMessage
{
    Id = "user-2",
    Content = [textPart, imagePart]
};
```

`AGUIUserContent` supports implicit conversions from `string`,
`List<AGUIInputContent>`, and `AGUIInputContent[]`. It also has a collection
builder, so C# collection expressions work. For reading, it implements
`IReadOnlyList<AGUIInputContent>`; a plain string is exposed as one
`AGUITextInputContent` part.

| C# property      | JSON field       | Type              | Description                            |
| ---------------- | ---------------- | ----------------- | -------------------------------------- |
| `Id`             | `id`             | `string?`         | Message ID                             |
| `Role`           | `role`           | `"user"`          | Fixed role discriminator               |
| `Content`        | `content`        | `AGUIUserContent` | Plain text or ordered multimodal parts |
| `Name`           | `name`           | `string?`         | Optional user name                     |
| `EncryptedValue` | `encryptedValue` | `string?`         | Optional opaque encrypted value        |

See [Multimodal Inputs](/sdk/dotnet/abstractions/multimodal-inputs) for the
`AGUIInputContent` hierarchy.

### AGUIToolMessage

```csharp theme={null}
var message = new AGUIToolMessage
{
    Id = "tool-msg-1",
    ToolCallId = "call-1",
    Content = """{"temperature":72}"""
};
```

| C# property      | JSON field       | Type      | Description                              |
| ---------------- | ---------------- | --------- | ---------------------------------------- |
| `Id`             | `id`             | `string?` | Message ID                               |
| `Role`           | `role`           | `"tool"`  | Fixed role discriminator                 |
| `Content`        | `content`        | `string`  | Tool result content                      |
| `ToolCallId`     | `toolCallId`     | `string`  | ID of the tool call this message answers |
| `Error`          | `error`          | `string?` | Optional error message                   |
| `EncryptedValue` | `encryptedValue` | `string?` | Optional opaque encrypted value          |

### AGUIActivityMessage

```csharp theme={null}
var message = new AGUIActivityMessage
{
    Id = "activity-1",
    ActivityType = "PLAN",
    Content = JsonDocument.Parse("""{"status":"running"}""").RootElement.Clone()
};
```

| C# property    | JSON field     | Type          | Description                                   |
| -------------- | -------------- | ------------- | --------------------------------------------- |
| `Id`           | `id`           | `string?`     | Message ID                                    |
| `Role`         | `role`         | `"activity"`  | Fixed role discriminator                      |
| `ActivityType` | `activityType` | `string`      | Activity discriminator for renderer selection |
| `Content`      | `content`      | `JsonElement` | Structured activity payload                   |

### AGUIReasoningMessage

```csharp theme={null}
var message = new AGUIReasoningMessage
{
    Id = "reasoning-1",
    Content = "Thinking through the problem..."
};
```

| C# property      | JSON field       | Type          | Description                     |
| ---------------- | ---------------- | ------------- | ------------------------------- |
| `Id`             | `id`             | `string?`     | Message ID                      |
| `Role`           | `role`           | `"reasoning"` | Fixed role discriminator        |
| `Content`        | `content`        | `string`      | Reasoning text                  |
| `EncryptedValue` | `encryptedValue` | `string?`     | Optional opaque encrypted value |

### AGUIToolCall

```csharp theme={null}
var call = new AGUIToolCall
{
    Id = "call-1",
    Type = "function",
    Function = new AGUIToolCallFunction
    {
        Name = "get_weather",
        Arguments = """{"city":"Seattle"}"""
    }
};
```

| C# property      | JSON field       | Type                   | Description                              |
| ---------------- | ---------------- | ---------------------- | ---------------------------------------- |
| `Id`             | `id`             | `string`               | Tool call ID                             |
| `Type`           | `type`           | `string`               | Tool call type; defaults to `"function"` |
| `Function`       | `function`       | `AGUIToolCallFunction` | Function name and JSON-encoded arguments |
| `EncryptedValue` | `encryptedValue` | `string?`              | Optional opaque encrypted value          |

`AGUIToolCallFunction` has `Name` (`name`) and `Arguments` (`arguments`).

## Context

`AGUIContext` represents a piece of contextual information provided to an agent.

```csharp theme={null}
var context = new AGUIContext
{
    Description = "Current customer tier",
    Value = "enterprise"
};
```

| C# property   | JSON field    | Type     | Description                                |
| ------------- | ------------- | -------- | ------------------------------------------ |
| `Description` | `description` | `string` | Description of what the context represents |
| `Value`       | `value`       | `string` | Context value                              |

## Tool

`AGUITool` defines a tool that an agent can call.

```csharp theme={null}
var tool = new AGUITool
{
    Name = "get_weather",
    Description = "Get the weather for a city",
    Parameters = JsonDocument.Parse("""
        {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
        """).RootElement.Clone(),
    Metadata = JsonDocument.Parse("""{"ui":"compact"}""").RootElement.Clone()
};
```

| C# property   | JSON field    | Type           | Description                         |
| ------------- | ------------- | -------------- | ----------------------------------- |
| `Name`        | `name`        | `string`       | Tool name                           |
| `Description` | `description` | `string?`      | Optional tool description           |
| `Parameters`  | `parameters`  | `JsonElement`  | JSON Schema for the tool parameters |
| `Metadata`    | `metadata`    | `JsonElement?` | Optional arbitrary tool metadata    |

## State

State is represented as `JsonElement?` on `RunAgentInput.State` and as
`JsonElement` payloads in `StateSnapshotEvent` and `StateDeltaEvent`.

```csharp theme={null}
input.State = JsonDocument.Parse("""{"draft":"hello"}""").RootElement.Clone();
```

The schema of the state is defined by the agent. The protocol only carries it.

## AgentCapabilities

`AgentCapabilities` is a structured declaration that an agent can expose so
clients can discover what it supports. All fields are optional.

```csharp theme={null}
var capabilities = new AgentCapabilities
{
    Identity = new IdentityCapabilities
    {
        Name = "Support Agent",
        Version = "1.0.0"
    },
    Transport = new TransportCapabilities
    {
        Streaming = true,
        Resumable = true
    },
    Tools = new ToolsCapabilities
    {
        Supported = true,
        ClientProvided = true
    },
    Multimodal = new MultimodalCapabilities
    {
        Input = new MultimodalInputCapabilities
        {
            Image = true,
            Audio = true,
            Pdf = true
        }
    }
};
```

| C# property      | JSON field       | Type                            | Description                                                            |
| ---------------- | ---------------- | ------------------------------- | ---------------------------------------------------------------------- |
| `Identity`       | `identity`       | `IdentityCapabilities?`         | Agent identity and metadata                                            |
| `Transport`      | `transport`      | `TransportCapabilities?`        | Streaming, websocket, binary, push, and resumability support           |
| `Tools`          | `tools`          | `ToolsCapabilities?`            | Tool support and tool-calling configuration                            |
| `Output`         | `output`         | `OutputCapabilities?`           | Structured output and supported MIME types                             |
| `State`          | `state`          | `StateCapabilities?`            | Snapshot, delta, memory, and persistence support                       |
| `MultiAgent`     | `multiAgent`     | `MultiAgentCapabilities?`       | Delegation, handoffs, and sub-agent information                        |
| `Reasoning`      | `reasoning`      | `ReasoningCapabilities?`        | Reasoning, streaming, and encrypted reasoning support                  |
| `Multimodal`     | `multimodal`     | `MultimodalCapabilities?`       | Multimodal input and output support                                    |
| `Execution`      | `execution`      | `ExecutionCapabilities?`        | Code execution and iteration/time limits                               |
| `HumanInTheLoop` | `humanInTheLoop` | `HumanInTheLoopCapabilities?`   | Approvals, interventions, feedback, interrupts, and approve-with-edits |
| `Custom`         | `custom`         | `IDictionary<string, object?>?` | Integration-specific capabilities                                      |

See [Capabilities](/concepts/capabilities) for protocol-level concepts and
usage patterns.

## Serialization

All protocol types are registered in `AGUIJsonSerializerContext`, a
source-generated `JsonSerializerContext`. Use it when serializing protocol
types in AOT-sensitive code.

```csharp theme={null}
var json = JsonSerializer.Serialize(
    input,
    AGUIJsonSerializerContext.Default.RunAgentInput);
```