IAgentPrismBuilder

Namespace AgentPrism · Assembly AgentPrism.Core.dll

The fluent chain that configures AgentPrism. Returned from the AddAgentPrism call.

public interface IAgentPrismBuilder

Extension Methods

AgentPrismClientToolExtensions.AddClientTool(IAgentPrismBuilder, string, string, JsonElement), AgentPrismContentGuardBuilderExtensions.AddContentGuard<TGuard>(IAgentPrismBuilder), AgentPrismOnlineEvaluationBuilderExtensions.AddModelRunJudge(IAgentPrismBuilder, Action<ModelRunJudgeOptions>), AgentPrismContentGuardBuilderExtensions.AddPatternContentGuard(IAgentPrismBuilder, Action<PatternContentGuardOptions>?), AgentPrismToolApprovalPolicyExtensions.AddToolApprovalPolicy(IAgentPrismBuilder, string, Func<ToolApprovalContext, ToolApprovalPolicyDecision>), AgentPrismSkillScriptBuilderExtensions.UseSkillScripts(IAgentPrismBuilder, Action<AgentPrismSkillScriptOptions>), VoiceConversationBuilderExtensions.UseVoiceConversation(IAgentPrismBuilder, IConfiguration), VoiceConversationBuilderExtensions.UseVoiceConversation(IAgentPrismBuilder), VoiceConversationBuilderExtensions.UseVoiceConversation(IAgentPrismBuilder, 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 AgentPrism does not model is registered here, and a registration made before AddAgentPrism wins over AgentPrism’s own, because every AgentPrism service is registered with TryAdd.

builder.AddAgentPrism()
       .Services.AddSingleton<IOrderGateway, OrderGateway>();

Methods

AddAgent(AgentDefinition)

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

IAgentPrismBuilder AddAgent(AgentDefinition definition)

Parameters

definition AgentDefinition

The agent definition.

Returns

IAgentPrismBuilder

The chain, for further configuration.

Remarks

builder.AddAgentPrism()
       .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.

IAgentPrismBuilder 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

IAgentPrismBuilder

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.

IAgentPrismBuilder 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

IAgentPrismBuilder

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.AddAgentPrism()
       .AddEvalCheck("mentionsOrderId", FunctionEvaluator.Create(
           "mentionsOrderId",
           response => response.Contains("order", StringComparison.OrdinalIgnoreCase)));

AddModelProvider(IModelProvider)

Registers a model provider.

IAgentPrismBuilder AddModelProvider(IModelProvider provider)

Parameters

provider IModelProvider

The provider.

Returns

IAgentPrismBuilder

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.AddAgentPrism()
       .AddModelProvider(new OnPremiseModelProvider(endpoint));

AddModelProvider(Func<IServiceProvider, IModelProvider>)

Registers a model provider through a factory.

IAgentPrismBuilder AddModelProvider(Func<IServiceProvider, IModelProvider> factory)

Parameters

factory Func<IServiceProvider, IModelProvider>

The factory that produces the provider.

Returns

IAgentPrismBuilder

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.

IAgentPrismBuilder AddSkill(AgentSkillDefinition skill)

Parameters

skill AgentSkillDefinition

The skill to register.

Returns

IAgentPrismBuilder

The chain, for further configuration.

Remarks

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

builder.AddAgentPrism()
       .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, bool)

Registers a tool.

IAgentPrismBuilder AddTool(AIFunction tool, bool requiresApproval)

Parameters

tool AIFunction

The tool to register.

requiresApproval bool

Whether explicit approval is required before the call.

Returns

IAgentPrismBuilder

The chain, for further configuration.

Remarks

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

builder.AddAgentPrism()
       .AddTool(refundTool, requiresApproval: true);

AddTool(Delegate, string?, string?, bool)

Builds a tool from a method and registers it.

[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.")]
IAgentPrismBuilder AddTool(Delegate method, string? name = null, string? description = null, bool requiresApproval = false)

Parameters

method Delegate

The method to expose as a tool.

name string?

The tool name. If left empty, the method name is used.

description string?

A description that tells the model when to call the tool.

requiresApproval bool

Whether explicit approval is required before the call.

Returns

IAgentPrismBuilder

The chain, for further configuration.

Remarks

This overload uses reflection through AIFunctionFactory and is therefore not safe under trimming or native AOT scenarios. Applications targeting AOT should use the IAgentPrismBuilder.AddTool overload instead.

AddToolsFrom<T>()

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

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

Returns

IAgentPrismBuilder

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 IAgentPrismBuilder.AddToolsFrom overload instead.

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

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

Exceptions

AgentPrismException

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 AgentPrismToolAttribute.

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

Parameters

type Type

The type to scan. May be a static class.

Returns

IAgentPrismBuilder

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.

AgentPrismException

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

Configure(Action<AgentPrismOptions>)

Modifies the runtime settings.

IAgentPrismBuilder Configure(Action<AgentPrismOptions> configure)

Parameters

configure Action<AgentPrismOptions>

The settings modifier.

Returns

IAgentPrismBuilder

The chain, for further configuration.

Remarks

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

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