.NET API

ITraconBuilder

Namespace Tracon · Assembly Tracon.Core.dll

The fluent chain that configures Tracon. Returned from the AddTracon call.

public interface ITraconBuilder

Extension Methods

TraconClientToolExtensions.AddClientTool(ITraconBuilder, string, string, JsonElement), TraconContentGuardBuilderExtensions.AddContentGuard<TGuard>(ITraconBuilder), TraconContentGuardBuilderExtensions.AddContentGuard(ITraconBuilder, IContentGuard), TraconContentGuardBuilderExtensions.AddContentGuard(ITraconBuilder, Func<IServiceProvider, IContentGuard>), TraconContentProtectionExtensions.AddContentProtection(ITraconBuilder, Action<TraconContentProtectionOptions>?), TraconContentProtectionExtensions.AddContentProtection<TProtector>(ITraconBuilder), TraconOnlineEvaluationBuilderExtensions.AddEvalEvaluatorFactory<TFactory>(ITraconBuilder), TraconOnlineEvaluationBuilderExtensions.AddEvalEvaluatorFactory(ITraconBuilder, IEvalEvaluatorFactory), TraconOnlineEvaluationBuilderExtensions.AddEvaluatorJudge(ITraconBuilder, string, IEvaluator), TraconOnlineEvaluationBuilderExtensions.AddEvaluatorJudge(ITraconBuilder, string, IEvaluator, Action<ModelRunJudgeOptions>), TraconOnlineEvaluationBuilderExtensions.AddModelRunJudge(ITraconBuilder, Action<ModelRunJudgeOptions>), TraconContentGuardBuilderExtensions.AddPatternContentGuard(ITraconBuilder, Action<PatternContentGuardOptions>?), TraconToolApprovalPolicyExtensions.AddToolApprovalPolicy(ITraconBuilder, string, Func<ToolApprovalContext, ToolApprovalPolicyDecision>), LiveVoiceBuilderExtensions.UseLiveVoice(ITraconBuilder, IConfiguration), LiveVoiceBuilderExtensions.UseLiveVoice(ITraconBuilder), LiveVoiceBuilderExtensions.UseLiveVoice(ITraconBuilder, Action<VoiceLiveOptions>), TraconSkillScriptBuilderExtensions.UseSkillScripts(ITraconBuilder, Action<TraconSkillScriptOptions>), VoiceConversationBuilderExtensions.UseVoiceConversation(ITraconBuilder, IConfiguration), VoiceConversationBuilderExtensions.UseVoiceConversation(ITraconBuilder), VoiceConversationBuilderExtensions.UseVoiceConversation(ITraconBuilder, Action<VoiceConversationOptions>)

Remarks

Provider and storage packages add their own extensions to this chain: UsePostgreSql, UseOpenAI, and so on.

Properties

Services

The underlying service collection.

IServiceCollection Services { get; }

Property Value

IServiceCollection

Remarks

The escape hatch: anything Tracon does not model is registered here. Every Tracon service is registered with TryAdd, so registration ORDER decides who wins, and the two seam shapes behave differently.

For a single-instance seam (for example ITenantContext): a registration made before AddTracon wins outright, and only one registration remains. A registration made after AddTracon also wins for a direct resolve, but Tracon’s own registration is not removed - it stays behind as a second, unused entry.

For a multi-registration seam (for example IAgentDecorator): a registration made before AddTracon joins the list alongside the built-in ones. A registration made after AddTracon also joins the list - the built-in implementation keeps running too, which is a real behavior difference from the single-instance case above.

// Runs before AddTracon(), so this registration wins outright.
builder.Services.AddSingleton(new OrderGateway());
builder.AddTracon();

Methods

AddAgent(AgentDefinition)

Defines a declarative agent in code. The definition passes through the Tracon compiler; model and tool validation is applied.

ITraconBuilder AddAgent(AgentDefinition definition)

Parameters

definition AgentDefinition

The agent definition.

Returns

The chain, for further configuration.

Remarks

builder.AddTracon()
       .AddAgent(new AgentDefinition
       {
           Name = "support",
           Instructions = "Answer support questions from the order data.",
           Model = new ModelBinding { Provider = "openai", Model = "gpt-4o-mini" },
           ToolNames = ["get_order_status"],
       });

AddAgent(string, Func<IServiceProvider, AIAgent>, string?)

Defines a factory-based agent in code. How the agent is built is entirely up to the caller.

ITraconBuilder AddAgent(string name, Func<IServiceProvider, AIAgent> factory, string? description = null)

Parameters

name string

The agent name.

factory Func<IServiceProvider, AIAgent>

The factory that produces the agent.

description string?

A short description.

Returns

The chain, for further configuration.

AddAgentDecorator<TDecorator>()

Registers a custom agent decorator as a singleton.

ITraconBuilder AddAgentDecorator<TDecorator>() where TDecorator : class, IAgentDecorator

Returns

The chain, for further configuration.

Type Parameters

TDecorator

The decorator implementation type.

Remarks

Calling this method more than once for the same decorator type has no effect. The decorator joins the pipeline alongside Tracon’s own (run recording, telemetry, tool approval); see IAgentDecorator.Order for where it lands. It must be thread-safe because the catalog can decorate agents concurrently.

builder.AddTracon()
       .AddAgentDecorator<AuditingAgentDecorator>();

AddAgentDecorator(IAgentDecorator)

Registers a configured custom agent decorator as a singleton.

ITraconBuilder AddAgentDecorator(IAgentDecorator decorator)

Parameters

decorator IAgentDecorator

The decorator instance.

Returns

The chain, for further configuration.

AddAgentDecorator(Func<IServiceProvider, IAgentDecorator>)

Registers a custom agent-decorator factory as a singleton.

ITraconBuilder AddAgentDecorator(Func<IServiceProvider, IAgentDecorator> factory)

Parameters

factory Func<IServiceProvider, IAgentDecorator>

The factory that creates the decorator.

Returns

The chain, for further configuration.

AddAgentSource<TSource>()

Registers a custom agent source as a singleton.

ITraconBuilder AddAgentSource<TSource>() where TSource : class, IAgentSource

Returns

The chain, for further configuration.

Type Parameters

TSource

The source implementation type.

Remarks

Calling this method more than once for the same source type has no effect. The source can serve global or tenant-aware agents. It must be thread-safe because the catalog calls its methods concurrently.

builder.AddTracon()
       .AddAgentSource<GitAgentSource>();

AddAgentSource(IAgentSource)

Registers a configured custom agent source as a singleton.

ITraconBuilder AddAgentSource(IAgentSource source)

Parameters

source IAgentSource

The source instance.

Returns

The chain, for further configuration.

AddAgentSource(Func<IServiceProvider, IAgentSource>)

Registers a custom agent-source factory as a singleton.

ITraconBuilder AddAgentSource(Func<IServiceProvider, IAgentSource> factory)

Parameters

factory Func<IServiceProvider, IAgentSource>

The factory that creates the source.

Returns

The chain, for further configuration.

AddEvalCheck(string, EvalCheck)

Registers a custom eval check. Eval suites can reference it by this kind name in their checks field.

ITraconBuilder AddEvalCheck(string kind, EvalCheck check)

Parameters

kind string

The check type name. Must not collide with a built-in type (for example nonEmpty).

check EvalCheck

A code-written check that does not call the model.

Returns

The chain, for further configuration.

Remarks

An EvalCheck produced with Microsoft.Agents.AI.FunctionEvaluator.Create(...) is expected. Same reason as tools: custom logic is only defined in code, and a free-form expression cannot be written from the interface.

builder.AddTracon()
       .AddEvalCheck("mentionsOrderId", FunctionEvaluator.Create(
           "mentionsOrderId",
           response => response.Contains("order", StringComparison.OrdinalIgnoreCase)));

AddLoopEvaluator(string, LoopEvaluator)

Registers a code-defined loop stop criterion. A definition’s LoopSettings.Criteria can then reference it by this kind name.

ITraconBuilder AddLoopEvaluator(string kind, LoopEvaluator evaluator)

Parameters

kind string

The criterion name. It must not be one of the built-in kinds (completionMarker, todoCompletion, aiJudge, backgroundTaskCompletion); shadowing one is rejected, so the same definition cannot mean different things in two applications.

evaluator LoopEvaluator

The criterion. Microsoft.Agents.AI.DelegateLoopEvaluator wraps a plain function; a subclass of LoopEvaluator covers anything larger.

Returns

The chain, for further configuration.

Remarks

Same reason as tools and eval checks: a stop criterion whose logic is code is only ever defined in code. A definition arriving from the management API names the criterion, it never writes it.

The loop types are marked for evaluation only by Microsoft Agent Framework, so naming one in your own code needs the suppression below:

#pragma warning disable MAAI001
builder.AddTracon()
       .AddLoopEvaluator("hasCitations", new DelegateLoopEvaluator((context, ct) =>
           new ValueTask<LoopEvaluation>(
               context.LastResponse?.Text?.Contains("[1]", StringComparison.Ordinal) == true
                   ? LoopEvaluation.Stop()
                   : LoopEvaluation.Continue("Add a numbered citation for every claim."))));
#pragma warning restore MAAI001

AddModelProvider<TProvider>()

Registers a custom model provider as a singleton.

ITraconBuilder AddModelProvider<TProvider>() where TProvider : class, IModelProvider

Returns

The chain, for further configuration.

Type Parameters

TProvider

The provider implementation type.

Remarks

Calling this method more than once for the same provider type has no effect. Prefer this overload when the provider has no state to configure by hand; use ITraconBuilder.AddModelProvider or the factory overload when it does.

builder.AddTracon()
       .AddModelProvider<OnPremiseModelProvider>();

AddModelProvider(IModelProvider)

Registers a model provider.

ITraconBuilder AddModelProvider(IModelProvider provider)

Parameters

provider IModelProvider

The provider.

Returns

The chain, for further configuration.

Remarks

The shipped provider packages (UseOpenAI, UseAnthropic, and the rest) call this method. Register your own provider here when the model sits behind an endpoint none of them describes.

builder.AddTracon()
       .AddModelProvider(new OnPremiseModelProvider(endpoint));

AddModelProvider(Func<IServiceProvider, IModelProvider>)

Registers a model provider through a factory.

ITraconBuilder AddModelProvider(Func<IServiceProvider, IModelProvider> factory)

Parameters

factory Func<IServiceProvider, IModelProvider>

The factory that produces the provider.

Returns

The chain, for further configuration.

AddRunJudge<TJudge>()

Registers a custom run judge as a singleton.

ITraconBuilder AddRunJudge<TJudge>() where TJudge : class, IRunJudge

Returns

The chain, for further configuration.

Type Parameters

TJudge

The judge implementation type.

Remarks

Repeating this overload for the same implementation type has no effect. The container creates and owns the singleton. The judge must be thread-safe because evaluations can overlap, including when a timed-out call finishes after a retry starts.

builder.AddTracon()
       .AddRunJudge<ResponseQualityJudge>();

AddRunJudge(IRunJudge)

Registers a configured run-judge instance as a singleton.

ITraconBuilder AddRunJudge(IRunJudge judge)

Parameters

judge IRunJudge

The judge instance.

Returns

The chain, for further configuration.

Remarks

The caller owns the instance and any resources it holds. Different configured instances of the same CLR type are preserved. Their IRunJudge.Name values must still be unique.

AddRunJudge(Func<IServiceProvider, IRunJudge>)

Registers a run-judge factory as a singleton.

ITraconBuilder AddRunJudge(Func<IServiceProvider, IRunJudge> factory)

Parameters

factory Func<IServiceProvider, IRunJudge>

The factory that creates the judge.

Returns

The chain, for further configuration.

Remarks

The container owns the produced singleton. The factory must not capture a scoped dependency because the result outlives that scope. Different factories and configured results are preserved.

AddScopedTool(AIFunction, Action<ToolRegistrationOptions>)

Registers a tool that runs inside its own dependency-injection scope on every call.

ITraconBuilder AddScopedTool(AIFunction tool, Action<ToolRegistrationOptions> configure)

Parameters

tool AIFunction

The tool to register.

configure Action<ToolRegistrationOptions>

Configures the tool metadata.

Returns

The chain, for further configuration.

Remarks

Identical in shape to ITraconBuilder.AddTool — the one difference is the word “scoped”, and its meaning is exactly this: every call opens a fresh DependencyInjection.IServiceScope, exposes it through AIFunctionArguments.Services, and closes it as soon as the call finishes. Microsoft Agent Framework otherwise passes an empty provider there — a dependency resolved from AIFunctionArguments.Services without this method throws or returns nothing, it is never silently wrong.

Use this for a tool that needs a repository, a DbContext, or any other per-call dependency. Two concurrent calls never share a scope.

builder.AddTracon()
       .AddScopedTool(AIFunctionFactory.Create(
           async (string orderId, AIFunctionArguments arguments) =>
           {
               var orders = arguments.Services!.GetRequiredService<IOrderRepository>();
               return await orders.GetAsync(orderId);
           },
           "get_order"),
           options => options.RequiredPermission = "orders.read");

AddScopedTool(AIFunction)

Registers a tool that runs inside its own dependency-injection scope on every call, with default metadata.

ITraconBuilder AddScopedTool(AIFunction tool)

Parameters

tool AIFunction

The tool to register.

Returns

The chain, for further configuration.

AddSkill(AgentSkillDefinition)

Defines a skill in code. A skill defined in code takes precedence over a runtime skill with the same name.

ITraconBuilder AddSkill(AgentSkillDefinition skill)

Parameters

skill AgentSkillDefinition

The skill to register.

Returns

The chain, for further configuration.

Remarks

A skill is instruction text an agent loads by name; it carries no code.

builder.AddTracon()
       .AddSkill(new AgentSkillDefinition
       {
           TenantId = "default",
           Name = "refund-policy",
           Description = "How a refund decision is made.",
           Instructions = "A refund under 100 USD is approved without review.",
       });

AddTool(AIFunction, Action<ToolRegistrationOptions>)

Registers a tool.

ITraconBuilder AddTool(AIFunction tool, Action<ToolRegistrationOptions> configure)

Parameters

tool AIFunction

The tool to register.

configure Action<ToolRegistrationOptions>

Configures the tool metadata.

Returns

The chain, for further configuration.

Remarks

The AOT-safe overload: the caller supplies the built AI.AIFunction, so no reflection is involved.

builder.AddTracon()
       .AddTool(refundTool, options => options.RequiresApproval = true);

AddTool(AIFunction)

Registers a tool with default metadata.

ITraconBuilder AddTool(AIFunction tool)

Parameters

tool AIFunction

The tool to register.

Returns

The chain, for further configuration.

AddTool(Delegate, string?, string?, Action<ToolRegistrationOptions>?)

Builds and registers a tool from a method.

[RequiresUnreferencedCode("Building a tool from a method uses reflection; type information may be lost in trimmed applications.")]
[RequiresDynamicCode("Building a tool from a method may require code generation at runtime.")]
ITraconBuilder AddTool(Delegate method, string? name = null, string? description = null, Action<ToolRegistrationOptions>? configure = null)

Parameters

method Delegate

The method to expose as a tool.

name string?

The tool name.

description string?

The tool description.

configure Action<ToolRegistrationOptions>?

Configures the tool metadata.

Returns

The chain, for further configuration.

AddToolsFrom<T>()

Registers, as tools, the methods on a type that are marked with TraconToolAttribute.

[RequiresUnreferencedCode("Tool scanning uses reflection; method information may be lost in trimmed applications.")]
[RequiresDynamicCode("Tool scanning may require code generation at runtime.")]
ITraconBuilder AddToolsFrom<T>()

Returns

The chain, for further configuration.

Type Parameters

T

The type to scan.

Remarks

Marking is an explicit choice: every new method added to the class is not automatically exposed to agents. Static methods bind directly; for instance methods, the owning object is resolved from the service provider at call time.

A static class cannot be a type argument (a C# rule). If your tools live in a static class, use the ITraconBuilder.AddToolsFrom overload instead.

This method uses reflection and is not safe under trimming or native AOT scenarios. Applications targeting AOT should use the ITraconBuilder.AddTool overload instead.

builder.AddTracon()
       .AddToolsFrom<OrderTools>();

Exceptions

TraconException

T has no marked method, or a marked method cannot be converted to a tool.

AddToolsFrom(Type)

Registers, as tools, the methods on a type that are marked with TraconToolAttribute.

[RequiresUnreferencedCode("Tool scanning uses reflection; method information may be lost in trimmed applications.")]
[RequiresDynamicCode("Tool scanning may require code generation at runtime.")]
ITraconBuilder AddToolsFrom(Type type)

Parameters

type Type

The type to scan. May be a static class.

Returns

The chain, for further configuration.

Remarks

A static class cannot be a type argument under C# rules; this overload makes the AddToolsFrom(typeof(OrderTools)) form possible.

Exceptions

ArgumentNullException

type is null.

TraconException

type has no marked method, or a marked method cannot be converted to a tool.

Configure(Action<TraconOptions>)

Modifies the runtime settings.

ITraconBuilder Configure(Action<TraconOptions> configure)

Parameters

configure Action<TraconOptions>

The settings modifier.

Returns

The chain, for further configuration.

Remarks

Runs after the configuration section is bound, so a value set here wins over appsettings.json.

builder.AddTracon()
       .Configure(options => options.Tools.DefaultTimeout = TimeSpan.FromSeconds(60));

RequireCustomBinding<T>()

Declares that T must resolve to the application’s own registration. The host does not start when Tracon’s built-in default is what resolves.

ITraconBuilder RequireCustomBinding<T>() where T : class

Returns

The chain, for further configuration.

Type Parameters

T

One of the seven embedding points: ITenantContext, IRunAttributionContext, IToolAuthorizationHandler, IRunAuthorizationHandler, IRunEventSink, IAttachmentStorage, or IToolApprovalPresenter. Any other type stops the host from starting, with a message naming the seven.

Remarks

Off by default: an application that never calls this behaves exactly as before. Every extension point is registered with TryAdd, so a host that binds nothing runs on the built-in default and starts silently. That suits a first run; it does not suit a deployment whose module order can leave an authorization handler on the permissive default without anyone noticing until the first unauthorized request.

The check runs while the host starts, not when endpoints are mapped, so an embedded host with no HTTP surface gets the same guarantee. Register the implementation BEFORE AddTracon: a TryAdd registration made afterwards is dropped, and the built-in default stays.

This is a composition gate. It proves which implementation is bound; it proves nothing about whether that implementation decides correctly.

builder.Services.AddSingleton<IRunAuthorizationHandler, OrderDeskAuthorization>();

builder.AddTracon()
       .RequireCustomBinding<IRunAuthorizationHandler>()
       .RequireCustomBinding<IToolAuthorizationHandler>();