# ChildAgentInvoker

> 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.childagentinvoker/
> Summary: ChildAgentInvoker: Wraps a sub-agent an agent may call; enforces depth, budget, and tenant limits and links the sub-run into the tree.

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

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

```csharp
public sealed class ChildAgentInvoker : AIAgent
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← AIAgent ← <a href="/api/tracon.childagentinvoker/">ChildAgentInvoker</a></dd><dt>Inherited Members</dt><dd>AIAgent.GetService(Type, object?), AIAgent.GetService&lt;TService&gt;(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&lt;ChatMessage&gt;, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(string, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(ChatMessage, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunStreamingAsync(IEnumerable&lt;ChatMessage&gt;, AgentSession?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync&lt;T&gt;(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync&lt;T&gt;(string, AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync&lt;T&gt;(ChatMessage, AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.RunAsync&lt;T&gt;(IEnumerable&lt;ChatMessage&gt;, AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken), AIAgent.Id, AIAgent.Name, AIAgent.Description, AIAgent.CurrentRunContext, <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

This is **not** an [IAgentDecorator](/api/tracon.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](/api/tracon.traconruncontext/)
scope and builds the [TraconRunOptions](/api/tracon.traconrunoptions/) object itself.

Tracon builds one wrapper for each entry of [AgentDefinition.CallableAgents](/api/tracon.agentdefinition/#Tracon_AgentDefinition_CallableAgents)
when it compiles the calling agent; there is no other way to obtain one.

## Properties

### <a id="Tracon_ChildAgentInvoker_Description"></a> Description

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

```csharp
public override string? Description { get; }
```

#### Property Value

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

#### Remarks

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

### <a id="Tracon_ChildAgentInvoker_Name"></a> Name

Gets the human-readable name of the agent.

```csharp
public override string Name { get; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.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

### <a id="Tracon_ChildAgentInvoker_CreateSessionCoreAsync_System_Threading_CancellationToken_"></a> CreateSessionCoreAsync\(CancellationToken\)

Core implementation of session creation logic.

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

#### Parameters

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) to monitor for cancellation requests. The default is [CancellationToken.None](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken).

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<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.

### <a id="Tracon_ChildAgentInvoker_DeserializeSessionCoreAsync_System_Text_Json_JsonElement_System_Text_Json_JsonSerializerOptions_System_Threading_CancellationToken_"></a> DeserializeSessionCoreAsync\(JsonElement, JsonSerializerOptions?, CancellationToken\)

Core implementation of session deserialization logic.

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

#### Parameters

`serializedState` [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement)

A [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement) containing the serialized session state.

`jsonSerializerOptions` [JsonSerializerOptions](https://learn.microsoft.com/dotnet/api/system.text.json.jsonserializeroptions)?

Optional settings to customize the deserialization process.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) to monitor for cancellation requests. The default is [CancellationToken.None](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken).

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<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.

### <a id="Tracon_ChildAgentInvoker_RunCoreAsync_System_Collections_Generic_IEnumerable_Microsoft_Extensions_AI_ChatMessage__Microsoft_Agents_AI_AgentSession_Microsoft_Agents_AI_AgentRunOptions_System_Threading_CancellationToken_"></a> RunCoreAsync\(IEnumerable<ChatMessage\>, AgentSession?, AgentRunOptions?, CancellationToken\)

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

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

#### Parameters

`messages` [IEnumerable](https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable\-1)<ChatMessage\>

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

`session` AgentSession?

The conversation session to use for this invocation. If [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/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](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) to monitor for cancellation requests. The default is [CancellationToken.None](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken).

#### Returns

 [Task](https://learn.microsoft.com/dotnet/api/system.threading.tasks.task\-1)<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.

### <a id="Tracon_ChildAgentInvoker_RunCoreStreamingAsync_System_Collections_Generic_IEnumerable_Microsoft_Extensions_AI_ChatMessage__Microsoft_Agents_AI_AgentSession_Microsoft_Agents_AI_AgentRunOptions_System_Threading_CancellationToken_"></a> RunCoreStreamingAsync\(IEnumerable<ChatMessage\>, AgentSession?, AgentRunOptions?, CancellationToken\)

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

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

#### Parameters

`messages` [IEnumerable](https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable\-1)<ChatMessage\>

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

`session` AgentSession?

The conversation session to use for this invocation. If [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/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](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) to monitor for cancellation requests. The default is [CancellationToken.None](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken).

#### Returns

 [IAsyncEnumerable](https://learn.microsoft.com/dotnet/api/system.collections.generic.iasyncenumerable\-1)<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.

### <a id="Tracon_ChildAgentInvoker_SerializeSessionCoreAsync_Microsoft_Agents_AI_AgentSession_System_Text_Json_JsonSerializerOptions_System_Threading_CancellationToken_"></a> SerializeSessionCoreAsync\(AgentSession, JsonSerializerOptions?, CancellationToken\)

Core implementation of session serialization logic.

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

#### Parameters

`session` AgentSession

The `AI.AgentSession` to serialize.

`jsonSerializerOptions` [JsonSerializerOptions](https://learn.microsoft.com/dotnet/api/system.text.json.jsonserializeroptions)?

Optional settings to customize the serialization process.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken) to monitor for cancellation requests. The default is [CancellationToken.None](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken).

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement)\>

A value task that represents the asynchronous operation. The task result contains a [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement) with the serialized session state.

#### Remarks

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