ChildAgentInvoker

Namespace Tracon · Assembly Tracon.Core.dll

Wraps a sub-agent an agent may call; enforces depth, budget, and tenant limits and links the sub-run into the tree.

public sealed class ChildAgentInvoker : AIAgent

Inheritance

object ← AIAgent ← ChildAgentInvoker

Inherited Members

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 an IAgentDecorator. Decorators apply to every agent resolved from the catalog; this wrapper only intervenes when one agent appears in another agent’s view. It does not touch the decorator order (recording 0 → telemetry 10 → approval 20).

The sub-agent is resolved late. This way, the calling agent’s compiled copy does not go stale when the sub-agent’s definition changes.

Microsoft Agent Framework calls the sub-agent with options = null . Tree information therefore cannot be read from the incoming options; the wrapper reads it from the TraconRunContext scope and builds the TraconRunOptions object itself.

Constructors

ChildAgentInvoker(CallableAgentResolver, ITenantContext, ILogger, string, CallableAgentInfo, TimeSpan, TimeSpan, TimeProvider?)

Creates a new sub-agent wrapper.

public ChildAgentInvoker(CallableAgentResolver resolver, ITenantContext tenantContext, ILogger logger, string callerName, CallableAgentInfo child, TimeSpan childDeadline, TimeSpan waitTimeout, TimeProvider? timeProvider = null)

Parameters

resolver CallableAgentResolver

Resolver that resolves the sub-agent from the catalog.

tenantContext ITenantContext

Tenant context.

logger ILogger

Logger.

callerName string

Name of the calling agent.

child CallableAgentInfo

Summary of the sub-agent being called.

childDeadline TimeSpan

The cooperative wait limit (144.1 layer 1), resolved beforehand from SubAgentSettings.ChildDeadline/TraconAgentGraphOptions.ChildDeadline. Must be greater than zero.

waitTimeout TimeSpan

The hard wait cutoff (144.1 layer 2), resolved beforehand from SubAgentSettings.WaitTimeout/TraconAgentGraphOptions.WaitTimeout. Must be greater than childDeadline.

timeProvider TimeProvider?

Time source for the wait race. Defaults to TimeProvider.System.

Exceptions

ArgumentNullException

One of the required dependencies is null.

ArgumentOutOfRangeException

childDeadline is not greater than zero, or waitTimeout is not greater than childDeadline.

Properties

Description

Gets a description of the agent’s purpose, capabilities, or behavior.

public override string? Description { get; }

Property Value

string?

Remarks

The description helps models and users understand the agent’s intended purpose and capabilities, which is particularly useful in multi-agent systems.

Name

Gets the human-readable name of the agent.

public override string Name { get; }

Property Value

string

Remarks

The agent name is typically used for display purposes and to help users identify the agent’s purpose or capabilities in user interfaces.

Methods

CreateSessionCoreAsync(CancellationToken)

Core implementation of session creation logic.

protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

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

Returns

ValueTask<AgentSession>

A value task that represents the asynchronous operation. The task result contains a new AI.AgentSession instance ready for use with this agent.

Remarks

This is the primary session creation method that implementations must override.

DeserializeSessionCoreAsync(JsonElement, JsonSerializerOptions?, CancellationToken)

Core implementation of session deserialization logic.

protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)

Parameters

serializedState JsonElement

A JsonElement containing the serialized session state.

jsonSerializerOptions JsonSerializerOptions?

Optional settings to customize the deserialization process.

cancellationToken CancellationToken

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

Returns

ValueTask<AgentSession>

A value task that represents the asynchronous operation. The task result contains a restored AI.AgentSession instance with the state from serializedState.

Remarks

This is the primary session deserialization method that implementations must override.

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.

SerializeSessionCoreAsync(AgentSession, JsonSerializerOptions?, CancellationToken)

Core implementation of session serialization logic.

protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)

Parameters

session AgentSession

The AI.AgentSession to serialize.

jsonSerializerOptions JsonSerializerOptions?

Optional settings to customize the serialization process.

cancellationToken CancellationToken

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

Returns

ValueTask<JsonElement>

A value task that represents the asynchronous operation. The task result contains a JsonElement with the serialized session state.

Remarks

This is the primary session serialization method that implementations must override.