# AgentDefinitionCompiler

> 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.agentdefinitioncompiler/
> Summary: AgentDefinitionCompiler: Chat agent, child agent (sub-agent), and harness agent production.

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

Chat agent, child agent (sub-agent), and harness agent production.

```csharp
public sealed class AgentDefinitionCompiler
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.agentdefinitioncompiler/">AgentDefinitionCompiler</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.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

The conversion goes through these steps:

- [ModelBinding](/api/tracon.modelbinding/) → [IModelProviderRegistry](/api/tracon.imodelproviderregistry/) → `AI.IChatClient`
- [AgentDefinition.ToolNames](/api/tracon.agentdefinition/#Tracon_AgentDefinition_ToolNames) → [IToolRegistry](/api/tracon.itoolregistry/) → list of `AI.AIFunction`
- `AsHarnessAgent` when [AgentDefinition.Harness](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Harness) is set, otherwise `AsAIAgent`

An unknown tool name results in a [TraconCompilationException](/api/tracon.traconcompilationexception/).
It is not silently skipped: an agent running with a missing tool is an
agent that does not do the work the user expects.

## Methods

### <a id="Tracon_AgentDefinitionCompiler_Compile_Tracon_AgentDefinition_"></a> Compile\(AgentDefinition\)

Converts a definition into an executable agent.

```csharp
public AIAgent Compile(AgentDefinition definition)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

#### Returns

 AIAgent

The executable agent.

#### Remarks

The synchronous path resolves **no** tenant state. No model
client the agent calls — its own model, the compaction summarizer, the
judge of an `aiJudge` loop criterion — goes through the current
tenant's egress policy or its own provider credential, because both need
an async store read. Compile an agent that runs for a tenant with
[AgentDefinitionCompiler.CompileAsync](/api/tracon.agentdefinitioncompiler/).

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

The model provider cannot be found, or the definition references a tool name that is not registered.

### <a id="Tracon_AgentDefinitionCompiler_Compile_Tracon_AgentDefinition_Tracon_ResolvedCallableAgents_"></a> Compile\(AgentDefinition, ResolvedCallableAgents\)

Converts a definition, together with its resolved sub-agents, into an executable agent.

```csharp
public AIAgent Compile(AgentDefinition definition, ResolvedCallableAgents callableAgents)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

`callableAgents` [ResolvedCallableAgents](/api/tracon.resolvedcallableagents/)

Sub-agent summaries resolved beforehand via [AgentDefinitionCompiler.ResolveCallableAgentsAsync](/api/tracon.agentdefinitioncompiler/#Tracon_AgentDefinitionCompiler_ResolveCallableAgentsAsync_Tracon_AgentDefinition_System_Threading_CancellationToken_).

#### Returns

 AIAgent

The executable agent.

#### Remarks

Resolves no tenant state; see [AgentDefinitionCompiler.Compile](/api/tracon.agentdefinitioncompiler/).

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

The model provider cannot be found, or the definition references a tool name that is not registered.

### <a id="Tracon_AgentDefinitionCompiler_Compile_Tracon_AgentDefinition_Tracon_ResolvedCallableAgents_System_Func_Microsoft_Extensions_AI_AIFunction_Microsoft_Extensions_AI_AIFunction__System_String_"></a> Compile\(AgentDefinition, ResolvedCallableAgents, Func<AIFunction, AIFunction\>?, string?\)

Compiles a definition together with its resolved sub-agents, transforming its tools.

```csharp
public AIAgent Compile(AgentDefinition definition, ResolvedCallableAgents callableAgents, Func<AIFunction, AIFunction>? toolTransform, string? culture = null)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

`callableAgents` [ResolvedCallableAgents](/api/tracon.resolvedcallableagents/)

Sub-agent summaries resolved beforehand via [AgentDefinitionCompiler.ResolveCallableAgentsAsync](/api/tracon.agentdefinitioncompiler/#Tracon_AgentDefinitionCompiler_ResolveCallableAgentsAsync_Tracon_AgentDefinition_System_Threading_CancellationToken_).

`toolTransform` [Func](https://learn.microsoft.com/dotnet/api/system.func\-2)<AIFunction, AIFunction\>?

Transform applied to every tool resolved from the registry. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null),
tools are bound as-is.

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

The requested culture, resolved against [AgentDefinition.InstructionsByCulture](/api/tracon.agentdefinition/#Tracon_AgentDefinition_InstructionsByCulture):
the exact tag first, then its parent (`tr-TR` falls back to `tr`),
then [AgentDefinition.Instructions](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Instructions), matching tags case-insensitively.
An unmatched culture never fails compilation. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) uses
[AgentDefinition.Instructions](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Instructions) unconditionally.

#### Returns

 AIAgent

The executable agent.

#### Remarks

The transform exists for replay
([ReplayToolMode.ReplayTools](/api/tracon.replaytoolmode/)): a `DelegatingAIFunction`
that replays recorded tool results preserves the wrapped tool's name,
description, and JSON schema - the model sees the tools
*exactly as before* but no body actually runs.

The transform applies only to tools resolved from the
[IToolRegistry](/api/tracon.itoolregistry/) registry. Tools opened by skills,
callable sub-agents and agent extensions come through an
`AIContextProvider` and do not pass through here; the caller must
disable them *at the definition level* instead.

The compiled agent cache ([CompiledAgentCache](/api/tracon.compiledagentcache/)) is
**not used** for this path: the transform changes per
call, and caching a replay agent would also break normal runs.

Resolves no tenant state; see [AgentDefinitionCompiler.Compile](/api/tracon.agentdefinitioncompiler/).

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

The model provider cannot be found, or the definition references a tool name that is not registered.

### <a id="Tracon_AgentDefinitionCompiler_CompileAsync_Tracon_AgentDefinition_System_Threading_CancellationToken_"></a> CompileAsync\(AgentDefinition, CancellationToken\)

Converts a definition into an executable agent (BYOK).

```csharp
public ValueTask<AIAgent> CompileAsync(AgentDefinition definition, CancellationToken cancellationToken)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

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

The cancellation token.

#### Returns

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

The executable agent.

#### Remarks

The async counterpart of [AgentDefinitionCompiler.Compile](/api/tracon.agentdefinitioncompiler/): resolves the
requesting tenant's egress policy before it builds any model client the agent calls,
and the tenant's own provider credential for the clients the tenant pays for. The
agent's own model and the compaction summarizer use
[IModelProviderRegistry.CreateChatClientAsync](/api/tracon.imodelproviderregistry/#Tracon_IModelProviderRegistry_CreateChatClientAsync_Tracon_ModelBinding_System_Threading_CancellationToken_). The judge of an
`aiJudge` loop criterion uses
[IModelProviderRegistry.CreateSetupChatClientAsync](/api/tracon.imodelproviderregistry/#Tracon_IModelProviderRegistry_CreateSetupChatClientAsync_Tracon_ModelBinding_System_Threading_CancellationToken_): it is the host's one
judge model and keeps the setup-time credential.

When no tenant context or provider binding is registered, behavior is identical
to the sync overload.

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

A model provider cannot be found, or the definition references a tool name that is
not registered.

 [TraconTenantProviderRefusedException](/api/tracon.tracontenantproviderrefusedexception/)

The current tenant's egress policy forbids a provider the agent calls, or the
tenant's provider binding cannot be resolved to a credential value. The message
names the agent; the type stays the refusal so a retry and a classifier read it
as one.

### <a id="Tracon_AgentDefinitionCompiler_CompileAsync_Tracon_AgentDefinition_Tracon_ResolvedCallableAgents_System_String_System_Threading_CancellationToken_"></a> CompileAsync\(AgentDefinition, ResolvedCallableAgents, string?, CancellationToken\)

Converts a definition, together with its resolved sub-agents, into an executable agent
(BYOK).

```csharp
public ValueTask<AIAgent> CompileAsync(AgentDefinition definition, ResolvedCallableAgents callableAgents, string? culture, CancellationToken cancellationToken)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

`callableAgents` [ResolvedCallableAgents](/api/tracon.resolvedcallableagents/)

Sub-agent summaries resolved beforehand via [AgentDefinitionCompiler.ResolveCallableAgentsAsync](/api/tracon.agentdefinitioncompiler/#Tracon_AgentDefinitionCompiler_ResolveCallableAgentsAsync_Tracon_AgentDefinition_System_Threading_CancellationToken_).

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

See [AgentDefinitionCompiler.Compile](/api/tracon.agentdefinitioncompiler/).

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

The cancellation token.

#### Returns

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

The executable agent.

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

See [AgentDefinitionCompiler.CompileAsync](/api/tracon.agentdefinitioncompiler/).

### <a id="Tracon_AgentDefinitionCompiler_CompileAsync_Tracon_AgentDefinition_Tracon_ResolvedCallableAgents_System_Func_Microsoft_Extensions_AI_AIFunction_Microsoft_Extensions_AI_AIFunction__System_String_System_Threading_CancellationToken_"></a> CompileAsync\(AgentDefinition, ResolvedCallableAgents, Func<AIFunction, AIFunction\>?, string?, CancellationToken\)

Compiles a definition together with its resolved sub-agents, transforming its tools
(BYOK).

```csharp
public ValueTask<AIAgent> CompileAsync(AgentDefinition definition, ResolvedCallableAgents callableAgents, Func<AIFunction, AIFunction>? toolTransform, string? culture, CancellationToken cancellationToken)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

`callableAgents` [ResolvedCallableAgents](/api/tracon.resolvedcallableagents/)

Sub-agent summaries resolved beforehand via [AgentDefinitionCompiler.ResolveCallableAgentsAsync](/api/tracon.agentdefinitioncompiler/#Tracon_AgentDefinitionCompiler_ResolveCallableAgentsAsync_Tracon_AgentDefinition_System_Threading_CancellationToken_).

`toolTransform` [Func](https://learn.microsoft.com/dotnet/api/system.func\-2)<AIFunction, AIFunction\>?

Transform applied to every tool resolved from the registry. See
[AgentDefinitionCompiler.Compile](/api/tracon.agentdefinitioncompiler/).

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

See [AgentDefinitionCompiler.Compile](/api/tracon.agentdefinitioncompiler/).

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

The cancellation token.

#### Returns

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

The executable agent.

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

See [AgentDefinitionCompiler.CompileAsync](/api/tracon.agentdefinitioncompiler/).

### <a id="Tracon_AgentDefinitionCompiler_CompileCachedAsync_Tracon_AgentDefinition_Tracon_CompiledAgentCache_System_String_System_String_System_Threading_CancellationToken_"></a> CompileCachedAsync\(AgentDefinition, CompiledAgentCache, string, string?, CancellationToken\)

Compiles a definition and stores it in the supplied cache when it is safe to do so.

```csharp
public ValueTask<AIAgent> CompileCachedAsync(AgentDefinition definition, CompiledAgentCache cache, string tenantId, string? culture = null, CancellationToken cancellationToken = default)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to compile.

`cache` [CompiledAgentCache](/api/tracon.compiledagentcache/)

The cache that owns compiled agents for this source.

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

The tenant whose compilation cache is used.

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

The requested instruction culture.

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

The cancellation token.

#### Returns

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

The executable agent.

### <a id="Tracon_AgentDefinitionCompiler_CompileParameterizedAsync_Tracon_AgentDefinition_System_String_System_Collections_Generic_IReadOnlyDictionary_System_String_System_String__System_Threading_CancellationToken_"></a> CompileParameterizedAsync\(AgentDefinition, string?, IReadOnlyDictionary<string, string\>?, CancellationToken\)

Binds a parameterized definition's instructions for a single set of
values and compiles it, bypassing [CompiledAgentCache](/api/tracon.compiledagentcache/).

```csharp
public ValueTask<AIAgent> CompileParameterizedAsync(AgentDefinition definition, string? culture, IReadOnlyDictionary<string, string>? values, CancellationToken cancellationToken)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The source definition. Its [AgentDefinition.Parameters](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Parameters)
schema is validated against `values` the same way
`AgentParameterValidator.ValidateValues` validates a run request -
callers that already ran that check (an HTTP endpoint) do not need to
repeat it; a caller that has not (an eval case) should call it first,
since this method does not itself report which parameter was missing.

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

The culture to resolve instructions with before binding.

`values` [IReadOnlyDictionary](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlydictionary\-2)<[string](https://learn.microsoft.com/dotnet/api/system.string), [string](https://learn.microsoft.com/dotnet/api/system.string)\>?

The parameter values for this one compilation.

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

The cancellation token.

#### Returns

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

The compiled agent.

#### Remarks

The bound text is written into a definition *copy*:
[AgentDefinition.InstructionsByCulture](/api/tracon.agentdefinition/#Tracon_AgentDefinition_InstructionsByCulture) is cleared (culture
resolution already happened, once, right here) and
[AgentDefinition.Parameters](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Parameters) is cleared (the copy's text no
longer contains template placeholders, so there is nothing left for
the compiler's schema check to validate).

Never cached: two compilations of the same definition with different
parameter values must never share one compiled instance, and
[CompiledAgentCache](/api/tracon.compiledagentcache/) has no notion of "value" in its key -
the same reason a tenant-specific provider credential (BYOK) bypasses it.

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

See [AgentDefinitionCompiler.CompileAsync](/api/tracon.agentdefinitioncompiler/).

### <a id="Tracon_AgentDefinitionCompiler_CreateDefinitionFingerprint_Tracon_AgentDefinition_"></a> CreateDefinitionFingerprint\(AgentDefinition\)

Produces the fingerprint of a definition's own content: the
[CompiledAgentCache](/api/tracon.compiledagentcache/) key component that decides whether a
compiled agent may be reused.

```csharp
public static string CreateDefinitionFingerprint(AgentDefinition definition)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The definition to fingerprint.

#### Returns

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

The fingerprint, as an uppercase hex SHA-256 string.

#### Remarks

**The whole serialized definition is hashed, deliberately.**
Listing the compile-relevant fields by hand would be cheaper, but a field
added to [AgentDefinition](/api/tracon.agentdefinition/) later would not reach the list, and
the failure mode is silent: the cache would serve an agent compiled from
the OLD value of that field. Serializing the record makes a new field part
of the fingerprint the moment it is declared.

This replaces [AgentDefinition.Version](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Version), which was a proxy for
content and stopped being one after a delete when the store restarted
numbering, so a recreated name was version `1` again. The built-in stores
keep the numbering now, but a custom store may not. Content is the thing that
was always meant; the version only stood in for it.

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

### <a id="Tracon_AgentDefinitionCompiler_ResolveCallableAgentsAsync_Tracon_AgentDefinition_System_Threading_CancellationToken_"></a> ResolveCallableAgentsAsync\(AgentDefinition, CancellationToken\)

Resolves the sub-agents a definition may call and produces the cache fingerprint.

```csharp
public ValueTask<ResolvedCallableAgents> ResolveCallableAgentsAsync(AgentDefinition definition, CancellationToken cancellationToken)
```

#### Parameters

`definition` [AgentDefinition](/api/tracon.agentdefinition/)

The agent definition being resolved.

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

Cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[ResolvedCallableAgents](/api/tracon.resolvedcallableagents/)\>

Sub-agent summaries and the fingerprint.

#### Exceptions

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

`definition` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconCompilationException](/api/tracon.traconcompilationexception/)

The definition wants to call a sub-agent but the feature is not registered, or it pins a sub-agent to a
version the sub-agent no longer has (or one defined in code, which has none).

### <a id="Tracon_AgentDefinitionCompiler_UsesTenantProviderOverrideAsync_Tracon_ModelBinding_System_Threading_CancellationToken_"></a> UsesTenantProviderOverrideAsync\(ModelBinding, CancellationToken\)

Reports whether compiling `binding` for the current
tenant would bake a tenant-specific provider credential into the
resulting chat client (BYOK).

```csharp
public ValueTask<bool> UsesTenantProviderOverrideAsync(ModelBinding binding, CancellationToken cancellationToken = default)
```

#### Parameters

`binding` [ModelBinding](/api/tracon.modelbinding/)

The model binding to check — usually an [AgentDefinition.Model](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Model).

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

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[bool](https://learn.microsoft.com/dotnet/api/system.boolean)\>

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if the caller must not hand the compiled agent
to [CompiledAgentCache](/api/tracon.compiledagentcache/): see
[IModelProviderRegistry.HasTenantProviderOverrideAsync](/api/tracon.imodelproviderregistry/#Tracon_IModelProviderRegistry_HasTenantProviderOverrideAsync_Tracon_ModelBinding_System_Threading_CancellationToken_) for
the full reason.

#### Remarks

A compiled agent can hold a second client the tenant pays for: the
summarizer of its [AgentDefinition.Compaction](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Compaction). A caller
that caches compiled agents itself asks about that binding too;
[AgentDefinitionCompiler.CompileCachedAsync](/api/tracon.agentdefinitioncompiler/#Tracon_AgentDefinitionCompiler_CompileCachedAsync_Tracon_AgentDefinition_Tracon_CompiledAgentCache_System_String_System_String_System_Threading_CancellationToken_) does.