.NET API
AgentDefinitionCompiler
Tracon.Core.dllChat agent, child agent (sub-agent), and harness agent production.
public sealed class AgentDefinitionCompilerInheritance
Section titled “Inheritance”object ← AgentDefinitionCompiler
Inherited Members
Section titled “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.
Constructors
Section titled “Constructors”AgentDefinitionCompiler(IModelProviderRegistry, IToolRegistry, ILoggerFactory?, IServiceProvider?, ChatHistoryProvider?, AgentSkillCatalog?, SkillScriptSupport?, CallableAgentResolver?, ITenantContext?, ModelBinding?, AgentFileStore?, IMcpResourceContextProviderFactory?, IVectorSearchStore?, IEmbeddingGenerator<string, Embedding<float>>?, int, IAgentDefinitionStore?, TraconAgentGraphOptions?, TimeProvider?, IEnumerable<TraconLoopEvaluatorRegistration>?, ModelRunJudgeOptions?)
Section titled “ AgentDefinitionCompiler(IModelProviderRegistry, IToolRegistry, ILoggerFactory?, IServiceProvider?, ChatHistoryProvider?, AgentSkillCatalog?, SkillScriptSupport?, CallableAgentResolver?, ITenantContext?, ModelBinding?, AgentFileStore?, IMcpResourceContextProviderFactory?, IVectorSearchStore?, IEmbeddingGenerator<string, Embedding<float>>?, int, IAgentDefinitionStore?, TraconAgentGraphOptions?, TimeProvider?, IEnumerable<TraconLoopEvaluatorRegistration>?, ModelRunJudgeOptions?)”Creates a new compiler.
public AgentDefinitionCompiler(IModelProviderRegistry models, IToolRegistry tools, ILoggerFactory? loggerFactory = null, IServiceProvider? services = null, ChatHistoryProvider? chatHistoryProvider = null, AgentSkillCatalog? skills = null, SkillScriptSupport? scripts = null, CallableAgentResolver? callableAgents = null, ITenantContext? tenantContext = null, ModelBinding? utilityModel = null, AgentFileStore? fileStore = null, IMcpResourceContextProviderFactory? mcpResources = null, IVectorSearchStore? vectorSearchStore = null, IEmbeddingGenerator<string, Embedding<float>>? embeddingGenerator = null, int knowledgeMaxResults = 5, IAgentDefinitionStore? definitionStore = null, TraconAgentGraphOptions? agentGraph = null, TimeProvider? timeProvider = null, IEnumerable<TraconLoopEvaluatorRegistration>? loopEvaluators = null, ModelRunJudgeOptions? judgeOptions = null)Parameters
Section titled “Parameters”models IModelProviderRegistry
Model provider registry.
tools IToolRegistry
Tool registry.
loggerFactory ILoggerFactory?
Logger factory passed to the produced agents.
services IServiceProvider?
Service provider passed to the produced agents.
chatHistoryProvider ChatHistoryProvider?
Chat history provider attached to the produced agents. When null, Microsoft Agent Framework’s in-memory default is used and history is carried inside the session state.
skills AgentSkillCatalog?
Catalog that resolves skill sources.
scripts SkillScriptSupport?
Skill script support. When null, no script can run;
the feature is turned on with UseSkillScripts.
callableAgents CallableAgentResolver?
Resolver for callable sub-agents. When null, no agent can call another agent.
tenantContext ITenantContext?
Tenant context. Used to verify that sub-calls do not change tenant.
utilityModel ModelBinding?
Default model for summarization in context compaction. Used when an
agent does not supply its own CompactionSettings.SummarizationModel;
when null, falls back to the agent’s own model.
fileStore AgentFileStore?
File store used by memory providers. When null, a
definition requesting MemorySettings.EnableFileMemory/EnableTextSearch
gets a compilation error.
mcpResources IMcpResourceContextProviderFactory?
Factory that builds the context provider for AgentDefinition.McpResourceUris (Mode A). When null, a definition requesting an MCP resource gets a compilation error.
vectorSearchStore IVectorSearchStore?
Semantic search store. When null, a
definition requesting MemorySettings.EnableVectorSearch gets a
compilation error.
embeddingGenerator IEmbeddingGenerator<string, Embedding<float>>?
Embedding generator. When null, a
definition requesting MemorySettings.EnableVectorSearch gets a
compilation error.
knowledgeMaxResults int
Maximum number of results the search_knowledge tool returns.
definitionStore IAgentDefinitionStore?
The definition store, used to resolve AgentDefinition.SharedInstructionsName. When null, a definition that references a shared instructions block gets a compilation error.
agentGraph TraconAgentGraphOptions?
Tree-wide defaults, including the sub-agent wait limits (TraconAgentGraphOptions.ChildDeadline/TraconAgentGraphOptions.WaitTimeout) a definition’s own AgentDefinition.SubAgents may override. When null, the type’s own defaults apply.
timeProvider TimeProvider?
Time source for the sub-agent wait race. Defaults to TimeProvider.System.
loopEvaluators IEnumerable<TraconLoopEvaluatorRegistration>?
The loop stop criteria registered in code with
ITraconBuilder.AddLoopEvaluator. A definition whose
LoopSettings.Criteria names a kind that is neither built in
nor registered here gets a compilation error.
judgeOptions ModelRunJudgeOptions?
The judge binding configured with AddModelRunJudge. It is the model
an aiJudge loop criterion calls. When null or
unconfigured, that criterion gets a compilation error rather than
borrowing the agent’s own model.
Exceptions
Section titled “Exceptions”One of the required dependencies is null.
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.
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.
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 (see InstructionCultureResolver). 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 and
callable sub-agents 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.
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 own provider credential and egress policy (IModelProviderRegistry.CreateChatClientAsync) before building the client. When no tenant context or provider binding is registered, behavior is identical to the sync overload.
Exceptions
Section titled “Exceptions”definition is null.
The model provider cannot be found, the definition references a tool name that is not registered, the current tenant’s egress policy forbids the provider, or the tenant’s provider binding cannot be resolved to a credential value.
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.
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.
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.