RunEventCustomTypes

Namespace Tracon · Assembly Tracon.Abstractions.dll

Validation for the CustomType string that qualifies a RunEventType.Custom event.

public static class RunEventCustomTypes

Inheritance

object ← RunEventCustomTypes

Inherited Members

object.GetType(), object.MemberwiseClone(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

Repeats the 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

AGUIToolsIgnored

The RunEventType.Custom 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.

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

Field Value

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.

Content

The RunEventType.Custom 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.

public const string Content = "tracon.content"

Field Value

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 and RunEventCustomTypes.OutputTruncated, the payload follows TraconRunRecordingOptions.RecordToolPayloads: with it off the event stays and Text stays, but Payload is 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.

OutputTruncated

The RunEventType.Custom type of the notice a run writes when the model stopped a plain-text response at its output token limit.

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

Field Value

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 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.

QuotaThreshold

The RunEventType.Custom 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.

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

Field Value

string

Remarks

Falls under 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).

ReservedPrefix

The prefix reserved for Tracon’s own use.

public const string ReservedPrefix = "tracon."

Field Value

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.

ToolInputDeclined

The RunEventType.Custom 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.

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

Field Value

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.

WorkflowEvent

The RunEventType.Custom 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.

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

Field Value

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. A workflow run’s stream sends the event as an event frame like every recorded event.

Methods

IsReserved(string?)

Checks whether customType falls inside the RunEventCustomTypes.ReservedPrefix namespace.

public static bool IsReserved(string? customType)

Parameters

customType string?

The candidate type.

Returns

bool

true if the type is reserved for Tracon.

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.

public static bool IsValidType(string? customType)

Parameters

customType string?

The candidate type.

Returns

bool

true if the type is valid.

Remarks

Uppercase letters are rejected, not normalized — the same reasoning as JobHandlerKeys.IsValidKey. 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.