.NET API
AgentDefinitionCompiler
Tracon.Core.dllChat agent, child agent (sub-agent), and harness agent production.
public sealed class AgentDefinitionCompiler- Inheritance
- object ← AgentDefinitionCompiler
- Inherited Members
- object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Remarks
Section titled “Remarks”The conversion goes through these steps:
- ModelBinding → IModelProviderRegistry →
AI.IChatClient - AgentDefinition.ToolNames → IToolRegistry → list of
AI.AIFunction AsHarnessAgentwhen AgentDefinition.Harness is set, otherwiseAsAIAgent
An unknown tool name results in a 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
Section titled “Methods”Compile(AgentDefinition)
Section titled “ Compile(AgentDefinition)”Converts a definition into an executable agent.
public AIAgent Compile(AgentDefinition definition)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
Returns
Section titled “Returns”AIAgent
The executable agent.
Remarks
Section titled “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.
Exceptions
Section titled “Exceptions”definition is null.
The model provider cannot be found, or the definition references a tool name that is not registered.
Compile(AgentDefinition, ResolvedCallableAgents)
Section titled “ Compile(AgentDefinition, ResolvedCallableAgents)”Converts a definition, together with its resolved sub-agents, into an executable agent.
public AIAgent Compile(AgentDefinition definition, ResolvedCallableAgents callableAgents)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
callableAgents ResolvedCallableAgents
Sub-agent summaries resolved beforehand via AgentDefinitionCompiler.ResolveCallableAgentsAsync.
Returns
Section titled “Returns”AIAgent
The executable agent.
Remarks
Section titled “Remarks”Resolves no tenant state; see AgentDefinitionCompiler.Compile.
Exceptions
Section titled “Exceptions”definition is null.
The model provider cannot be found, or the definition references a tool name that is not registered.
Compile(AgentDefinition, ResolvedCallableAgents, Func<AIFunction, AIFunction>?, string?)
Section titled “ Compile(AgentDefinition, ResolvedCallableAgents, Func<AIFunction, AIFunction>?, string?)”Compiles a definition together with its resolved sub-agents, transforming its tools.
public AIAgent Compile(AgentDefinition definition, ResolvedCallableAgents callableAgents, Func<AIFunction, AIFunction>? toolTransform, string? culture = null)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
callableAgents ResolvedCallableAgents
Sub-agent summaries resolved beforehand via AgentDefinitionCompiler.ResolveCallableAgentsAsync.
toolTransform Func<AIFunction, AIFunction>?
Transform applied to every tool resolved from the registry. When null, tools are bound as-is.
culture string?
The requested culture, resolved against AgentDefinition.InstructionsByCulture:
the exact tag first, then its parent (tr-TR falls back to tr),
then AgentDefinition.Instructions, matching tags case-insensitively.
An unmatched culture never fails compilation. null uses
AgentDefinition.Instructions unconditionally.
Returns
Section titled “Returns”AIAgent
The executable agent.
Remarks
Section titled “Remarks”The transform exists for replay
(ReplayToolMode.ReplayTools): 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 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) 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.
Exceptions
Section titled “Exceptions”definition is null.
The model provider cannot be found, or the definition references a tool name that is not registered.
CompileAsync(AgentDefinition, CancellationToken)
Section titled “ CompileAsync(AgentDefinition, CancellationToken)”Converts a definition into an executable agent (BYOK).
public ValueTask<AIAgent> CompileAsync(AgentDefinition definition, CancellationToken cancellationToken)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<AIAgent>
The executable agent.
Remarks
Section titled “Remarks”The async counterpart of AgentDefinitionCompiler.Compile: 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. The judge of an
aiJudge loop criterion uses
IModelProviderRegistry.CreateSetupChatClientAsync: 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
Section titled “Exceptions”definition is null.
A model provider cannot be found, or the definition references a tool name that is not registered.
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.
CompileAsync(AgentDefinition, ResolvedCallableAgents, string?, CancellationToken)
Section titled “ CompileAsync(AgentDefinition, ResolvedCallableAgents, string?, CancellationToken)”Converts a definition, together with its resolved sub-agents, into an executable agent (BYOK).
public ValueTask<AIAgent> CompileAsync(AgentDefinition definition, ResolvedCallableAgents callableAgents, string? culture, CancellationToken cancellationToken)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
callableAgents ResolvedCallableAgents
Sub-agent summaries resolved beforehand via AgentDefinitionCompiler.ResolveCallableAgentsAsync.
culture string?
See AgentDefinitionCompiler.Compile.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<AIAgent>
The executable agent.
Exceptions
Section titled “Exceptions”definition is null.
See AgentDefinitionCompiler.CompileAsync.
CompileAsync(AgentDefinition, ResolvedCallableAgents, Func<AIFunction, AIFunction>?, string?, CancellationToken)
Section titled “ CompileAsync(AgentDefinition, ResolvedCallableAgents, Func<AIFunction, AIFunction>?, string?, CancellationToken)”Compiles a definition together with its resolved sub-agents, transforming its tools (BYOK).
public ValueTask<AIAgent> CompileAsync(AgentDefinition definition, ResolvedCallableAgents callableAgents, Func<AIFunction, AIFunction>? toolTransform, string? culture, CancellationToken cancellationToken)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
callableAgents ResolvedCallableAgents
Sub-agent summaries resolved beforehand via AgentDefinitionCompiler.ResolveCallableAgentsAsync.
toolTransform Func<AIFunction, AIFunction>?
Transform applied to every tool resolved from the registry. See AgentDefinitionCompiler.Compile.
culture string?
See AgentDefinitionCompiler.Compile.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<AIAgent>
The executable agent.
Exceptions
Section titled “Exceptions”definition is null.
See AgentDefinitionCompiler.CompileAsync.
CompileCachedAsync(AgentDefinition, CompiledAgentCache, string, string?, CancellationToken)
Section titled “ CompileCachedAsync(AgentDefinition, CompiledAgentCache, string, string?, CancellationToken)”Compiles a definition and stores it in the supplied cache when it is safe to do so.
public ValueTask<AIAgent> CompileCachedAsync(AgentDefinition definition, CompiledAgentCache cache, string tenantId, string? culture = null, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to compile.
cache CompiledAgentCache
The cache that owns compiled agents for this source.
tenantId string
The tenant whose compilation cache is used.
culture string?
The requested instruction culture.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<AIAgent>
The executable agent.
CompileParameterizedAsync(AgentDefinition, string?, IReadOnlyDictionary<string, string>?, CancellationToken)
Section titled “ CompileParameterizedAsync(AgentDefinition, string?, IReadOnlyDictionary<string, string>?, CancellationToken)”Binds a parameterized definition’s instructions for a single set of values and compiles it, bypassing CompiledAgentCache.
public ValueTask<AIAgent> CompileParameterizedAsync(AgentDefinition definition, string? culture, IReadOnlyDictionary<string, string>? values, CancellationToken cancellationToken)Parameters
Section titled “Parameters”definition AgentDefinition
The source definition. Its 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?
The culture to resolve instructions with before binding.
values IReadOnlyDictionary<string, string>?
The parameter values for this one compilation.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<AIAgent>
The compiled agent.
Remarks
Section titled “Remarks”The bound text is written into a definition copy: AgentDefinition.InstructionsByCulture is cleared (culture resolution already happened, once, right here) and 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 has no notion of “value” in its key - the same reason a tenant-specific provider credential (BYOK) bypasses it.
Exceptions
Section titled “Exceptions”definition is null.
See AgentDefinitionCompiler.CompileAsync.
CreateDefinitionFingerprint(AgentDefinition)
Section titled “ CreateDefinitionFingerprint(AgentDefinition)”Produces the fingerprint of a definition’s own content: the CompiledAgentCache key component that decides whether a compiled agent may be reused.
public static string CreateDefinitionFingerprint(AgentDefinition definition)Parameters
Section titled “Parameters”definition AgentDefinition
The definition to fingerprint.
Returns
Section titled “Returns”The fingerprint, as an uppercase hex SHA-256 string.
Remarks
Section titled “Remarks”The whole serialized definition is hashed, deliberately. Listing the compile-relevant fields by hand would be cheaper, but a field added to 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, 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
Section titled “Exceptions”definition is null.
ResolveCallableAgentsAsync(AgentDefinition, CancellationToken)
Section titled “ ResolveCallableAgentsAsync(AgentDefinition, CancellationToken)”Resolves the sub-agents a definition may call and produces the cache fingerprint.
public ValueTask<ResolvedCallableAgents> ResolveCallableAgentsAsync(AgentDefinition definition, CancellationToken cancellationToken)Parameters
Section titled “Parameters”definition AgentDefinition
The agent definition being resolved.
cancellationToken CancellationToken
Cancellation token.
Returns
Section titled “Returns”ValueTask<ResolvedCallableAgents>
Sub-agent summaries and the fingerprint.
Exceptions
Section titled “Exceptions”definition is null.
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).
UsesTenantProviderOverrideAsync(ModelBinding, CancellationToken)
Section titled “ UsesTenantProviderOverrideAsync(ModelBinding, CancellationToken)”Reports whether compiling binding for the current
tenant would bake a tenant-specific provider credential into the
resulting chat client (BYOK).
public ValueTask<bool> UsesTenantProviderOverrideAsync(ModelBinding binding, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”binding ModelBinding
The model binding to check — usually an AgentDefinition.Model.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”true if the caller must not hand the compiled agent to CompiledAgentCache: see IModelProviderRegistry.HasTenantProviderOverrideAsync for the full reason.
Remarks
Section titled “Remarks”A compiled agent can hold a second client the tenant pays for: the summarizer of its AgentDefinition.Compaction. A caller that caches compiled agents itself asks about that binding too; AgentDefinitionCompiler.CompileCachedAsync does.