# RunEventCustomTypes

> 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.runeventcustomtypes/
> Summary: RunEventCustomTypes: Validation for the CustomType string that qualifies a RunEventType.Custom event.

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

Validation for the `CustomType` string that qualifies a
[RunEventType.Custom](/api/tracon.runeventtype/) event.

```csharp
public static class RunEventCustomTypes
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.runeventcustomtypes/">RunEventCustomTypes</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.memberwiseclone">object.MemberwiseClone()</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

Repeats the [JobHandlerKeys](/api/tracon.jobhandlerkeys/) pattern: a namespaced, lowercase
ASCII string with a reserved prefix Tracon itself never emits, so a
future built-in custom type can never collide with a consumer's own.

## Fields

### <a id="Tracon_RunEventCustomTypes_AGUIToolsIgnored"></a> AGUIToolsIgnored

The [RunEventType.Custom](/api/tracon.runeventtype/) type of the notice a run records when the front end of an AG-UI request
declared tools the agent does not carry as client-side tools.

```csharp
public const string AGUIToolsIgnored = "tracon.agui.tools.ignored"
```

#### Field Value

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

#### Remarks

An AG-UI front end sends all of its tools with every request. Tracon runs only the client-side tools that
are registered in code and named in the agent's definition (`AddClientTool`); the schema comes from the
code, never from the request. A declared tool outside that set is ignored, and this event says so: the model
never saw it.

The payload is a JSON object with `tools`, the ignored names, capped at 50 names of at most 128
characters each. It never carries a schema or a description from the request.

### <a id="Tracon_RunEventCustomTypes_Content"></a> Content

The [RunEventType.Custom](/api/tracon.runeventtype/) type of the event a run writes for model
content that no other event type covers: a hosted tool call or result, a provider
`ErrorContent`, generated or attached data, a file reference, and any content
type Tracon does not know yet.

```csharp
public const string Content = "tracon.content"
```

#### Field Value

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

#### Remarks

`Text` is a short summary such as `web_search call` or `error: rate_limited`.
The payload is a JSON object with a `type` key and metadata, plus one bounded text:
`hosted_tool_call` and `hosted_tool_result` carry `tool`
(`web_search`, `code_interpreter`, `image_generation` or
`mcp_server`) and `callId`; `error` carries `errorCode` and
`message`; `data` carries `mediaType` and `length` in bytes;
`uri` carries `mediaType`; `hosted_file` and
`hosted_vector_store` carry `id`; `unrecognized` carries
`clrType`. It never carries the content itself: no data bytes, no address of
a `uri` (a signed URL can hold a credential), no tool inputs or outputs. The one
free text is the provider's `message` of an `error`, cut at 2 048 characters
(and shorter when `MaxPayloadLength` needs it) so the JSON stays whole.

Unlike [RunEventCustomTypes.QuotaThreshold](/api/tracon.runeventcustomtypes/#Tracon_RunEventCustomTypes_QuotaThreshold) and [RunEventCustomTypes.OutputTruncated](/api/tracon.runeventcustomtypes/#Tracon_RunEventCustomTypes_OutputTruncated), the payload
follows `TraconRunRecordingOptions.RecordToolPayloads`: with it off the event
stays and `Text` stays, but `Payload` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null). Plain
model text and reasoning, tool calls and results, and usage and approval content
keep their own events or accounting and never produce this event. The live stream
of an agent run does not carry it; read it from `GET /api/runs/{id}/events`.

### <a id="Tracon_RunEventCustomTypes_OutputTruncated"></a> OutputTruncated

The [RunEventType.Custom](/api/tracon.runeventtype/) type of the notice a run writes when
the model stopped a plain-text response at its output token limit.

```csharp
public const string OutputTruncated = "tracon.output.truncated"
```

#### Field Value

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

#### Remarks

The run does not fail: a partial text answer is still useful, so the run
keeps its status and this event says the answer is incomplete. A structured
(JSON) response cut off the same way fails its run with
[RunErrorClass.OutputTruncated](/api/tracon.runerrorclass/) instead, because a partial JSON
document has no use.

The payload carries the provider name, what cut the answer off
(`cause`: `output_limit` or `context_window`) and, when the
binding set one, the output token limit. It never carries the response text.
Written only for the agent's own model calls, not for a side-channel call such
as a context summarizer or a loop judge.

The live stream of an agent run (`POST /api/agents/{name}/run` without
`Idempotency-Key`) also carries this event, always: it arrives as a
`custom` frame right before `done`, with the same data
`GET /api/runs/{id}/events` serves. Each recorded event is one frame, so a
harness loop whose iterations were cut sends more than one. No event is
written, and no frame is sent, when run recording is off.

### <a id="Tracon_RunEventCustomTypes_QuotaThreshold"></a> QuotaThreshold

The [RunEventType.Custom](/api/tracon.runeventtype/) type of the quota threshold
notice a run's completion writes into its own event stream when its consumption
crossed the threshold: the root run, or a child run of its call tree.

```csharp
public const string QuotaThreshold = "tracon.quota.threshold"
```

#### Field Value

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

#### Remarks

Falls under [RunEventCustomTypes.ReservedPrefix](/api/tracon.runeventcustomtypes/#Tracon_RunEventCustomTypes_ReservedPrefix): a consumer cannot write an
event under this type, so a client can trust that every event carrying
it came from Tracon itself, not from the agent's own tool code.
Off by default (`TraconQuotaOptions.PublishThresholdToRunStream`).

### <a id="Tracon_RunEventCustomTypes_ReservedPrefix"></a> ReservedPrefix

The prefix reserved for Tracon's own use.

```csharp
public const string ReservedPrefix = "tracon."
```

#### Field Value

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

#### Remarks

A consumer's `CustomType` starting with this prefix is rejected
at write time — not because Tracon ships a built-in custom type
today, but so one could be added later without ever colliding with a
consumer's own.

### <a id="Tracon_RunEventCustomTypes_ToolInputDeclined"></a> ToolInputDeclined

The [RunEventType.Custom](/api/tracon.runeventtype/) type of the event a run writes when an MCP server asked
the user for input in the middle of a tool call and Tracon answered the server with
`decline` instead of asking the user.

```csharp
public const string ToolInputDeclined = "tracon.tool.input.declined"
```

#### Field Value

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

#### Remarks

The payload is a JSON object with `server` (the MCP server's name), `tool` (the
qualified tool name) and `reason`: `no_run` (the request reached the client outside
a tool call that is still running), `url_mode` (the server asked to open an address;
Tracon asks only for form fields), `child_run` (an agent called by another agent cannot
ask the user, the same as for approvals), `no_session` (the run has no `sessionId`,
so the answer has nowhere to go; an OpenAI-compatible Chat Completions call and an MCP tool
call never have one), `no_channel` (the run has a session, but the surface that started
it cannot carry the answer: an A2A task, a Responses call with a conversation, a queued run),
`no_termination` (the tool was not called by the function-invocation loop) or
`mismatch` (the replayed call asked something other than the user was asked). It never
carries the requested fields or any answer. Declining is a complete answer to the server; the
server decides what the tool does next. A request that reaches the client outside any run
(a server on the earlier protocol sends one that way) has no run to hold the event and is
only logged.

### <a id="Tracon_RunEventCustomTypes_WorkflowEvent"></a> WorkflowEvent

The [RunEventType.Custom](/api/tracon.runeventtype/) type of the event a workflow run writes for a
`WorkflowEvent` that Tracon has no event type for, such as a custom event type
an executor of a code workflow raises.

```csharp
public const string WorkflowEvent = "tracon.workflow.event"
```

#### Field Value

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

#### Remarks

`Text` is the CLR type name of the event. The payload is a JSON object with
`eventType` (the full type name), `executorId` when the event type derives
from the framework's executor event, and `data`: the text of a string or chat
message payload (cut at 2 048 characters), or only the type name of any other payload,
never its `ToString`. The payload follows
`TraconRunRecordingOptions.RecordToolPayloads` like [RunEventCustomTypes.Content](/api/tracon.runeventcustomtypes/#Tracon_RunEventCustomTypes_Content). A
workflow run's stream sends the event as an `event` frame like every recorded
event.

## Methods

### <a id="Tracon_RunEventCustomTypes_IsReserved_System_String_"></a> IsReserved\(string?\)

Checks whether `customType` falls inside the
[RunEventCustomTypes.ReservedPrefix](/api/tracon.runeventcustomtypes/#Tracon_RunEventCustomTypes_ReservedPrefix) namespace.

```csharp
public static bool IsReserved(string? customType)
```

#### Parameters

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

The candidate type.

#### Returns

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

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if the type is reserved for Tracon.

### <a id="Tracon_RunEventCustomTypes_IsValidType_System_String_"></a> IsValidType\(string?\)

Checks whether `customType` is a valid custom event
type: 1-128 characters, lowercase ASCII letters, digits, `.`,
`_`, or `-`, starting with a letter or digit.

```csharp
public static bool IsValidType(string? customType)
```

#### Parameters

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

The candidate type.

#### Returns

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

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if the type is valid.

#### Remarks

Uppercase letters are rejected, not normalized — the same reasoning as
[JobHandlerKeys.IsValidKey](/api/tracon.jobhandlerkeys/#Tracon_JobHandlerKeys_IsValidKey_System_String_). A consumer that read back its
own event compares the type ordinally, so allowing case variants would
let `"Contoso.Preview"` and `"contoso.preview"` silently
become two different types.