| | | 1 | | using Microsoft.Extensions.DependencyInjection; |
| | | 2 | | using Microsoft.Extensions.DependencyInjection.Extensions; |
| | | 3 | | |
| | | 4 | | namespace NexusLabs.Needlr.AgentFramework; |
| | | 5 | | |
| | | 6 | | /// <summary> |
| | | 7 | | /// Fluent builder for configuring the Microsoft Agent Framework with Needlr function discovery. |
| | | 8 | | /// </summary> |
| | | 9 | | /// <remarks> |
| | | 10 | | /// <para> |
| | | 11 | | /// When the Needlr source generator is active (the common case), this class uses pre-built |
| | | 12 | | /// <see cref="IAIFunctionProvider"/> instances registered by the generated <c>[ModuleInitializer]</c>. |
| | | 13 | | /// No reflection is required in that path. |
| | | 14 | | /// </para> |
| | | 15 | | /// <para> |
| | | 16 | | /// When the source generator is not used, this class falls back to reflection to discover |
| | | 17 | | /// methods decorated with <see cref="AgentFunctionAttribute"/>. That path carries |
| | | 18 | | /// <c>[RequiresDynamicCode]</c> and is not NativeAOT-compatible. |
| | | 19 | | /// </para> |
| | | 20 | | /// </remarks> |
| | | 21 | | /// <example> |
| | | 22 | | /// <code> |
| | | 23 | | /// // Obtained from SyringeAgentFrameworkExtensions.UsingAgentFramework() |
| | | 24 | | /// AgentFrameworkSyringe syringe = app.Services.UsingAgentFramework(); |
| | | 25 | | /// |
| | | 26 | | /// // Register function types and build the factory |
| | | 27 | | /// IAgentFactory factory = syringe |
| | | 28 | | /// .AddAgentFunctionsFromGenerated(GeneratedAgentFunctions.AllFunctionTypes) |
| | | 29 | | /// .BuildAgentFactory(); |
| | | 30 | | /// |
| | | 31 | | /// // Create agents from the factory |
| | | 32 | | /// var supportAgent = factory.CreateAgent<CustomerSupportAgent>(); |
| | | 33 | | /// </code> |
| | | 34 | | /// </example> |
| | | 35 | | [DoNotAutoRegister] |
| | | 36 | | public sealed record AgentFrameworkSyringe |
| | | 37 | | { |
| | 430 | 38 | | public required IServiceProvider ServiceProvider { get; init; } |
| | | 39 | | |
| | 954 | 40 | | internal List<Action<AgentFrameworkConfigureOptions>>? ConfigureAgentFactory { get; init; } = []; |
| | | 41 | | |
| | 1040 | 42 | | internal List<Type>? FunctionTypes { get; init; } = []; |
| | | 43 | | |
| | 813 | 44 | | internal IReadOnlyDictionary<string, IReadOnlyList<Type>>? FunctionGroupMap { get; init; } |
| | | 45 | | |
| | 1572 | 46 | | internal List<Type>? AgentTypes { get; init; } = []; |
| | | 47 | | |
| | | 48 | | /// <summary> |
| | | 49 | | /// Agent-builder plugins applied to every agent created by the factory. |
| | | 50 | | /// Populated by middleware extension methods such as <c>UsingToolResultMiddleware()</c> |
| | | 51 | | /// and <c>UsingResilience()</c>. |
| | | 52 | | /// </summary> |
| | 294 | 53 | | internal IReadOnlyList<IAIAgentBuilderPlugin>? Plugins { get; init; } |
| | | 54 | | |
| | | 55 | | /// <summary> |
| | | 56 | | /// Factory that creates an <see cref="IAIAgentBuilderPlugin"/> from a |
| | | 57 | | /// <see cref="AgentResilienceAttribute"/> found on an agent type. |
| | | 58 | | /// Set by <c>UsingResilience()</c> to enable per-agent resilience overrides via |
| | | 59 | | /// <c>[AgentResilience]</c>. |
| | | 60 | | /// </summary> |
| | 197 | 61 | | internal Func<AgentResilienceAttribute, IAIAgentBuilderPlugin>? PerAgentResilienceFactory { get; init; } |
| | | 62 | | |
| | | 63 | | /// <summary> |
| | | 64 | | /// Metrics configuration (meter name, ActivitySource name). Populated by |
| | | 65 | | /// <c>ConfigureMetrics()</c>. |
| | | 66 | | /// </summary> |
| | 44 | 67 | | internal Diagnostics.AgentFrameworkMetricsOptions? MetricsOptions { get; init; } |
| | | 68 | | |
| | | 69 | | /// <summary> |
| | | 70 | | /// Whether <c>UsingTokenTracking()</c> has already been called. Prevents |
| | | 71 | | /// double-wiring the recording middleware when both <c>UsingTokenBudget()</c> |
| | | 72 | | /// and <c>UsingDiagnostics()</c> are used together. |
| | | 73 | | /// </summary> |
| | 73 | 74 | | internal bool TokenTrackingWired { get; init; } |
| | | 75 | | |
| | | 76 | | public IAgentFactory BuildAgentFactory() |
| | | 77 | | { |
| | 189 | 78 | | var groupTypes = (FunctionGroupMap ?? new Dictionary<string, IReadOnlyList<Type>>()) |
| | 319 | 79 | | .SelectMany(kvp => kvp.Value); |
| | | 80 | | |
| | 189 | 81 | | var allFunctionTypes = (FunctionTypes ?? []) |
| | 189 | 82 | | .Concat(groupTypes) |
| | 189 | 83 | | .Distinct() |
| | 189 | 84 | | .ToList(); |
| | | 85 | | |
| | 189 | 86 | | var agentTypeMap = new Dictionary<string, Type>(StringComparer.Ordinal); |
| | 1059 | 87 | | foreach (var t in AgentTypes ?? []) |
| | | 88 | | { |
| | 341 | 89 | | var key = t.FullName ?? t.Name; |
| | 341 | 90 | | if (!agentTypeMap.TryAdd(key, t)) |
| | | 91 | | { |
| | 1 | 92 | | throw new InvalidOperationException( |
| | 1 | 93 | | $"Duplicate agent registration: '{key}' is already registered as " + |
| | 1 | 94 | | $"'{agentTypeMap[key].AssemblyQualifiedName}'. Cannot also register " + |
| | 1 | 95 | | $"'{t.AssemblyQualifiedName}'. Ensure each [NeedlrAiAgent] class has a unique fully-qualified name." |
| | | 96 | | } |
| | | 97 | | } |
| | | 98 | | |
| | 188 | 99 | | AgentFrameworkGeneratedBootstrap.TryGetAIFunctionProvider(out var generatedProvider); |
| | | 100 | | |
| | 188 | 101 | | return new AgentFactory( |
| | 188 | 102 | | serviceProvider: ServiceProvider, |
| | 188 | 103 | | configureCallbacks: ConfigureAgentFactory ?? [], |
| | 188 | 104 | | functionTypes: allFunctionTypes, |
| | 188 | 105 | | functionGroupMap: FunctionGroupMap, |
| | 188 | 106 | | agentTypeMap: agentTypeMap, |
| | 188 | 107 | | generatedProvider: generatedProvider, |
| | 188 | 108 | | plugins: Plugins ?? [], |
| | 188 | 109 | | perAgentResilienceFactory: PerAgentResilienceFactory); |
| | | 110 | | } |
| | | 111 | | } |