RunRecordingAgent

Namespace Tracon · Assembly Tracon.Core.dll

Run completion: usage/cost merging, error mapping, and the terminal store write. RunRecordingAgent.CompleteAsync fans out to the root-only notifications in RunRecordingAgent.Notifications.cs, but owns the outcome itself.

public sealed class RunRecordingAgent : DelegatingAIAgent

Inheritance

object ← AIAgent ← DelegatingAIAgent ← RunRecordingAgent

Inherited Members

DelegatingAIAgent.GetService(Type, object?), DelegatingAIAgent.Name, DelegatingAIAgent.Description, AIAgent.GetService(Type, object?), AIAgent.GetService<TService>(object?), AIAgent.CreateSessionAsync(CancellationToken), AIAgent.SerializeSessionAsync(AgentSession, JsonSerializerOptions?, CancellationToken), AIAgent.DeserializeSessionAsync(JsonElement, JsonSerializerOptions?, CancellationToken), AIAgent.RunAsync(AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync(string, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync(ChatMessage, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync(IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(string, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(ChatMessage, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync<T>(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync<T>(string, AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync<T>(ChatMessage, AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync<T>(IEnumerable<ChatMessage>, AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.Id, AIAgent.Name, AIAgent.Description, AIAgent.CurrentRunContext, object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

This is not a Microsoft Agent Framework middleware but a AI.DelegatingAIAgent wrapper. The reason: the MAF middleware chain is specific to one agent, and HarnessAgent adds its own inner decorators. The outer wrapper works the same way on every agent type, the harness included.

Tool calls are read from the AI.FunctionCallContent and AI.FunctionResultContent contents that MAF produces; no separate hook is necessary.

The root span starts here. The wrapper is the outermost decorator (Order = 0), therefore the tracon.run span that it opens collects the spans of the inner wrappers and of the model calls as children. This is the only way to link the run identifier and the trace identifier to each other.

Constructors

RunRecordingAgent(AIAgent, IRunStore, ITenantContext, TraconRunRecordingOptions, ILogger<RunRecordingAgent>, TraconMetrics?, RunTraceCollector?, string?, string?, TimeProvider?, TraconAgentGraphOptions?, int?, bool, IRunPricingResolver?, QuotaEnforcer?, IWebhookPublisher?, IRunCancellationRegistry?, IRunErrorClassifier?, IRunInputStore?, RunSampler?, ContentGuardPipeline?, IRunAttributionContext?, IReadOnlyList<IRunEventSink>?, ToolApprovalPresenterRunner?)

Creates a new recording wrapper.

public RunRecordingAgent(AIAgent innerAgent, IRunStore runStore, ITenantContext tenantContext, TraconRunRecordingOptions options, ILogger<RunRecordingAgent> logger, TraconMetrics? metrics = null, RunTraceCollector? traceCollector = null, string? modelId = null, string? modelProvider = null, TimeProvider? timeProvider = null, TraconAgentGraphOptions? graphOptions = null, int? agentVersion = null, bool includeAgentVersionTag = true, IRunPricingResolver? pricingResolver = null, QuotaEnforcer? quotaEnforcer = null, IWebhookPublisher? webhookPublisher = null, IRunCancellationRegistry? cancellationRegistry = null, IRunErrorClassifier? errorClassifier = null, IRunInputStore? runInputStore = null, RunSampler? runSampler = null, ContentGuardPipeline? contentGuardPipeline = null, IRunAttributionContext? attributionContext = null, IReadOnlyList<IRunEventSink>? sinks = null, ToolApprovalPresenterRunner? approvalPresenterRunner = null)

Parameters

innerAgent AIAgent

The wrapped agent.

runStore IRunStore

The store that the events are written to.

tenantContext ITenantContext

The tenant context.

options TraconRunRecordingOptions

The recording detail settings.

logger ILogger<RunRecordingAgent>

The logger.

metrics TraconMetrics?

The metric instruments. When null, no metric is emitted.

traceCollector RunTraceCollector?

The span collector. When null, no span is written.

modelId string?

The model that the agent is bound to. null when unknown.

modelProvider string?

The model provider that the agent is bound to. It is used only for cost resolution and is not persisted.

timeProvider TimeProvider?

The time source. When null, the system clock is used.

graphOptions TraconAgentGraphOptions?

The call tree limits. When null, the defaults are used.

agentVersion int?

The current definition version that comes from the catalog summary of the agent. null when it is unknown (for example a code agent). On a run that an A/B experiment resolves, TraconRunOptions.AgentVersion overrides it.

includeAgentVersionTag bool

Whether the Tags.AgentVersion tag is added to the span and to the metrics. See TraconObservabilityOptions.IncludeAgentVersionTag.

pricingResolver IRunPricingResolver?

The cost resolver. When null, no cost is calculated.

quotaEnforcer QuotaEnforcer?

The quota accountant. When null, consumption is not counted. Only root runs are counted; child runs are part of the same request and must not be counted twice.

webhookPublisher IWebhookPublisher?

The event publisher. When null, no run.* event is emitted.

cancellationRegistry IRunCancellationRegistry?

The cancellation registry. When null, the run cannot be canceled from outside (POST /api/runs/{id}/cancel).

errorClassifier IRunErrorClassifier?

The error classifier. When null, the error class and the grouping fingerprint are not calculated (RunError.Class/RunError.Fingerprint stay empty).

runInputStore IRunInputStore?

The input store. When null, or when TraconRunRecordingOptions.RecordRunInput is off, the input is not written and the run cannot be replayed.

runSampler RunSampler?

The online evaluation sampler. When null, no run is sampled.

contentGuardPipeline ContentGuardPipeline?

The content guard pipeline. When null, or when ContentGuardPipeline.HasGuards is false, the input is recorded raw. When it is supplied, the input written to the RunStarted event and to IRunInputStore passes through the SAME inspection as the text that Tracon.ContentGuardingChatClient sends to the model — if the two diverge, masked or blocked content stays raw in the durable store.

attributionContext IRunAttributionContext?

The attribution context. When null, the run records no user and no labels — the same outcome as the built-in DefaultRunAttributionContext with no ambient scope open.

sinks IReadOnlyList<IRunEventSink>?

The run event observers. When null or empty, every event goes to runStore only — the identical hot path as before this extension point existed.

approvalPresenterRunner ToolApprovalPresenterRunner?

Resolves the ToolApprovalPresentation of a pending tool call. When null, no presentation is resolved — identical behavior to before IToolApprovalPresenter existed.

Exceptions

ArgumentNullException

When one of the required dependencies is null.

Methods

RunCoreAsync(IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken)

Core implementation of the agent invocation logic with a collection of chat messages.

protected override Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)

Parameters

messages IEnumerable<ChatMessage>

The collection of messages to send to the agent for processing.

session AgentSession?

The conversation session to use for this invocation. If null, a new session will be created. The session will be updated with the input messages and any response messages generated during invocation.

options AgentRunOptions?

Optional configuration parameters for controlling the agent’s invocation behavior.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is CancellationToken.None.

Returns

Task<AgentResponse>

A task that represents the asynchronous operation. The task result contains an AI.AgentResponse with the agent’s output.

Remarks

This is the primary invocation method that implementations must override. It handles collections of messages, allowing for complex conversational scenarios including multi-turn interactions, function calls, and context-rich conversations.

The messages are processed in the order provided and become part of the conversation history. The agent’s response will also be added to session if one is provided.

RunCoreStreamingAsync(IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken)

Core implementation of the agent streaming invocation logic with a collection of chat messages.

protected override IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)

Parameters

messages IEnumerable<ChatMessage>

The collection of messages to send to the agent for processing.

session AgentSession?

The conversation session to use for this invocation. If null, a new session will be created. The session will be updated with the input messages and any response updates generated during invocation.

options AgentRunOptions?

Optional configuration parameters for controlling the agent’s invocation behavior.

cancellationToken CancellationToken

The CancellationToken to monitor for cancellation requests. The default is CancellationToken.None.

Returns

IAsyncEnumerable<AgentResponseUpdate>

An asynchronous enumerable of AI.AgentResponseUpdate instances representing the streaming response.

Remarks

This is the primary streaming invocation method that implementations must override. It provides real-time updates as the agent processes the input and generates its response, enabling more responsive user experiences.

Each AI.AgentResponseUpdate represents a portion of the complete response, allowing consumers to display partial results, implement progressive loading, or provide immediate feedback to users.