# RunEvent

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.runevent/
> Summary: RunEvent: A single event produced during a run. Events are append-only: they are never updated, only added.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

A single event produced during a run. Events are *append-only*: they are
never updated, only added.

```csharp
public sealed record RunEvent : IEquatable<RunEvent>
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.runevent/">RunEvent</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;RunEvent&gt;</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

[RunEvent.Sequence](/api/tracon.runevent/#Tracon_RunEvent_Sequence) comes from a single writer and increases from 0 within a
run. That is what lets live streaming (SSE) and historical replay share one code
path; a client can resume from the sequence number it reached when a connection
dropped.

Which fields are populated for each event type:

| Value | Fields and meaning |
|---|---|
| [RunEventType.RunStarted](/api/tracon.runeventtype/) | `Text`, the first user message that triggered the run. It is the ONLY place the input text is persisted. |
| [RunEventType.MessageDelta](/api/tracon.runeventtype/) | `Text` |
| [RunEventType.ToolInvoking](/api/tracon.runeventtype/) | [RunEvent.ToolName](/api/tracon.runevent/#Tracon_RunEvent_ToolName), [RunEvent.ToolCallId](/api/tracon.runevent/#Tracon_RunEvent_ToolCallId), [RunEvent.Payload](/api/tracon.runevent/#Tracon_RunEvent_Payload) (arguments) |
| [RunEventType.ToolInvoked](/api/tracon.runeventtype/) | [RunEvent.ToolName](/api/tracon.runevent/#Tracon_RunEvent_ToolName), [RunEvent.ToolCallId](/api/tracon.runevent/#Tracon_RunEvent_ToolCallId), [RunEvent.Payload](/api/tracon.runevent/#Tracon_RunEvent_Payload) (result) |
| [RunEventType.ToolFailed](/api/tracon.runeventtype/) | [RunEvent.ToolName](/api/tracon.runevent/#Tracon_RunEvent_ToolName), [RunEvent.ToolCallId](/api/tracon.runevent/#Tracon_RunEvent_ToolCallId), `Text` (error message) |
| [RunEventType.RunFailed](/api/tracon.runeventtype/) | `Text` (error message) |
| [RunEventType.Custom](/api/tracon.runeventtype/) | [RunEvent.CustomType](/api/tracon.runevent/#Tracon_RunEvent_CustomType), [RunEvent.Payload](/api/tracon.runevent/#Tracon_RunEvent_Payload) (consumer-defined, unexamined) |

## Constructors

### <a id="Tracon_RunEvent__ctor"></a> RunEvent\(\)

```csharp
public RunEvent()
```

## Properties

### <a id="Tracon_RunEvent_CustomType"></a> CustomType

Gets the namespaced type that qualifies a [RunEventType.Custom](/api/tracon.runeventtype/)
event. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for every other event type.

```csharp
public string? CustomType { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_RunEvent_Payload"></a> Payload

Gets the free-form JSON payload that carries tool arguments and results.

```csharp
public string? Payload { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_RunEvent_RunId"></a> RunId

Gets the run the event belongs to.

```csharp
public required Guid RunId { get; init; }
```

#### Property Value

 [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

### <a id="Tracon_RunEvent_Sequence"></a> Sequence

Gets the sequence number within the run. It starts at 0 and increases without gaps.

```csharp
public required long Sequence { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)

### <a id="Tracon_RunEvent_TenantId"></a> TenantId

Gets the EXPECTED tenant of the run the event is written to. Defence in depth.

```csharp
[JsonIgnore]
public string? TenantId { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

#### Remarks

When populated, the store applies the write only if the target run belongs to
that tenant; otherwise the write is dropped and an error is raised. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) no tenant check is made.

This field is not filled from the ambient tenant. `TenantId` may
deliberately override the ambient tenant — that is how workflows and the job
queue work — and filtering by the ambient value would silently drop legitimate
writes. The value is the tenant known to whoever opened the run.

The field is WRITE-side only: it is not stored in a column, it is only the
`WHERE` guard of the write. Reading it back would always give [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), so it is removed from the transport contract with `Serialization.JsonIgnoreAttribute`.

### <a id="Tracon_RunEvent_Text"></a> Text

Gets the text content. Its meaning depends on the event type.

```csharp
public string? Text { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_RunEvent_Timestamp"></a> Timestamp

Gets the moment the event occurred (UTC), in whole microseconds.

```csharp
public required DateTimeOffset Timestamp { get; init; }
```

#### Property Value

 [DateTimeOffset](https://learn.microsoft.com/dotnet/api/system.datetimeoffset)

### <a id="Tracon_RunEvent_ToolCallId"></a> ToolCallId

Gets the tool call id, which separates several calls to the same tool.

```csharp
public string? ToolCallId { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_RunEvent_ToolName"></a> ToolName

Gets the tool name. Populated only on tool events.

```csharp
public string? ToolName { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_RunEvent_Type"></a> Type

Gets the event type.

```csharp
public required RunEventType Type { get; init; }
```

#### Property Value

 [RunEventType](/api/tracon.runeventtype/)

## Methods

### <a id="Tracon_RunEvent_Equals_System_Object_"></a> Equals\(object?\)

```csharp
public override bool Equals(object? obj)
```

#### Parameters

`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_RunEvent_Equals_Tracon_RunEvent_"></a> Equals\(RunEvent?\)

```csharp
public bool Equals(RunEvent? other)
```

#### Parameters

`other` [RunEvent](/api/tracon.runevent/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_RunEvent_GetHashCode"></a> GetHashCode\(\)

```csharp
public override int GetHashCode()
```

#### Returns

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

### <a id="Tracon_RunEvent_ToString"></a> ToString\(\)

```csharp
public override string ToString()
```

#### Returns

 [string](https://learn.microsoft.com/dotnet/api/system.string)

## Operators

### <a id="Tracon_RunEvent_op_Equality_Tracon_RunEvent_Tracon_RunEvent_"></a> operator ==\(RunEvent?, RunEvent?\)

```csharp
public static bool operator ==(RunEvent? left, RunEvent? right)
```

#### Parameters

`left` [RunEvent](/api/tracon.runevent/)?

`right` [RunEvent](/api/tracon.runevent/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_RunEvent_op_Inequality_Tracon_RunEvent_Tracon_RunEvent_"></a> operator \!=\(RunEvent?, RunEvent?\)

```csharp
public static bool operator !=(RunEvent? left, RunEvent? right)
```

#### Parameters

`left` [RunEvent](/api/tracon.runevent/)?

`right` [RunEvent](/api/tracon.runevent/)?

#### Returns

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)