diff --git a/demo/AgentCore.Demo/config/example.yaml b/demo/AgentCore.Demo/config/example.yaml index 57b09baf..77e364b7 100644 --- a/demo/AgentCore.Demo/config/example.yaml +++ b/demo/AgentCore.Demo/config/example.yaml @@ -163,6 +163,10 @@ tools: # ISecretResolverPort resolves it at startup through the four-step chain in D22. headers: { Authorization: "Bearer ${secret:orders-api-key}" } + # A binds: name is registered one of two ways, and the way decides who writes the schema. + # + # options.Bind("CreateCase", (json, ct) => ...) reads the arguments as one JSON object, so the + # declaration writes parameters: below and the host digs the values out by hand. - id: create_case kind: binding binds: CreateCase @@ -172,6 +176,16 @@ tools: properties: { summary: { type: string } } required: [ summary ] + # options.Bind("CloseCase", (string caseId, string reason) => ...) registers a typed method + # instead. Its parameters are the arguments, and their schema, so this declaration writes no + # parameters: at all. Writing one anyway is a boot failure: the two would drift apart. + # A [Description] attribute on a parameter is what the model reads about it. + # + # - id: close_case + # kind: binding + # binds: CloseCase + # description: Close a service case once the customer is happy. + # kind: agent is agent-as-tool, and it is not handoff. The outer agent calls the inner agent, # reads the reply, and keeps control. graph: with pattern: handoff transfers control instead, # so the two do not overlap. The compiler wraps the inner agent with AsAIFunction(), and the diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index d28ca41c..f22050c2 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -1199,8 +1199,10 @@ AgentCore.Application.Tools.Binding.ToolBindingRegistry.Contains(string! name) - AgentCore.Application.Tools.Binding.ToolBindingRegistry.Count.get -> int AgentCore.Application.Tools.Binding.ToolBindingRegistry.Names.get -> System.Collections.Generic.IReadOnlyCollection! AgentCore.Application.Tools.Binding.ToolBindingRegistry.Register(string! name, AgentCore.Application.Tools.Binding.ToolBinding! binding) -> AgentCore.Application.Tools.Binding.ToolBindingRegistry! +AgentCore.Application.Tools.Binding.ToolBindingRegistry.Register(string! name, System.Delegate! method) -> AgentCore.Application.Tools.Binding.ToolBindingRegistry! AgentCore.Application.Tools.Binding.ToolBindingRegistry.ToolBindingRegistry() -> void AgentCore.Application.Tools.Binding.ToolBindingRegistry.TryGetBinding(string! name, out AgentCore.Application.Tools.Binding.ToolBinding? binding) -> bool +AgentCore.Application.Tools.Binding.ToolBindingRegistry.TryGetMethod(string! name, out System.Delegate? method) -> bool AgentCore.Application.Tools.Builtin.BuiltinToolNames AgentCore.Application.Tools.Builtin.BuiltinToolPorts AgentCore.Application.Tools.Builtin.BuiltinToolPorts.$() -> AgentCore.Application.Tools.Builtin.BuiltinToolPorts! diff --git a/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs b/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs index 8267f2b9..4f4ae5d3 100644 --- a/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs +++ b/src/AgentCore.Application/Tools/Binding/BindingToolSource.cs @@ -22,7 +22,10 @@ public BindingToolSource(ToolBindingRegistry registry) } /// - /// A binds: name is missing or not registered. + /// + /// A binds: name is missing, is not registered, or names a typed method while the + /// declaration also writes parameters:. + /// public ValueTask> ProvideAsync( ToolSourceContext context, CancellationToken cancellationToken = default) { @@ -36,6 +39,23 @@ public ValueTask> ProvideAsync( throw ToolSourceError.Fail($"the tool '{declared.Id}' is kind: binding and names no binds:."); } + if (_registry.TryGetMethod(name, out var method) && method is not null) + { + if (declared.Parameters is not null) + { + throw ToolSourceError.Fail( + $"the tool '{declared.Id}' binds to '{name}', which the host registered as a typed " + + "method, and it also declares parameters:. The method signature is the schema, so " + + "the two disagree the moment either one changes. Take the parameters: off the " + + "declaration, or register the name as a ToolBinding instead."); + } + + var typed = method; + registrations.Add(new ToolRegistration( + declared.Id, declared.Description ?? string.Empty, () => new TypedBindingTool(declared, typed))); + continue; + } + if (!_registry.TryGetBinding(name, out var binding) || binding is null) { throw ToolSourceError.Fail( diff --git a/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs b/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs index a3b5ccae..1228d5f5 100644 --- a/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs +++ b/src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs @@ -17,7 +17,7 @@ namespace AgentCore.Application.Tools.Binding; /// public sealed class ToolBindingRegistry { - private readonly Dictionary _bindings = new(StringComparer.Ordinal); + private readonly Dictionary _bindings = new(StringComparer.Ordinal); /// Gets the number of names the host registered. public int Count => _bindings.Count; @@ -25,25 +25,33 @@ public sealed class ToolBindingRegistry /// Gets the names the host registered. public IReadOnlyCollection Names => _bindings.Keys; - /// Registers one host delegate. + /// Registers one host delegate that reads the arguments as JSON. /// The name a binds: field writes. /// The delegate the tool calls. /// This registry, so a host chains its registrations. /// The name is already registered. public ToolBindingRegistry Register(string name, ToolBinding binding) { - ArgumentException.ThrowIfNullOrEmpty(name); ArgumentNullException.ThrowIfNull(binding); + return Add(name, binding); + } - if (!_bindings.TryAdd(name, binding)) - { - throw new ArgumentException($"the binding '{name}' is already registered.", nameof(name)); - } - - return this; + /// Registers one host method, and its parameters become the tool's arguments. + /// The name a binds: field writes. + /// + /// The method the tool calls. Its parameters are the arguments the model fills, and their JSON + /// Schema, so the declaration this name serves must write no parameters:. A + /// on a parameter reaches the model. + /// + /// This registry, so a host chains its registrations. + /// The name is already registered. + public ToolBindingRegistry Register(string name, Delegate method) + { + ArgumentNullException.ThrowIfNull(method); + return Add(name, method); } - /// Reports whether one name is registered. + /// Reports whether one name is registered, either way. /// The name a binds: field writes. /// when the host registered the name. public bool Contains(string name) @@ -52,13 +60,51 @@ public bool Contains(string name) return _bindings.ContainsKey(name); } - /// Reads the delegate one name points at. + /// Reads the JSON delegate one name points at. /// The name a binds: field writes. - /// The delegate, when the name is registered. - /// when the host registered the name. + /// The delegate, when the host registered this name as a JSON delegate. + /// + /// when the host registered the name as a . A + /// name the host registered as a typed method answers ; read it with + /// . + /// public bool TryGetBinding(string name, out ToolBinding? binding) { ArgumentNullException.ThrowIfNull(name); - return _bindings.TryGetValue(name, out binding); + + binding = _bindings.TryGetValue(name, out var registered) ? registered as ToolBinding : null; + + return binding is not null; + } + + /// Reads the typed method one name points at. + /// The name a binds: field writes. + /// The method, when the host registered this name as a typed method. + /// + /// when the host registered the name as a typed method. A name the host + /// registered as a answers ; read it with + /// . + /// + public bool TryGetMethod(string name, out Delegate? method) + { + ArgumentNullException.ThrowIfNull(name); + + method = _bindings.TryGetValue(name, out var registered) && registered is not ToolBinding + ? registered + : null; + + return method is not null; + } + + private ToolBindingRegistry Add(string name, Delegate registered) + { + ArgumentException.ThrowIfNullOrEmpty(name); + + if (!_bindings.TryAdd(name, registered)) + { + throw new ArgumentException($"the binding '{name}' is already registered.", nameof(name)); + } + + return this; } } diff --git a/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs b/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs new file mode 100644 index 00000000..f584f2f8 --- /dev/null +++ b/src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs @@ -0,0 +1,28 @@ +using System.Text.Json; +using AgentCore.Application.Configuration.Schema; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Tools.Binding; + +/// +/// One kind: binding tool whose arguments come from a host method's signature. +/// +internal sealed class TypedBindingTool : DeclaredTool +{ + private readonly AIFunction _inner; + + internal TypedBindingTool(ToolConfiguration tool, Delegate method) + : base(tool) + => _inner = AIFunctionFactory.Create(method, tool.Id, tool.Description); + + /// + /// Gets the schema the host method's parameters describe. It replaces the base schema, which + /// reads the document's parameters:, because a typed binding declares none. + /// + public override JsonElement JsonSchema => _inner.JsonSchema; + + protected override ValueTask CallAsync( + AIFunctionArguments arguments, + CancellationToken cancellationToken) + => _inner.InvokeAsync(arguments, cancellationToken); +} diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs index 03e92b82..4aa6c5c3 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs @@ -303,4 +303,18 @@ public AgentCoreOptions Bind(string name, ToolBinding binding) Bindings.Register(name, binding); return this; } + + /// Registers one host method behind a binds: name. + /// The name a binds: field writes, such as CreateCase. + /// + /// The method the tool calls. Its parameters are the arguments the model fills, and their JSON + /// Schema, so the declaration writes no parameters:. + /// + /// These options, so a host chains its calls. + /// The name is already registered. + public AgentCoreOptions Bind(string name, Delegate method) + { + Bindings.Register(name, method); + return this; + } } diff --git a/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt b/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt index 2059545f..7684ad40 100644 --- a/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt +++ b/src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt @@ -11,6 +11,7 @@ AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.AddToolSource(System.Func! toolSource) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.AgentCoreOptions() -> void AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Bind(string! name, AgentCore.Application.Tools.Binding.ToolBinding! binding) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! +AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Bind(string! name, System.Delegate! method) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions! AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Bindings.get -> AgentCore.Application.Tools.Binding.ToolBindingRegistry! AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Configuration.get -> AgentCore.Application.Configuration.Schema.AgentCoreConfiguration? AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Configuration.set -> void diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs index d659a453..c994b4fa 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs @@ -17,6 +17,28 @@ namespace AgentCore.Application.Tests.Configuration.Validation; /// public sealed class ConfigurationValidatorTests { + /// The smallest provider set that satisfies checks 1 and 2 on its own. + private const string MinimalProviders = + """ + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + llm: + - { kind: openai, model: gpt-4.1-mini, as: reply } + """; + + /// without llm:, for checks that never read a model. + private const string SpeechOnlyProviders = + """ + providers: + call: { kind: telnyx-relay } + speech: + stt: { kind: telnyx-relay } + tts: { kind: telnyx-relay } + """; + [Fact] public void TheExample_PassesEveryCheck() { @@ -116,18 +138,12 @@ public void AnUnknownGuard_FailsCheckTwoWithThePointerOfTheExit() [Fact] public void AnUnknownExtractorModel_FailsCheckTwoWithThePointerOfTheReference() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: broken extractor: model: { ref: ghost } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); @@ -139,18 +155,12 @@ public void AnUnknownExtractorModel_FailsCheckTwoWithThePointerOfTheReference() [Fact] public void AnUnknownJudgeModel_FailsCheckTwoWithThePointerOfTheReference() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: broken evaluation: judge: { ref: ghost } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); @@ -162,18 +172,12 @@ public void AnUnknownJudgeModel_FailsCheckTwoWithThePointerOfTheReference() [Fact] public void AnUnknownTitlerModel_FailsCheckTwoWithThePointerOfTheReference() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: broken titler: model: { ref: ghost } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); @@ -185,18 +189,12 @@ public void AnUnknownTitlerModel_FailsCheckTwoWithThePointerOfTheReference() [Fact] public void AnEvaluationSectionWithNoJudge_PassesCheckTwo() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: quiet evaluation: sampleRate: 0 - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; Assert.Empty(Evaluate(document, ConfigurationCheck.ReferenceResolution)); @@ -205,19 +203,13 @@ public void AnEvaluationSectionWithNoJudge_PassesCheckTwo() [Fact] public void AnUnknownAgentModel_FailsCheckTwoWithThePointerOfThatAgent() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: broken agents: items: - { id: greeter, model: { ref: ghost } } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); @@ -229,7 +221,7 @@ public void AnUnknownAgentModel_FailsCheckTwoWithThePointerOfThatAgent() [Fact] public void AnUnknownDefaultModel_FailsCheckTwoWithThePointerOfTheDefaults() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: broken agents: @@ -237,13 +229,7 @@ public void AnUnknownDefaultModel_FailsCheckTwoWithThePointerOfTheDefaults() model: { ref: ghost } items: - { id: greeter } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; var error = Assert.Single(Evaluate(document, ConfigurationCheck.ReferenceResolution)); @@ -399,6 +385,50 @@ private static AgentCoreConfiguration Scoped( private static ExtractorConfiguration AnExtractor() => new() { Model = new ModelReference { Ref = "small" } }; + /// One facet slot, named by and by fromState. + private static AgentCoreConfiguration OneFacetScope( + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) => + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = FacetSlot() }, + AnExtractor(), + ambiguity, + mapper); + + /// with a vocabulary slot in place of the facet slot. + private static AgentCoreConfiguration OneVocabularyScope( + StateSlotConfiguration slot, + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) => + Scoped( + ["applies_to"], + Star, + new Dictionary { ["applies_to"] = slot }, + AnExtractor(), + ambiguity, + mapper); + + /// + /// Two facet slots. This is the smallest scope that keeps the single-facet ambiguity warning + /// (K33) silent, so it is the base for every test that asserts no warning. + /// + private static AgentCoreConfiguration TwoFacetScope( + KnowledgeAmbiguityConfiguration? ambiguity = null, + string? mapper = null) => + Scoped( + ["applies_to", "brand"], + new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }, + new Dictionary + { + ["applies_to"] = FacetSlot(), + ["brand"] = FacetSlot(), + }, + AnExtractor(), + ambiguity, + mapper); + [Fact] public void Evaluate_FromStateNamesAnUndeclaredSlot_Fails() { @@ -575,13 +605,7 @@ public void Evaluate_FacetSlotDeclaresVocabularyInsteadOfEnum_PassesTheEnumRow() { var slot = FacetSlot() with { EnumValues = null, Vocabulary = new SlotVocabularyConfiguration { From = "knowledge" } }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(OneVocabularyScope(slot, AnAmbiguity())); Assert.Empty(result.Errors); } @@ -600,13 +624,7 @@ public void Evaluate_SlotDeclaresBothEnumAndVocabulary_Fails() { var slot = VocabSlot() with { EnumValues = [JsonValue.Create("f63")!] }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(OneVocabularyScope(slot, AnAmbiguity())); var error = Assert.Single(result.Errors); Assert.Equal("/state/applies_to/vocabulary", error.Pointer); @@ -669,13 +687,7 @@ public void Evaluate_VocabularyMaxValuesBelowTwo_Fails() { var slot = VocabSlot(new SlotVocabularyConfiguration { From = "knowledge", MaxValues = 1 }); - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(OneVocabularyScope(slot, AnAmbiguity())); var error = Assert.Single(result.Errors); Assert.Equal("/state/applies_to/vocabulary/maxValues", error.Pointer); @@ -687,13 +699,7 @@ public void Evaluate_VocabularyRefreshSecondsNegative_Fails() { var slot = VocabSlot(new SlotVocabularyConfiguration { From = "knowledge", RefreshSeconds = -5 }); - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(OneVocabularyScope(slot, AnAmbiguity())); var error = Assert.Single(result.Errors); Assert.Equal("/state/applies_to/vocabulary/refreshSeconds", error.Pointer); @@ -703,12 +709,7 @@ public void Evaluate_VocabularyRefreshSecondsNegative_Fails() [Fact] public void Evaluate_VocabularyWithNoAmbiguity_Fails() { - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = VocabSlot() }, - AnExtractor())); + var result = ConfigurationValidator.EvaluateStructure(OneVocabularyScope(VocabSlot())); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity", error.Pointer); @@ -729,13 +730,7 @@ public void Evaluate_AmbiguityMaxCandidatesBelowTwo_Fails() { var ambiguity = new KnowledgeAmbiguityConfiguration { MaxCandidates = 1 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity/maxCandidates", error.Pointer); @@ -746,13 +741,7 @@ public void Evaluate_AmbiguityMaxAsksBelowZero_Fails() { var ambiguity = new KnowledgeAmbiguityConfiguration { MaxAsks = -1 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity/maxAsks", error.Pointer); @@ -764,13 +753,7 @@ public void Evaluate_AmbiguityMaxAsksOfZero_IsLegal() // K38: 0 means gate only. It must never trip the same floor that refuses a negative count. var ambiguity = new KnowledgeAmbiguityConfiguration { MaxAsks = 0 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); Assert.Empty(result.Errors); } @@ -780,13 +763,7 @@ public void Evaluate_AmbiguityProbeDeadlineSecondsBelowOne_Fails() { var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 0 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity/probeDeadlineSeconds", error.Pointer); @@ -797,13 +774,7 @@ public void Evaluate_AmbiguityProbeWaitMarginSecondsBelowOne_Fails() { var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeWaitMarginSeconds = 0 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); @@ -813,13 +784,7 @@ public void Evaluate_AmbiguityProbeWaitMarginSecondsBelowOne_Fails() public void Evaluate_VocabularyWithCustomMapper_Fails() { var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = VocabSlot() }, - AnExtractor(), - ambiguity: AnAmbiguity(), - mapper: "custom-mapper")); + OneVocabularyScope(VocabSlot(), AnAmbiguity(), mapper: "custom-mapper")); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/mapper", error.Pointer); @@ -830,20 +795,8 @@ public void Evaluate_AmbiguityWithCustomMapperAndNoVocabulary_Fails() { // The probe reads Extras, and nothing about vocabulary puts it there. A document that declares // ambiguity without vocabulary must still be refused a mapper that leaves Extras empty. - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to", "brand"], - wildcard, - new Dictionary - { - ["applies_to"] = FacetSlot(), - ["brand"] = FacetSlot(), - }, - AnExtractor(), - ambiguity: AnAmbiguity(), - mapper: "custom-mapper")); + TwoFacetScope(AnAmbiguity(), mapper: "custom-mapper")); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/mapper", error.Pointer); @@ -855,13 +808,7 @@ public void Evaluate_AmbiguityProbeDeadlineSecondsAboveTheTimerCeiling_Fails() // CancelAfter throws above int.MaxValue milliseconds, from a call site with no pointer. var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeDeadlineSeconds = 3_000_000 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity/probeDeadlineSeconds", error.Pointer); @@ -873,13 +820,7 @@ public void Evaluate_AmbiguityProbeWaitMarginSecondsAboveTheTimerCeiling_Fails() { var ambiguity = new KnowledgeAmbiguityConfiguration { ProbeWaitMarginSeconds = 3_000_000 }; - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: ambiguity)); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(ambiguity)); var error = Assert.Single(result.Errors); Assert.Equal("/providers/knowledge/ambiguity/probeWaitMarginSeconds", error.Pointer); @@ -891,13 +832,7 @@ public void Evaluate_VocabularyRefreshSecondsAboveTheTimerCeiling_Fails() // PeriodicTimer throws above uint.MaxValue - 1 milliseconds, inside BootAsync. var slot = VocabSlot(new SlotVocabularyConfiguration { From = "knowledge", RefreshSeconds = 86_400_000 }); - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = slot }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(OneVocabularyScope(slot, AnAmbiguity())); var error = Assert.Single(result.Errors); Assert.Equal("/state/applies_to/vocabulary/refreshSeconds", error.Pointer); @@ -919,13 +854,7 @@ public void Evaluate_AmbiguityWithEmptyFromState_Warns() [Fact] public void Evaluate_AmbiguityWithSingleFacetFromState_Warns() { - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to"], - Star, - new Dictionary { ["applies_to"] = FacetSlot() }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(OneFacetScope(AnAmbiguity())); Assert.Empty(result.Errors); var warning = Assert.Single(result.Warnings); @@ -935,19 +864,7 @@ public void Evaluate_AmbiguityWithSingleFacetFromState_Warns() [Fact] public void Evaluate_AmbiguityWithTwoFacetsFromState_DoesNotWarn() { - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; - - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to", "brand"], - wildcard, - new Dictionary - { - ["applies_to"] = FacetSlot(), - ["brand"] = FacetSlot(), - }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(TwoFacetScope(AnAmbiguity())); Assert.Empty(result.Errors); Assert.Empty(result.Warnings); @@ -956,19 +873,7 @@ public void Evaluate_AmbiguityWithTwoFacetsFromState_DoesNotWarn() [Fact] public void Evaluate_AmbiguityOnAGraphDocument_Warns() { - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; - - var configuration = Scoped( - ["applies_to", "brand"], - wildcard, - new Dictionary - { - ["applies_to"] = FacetSlot(), - ["brand"] = FacetSlot(), - }, - AnExtractor(), - ambiguity: AnAmbiguity()) - with { Graph = new GraphConfiguration() }; + var configuration = TwoFacetScope(AnAmbiguity()) with { Graph = new GraphConfiguration() }; var result = ConfigurationValidator.EvaluateStructure(configuration); @@ -985,19 +890,7 @@ public void Evaluate_AmbiguityOnAGraphDocument_Warns() [Fact] public void Evaluate_AmbiguityOnANonGraphDocument_DoesNotWarnAboutGraph() { - var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["applies_to", "brand"] }; - - var result = ConfigurationValidator.EvaluateStructure( - Scoped( - ["applies_to", "brand"], - wildcard, - new Dictionary - { - ["applies_to"] = FacetSlot(), - ["brand"] = FacetSlot(), - }, - AnExtractor(), - ambiguity: AnAmbiguity())); + var result = ConfigurationValidator.EvaluateStructure(TwoFacetScope(AnAmbiguity())); Assert.Empty(result.Errors); Assert.Empty(result.Warnings); @@ -1721,16 +1614,12 @@ public void ValidateToolReferences_AnIdOnlyDiscoveryServes_Passes() [Fact] public void ValidateLinkerNames_ANameNothingRegistered_FailsNamingItAndThePointer() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: broken-linker state: applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge, linker: bogus } } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } + {{SpeechOnlyProviders}} """; var configuration = ConfigurationLoader.LoadYaml(document); @@ -1751,16 +1640,12 @@ public void ValidateLinkerNames_ANameNothingRegistered_FailsNamingItAndThePointe [Fact] public void ValidateLinkerNames_ARegisteredName_DoesNotThrow() { - const string document = """ + const string document = $$""" apiVersion: agentcore/v1 name: fine-linker state: applies_to: { type: string, writer: extractor, vocabulary: { from: knowledge, linker: exact } } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } + {{SpeechOnlyProviders}} """; var configuration = ConfigurationLoader.LoadYaml(document); diff --git a/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs b/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs new file mode 100644 index 00000000..2c5346d0 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Tools/TypedBindingToolTests.cs @@ -0,0 +1,235 @@ +using System.ComponentModel; +using System.Text.Json; +using System.Text.Json.Nodes; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Tools; +using AgentCore.Application.Tools.Binding; +using AgentCore.Application.Tools.Registry; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Tools; + +/// +/// The typed half of kind: binding: the host registers a method, and its signature is the +/// argument schema the model reads. +/// +/// +/// The document writes binds: CreateCase and no parameters:. Everything the model +/// needs to fill the call comes off the method, so the two can never drift apart. +/// +public sealed class TypedBindingToolTests +{ + private static readonly ToolConfiguration OpenCase = new() + { + Id = "open_case", + Kind = ToolKind.Binding, + Binds = "CreateCase", + Description = "Open a service case for a human agent.", + }; + + // --------------------------------------------------------------------------------------------- + // The registry. + // --------------------------------------------------------------------------------------------- + [Fact] + public void ATypedMethodAndAJsonDelegate_AreReadBackApart() + { + ToolBindingRegistry registry = new(); + registry.Register("CreateCase", (string summary) => summary); + registry.Register("CloseCase", (_, _) => ValueTask.FromResult(null)); + + Assert.True(registry.TryGetMethod("CreateCase", out var method)); + Assert.NotNull(method); + Assert.False(registry.TryGetBinding("CreateCase", out var absentBinding)); + Assert.Null(absentBinding); + + Assert.True(registry.TryGetBinding("CloseCase", out var binding)); + Assert.NotNull(binding); + Assert.False(registry.TryGetMethod("CloseCase", out var absentMethod)); + Assert.Null(absentMethod); + } + + [Fact] + public void ATypedMethod_CountsAgainstTheSameNames() + { + ToolBindingRegistry registry = new(); + registry.Register("CreateCase", (string summary) => summary); + + Assert.Equal(1, registry.Count); + Assert.True(registry.Contains("CreateCase")); + Assert.Contains("CreateCase", registry.Names); + } + + [Fact] + public void TheSameNameTypedThenJson_FailsAtStartup() + { + ToolBindingRegistry registry = new(); + registry.Register("CreateCase", (string summary) => summary); + + Assert.Throws( + () => registry.Register("CreateCase", (_, _) => ValueTask.FromResult(null))); + } + + // --------------------------------------------------------------------------------------------- + // The schema the model reads. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheSchemaComesOffTheMethodSignature() + { + var tool = await CreateAsync( + ([Description("What the customer wants.")] string summary, int priority = 3) => $"{summary}/{priority}"); + + var properties = tool.JsonSchema.GetProperty("properties"); + Assert.True(properties.TryGetProperty("summary", out var summaryProperty)); + Assert.True(properties.TryGetProperty("priority", out _)); + Assert.Equal("What the customer wants.", summaryProperty.GetProperty("description").GetString()); + } + + [Fact] + public async Task AParameterWithADefault_IsNotRequired() + { + var tool = await CreateAsync((string summary, int priority = 3) => $"{summary}/{priority}"); + + var required = tool.JsonSchema.GetProperty("required").EnumerateArray().Select(e => e.GetString()).ToList(); + + Assert.Contains("summary", required); + Assert.DoesNotContain("priority", required); + } + + [Fact] + public async Task TheNameAndDescription_StillComeFromTheDocument() + { + var tool = await CreateAsync((string summary) => summary); + + Assert.Equal("open_case", tool.Name); + Assert.Equal("Open a service case for a human agent.", tool.Description); + } + + // --------------------------------------------------------------------------------------------- + // Calling. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task TheModelArgumentsReachTheMethodParameters() + { + string? seenSummary = null; + int seenPriority = 0; + var tool = await CreateAsync((string summary, int priority) => + { + seenSummary = summary; + seenPriority = priority; + return "C-1"; + }); + + var result = await tool.InvokeAsync( + new AIFunctionArguments { ["summary"] = "broken belt", ["priority"] = 1 }, + TestContext.Current.CancellationToken); + + Assert.Equal("broken belt", seenSummary); + Assert.Equal(1, seenPriority); + Assert.Equal("C-1", $"{result}"); + } + + /// Arguments arrive off the wire as , not as CLR values. + [Fact] + public async Task ArgumentsThatArriveAsJsonElements_BindToo() + { + var tool = await CreateAsync((string summary, int priority) => $"{summary}/{priority}"); + using var document = JsonDocument.Parse("""{"summary":"loose bolt","priority":7}"""); + + var result = await tool.InvokeAsync( + new AIFunctionArguments + { + ["summary"] = document.RootElement.GetProperty("summary"), + ["priority"] = document.RootElement.GetProperty("priority"), + }, + TestContext.Current.CancellationToken); + + Assert.Equal("loose bolt/7", $"{result}"); + } + + [Fact] + public async Task AnArgumentTheModelLeftOut_TakesTheMethodDefault() + { + var tool = await CreateAsync((string summary, int priority = 3) => $"{summary}/{priority}"); + + var result = await tool.InvokeAsync( + new AIFunctionArguments { ["summary"] = "no power" }, TestContext.Current.CancellationToken); + + Assert.Equal("no power/3", $"{result}"); + } + + [Fact] + public async Task TheCancellationTokenReachesTheMethod() + { + var tool = await CreateAsync((string summary, CancellationToken cancellationToken) => + { + cancellationToken.ThrowIfCancellationRequested(); + return summary; + }); + + using CancellationTokenSource cancelled = new(); + await cancelled.CancelAsync(); + + await Assert.ThrowsAnyAsync(async () => + await tool.InvokeAsync(new AIFunctionArguments { ["summary"] = "anything" }, cancelled.Token)); + } + + /// The error policy of section 8.7 keys off , not off the delegate. + [Fact] + public async Task ATypedBinding_IsStillADeclaredTool() + { + var tool = await CreateAsync((string summary) => summary); + + Assert.IsAssignableFrom(tool); + } + + // --------------------------------------------------------------------------------------------- + // The boot rules. + // --------------------------------------------------------------------------------------------- + [Fact] + public async Task ATypedBindingThatAlsoDeclaresParameters_FailsTheBoot() + { + ToolBindingRegistry bindings = new(); + bindings.Register("CreateCase", (string summary) => summary); + + var declared = OpenCase with + { + Parameters = JsonNode.Parse("""{"type":"object","properties":{"summary":{"type":"string"}}}"""), + }; + + var failure = await Assert.ThrowsAsync(async () => + await new BindingToolSource(bindings).ProvideAsync( + ContextFor(declared), TestContext.Current.CancellationToken)); + + Assert.Contains("parameters:", failure.Message, StringComparison.Ordinal); + Assert.Contains("open_case", failure.Message, StringComparison.Ordinal); + } + + [Fact] + public async Task ATypedBinding_BecomesOneRegistration() + { + ToolBindingRegistry bindings = new(); + bindings.Register("CreateCase", (string summary) => summary); + + var registrations = await new BindingToolSource(bindings).ProvideAsync( + ContextFor(OpenCase), TestContext.Current.CancellationToken); + + Assert.Equal("open_case", Assert.Single(registrations).Id); + } + + private static ToolSourceContext ContextFor(ToolConfiguration tool) + => new(new AgentCoreConfiguration { ApiVersion = "agentcore/v1", Name = "test", Tools = [tool] }); + + /// Builds the tool the way the boot does: through the source, off the document. + private static async Task CreateAsync(Delegate method) + { + ToolBindingRegistry bindings = new(); + bindings.Register("CreateCase", method); + + var registrations = await new BindingToolSource(bindings).ProvideAsync( + ContextFor(OpenCase), TestContext.Current.CancellationToken); + + return Assert.IsAssignableFrom(Assert.Single(registrations).Materialise()); + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs index 1a22256b..e57b25c2 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs @@ -43,78 +43,74 @@ namespace AgentCore.AspNetCore.Tests.DependencyInjection; /// public sealed class AddAgentCoreTests { - private const string OneAgentYaml = + /// The call and speech providers every document below shares. + private const string SpeechAndCall = """ - apiVersion: agentcore/v1 - name: composed - agents: - items: - - { id: only, instructions: "I answer everything" } providers: call: { kind: telnyx-relay } speech: stt: { kind: telnyx-relay } tts: { kind: telnyx-relay } + """; + + /// plus the single reply model most documents declare. + private const string MinimalProviders = + $$""" + {{SpeechAndCall}} llm: - { kind: openai, model: gpt-4.1-mini, as: reply } """; + private const string OneAgentYaml = + $$""" + apiVersion: agentcore/v1 + name: composed + agents: + items: + - { id: only, instructions: "I answer everything" } + {{MinimalProviders}} + """; + // The same agent, and a document that names a telemetry vendor. private const string TelemetryYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} telemetry: { kind: test } """; // The same agent, and a document that names a moderation vendor. private const string ModeratedYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} moderation: { kind: test } """; // The same agent, served by a vendor this host's fake adapter does not answer to. private const string OtherVendorYaml = - """ + $$""" apiVersion: agentcore/v1 name: other-vendor agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } + {{SpeechAndCall}} llm: - { kind: anthropic, model: claude-sonnet-5, as: reply } """; // The same agent, with both tunable keys of the document set away from their default. private const string TunedYaml = - """ + $$""" apiVersion: agentcore/v1 name: tuned fallbackReply: "One moment please. I will try that again." @@ -123,17 +119,11 @@ public sealed class AddAgentCoreTests agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; private const string BindingYaml = - """ + $$""" apiVersion: agentcore/v1 name: with-binding tools: @@ -148,17 +138,11 @@ public sealed class AddAgentCoreTests agents: items: - { id: only, instructions: "I answer everything", tools: [ create_case ] } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; private const string SecretYaml = - """ + $$""" apiVersion: agentcore/v1 name: with-secret tools: @@ -176,19 +160,13 @@ public sealed class AddAgentCoreTests agents: items: - { id: only, instructions: "I answer everything", tools: [ lookup_order ] } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // Row 4 of the section 8.2 compile table, with a guarded edge on each exit of the start node. // Check 5 proves the two guards exclusive, so exactly one edge fires for each call. private const string GuardedGraphYaml = - """ + $$""" apiVersion: agentcore/v1 name: guarded-composed state: @@ -209,11 +187,7 @@ public sealed class AddAgentCoreTests edges: - { from: route, to: escalated, when: wants_human } - { from: route, to: handled, when: stays_with_bot } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } + {{SpeechAndCall}} llm: - { kind: openai, model: gpt-4.1-mini, as: router } - { kind: openai, model: gpt-4.1-mini, as: human } @@ -222,7 +196,7 @@ public sealed class AddAgentCoreTests // A stage names a target that policy.stages does not declare, so check 2 fails the load. private const string BrokenYaml = - """ + $$""" apiVersion: agentcore/v1 name: broken agents: @@ -232,19 +206,13 @@ public sealed class AddAgentCoreTests initial: start stages: - { id: start, agent: only, to: [ { stage: nowhere } ] } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // A state slot's from: names a tool no tools: entry declares, and no mcp: server offers it // either, so nothing in the served set ever resolves it. private const string UndeclaredToolYaml = - """ + $$""" apiVersion: agentcore/v1 name: broken-tool-reference state: @@ -252,51 +220,33 @@ public sealed class AddAgentCoreTests agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // An agent's tools: names an id nothing serves. Unlike UndeclaredToolYaml, the fault sits in // agents.items[].tools rather than state:, so the pointer must name the agent and not a bare // /tools. private const string UndeclaredAgentToolYaml = - """ + $$""" apiVersion: agentcore/v1 name: broken-agent-tool-reference agents: items: - { id: only, instructions: "I answer everything", tools: [ no_such_tool ] } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // Declares no tools: at all. 'discovered_only' is served only by a fake IToolSource the test // registers, never named anywhere in the document itself, so the only way this boots is if the // reference pass resolves against what got discovered rather than what got declared. private const string DiscoveredOnlyToolYaml = - """ + $$""" apiVersion: agentcore/v1 name: discovered-only-tool agents: items: - { id: only, instructions: "I answer everything", tools: [ discovered_only ] } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // A kind: agent tool reaches no source at all: the compiler builds it once the agent it names @@ -305,7 +255,7 @@ public sealed class AddAgentCoreTests // A declared kind: agent tool whose id a registered source also discovers. The collision is only // found after every source has answered, so by then the source is open. private const string CollidingAgentToolYaml = - """ + $$""" apiVersion: agentcore/v1 name: colliding tools: @@ -325,17 +275,11 @@ public sealed class AddAgentCoreTests initial: talk stages: - { id: talk, agent: front, terminal: true } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; private const string DelegatingAgentToolYaml = - """ + $$""" apiVersion: agentcore/v1 name: delegating tools: @@ -355,13 +299,7 @@ public sealed class AddAgentCoreTests initial: talk stages: - { id: talk, agent: front, terminal: true } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // BrokenYaml's structural defect (an unreachable policy transition), plus an mcp: server whose @@ -370,7 +308,7 @@ public sealed class AddAgentCoreTests // executable fails Process.Start synchronously, so if discovery ran first this would instead // report the MCP failure. See AddAgentCore_TheStructuralFaultSurfaces_BeforeMcpIsEverAsked. private const string StructuralFaultPlusUnreachableMcpYaml = - """ + $$""" apiVersion: agentcore/v1 name: broken-plus-mcp mcp: @@ -385,13 +323,7 @@ public sealed class AddAgentCoreTests initial: start stages: - { id: start, agent: only, to: [ { stage: nowhere } ] } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} """; // ------------------------------------------------------------------------------------------- @@ -1043,7 +975,7 @@ public async Task AddAgentCore_KeepsAnEvaluationServiceTheHostRegisteredFirst() // The same agent, and a document that gives the titler a model of its own. private const string TitlerYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: @@ -1051,13 +983,7 @@ public async Task AddAgentCore_KeepsAnEvaluationServiceTheHostRegisteredFirst() - { id: only, instructions: "I answer everything" } titler: model: { ref: titles } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} - { kind: openai, model: gpt-4.1-nano, as: titles } """; @@ -1125,37 +1051,25 @@ public async IAsyncEnumerable GenerateFromAsync( // The same agent, and a document that names the built-in memory kind on purpose. private const string MemoryAuditYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} audit: { kind: memory } """; // The same agent, served by an audit vendor the host registers itself. private const string VendorAuditYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} audit: { kind: test } """; @@ -1261,37 +1175,25 @@ private static InMemoryAuditSink Sink(IServiceProvider provider) // The same agent, served by a call-store vendor the host registers itself. private const string VendorTranscriptYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} calls: { kind: test } """; // The same agent, served by a knowledge vendor the host registers itself. private const string VendorKnowledgeYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} knowledge: { kind: test, collection: manuals, fields: { body: body } } """; @@ -1299,19 +1201,13 @@ private static InMemoryAuditSink Sink(IServiceProvider provider) // document that names both puts a failure strictly after an open. Nothing else in the boot has // that shape. private const string CallStoreThenModerationFailureYaml = - """ + $$""" apiVersion: agentcore/v1 name: composed agents: items: - { id: only, instructions: "I answer everything" } - providers: - call: { kind: telnyx-relay } - speech: - stt: { kind: telnyx-relay } - tts: { kind: telnyx-relay } - llm: - - { kind: openai, model: gpt-4.1-mini, as: reply } + {{MinimalProviders}} calls: { kind: test } moderation: { kind: test } """; diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs index 1e9c1f30..3380580d 100644 --- a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/QdrantKnowledgeAdapterTests.cs @@ -32,13 +32,7 @@ public async Task CreateSearchAsync_CollectionMissing_FailsTheStart() // A29. AgentCore never creates. If it did, it would put an empty concrete collection where // the ingester's alias belongs, and the next ingest run then has a name it cannot claim. var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = "does-not-exist", - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry("does-not-exist"); var thrown = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken)); @@ -66,13 +60,7 @@ public async Task CreateSearchAsync_StartupFailure_DisposesTheClient() return captured; }, Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = "does-not-exist", - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry("does-not-exist"); await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( @@ -151,13 +139,7 @@ await client.CreateCollectionAsync( try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); var thrown = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( @@ -179,24 +161,12 @@ public async Task CreateSearchAsync_DenseVectorIsTheWrongWidth_FailsTheStart() // vector that is NOT 8-wide, so only the size comparison -- not the name check -- can catch it. var collection = $"wrongwidth-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = 4, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection, 4); try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); var thrown = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( @@ -228,13 +198,7 @@ public async Task CreateSearchAsync_RealCollection_Opens() try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); var port = await adapter.CreateSearchAsync(entry, secrets: null, embeddings: null, requireScope: true, TestContext.Current.CancellationToken); @@ -269,20 +233,12 @@ public async Task CreateSearchAsync_TheStoreItOpens_FetchesWhatTheMostGenerousAg try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); using var port = (IDisposable)await adapter.CreateSearchAsync( entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - var options = (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) - .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(port)!; + var options = OptionsOf(port); Assert.Equal(AgentKnowledgeConfiguration.MaximumLimit, options.Limit); Assert.True( @@ -314,20 +270,12 @@ public async Task CreateSearchAsync_TheStoreItOpens_QueriesTheNamesTheStartupChe try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); using var port = (IDisposable)await adapter.CreateSearchAsync( entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); - var options = (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) - .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(port)!; + var options = OptionsOf(port); Assert.Equal("dense", options.VectorName, StringComparer.Ordinal); Assert.Equal("text", options.Fields!.Lexical, StringComparer.Ordinal); @@ -360,13 +308,7 @@ await client.DeletePayloadAsync( collection, ["body"], everyPoint, cancellationToken: TestContext.Current.CancellationToken); var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); var thrown = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( @@ -390,24 +332,12 @@ public async Task CreateSearchAsync_EmptyCollection_Opens() // unbootable in the window between creating the alias and the first ingest run filling it. var collection = $"empty-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection); try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); using var port = (IDisposable)await adapter.CreateSearchAsync( entry, secrets: null, embeddings: null, requireScope: false, TestContext.Current.CancellationToken); @@ -427,13 +357,7 @@ public async Task CreateSearchAsync_Uuid5LookupOverNumericPointKeys_FailsTheStar // needs one such point -- with a numeric key, which no uuid5 or direct formula ever produces. var collection = $"numeric-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection); try { @@ -486,13 +410,7 @@ public async Task CreateSearchAsync_EmptyCollection_OpensUnderEveryLookupMode(Kn { var collection = $"empty-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection); try { @@ -565,13 +483,7 @@ public async Task CreateSearchAsync_AGeneratorPassedThroughThePort_OpensTheStore try { var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient()); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); using var port = (IDisposable)await adapter.CreateSearchAsync( entry, secrets: null, embeddings: Embeddings, requireScope: false, TestContext.Current.CancellationToken); @@ -652,24 +564,11 @@ public async Task CreateSearchAsync_DirectLookupOverANonGuidCardId_NamesTheIdAnd const string cardId = "direct-01"; var collection = $"direct-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection); try { - var point = new PointStruct - { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors - { - Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, - }, - }; + var point = DensePoint(); point.Payload["card_id"] = cardId; point.Payload["body"] = "direct lookup card"; point.Payload["see_also"] = new Value { ListValue = new ListValue() }; @@ -842,12 +741,8 @@ public async Task CreateSearchAsync_DocumentDeclaresAWildcard_ReachesTheStoreOpt var port = await Adapter().CreateSearchAsync( entry, secrets: null, Embedder(), requireScope: true, TestContext.Current.CancellationToken); - // QdrantKnowledgeStore keeps its options private, so reflection is the only way to observe - // what the adapter copied onto them. The filter those options go on to produce is covered by - // QdrantWildcardScopeTests. - var options = (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) - .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! - .GetValue(port)!; + // The filter these options go on to produce is covered by QdrantWildcardScopeTests. + var options = OptionsOf(port); Assert.Equal("*", options.ScopeWildcard); Assert.Equal(["model"], options.ScopeWildcardFacets); @@ -917,24 +812,11 @@ public async Task CreateSearchAsync_IdRoleDisabled_OpensACollectionWithNoIdField // nothing but body, and the document says so with fields.id: null. var collection = $"noid-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection); try { - var point = new PointStruct - { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors - { - Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, - }, - }; + var point = DensePoint(); point.Payload["body"] = "a card with no id concept"; await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); @@ -968,35 +850,16 @@ public async Task CreateSearchAsync_DefaultIdOverACollectionWithoutOne_StillFail // mentions fields.id declared card_id, and a collection without it is still drift. var collection = $"noiddefault-{Guid.NewGuid():N}"; using var client = QdrantServer.CreateClient(); - await client.CreateCollectionAsync( - collection, - vectorsConfig: new VectorParamsMap - { - Map = { ["dense"] = new VectorParams { Size = KbShapedCorpus.Dim, Distance = Distance.Cosine } }, - }, - cancellationToken: TestContext.Current.CancellationToken); + await CreateDenseCollectionAsync(client, collection); try { - var point = new PointStruct - { - Id = new PointId { Uuid = Guid.NewGuid().ToString() }, - Vectors = new Vectors - { - Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, - }, - }; + var point = DensePoint(); point.Payload["body"] = "a card with no id concept"; await client.UpsertAsync(collection, [point], cancellationToken: TestContext.Current.CancellationToken); var adapter = new QdrantKnowledgeAdapter(_ => QdrantServer.CreateClient(), Embeddings); - var entry = new KnowledgeProviderConfiguration - { - Kind = "qdrant", - Collection = collection, - Vector = "dense", - Fields = KbShapedCorpus.Fields, - }; + var entry = DenseEntry(collection); var failure = await Assert.ThrowsAsync( async () => await adapter.CreateSearchAsync( @@ -1110,6 +973,46 @@ private sealed class BlankMapper : IKnowledgePointMapper Scope = KbShapedCorpus.Scope, }; + /// A point carrying an 8-wide "dense" vector and no payload. The caller fills it. + private static PointStruct DensePoint() => new() + { + Id = new PointId { Uuid = Guid.NewGuid().ToString() }, + Vectors = new Vectors + { + Vectors_ = new NamedVectors { Vectors = { ["dense"] = new float[KbShapedCorpus.Dim] } }, + }, + }; + + /// + /// The options the adapter handed the store. No corpus can tell "queried the right name" from + /// "queried a name that happens to match", so these facts read the store's own field. + /// + private static QdrantKnowledgeStoreOptions OptionsOf(object port) => + (QdrantKnowledgeStoreOptions)typeof(QdrantKnowledgeStore) + .GetField("_options", BindingFlags.NonPublic | BindingFlags.Instance)! + .GetValue(port)!; + + private static KnowledgeProviderConfiguration DenseEntry(string collection) => new() + { + Kind = "qdrant", + Collection = collection, + Vector = "dense", + Fields = KbShapedCorpus.Fields, + }; + + /// A collection carrying one named "dense" vector, the shape every fixture here uses. + private static Task CreateDenseCollectionAsync( + QdrantClient client, + string collection, + ulong size = KbShapedCorpus.Dim) => + client.CreateCollectionAsync( + collection, + vectorsConfig: new VectorParamsMap + { + Map = { ["dense"] = new VectorParams { Size = size, Distance = Distance.Cosine } }, + }, + cancellationToken: TestContext.Current.CancellationToken); + private static QdrantKnowledgeAdapter Adapter() => new(_ => QdrantServer.CreateClient()); private static FakeEmbeddingGenerator Embedder() => new(KbShapedCorpus.QueryVector());