From d53493bc0719213f0814f516390d5f24c0995507 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 16:21:14 -0600 Subject: [PATCH 1/8] feat: add web search and compaction functionality --- demo/AgentCore.Demo/config/example.yaml | 31 ++- .../Compilation/AgentCompaction.cs | 75 ++++++ .../AgentContextProviderCompiler.cs | 108 ++++++++ .../Compilation/AgentToolCompiler.cs | 108 ++++++++ .../Compilation/ConfigurationCompiler.cs | 148 +---------- .../Schema/AgentsConfiguration.cs | 6 + .../Schema/CallProviderConfiguration.cs | 19 ++ .../Schema/CompactionConfiguration.cs | 64 +++++ .../Schema/EmbeddingProviderConfiguration.cs | 19 ++ .../Schema/LlmProviderConfiguration.cs | 28 ++ .../Schema/ProvidersConfiguration.cs | 78 ------ .../Schema/SpeechProviderConfiguration.cs | 13 + .../Schema/VendorProviderConfiguration.cs | 10 + .../Schema/agentcore-v1.schema.json | 36 +++ src/AgentCore.Application/Diagnostics/Log.cs | 18 ++ .../Llm/CompositeChatClientFactory.cs | 10 + .../Ports/IChatClientAdapter.cs | 21 +- .../Ports/IChatClientFactory.cs | 10 +- .../PublicAPI.Unshipped.txt | 72 ++++++ .../Compaction/CappedToolCallFormatter.cs | 68 +++++ .../Compaction/CompactionStrategyFactory.cs | 55 ++++ .../Tools/Builtin/BuiltinToolNames.cs | 3 + .../Tools/Builtin/BuiltinToolSource.cs | 5 +- .../Tools/Builtin/WebSearchToolDefinition.cs | 20 ++ .../Llm/OpenAI/OpenAiChatClientAdapter.cs | 8 + .../PublicAPI.Unshipped.txt | 1 + .../Compilation/CompactionCompilationTests.cs | 240 ++++++++++++++++++ .../Compilation/HostedWebSearchDropTests.cs | 207 +++++++++++++++ .../Configuration/AgentCompactionTests.cs | 87 +++++++ .../Configuration/ConfigurationLoaderTests.cs | 6 +- .../ConfigurationSchemaValidatorTests.cs | 21 ++ .../Configuration/ExampleDocument.cs | 25 +- .../Llm/HostedWebSearchCapabilityTests.cs | 56 ++++ .../Runtime/CappedToolCallFormatterTests.cs | 82 ++++++ .../Runtime/CompactionStrategyFactoryTests.cs | 113 +++++++++ .../Tools/BuiltinToolTests.cs | 12 +- .../Tools/WebSearchToolDefinitionTests.cs | 37 +++ 37 files changed, 1662 insertions(+), 258 deletions(-) create mode 100644 src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs create mode 100644 src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs create mode 100644 src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs create mode 100644 src/AgentCore.Application/Configuration/Schema/CallProviderConfiguration.cs create mode 100644 src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs create mode 100644 src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs create mode 100644 src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs create mode 100644 src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs create mode 100644 src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs create mode 100644 src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs create mode 100644 src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs create mode 100644 tests/AgentCore.Application.Tests/Compilation/CompactionCompilationTests.cs create mode 100644 tests/AgentCore.Application.Tests/Compilation/HostedWebSearchDropTests.cs create mode 100644 tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs create mode 100644 tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs create mode 100644 tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs create mode 100644 tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs diff --git a/demo/AgentCore.Demo/config/example.yaml b/demo/AgentCore.Demo/config/example.yaml index 77e364b7..50d8b513 100644 --- a/demo/AgentCore.Demo/config/example.yaml +++ b/demo/AgentCore.Demo/config/example.yaml @@ -176,6 +176,12 @@ tools: properties: { summary: { type: string } } required: [ summary ] + # A marker, not code: it tells the model provider it may run a hosted web search, and only a + # provider that runs one acts on it. AgentToolCompiler drops this tool, per agent, for a model + # providers.llm[] never named webSearch: false for but whose adapter reports it cannot search — + # a warning at compile time, never a boot failure. + - { id: search, kind: builtin, uses: web.search } + # 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. @@ -225,6 +231,24 @@ agents: # scoped agent with no scope open says it cannot look the answer up rather than searching # everything. Set scoped: false on an agent that is meant to read the whole corpus. knowledge: { mode: prefetch, limit: 5, citations: false } + + # Every strategy here is deterministic: the same messages give the same result, from empty + # state. Summarization is not offered on purpose — a resumed call rebuilds a new session and + # re-derives from the replayed words, so a strategy that called a model would give one call two + # different histories. tool_result folds old tool-call groups into one short line each; the + # other three are truncate, sliding_window and context_window. trigger: names exactly one of + # tokens, messages, turns or groups — naming zero or two is a load error. keep: is how many + # newest groups the strategy never touches; foldResultChars: is how much of a tool result + # tool_result carries forward per fold. There is no per-agent opt-out: an omitted block inherits + # this one, so give compaction to some agents and not others by declaring the block on those + # agents instead of here. + # + # context_window here, not tool_result: tool_result folds only function tool calls, and the + # analyst agent below carries search, a hosted tool whose results are no such thing — tool_result + # would leave them growing the conversation forever. context_window folds tool_result's own work + # first and then truncates, and truncate drops whole groups regardless of what is inside them, so + # it still bounds a conversation a hosted tool is filling. + compaction: { strategy: context_window, trigger: { messages: 40 }, keep: 6, foldResultChars: 300 } items: # voice, scripted — one model round trip, no source labels spoken aloud. Inherits mode: # prefetch, limit: 5, citations: false from defaults above. @@ -235,7 +259,7 @@ agents: - { id: closer, instructions: "", tools: [] } # internal — everything on, and it searches every product on purpose - - { id: analyst, instructions: "", tools: [ lookup_order, create_case ], + - { id: analyst, instructions: "", tools: [ lookup_order, create_case, search ], knowledge: { mode: tool, limit: 8, citations: true, scoped: false } } # customer facing — tools yes, citations no. It sets two keys and inherits limit: 5. @@ -289,7 +313,10 @@ providers: - { kind: openai, model: gpt-4.1-mini, as: reply } # the voice path, chosen on latency - { kind: openai, model: gpt-5.4-nano, as: fill } # the extractor, chosen on null discipline - { kind: openai, model: gpt-4.1, as: judge } # evaluation only, chosen on judgement - - { kind: openai, model: gpt-4.1-nano, as: cheap } # ui.draw only, chosen on price + - { kind: openai, model: gpt-4.1-nano, as: cheap, webSearch: false } # ui.draw only, chosen on price + # webSearch: false above is a veto, not a default: omitted or true both leave the choice to the + # vendor's adapter. cheap only ever draws pictures, so vetoing it here costs nothing and stops a + # future search tool from ever running on the least capable model by accident. # Three planes, and they are not duplicates. call is the media pipe and owns the inbound route. # speech is recognition and synthesis. telephony is call control, which must outlive any one # media leg because a warm transfer creates a second one. diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs b/src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs new file mode 100644 index 00000000..0393a7ae --- /dev/null +++ b/src/AgentCore.Application/Configuration/Compilation/AgentCompaction.cs @@ -0,0 +1,75 @@ +using AgentCore.Application.Configuration.Schema; + +namespace AgentCore.Application.Configuration.Compilation; + +/// One agent's compaction: block, fully resolved. +/// The strategy to build. +/// The one condition that makes compaction run. +/// How many newest groups the strategy never touches. +/// How much of a tool result a fold carries forward. +public sealed record ResolvedCompaction( + CompactionStrategyKind Strategy, + CompactionTriggerConfiguration Trigger, + int Keep, + int FoldResultChars); + +/// +/// Composes one agent's compaction: block from agents.defaults.compaction and the +/// agent's own block, key by key. +/// +public static class AgentCompaction +{ + /// The strategy used when neither the agent nor the defaults name one. + public const CompactionStrategyKind DefaultStrategy = CompactionStrategyKind.ToolResult; + + /// The newest groups a strategy never touches, when nothing names a number. + public const int DefaultKeep = 4; + + /// + /// How much of a tool result a fold carries forward, when nothing names a number. Enough for + /// the model to recognise what a tool already returned, and not enough to refill the window. + /// + public const int DefaultFoldResultChars = 200; + + /// Composes one agent's resolved compaction settings. + /// The agents.defaults section, or . + /// The agent to resolve. + /// + /// The resolved settings, or when neither the defaults nor the agent + /// declares a compaction: block. + /// + /// The composed trigger names other than one condition. + public static ResolvedCompaction? Compose(AgentDefaults? defaults, AgentConfiguration agent) + { + ArgumentNullException.ThrowIfNull(agent); + + var own = agent.Compaction; + var shared = defaults?.Compaction; + + if (own is null && shared is null) + { + return null; + } + + var trigger = own?.Trigger ?? shared?.Trigger ?? new CompactionTriggerConfiguration(); + + var named = new int?[] { trigger.Tokens, trigger.Messages, trigger.Turns, trigger.Groups } + .Count(value => value is not null); + + if (named != 1) + { + // Zero would compact on every turn; two would leave the document silent about whether + // they are combined with All or Any. + throw new ArgumentException( + $"the agent '{agent.Id}' has a compaction trigger naming {named} conditions. It must " + + "name exactly one of tokens, messages, turns or groups.", + nameof(agent)); + } + + return new ResolvedCompaction( + own?.Strategy ?? shared?.Strategy ?? DefaultStrategy, + trigger, + own?.Keep ?? shared?.Keep ?? DefaultKeep, + own?.FoldResultChars ?? shared?.FoldResultChars ?? DefaultFoldResultChars); + } +} diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs new file mode 100644 index 00000000..7b204724 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Compilation/AgentContextProviderCompiler.cs @@ -0,0 +1,108 @@ +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Knowledge; +using AgentCore.Application.Ports; +using AgentCore.Application.Runtime; +using AgentCore.Application.Runtime.Compaction; +using AgentCore.Application.Skills; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.Compaction; +namespace AgentCore.Application.Configuration.Compilation; + +internal static class AgentContextProviderCompiler +{ + /// + /// The formatter an agent cites through when the host bound none. Stateless, so every agent in + /// every document reads the one instance. + /// + private static readonly SourceLocatorCitationFormatter DefaultCitations = new(); + + /// + /// Builds the context providers of one agent. and + /// are the document's ambiguity wiring (§7), the same + /// for every agent — built once by the caller rather than re-derived per agent. + /// + public static List Build( + AgentDefaults? defaults, + AgentConfiguration item, + AgentCompilationContext context, + string pointer, + ResolvedClarification clarification, + ClarificationProvider? clarificationProvider) + { + List providers = [new TurnContextProvider()]; + + // Bound ahead of the knowledge early-return below: channel 1 asks about a scope's fromState + // slots regardless of whether THIS agent composes its own knowledge: block, because the + // clarification is document-level state, not a per-agent search setting. + if (clarificationProvider is not null) + { + providers.Add(clarificationProvider); + } + + if (item.Skills.Count > 0) + { + if (context.Skills is not { } catalog) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "skills"), + $"the agent '{item.Id}' declares a skills: list and this host bound no skills " + + "folder, so there is nothing to load. Call options.UseSkills(...) with the " + + "folder that holds the SKILL.md directories, or remove the skills: list."); + } + + providers.Add(SkillsProviderFactory.Create(catalog, item.Skills, context.Loggers)); + } + + ResolvedCompaction? compaction; + try + { + compaction = AgentCompaction.Compose(defaults, item); + } + catch (ArgumentException exception) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(ConfigurationError.AppendPointer(pointer, "compaction"), "trigger"), + exception.Message); + } + + // Bound ahead of the knowledge early-return below, for the same reason: a compaction: block + // is independent of whether this agent composes a knowledge: block. + if (compaction is { } resolved) + { +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. + providers.Add(new CompactionProvider( + CompactionStrategyFactory.Create(resolved), + loggerFactory: context.Loggers)); +#pragma warning restore MAAI001 + } + + if (AgentKnowledge.Compose(defaults, item) is not { } composed) + { + return providers; + } + + if (context.Knowledge is not { } port) + { + throw ConfigurationCompiler.Fail( + ConfigurationError.AppendPointer(pointer, "knowledge"), + $"the agent '{item.Id}' declares a knowledge: block and this host registered no " + + "knowledge vendor, so there is no store to read. Call " + + "options.UseKnowledgeStores(...) with an adapter that serves " + + $"{nameof(IKnowledgeRetrievalPort)}, or remove the knowledge: block."); + } + + // The same document-level wiring channel 1 reads above, carried onto this agent's own + // resolved knowledge so the search side does not have to re-derive it. + var knowledge = composed with { Clarification = clarification }; + + providers.Add(KnowledgeProviderFactory.Create( + port, + knowledge, + item.Id, + context.Citations ?? DefaultCitations, + context.Loggers)); + + return providers; + } +} diff --git a/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs new file mode 100644 index 00000000..b787ab31 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Compilation/AgentToolCompiler.cs @@ -0,0 +1,108 @@ +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Diagnostics; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; +namespace AgentCore.Application.Configuration.Compilation; + +internal static class AgentToolCompiler +{ + public static List? Build( + AgentConfiguration item, + ModelReference? model, + Dictionary declared, + AgentCompilationContext context, + string pointer, + Func resolveAgent) + { + if (item.Tools.Count == 0) + { + return null; + } + + List tools = []; + for (var index = 0; index < item.Tools.Count; index++) + { + var id = item.Tools[index]; + + var toolPointer = ConfigurationError.AppendPointer( + ConfigurationError.AppendPointer(pointer, "tools"), index); + + if (!declared.TryGetValue(id, out var tool)) + { + if (context.Tools is { } discovered && discovered.Contains(id)) + { + Add(tools, discovered.Resolve(id), item.Id, id, model, context); + continue; + } + + if (context.Tools is null) + { + // No factory, so nothing this loop could have built anyway. + continue; + } + + throw ConfigurationCompiler.Fail(toolPointer, $"the tool id '{id}' is not declared in tools:, and no tool source serves it."); + } + + if (tool.Kind == ToolKind.Agent) + { + // A kind: agent tool needs no tool factory. Section 7 says section 8 adds no port, + // and this kind adds none either: the inner agent is already in the document. + Add(tools, AgentDelegationTool.Create(tool, ResolveInner(tool, resolveAgent, toolPointer)), item.Id, id, model, context); + continue; + } + + if (context.Tools is { } registry) + { + if (!registry.Contains(id)) + { + throw ConfigurationCompiler.Fail(toolPointer, $"the tool id '{id}' is declared, and no tool source serves it."); + } + + Add(tools, registry.Resolve(id), item.Id, id, model, context); + } + } + + return tools.Count == 0 ? null : tools; + } + + /// Adds one tool, unless it is a hosted search this agent's model cannot run. + /// + /// Tested by type and not by the builtin name, so a hosted search tool a host supplies through + /// its own IToolSource is covered by the same rule. + /// + private static void Add( + List tools, + AITool tool, + string agentId, + string toolId, + ModelReference? model, + AgentCompilationContext context) + { + if (tool is HostedWebSearchTool && !context.ChatClients.SupportsHostedWebSearch(model)) + { + var logger = context.Loggers?.CreateLogger(typeof(AgentToolCompiler)) ?? NullLogger.Instance; + var modelDescription = model is { Ref.Length: > 0 } ? $"the model '{model.Ref}'" : "this agent's default model"; + Log.HostedWebSearchDropped(logger, agentId, toolId, modelDescription); + return; + } + + tools.Add(tool); + } + + private static AIAgent ResolveInner(ToolConfiguration tool, Func resolveAgent, string pointer) + { + if (tool.Agent is not { Length: > 0 } id) + { + throw ConfigurationCompiler.Fail(pointer, $"the tool '{tool.Id}' is kind: agent and names no agent:."); + } + + return resolveAgent(id) + ?? throw ConfigurationCompiler.Fail( + pointer, + $"the tool '{tool.Id}' delegates to the agent '{id}', which agents.items does not declare."); + } +} diff --git a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs index 1fb0665d..67b68f93 100644 --- a/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs +++ b/src/AgentCore.Application/Configuration/Compilation/ConfigurationCompiler.cs @@ -49,12 +49,6 @@ namespace AgentCore.Application.Configuration.Compilation; /// public static class ConfigurationCompiler { - /// - /// The formatter an agent cites through when the host bound none. Stateless, so every agent in - /// every document reads the one instance. - /// - private static readonly SourceLocatorCitationFormatter DefaultCitations = new(); - /// Picks the row of the compile table one document selects. /// The loaded document. /// The row. @@ -274,10 +268,10 @@ private static Dictionary BuildAgents( ChatOptions = new ChatOptions { Instructions = AgentInstructions.Compose(section.Defaults, item), - Tools = BuildTools(item, tools, context, pointer, Resolve), + Tools = AgentToolCompiler.Build(item, item.Model ?? section.Defaults?.Model, tools, context, pointer, Resolve), }, ChatHistoryProvider = history, - AIContextProviders = BuildContextProviders( + AIContextProviders = AgentContextProviderCompiler.Build( section.Defaults, item, context, pointer, clarification, clarificationProvider), }); path.RemoveAt(path.Count - 1); @@ -291,72 +285,6 @@ private static Dictionary BuildAgents( } } - /// - /// Builds the context providers of one agent. and - /// are the document's ambiguity wiring (§7), the same - /// for every agent — built once by the caller rather than re-derived per agent. - /// - private static List BuildContextProviders( - AgentDefaults? defaults, - AgentConfiguration item, - AgentCompilationContext context, - string pointer, - ResolvedClarification clarification, - ClarificationProvider? clarificationProvider) - { - List providers = [new TurnContextProvider()]; - - // Bound ahead of the knowledge early-return below: channel 1 asks about a scope's fromState - // slots regardless of whether THIS agent composes its own knowledge: block, because the - // clarification is document-level state, not a per-agent search setting. - if (clarificationProvider is not null) - { - providers.Add(clarificationProvider); - } - - if (item.Skills.Count > 0) - { - if (context.Skills is not { } catalog) - { - throw Fail( - ConfigurationError.AppendPointer(pointer, "skills"), - $"the agent '{item.Id}' declares a skills: list and this host bound no skills " - + "folder, so there is nothing to load. Call options.UseSkills(...) with the " - + "folder that holds the SKILL.md directories, or remove the skills: list."); - } - - providers.Add(SkillsProviderFactory.Create(catalog, item.Skills, context.Loggers)); - } - - if (AgentKnowledge.Compose(defaults, item) is not { } composed) - { - return providers; - } - - if (context.Knowledge is not { } port) - { - throw Fail( - ConfigurationError.AppendPointer(pointer, "knowledge"), - $"the agent '{item.Id}' declares a knowledge: block and this host registered no " - + "knowledge vendor, so there is no store to read. Call " - + "options.UseKnowledgeStores(...) with an adapter that serves " - + $"{nameof(IKnowledgeRetrievalPort)}, or remove the knowledge: block."); - } - - // The same document-level wiring channel 1 reads above, carried onto this agent's own - // resolved knowledge so the search side does not have to re-derive it. - var knowledge = composed with { Clarification = clarification }; - - providers.Add(KnowledgeProviderFactory.Create( - port, - knowledge, - item.Id, - context.Citations ?? DefaultCitations, - context.Loggers)); - - return providers; - } - /// Puts the auditing function-invocation loop into the pipeline of one agent. private static AuditingFunctionInvokingChatClient WithToolFailureAuditing(IChatClient model) => new(model.AsBuilder() @@ -364,78 +292,6 @@ private static AuditingFunctionInvokingChatClient WithToolFailureAuditing(IChatC .Use(static innerClient => new ModelFacingChatClient(innerClient)) .Build()); - private static List? BuildTools( - AgentConfiguration item, - Dictionary declared, - AgentCompilationContext context, - string pointer, - Func resolveAgent) - { - if (item.Tools.Count == 0) - { - return null; - } - - List tools = []; - for (var index = 0; index < item.Tools.Count; index++) - { - var id = item.Tools[index]; - - var toolPointer = ConfigurationError.AppendPointer( - ConfigurationError.AppendPointer(pointer, "tools"), index); - - if (!declared.TryGetValue(id, out var tool)) - { - if (context.Tools is { } discovered && discovered.Contains(id)) - { - tools.Add(discovered.Resolve(id)); - continue; - } - - if (context.Tools is null) - { - // No factory, so nothing this loop could have built anyway. - continue; - } - - throw Fail(toolPointer, $"the tool id '{id}' is not declared in tools:, and no tool source serves it."); - } - - if (tool.Kind == ToolKind.Agent) - { - // A kind: agent tool needs no tool factory. Section 7 says section 8 adds no port, - // and this kind adds none either: the inner agent is already in the document. - tools.Add(AgentDelegationTool.Create(tool, ResolveInner(tool, resolveAgent, toolPointer))); - continue; - } - - if (context.Tools is { } registry) - { - if (!registry.Contains(id)) - { - throw Fail(toolPointer, $"the tool id '{id}' is declared, and no tool source serves it."); - } - - tools.Add(registry.Resolve(id)); - } - } - - return tools.Count == 0 ? null : tools; - } - - private static AIAgent ResolveInner(ToolConfiguration tool, Func resolveAgent, string pointer) - { - if (tool.Agent is not { Length: > 0 } id) - { - throw Fail(pointer, $"the tool '{tool.Id}' is kind: agent and names no agent:."); - } - - return resolveAgent(id) - ?? throw Fail( - pointer, - $"the tool '{tool.Id}' delegates to the agent '{id}', which agents.items does not declare."); - } - internal static ConfigurationLoadException Fail(string pointer, string message) => new(new ConfigurationError { diff --git a/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs index 30ff57c9..f2948f57 100644 --- a/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/AgentsConfiguration.cs @@ -47,6 +47,9 @@ public sealed record AgentDefaults /// Gets the shared knowledge: block, or when the document declares none. public AgentKnowledgeConfiguration? Knowledge { get; init; } + + /// Gets the shared compaction: block, or when the document declares none. + public CompactionConfiguration? Compaction { get; init; } } /// @@ -71,6 +74,9 @@ public sealed record AgentConfiguration /// Gets this agent's knowledge: block, or to inherit key by key. public AgentKnowledgeConfiguration? Knowledge { get; init; } + + /// Gets this agent's compaction: block, or to inherit key by key. + public CompactionConfiguration? Compaction { get; init; } } /// diff --git a/src/AgentCore.Application/Configuration/Schema/CallProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/CallProviderConfiguration.cs new file mode 100644 index 00000000..3c5fd6df --- /dev/null +++ b/src/AgentCore.Application/Configuration/Schema/CallProviderConfiguration.cs @@ -0,0 +1,19 @@ +namespace AgentCore.Application.Configuration.Schema; + +/// +/// The vendor that carries the call, and the limits of the socket it opens. +/// +public sealed record CallProviderConfiguration +{ + /// Gets the vendor that carries the call, such as telnyx-relay. + public required string Kind { get; init; } + + /// Gets how long the socket waits with no inbound frame before ending the call, or null for the adapter's default. + public int? IdleTimeoutSeconds { get; init; } + + /// Gets how long teardown gives a stuck task before moving on, or null for the adapter's default. + public int? CloseTimeoutSeconds { get; init; } + + /// Gets the largest inbound frame the socket accepts, in bytes, or null for the adapter's default. + public int? MaxFrameBytes { get; init; } +} diff --git a/src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs new file mode 100644 index 00000000..c47e2eb5 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Schema/CompactionConfiguration.cs @@ -0,0 +1,64 @@ +namespace AgentCore.Application.Configuration.Schema; + +/// The strategies a compaction: block may name. +public enum CompactionStrategyKind +{ + /// + /// Folds old tool-call groups into one short line each. It folds only function tool calls — a + /// group built from and its result. A + /// provider-run tool, such as hosted web search, is not folded: its messages are not that + /// content type, so this strategy leaves them untouched. Use + /// for a conversation that mixes the two, since its truncate phase + /// drops whole groups regardless of what is inside them. + /// + ToolResult, + + /// Removes the oldest non-system groups. + Truncate, + + /// Removes the oldest user turns and everything that answered them. + SlidingWindow, + + /// + /// Folds tool results, then truncates. The name names the goal, not the mechanism: nothing here + /// reads the model's actual context window. The size this strategy holds to comes entirely from + /// this block's own and + /// . + /// + ContextWindow, +} + +/// When compaction runs. Exactly one member is set. +public sealed record CompactionTriggerConfiguration +{ + /// Gets the token count above which compaction runs. + public int? Tokens { get; init; } + + /// Gets the message count above which compaction runs. + public int? Messages { get; init; } + + /// Gets the turn count above which compaction runs. + public int? Turns { get; init; } + + /// Gets the group count above which compaction runs. + public int? Groups { get; init; } +} + +/// One agent's compaction: block, as the document writes it. +public sealed record CompactionConfiguration +{ + /// Gets the strategy, or to inherit. + public CompactionStrategyKind? Strategy { get; init; } + + /// Gets when compaction runs, or to inherit. + public CompactionTriggerConfiguration? Trigger { get; init; } + + /// Gets how many newest groups the strategy never touches, or null to inherit. + public int? Keep { get; init; } + + /// + /// Gets how many characters of each tool result a fold carries forward, or null to inherit. + /// only. + /// + public int? FoldResultChars { get; init; } +} diff --git a/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs new file mode 100644 index 00000000..5cc3c7a3 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Schema/EmbeddingProviderConfiguration.cs @@ -0,0 +1,19 @@ +namespace AgentCore.Application.Configuration.Schema; + +/// +/// The embedding provider: the vendor that turns a query into a vector, and the model it uses. +/// +public sealed record EmbeddingProviderConfiguration +{ + /// Gets the vendor, such as openai. + public required string Kind { get; init; } + + /// Gets the model name the vendor knows, such as text-embedding-3-small. + public required string Model { get; init; } + + /// + /// Gets the vector width to ask the vendor for, or for the model's own. + /// It must match the width the knowledge collection was built with. + /// + public int? Dimensions { get; init; } +} diff --git a/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs new file mode 100644 index 00000000..46e4da97 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Schema/LlmProviderConfiguration.cs @@ -0,0 +1,28 @@ +namespace AgentCore.Application.Configuration.Schema; + +/// +/// One large language model, and the name a points at. +/// +public sealed record LlmProviderConfiguration +{ + /// Gets the vendor, such as openai. + public required string Kind { get; init; } + + /// Gets the model name the vendor knows. + public required string Model { get; init; } + + /// Gets the name this entry answers to, such as reply or fill. + public required string As { get; init; } + + /// + /// Gets how hard a reasoning model thinks before it answers, or to send + /// nothing and let the vendor decide. + /// + public string? ReasoningEffort { get; init; } + + /// + /// Gets whether this entry may run a hosted web search, or to let the + /// vendor's adapter decide. + /// + public bool? WebSearch { get; init; } +} diff --git a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs index 1be4229a..8d654b64 100644 --- a/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs +++ b/src/AgentCore.Application/Configuration/Schema/ProvidersConfiguration.cs @@ -3,84 +3,6 @@ namespace AgentCore.Application.Configuration.Schema; -/// -/// One large language model, and the name a points at. -/// -public sealed record LlmProviderConfiguration -{ - /// Gets the vendor, such as openai. - public required string Kind { get; init; } - - /// Gets the model name the vendor knows. - public required string Model { get; init; } - - /// Gets the name this entry answers to, such as reply or fill. - public required string As { get; init; } - - /// - /// Gets how hard a reasoning model thinks before it answers, or to send - /// nothing and let the vendor decide. - /// - public string? ReasoningEffort { get; init; } -} - -/// -/// A provider that names one vendor and nothing else, such as speech or telephony. -/// -public sealed record VendorProviderConfiguration -{ - /// Gets the vendor, such as telnyx-relay. - public required string Kind { get; init; } -} - -/// -/// The two speech roles: who turns sound into text, and who turns text back into sound. -/// -public sealed record SpeechProviderConfiguration -{ - /// Gets the recognition vendor: what the caller said, turned into text. - public required VendorProviderConfiguration Stt { get; init; } - - /// Gets the synthesis vendor: text, turned into what the caller hears. - public required VendorProviderConfiguration Tts { get; init; } -} - -/// -/// The vendor that carries the call, and the limits of the socket it opens. -/// -public sealed record CallProviderConfiguration -{ - /// Gets the vendor that carries the call, such as telnyx-relay. - public required string Kind { get; init; } - - /// Gets how long the socket waits with no inbound frame before ending the call, or null for the adapter's default. - public int? IdleTimeoutSeconds { get; init; } - - /// Gets how long teardown gives a stuck task before moving on, or null for the adapter's default. - public int? CloseTimeoutSeconds { get; init; } - - /// Gets the largest inbound frame the socket accepts, in bytes, or null for the adapter's default. - public int? MaxFrameBytes { get; init; } -} - -/// -/// The embedding provider: the vendor that turns a query into a vector, and the model it uses. -/// -public sealed record EmbeddingProviderConfiguration -{ - /// Gets the vendor, such as openai. - public required string Kind { get; init; } - - /// Gets the model name the vendor knows, such as text-embedding-3-small. - public required string Model { get; init; } - - /// - /// Gets the vector width to ask the vendor for, or for the model's own. - /// It must match the width the knowledge collection was built with. - /// - public int? Dimensions { get; init; } -} - /// /// How a card's payload is named in the collection this deployment reads. /// diff --git a/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs new file mode 100644 index 00000000..9260b05e --- /dev/null +++ b/src/AgentCore.Application/Configuration/Schema/SpeechProviderConfiguration.cs @@ -0,0 +1,13 @@ +namespace AgentCore.Application.Configuration.Schema; + +/// +/// The two speech roles: who turns sound into text, and who turns text back into sound. +/// +public sealed record SpeechProviderConfiguration +{ + /// Gets the recognition vendor: what the caller said, turned into text. + public required VendorProviderConfiguration Stt { get; init; } + + /// Gets the synthesis vendor: text, turned into what the caller hears. + public required VendorProviderConfiguration Tts { get; init; } +} diff --git a/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs b/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs new file mode 100644 index 00000000..39f4dd58 --- /dev/null +++ b/src/AgentCore.Application/Configuration/Schema/VendorProviderConfiguration.cs @@ -0,0 +1,10 @@ +namespace AgentCore.Application.Configuration.Schema; + +/// +/// A provider that names one vendor and nothing else, such as speech or telephony. +/// +public sealed record VendorProviderConfiguration +{ + /// Gets the vendor, such as telnyx-relay. + public required string Kind { get; init; } +} diff --git a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json index 8b7ae35f..508b4bbd 100644 --- a/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json +++ b/src/AgentCore.Application/Configuration/Schema/agentcore-v1.schema.json @@ -695,6 +695,9 @@ }, "knowledge": { "$ref": "#/$defs/agentKnowledge" + }, + "compaction": { + "$ref": "#/$defs/compaction" } } }, @@ -750,6 +753,9 @@ "knowledge": { "$ref": "#/$defs/agentKnowledge" }, + "compaction": { + "$ref": "#/$defs/compaction" + }, "tools": { "type": "array", "items": { @@ -764,6 +770,32 @@ } } }, + "compaction": { + "type": ["object", "null"], + "description": "Decision 3: no strategy here calls a model. A resumed call rebuilds a new session and re-derives from the replayed words, so a strategy that called a model would give one call two histories.", + "additionalProperties": false, + "properties": { + "strategy": { + "type": "string", + "enum": ["tool_result", "truncate", "sliding_window", "context_window"] + }, + "trigger": { + "type": "object", + "additionalProperties": false, + "minProperties": 1, + "maxProperties": 1, + "description": "Exactly one condition. Zero would compact on every turn; two would leave the document silent about whether they are combined with All or Any.", + "properties": { + "tokens": { "type": "integer", "minimum": 1 }, + "messages": { "type": "integer", "minimum": 1 }, + "turns": { "type": "integer", "minimum": 1 }, + "groups": { "type": "integer", "minimum": 1 } + } + }, + "keep": { "type": "integer", "minimum": 0 }, + "foldResultChars": { "type": "integer", "minimum": 1 } + } + }, "policy": { "type": "object", "required": [ @@ -1017,6 +1049,10 @@ "high" ], "description": "How hard a reasoning model thinks before it answers. Omit it to send nothing and let the vendor decide. Some reasoning models refuse function tools on the chat-completions path unless this is 'none'." + }, + "webSearch": { + "type": "boolean", + "description": "Whether this entry may run a hosted web search. An opt-out: omitted or true lets the vendor's adapter decide, false vetoes it even on a model the adapter thinks is capable." } } }, diff --git a/src/AgentCore.Application/Diagnostics/Log.cs b/src/AgentCore.Application/Diagnostics/Log.cs index 0e47a79d..5645fdc5 100644 --- a/src/AgentCore.Application/Diagnostics/Log.cs +++ b/src/AgentCore.Application/Diagnostics/Log.cs @@ -218,4 +218,22 @@ public static partial void KnowledgeScopeComposed( Message = "The probe of agent {Agent} did not answer for facet {Facet}. The turn was told the " + "knowledge base holds nothing and the call continues.")] public static partial void KnowledgeProbeFailed(ILogger logger, string agent, string facet, Exception exception); + + /// An agent declared a hosted-search tool, and its model reports no hosted web search. + /// The logger of the compiler. + /// The id of the agent that declared the tool. + /// The id of the tool that was dropped. + /// + /// A phrase naming the model, such as "the model 'reply'" or "this agent's default + /// model" when the agent names none. Built at the call site so this message never renders an + /// empty pair of quotes. + /// + [LoggerMessage( + EventId = 18, + Level = LogLevel.Warning, + Message = "The agent '{AgentId}' declares the tool '{ToolId}', which asks the model provider " + + "to run a web search, and {Model} reports no hosted web search, so the tool was not " + + "added. Point this agent at a model whose vendor runs a hosted web search, or remove " + + "the tool from this agent.")] + public static partial void HostedWebSearchDropped(ILogger logger, string agentId, string toolId, string model); } diff --git a/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs b/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs index afd64927..a209302a 100644 --- a/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs +++ b/src/AgentCore.Application/Llm/CompositeChatClientFactory.cs @@ -37,6 +37,7 @@ public sealed class CompositeChatClientFactory : IChatClientFactory, IDisposable private readonly Dictionary _entries = new(StringComparer.Ordinal); private readonly Dictionary _vendor = new(StringComparer.Ordinal); private readonly ConcurrentDictionary _shaped = new(StringComparer.Ordinal); + private readonly Dictionary _capable = new(StringComparer.Ordinal); private LlmProviderConfiguration? _default; private int _disposed; @@ -87,6 +88,7 @@ public static async ValueTask CreateAsync( factory._vendor[entry.As] = await adapter .CreateClientAsync(entry, secrets, cancellationToken) .ConfigureAwait(false); + factory._capable[entry.As] = adapter.SupportsHostedWebSearch(entry); factory._default ??= entry; } @@ -124,6 +126,14 @@ public IChatClient GetChatClient(ModelReference? model) .Build()); } + /// + public bool SupportsHostedWebSearch(ModelReference? model) + { + ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this); + + return _capable.TryGetValue(model?.Ref ?? _default?.As ?? string.Empty, out var capable) && capable; + } + /// Releases every client the adapters built. /// /// A shaped client is a view over a shared vendor client, not an owner of one: it holds no diff --git a/src/AgentCore.Application/Ports/IChatClientAdapter.cs b/src/AgentCore.Application/Ports/IChatClientAdapter.cs index 2c2b8b69..c2736509 100644 --- a/src/AgentCore.Application/Ports/IChatClientAdapter.cs +++ b/src/AgentCore.Application/Ports/IChatClientAdapter.cs @@ -6,18 +6,6 @@ namespace AgentCore.Application.Ports; /// /// Builds the vendor client behind one providers.llm[].kind value. /// -/// -/// -/// The document names a vendor in kind and the host registers one adapter for each vendor it -/// supports. CompositeChatClientFactory routes each entry to the adapter whose -/// matches, so a document that changes vendors changes no code. -/// -/// -/// An adapter owns its vendor only: the SDK client, the credential, the model name. Everything -/// vendor-neutral — the as map, the default entry, the temperature wrapper, the cache — lives -/// in the composite, so no adapter repeats it. -/// -/// public interface IChatClientAdapter : IVendorAdapter { /// Builds the vendor client of one entry. @@ -25,12 +13,13 @@ public interface IChatClientAdapter : IVendorAdapter /// The chain a credential resolves through, or . /// Cancels the build. /// The client. The composite owns and disposes it; the adapter never does. - /// - /// This runs once for each as name, while the host starts. A bad credential therefore - /// stops the host, never a call. - /// ValueTask CreateClientAsync( LlmProviderConfiguration entry, ISecretResolverPort? secrets, CancellationToken cancellationToken = default); + + /// Whether this vendor runs a hosted web search for one entry. + /// The providers.llm[] entry this adapter serves. + /// when the vendor runs the search itself. + bool SupportsHostedWebSearch(LlmProviderConfiguration entry) => false; } diff --git a/src/AgentCore.Application/Ports/IChatClientFactory.cs b/src/AgentCore.Application/Ports/IChatClientFactory.cs index fe1f4cde..abcc2603 100644 --- a/src/AgentCore.Application/Ports/IChatClientFactory.cs +++ b/src/AgentCore.Application/Ports/IChatClientFactory.cs @@ -6,11 +6,6 @@ namespace AgentCore.Application.Ports; /// /// Resolves a { ref: reply } model reference to a chat client. /// -/// -/// providers: configures adapters and never changes agent shape, so the compiler never reads -/// a vendor name. It asks for the client behind the as name and builds the same agent either -/// way. This is the seam where the LLM port binds. -/// public interface IChatClientFactory { /// Gets the chat client one model reference names. @@ -20,4 +15,9 @@ public interface IChatClientFactory /// /// The chat client. The compiler never disposes it. IChatClient GetChatClient(ModelReference? model); + + /// Whether the vendor behind one model reference runs a hosted web search. + /// The reference, or for the factory's default entry. + /// when the vendor runs the search itself. + bool SupportsHostedWebSearch(ModelReference? model) => false; } diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index f22050c2..2ae805c1 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -144,6 +144,7 @@ AgentCore.Application.Calls.Memory.InMemoryCallStore.SetExternalIdAsync(string! AgentCore.Application.Calls.Memory.InMemoryCallStore.SetStatusAsync(string! callId, AgentCore.Application.Calls.CallStatus status, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Calls.Memory.InMemoryCallStore.SweepAsync(System.TimeSpan retention, int batchSize = 500, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Calls.Memory.InMemoryCallStore.TruncateAsync(string! callId, int fromOrdinal, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Configuration.Compilation.AgentCompaction AgentCore.Application.Configuration.Compilation.AgentCompilationContext AgentCore.Application.Configuration.Compilation.AgentCompilationContext.AgentCompilationContext(AgentCore.Application.Ports.IChatClientFactory! chatClients) -> void AgentCore.Application.Configuration.Compilation.AgentCompilationContext.CallStore.get -> AgentCore.Application.Ports.ICallStore? @@ -201,6 +202,19 @@ AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardFa AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardFacets.init -> void AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardValue.get -> string? AgentCore.Application.Configuration.Compilation.ResolvedClarification.WildcardValue.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedCompaction +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.$() -> AgentCore.Application.Configuration.Compilation.ResolvedCompaction! +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Deconstruct(out AgentCore.Application.Configuration.Schema.CompactionStrategyKind Strategy, out AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! Trigger, out int Keep, out int FoldResultChars) -> void +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Equals(AgentCore.Application.Configuration.Compilation.ResolvedCompaction? other) -> bool +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.FoldResultChars.get -> int +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.FoldResultChars.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Keep.get -> int +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Keep.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.ResolvedCompaction(AgentCore.Application.Configuration.Schema.CompactionStrategyKind Strategy, AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! Trigger, int Keep, int FoldResultChars) -> void +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Strategy.get -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Strategy.init -> void +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Trigger.get -> AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! +AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Trigger.init -> void AgentCore.Application.Configuration.Compilation.ResolvedKnowledge AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.$() -> AgentCore.Application.Configuration.Compilation.ResolvedKnowledge! AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Citations.get -> bool @@ -280,6 +294,8 @@ AgentCore.Application.Configuration.Parsing.YamlToJson AgentCore.Application.Configuration.Schema.AgentConfiguration AgentCore.Application.Configuration.Schema.AgentConfiguration.$() -> AgentCore.Application.Configuration.Schema.AgentConfiguration! AgentCore.Application.Configuration.Schema.AgentConfiguration.AgentConfiguration() -> void +AgentCore.Application.Configuration.Schema.AgentConfiguration.Compaction.get -> AgentCore.Application.Configuration.Schema.CompactionConfiguration? +AgentCore.Application.Configuration.Schema.AgentConfiguration.Compaction.init -> void AgentCore.Application.Configuration.Schema.AgentConfiguration.Equals(AgentCore.Application.Configuration.Schema.AgentConfiguration? other) -> bool AgentCore.Application.Configuration.Schema.AgentConfiguration.Id.get -> string! AgentCore.Application.Configuration.Schema.AgentConfiguration.Id.init -> void @@ -330,6 +346,8 @@ AgentCore.Application.Configuration.Schema.AgentCoreConfiguration.Tools.init -> AgentCore.Application.Configuration.Schema.AgentDefaults AgentCore.Application.Configuration.Schema.AgentDefaults.$() -> AgentCore.Application.Configuration.Schema.AgentDefaults! AgentCore.Application.Configuration.Schema.AgentDefaults.AgentDefaults() -> void +AgentCore.Application.Configuration.Schema.AgentDefaults.Compaction.get -> AgentCore.Application.Configuration.Schema.CompactionConfiguration? +AgentCore.Application.Configuration.Schema.AgentDefaults.Compaction.init -> void AgentCore.Application.Configuration.Schema.AgentDefaults.Equals(AgentCore.Application.Configuration.Schema.AgentDefaults? other) -> bool AgentCore.Application.Configuration.Schema.AgentDefaults.Instructions.get -> string? AgentCore.Application.Configuration.Schema.AgentDefaults.Instructions.init -> void @@ -369,6 +387,35 @@ AgentCore.Application.Configuration.Schema.CallProviderConfiguration.Kind.get -> AgentCore.Application.Configuration.Schema.CallProviderConfiguration.Kind.init -> void AgentCore.Application.Configuration.Schema.CallProviderConfiguration.MaxFrameBytes.get -> int? AgentCore.Application.Configuration.Schema.CallProviderConfiguration.MaxFrameBytes.init -> void +AgentCore.Application.Configuration.Schema.CompactionConfiguration +AgentCore.Application.Configuration.Schema.CompactionConfiguration.$() -> AgentCore.Application.Configuration.Schema.CompactionConfiguration! +AgentCore.Application.Configuration.Schema.CompactionConfiguration.CompactionConfiguration() -> void +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Equals(AgentCore.Application.Configuration.Schema.CompactionConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.CompactionConfiguration.FoldResultChars.get -> int? +AgentCore.Application.Configuration.Schema.CompactionConfiguration.FoldResultChars.init -> void +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Keep.get -> int? +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Keep.init -> void +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Strategy.get -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind? +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Strategy.init -> void +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Trigger.get -> AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? +AgentCore.Application.Configuration.Schema.CompactionConfiguration.Trigger.init -> void +AgentCore.Application.Configuration.Schema.CompactionStrategyKind +AgentCore.Application.Configuration.Schema.CompactionStrategyKind.ContextWindow = 3 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind +AgentCore.Application.Configuration.Schema.CompactionStrategyKind.SlidingWindow = 2 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind +AgentCore.Application.Configuration.Schema.CompactionStrategyKind.ToolResult = 0 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind +AgentCore.Application.Configuration.Schema.CompactionStrategyKind.Truncate = 1 -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.$() -> AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration! +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.CompactionTriggerConfiguration() -> void +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Equals(AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? other) -> bool +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Groups.get -> int? +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Groups.init -> void +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Messages.get -> int? +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Messages.init -> void +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Tokens.get -> int? +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Tokens.init -> void +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Turns.get -> int? +AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Turns.init -> void AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.$() -> AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration! AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.Dimensions.get -> int? @@ -557,6 +604,8 @@ AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.Model.get -> AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.Model.init -> void AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.ReasoningEffort.get -> string? AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.ReasoningEffort.init -> void +AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.WebSearch.get -> bool? +AgentCore.Application.Configuration.Schema.LlmProviderConfiguration.WebSearch.init -> void AgentCore.Application.Configuration.Schema.McpAllowEntry AgentCore.Application.Configuration.Schema.McpAllowEntry.$() -> AgentCore.Application.Configuration.Schema.McpAllowEntry! AgentCore.Application.Configuration.Schema.McpAllowEntry.As.get -> string? @@ -894,6 +943,7 @@ AgentCore.Application.Knowledge.SourceLocatorCitationFormatter.SourceLocatorCita AgentCore.Application.Llm.CompositeChatClientFactory AgentCore.Application.Llm.CompositeChatClientFactory.Dispose() -> void AgentCore.Application.Llm.CompositeChatClientFactory.GetChatClient(AgentCore.Application.Configuration.Schema.ModelReference? model) -> Microsoft.Extensions.AI.IChatClient! +AgentCore.Application.Llm.CompositeChatClientFactory.SupportsHostedWebSearch(AgentCore.Application.Configuration.Schema.ModelReference? model) -> bool AgentCore.Application.Policy.StagePolicy AgentCore.Application.Policy.StagePolicy.Advance(System.Collections.Generic.IReadOnlyDictionary! state) -> string! AgentCore.Application.Policy.StagePolicy.Configuration.get -> AgentCore.Application.Configuration.Schema.PolicyConfiguration! @@ -952,8 +1002,10 @@ AgentCore.Application.Ports.ICallTitler.GenerateAsync(string! callId, System.Thr AgentCore.Application.Ports.ICallTitler.GenerateFromAsync(string! callId, System.Collections.Generic.IReadOnlyList! messages, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable! AgentCore.Application.Ports.IChatClientAdapter AgentCore.Application.Ports.IChatClientAdapter.CreateClientAsync(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +AgentCore.Application.Ports.IChatClientAdapter.SupportsHostedWebSearch(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry) -> bool AgentCore.Application.Ports.IChatClientFactory AgentCore.Application.Ports.IChatClientFactory.GetChatClient(AgentCore.Application.Configuration.Schema.ModelReference? model) -> Microsoft.Extensions.AI.IChatClient! +AgentCore.Application.Ports.IChatClientFactory.SupportsHostedWebSearch(AgentCore.Application.Configuration.Schema.ModelReference? model) -> bool AgentCore.Application.Ports.IConversationPort AgentCore.Application.Ports.IConversationPort.CallId.get -> string! AgentCore.Application.Ports.IConversationPort.Interrupt(string! utteranceUntilInterrupt, System.TimeSpan durationUntilInterrupt, bool cutsRunningTurn = true) -> bool @@ -1297,6 +1349,9 @@ const AgentCore.Application.Audit.QueuedAuditSink.DefaultBatchSize = 100 -> int const AgentCore.Application.Audit.QueuedAuditSink.DefaultCapacity = 10000 -> int const AgentCore.Application.Calls.CallSessionState.CurrentVersion = 1 -> int const AgentCore.Application.Calls.CallStoreFactory.MemoryKind = "memory" -> string! +const AgentCore.Application.Configuration.Compilation.AgentCompaction.DefaultFoldResultChars = 200 -> int +const AgentCore.Application.Configuration.Compilation.AgentCompaction.DefaultKeep = 4 -> int +const AgentCore.Application.Configuration.Compilation.AgentCompaction.DefaultStrategy = AgentCore.Application.Configuration.Schema.CompactionStrategyKind.ToolResult -> AgentCore.Application.Configuration.Schema.CompactionStrategyKind const AgentCore.Application.Configuration.Compilation.AgentInstructions.Separator = "\n\n" -> string! const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultCitations = false -> bool const AgentCore.Application.Configuration.Compilation.AgentKnowledge.DefaultLimit = 5 -> int @@ -1359,6 +1414,7 @@ const AgentCore.Application.State.StateExtractor.SchemaName = "agentcore_state" const AgentCore.Application.State.UnfilledSlotReminder.CloseTag = "" -> string! const AgentCore.Application.State.UnfilledSlotReminder.OpenTag = "" -> string! const AgentCore.Application.Tools.Builtin.BuiltinToolNames.Draw = "ui.draw" -> string! +const AgentCore.Application.Tools.Builtin.BuiltinToolNames.WebSearch = "web.search" -> string! const AgentCore.Application.Tools.ToolErrorResult.ErrorProperty = "error" -> string! const AgentCore.Application.Tools.ToolErrorResult.MessageProperty = "message" -> string! const AgentCore.Application.Tools.ToolErrorResult.ToolProperty = "tool" -> string! @@ -1388,6 +1444,7 @@ static AgentCore.Application.Calls.CallSessionState.operator !=(AgentCore.Applic static AgentCore.Application.Calls.CallSessionState.operator ==(AgentCore.Application.Calls.CallSessionState? left, AgentCore.Application.Calls.CallSessionState? right) -> bool static AgentCore.Application.Calls.CallStateJson.Options.get -> System.Text.Json.JsonSerializerOptions! static AgentCore.Application.Calls.CallStoreFactory.OpenAsync(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Collections.Generic.IReadOnlyList! adapters, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +static AgentCore.Application.Configuration.Compilation.AgentCompaction.Compose(AgentCore.Application.Configuration.Schema.AgentDefaults? defaults, AgentCore.Application.Configuration.Schema.AgentConfiguration! agent) -> AgentCore.Application.Configuration.Compilation.ResolvedCompaction? static AgentCore.Application.Configuration.Compilation.AgentInstructions.Compose(AgentCore.Application.Configuration.Schema.AgentDefaults? defaults, AgentCore.Application.Configuration.Schema.AgentConfiguration! agent) -> string? static AgentCore.Application.Configuration.Compilation.AgentKnowledge.AllScoped(AgentCore.Application.Configuration.Schema.AgentsConfiguration! agents) -> bool static AgentCore.Application.Configuration.Compilation.AgentKnowledge.AnyDeclared(AgentCore.Application.Configuration.Schema.AgentsConfiguration! agents) -> bool @@ -1398,6 +1455,8 @@ static AgentCore.Application.Configuration.Compilation.ConfigurationCompiler.Sel static AgentCore.Application.Configuration.Compilation.ResolvedClarification.From(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration) -> AgentCore.Application.Configuration.Compilation.ResolvedClarification! static AgentCore.Application.Configuration.Compilation.ResolvedClarification.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedClarification? left, AgentCore.Application.Configuration.Compilation.ResolvedClarification? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedClarification.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedClarification? left, AgentCore.Application.Configuration.Compilation.ResolvedClarification? right) -> bool +static AgentCore.Application.Configuration.Compilation.ResolvedCompaction.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedCompaction? left, AgentCore.Application.Configuration.Compilation.ResolvedCompaction? right) -> bool +static AgentCore.Application.Configuration.Compilation.ResolvedCompaction.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedCompaction? left, AgentCore.Application.Configuration.Compilation.ResolvedCompaction? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.operator !=(AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? left, AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? right) -> bool static AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.operator ==(AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? left, AgentCore.Application.Configuration.Compilation.ResolvedKnowledge? right) -> bool static AgentCore.Application.Configuration.Parsing.ConfigurationError.AppendPointer(string! pointer, int index) -> string! @@ -1434,6 +1493,10 @@ static AgentCore.Application.Configuration.Schema.AgentsConfiguration.operator ! static AgentCore.Application.Configuration.Schema.AgentsConfiguration.operator ==(AgentCore.Application.Configuration.Schema.AgentsConfiguration? left, AgentCore.Application.Configuration.Schema.AgentsConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.CallProviderConfiguration.operator !=(AgentCore.Application.Configuration.Schema.CallProviderConfiguration? left, AgentCore.Application.Configuration.Schema.CallProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.CallProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.CallProviderConfiguration? left, AgentCore.Application.Configuration.Schema.CallProviderConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.CompactionConfiguration.operator !=(AgentCore.Application.Configuration.Schema.CompactionConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.CompactionConfiguration.operator ==(AgentCore.Application.Configuration.Schema.CompactionConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.operator !=(AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? right) -> bool +static AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.operator ==(AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? left, AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.operator !=(AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? left, AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.operator ==(AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? left, AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration? right) -> bool static AgentCore.Application.Configuration.Schema.EvaluationConfiguration.operator !=(AgentCore.Application.Configuration.Schema.EvaluationConfiguration? left, AgentCore.Application.Configuration.Schema.EvaluationConfiguration? right) -> bool @@ -1637,6 +1700,9 @@ override AgentCore.Application.Calls.CallSessionState.ToString() -> string! override AgentCore.Application.Configuration.Compilation.ResolvedClarification.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Compilation.ResolvedClarification.GetHashCode() -> int override AgentCore.Application.Configuration.Compilation.ResolvedClarification.ToString() -> string! +override AgentCore.Application.Configuration.Compilation.ResolvedCompaction.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Compilation.ResolvedCompaction.GetHashCode() -> int +override AgentCore.Application.Configuration.Compilation.ResolvedCompaction.ToString() -> string! override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.GetHashCode() -> int override AgentCore.Application.Configuration.Compilation.ResolvedKnowledge.ToString() -> string! @@ -1670,6 +1736,12 @@ override AgentCore.Application.Configuration.Schema.AgentsConfiguration.ToString override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.CallProviderConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.CompactionConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.CompactionConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.CompactionConfiguration.ToString() -> string! +override AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.Equals(object? obj) -> bool +override AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.GetHashCode() -> int +override AgentCore.Application.Configuration.Schema.CompactionTriggerConfiguration.ToString() -> string! override AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.Equals(object? obj) -> bool override AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.GetHashCode() -> int override AgentCore.Application.Configuration.Schema.EmbeddingProviderConfiguration.ToString() -> string! diff --git a/src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs b/src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs new file mode 100644 index 00000000..b7b863dd --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/CappedToolCallFormatter.cs @@ -0,0 +1,68 @@ +using System.Text; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Runtime.Compaction; + +#pragma warning disable MAAI001 // CompactionMessageGroup is the framework's own experimental surface. + +/// +/// Writes a folded tool-call group as the tool's name and the head of its result. +/// +internal static class CappedToolCallFormatter +{ + private const char Cut = '…'; + + /// Builds a formatter that carries at most of each result. + /// Characters of each tool result to keep. Must be positive. + /// The formatter, for ToolResultCompactionStrategy.ToolCallFormatter. + public static Func Create(int maxResultChars) + { + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxResultChars); + + return group => + { + ArgumentNullException.ThrowIfNull(group); + + var calls = group.Messages + .SelectMany(message => message.Contents.OfType()) + .ToList(); + + if (calls.Count == 0) + { + return string.Empty; + } + + // A repeated CallId is a duplicated tool result — a replayed transcript, or a provider + // that reused an id across parallel calls. MAF's own DefaultToolCallFormatter resolves + // that the same way: last one written wins. + var results = new Dictionary(StringComparer.Ordinal); + foreach (var result in group.Messages.SelectMany(message => message.Contents.OfType())) + { + results[result.CallId] = result.Result?.ToString() ?? string.Empty; + } + + StringBuilder written = new("[Tool Calls]"); + foreach (var call in calls) + { + written.Append('\n').Append(call.Name).Append(':'); + + if (!results.TryGetValue(call.CallId, out var result) || result.Length == 0) + { + continue; + } + + written.Append("\n - ").Append(result.AsSpan(0, Math.Min(result.Length, maxResultChars))); + + if (result.Length > maxResultChars) + { + written.Append(Cut); + } + } + + return written.ToString(); + }; + } +} + +#pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs new file mode 100644 index 00000000..afde5f06 --- /dev/null +++ b/src/AgentCore.Application/Runtime/Compaction/CompactionStrategyFactory.cs @@ -0,0 +1,55 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Schema; +using Microsoft.Agents.AI.Compaction; + +namespace AgentCore.Application.Runtime.Compaction; + +/// +/// Builds the MAF compaction strategy one agent's resolved compaction: block names. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. +internal static class CompactionStrategyFactory +{ + /// Builds the strategy. + /// The agent's resolved block. + /// The strategy, ready for a . + public static CompactionStrategy Create(ResolvedCompaction settings) + { + ArgumentNullException.ThrowIfNull(settings); + + var trigger = Trigger(settings.Trigger); + + return settings.Strategy switch + { + CompactionStrategyKind.Truncate => new TruncationCompactionStrategy(trigger, settings.Keep), + CompactionStrategyKind.SlidingWindow => new SlidingWindowCompactionStrategy(trigger, settings.Keep), + CompactionStrategyKind.ContextWindow => ContextWindow(settings), + _ => ToolResult(settings, trigger), + }; + } + + private static ToolResultCompactionStrategy ToolResult(ResolvedCompaction settings, CompactionTrigger trigger) + => new(trigger, settings.Keep) + { + ToolCallFormatter = CappedToolCallFormatter.Create(settings.FoldResultChars), + }; + + private static PipelineCompactionStrategy ContextWindow(ResolvedCompaction settings) + => new PipelineCompactionStrategy( + [ + ToolResult(settings, Trigger(settings.Trigger)), + new TruncationCompactionStrategy(Trigger(settings.Trigger), settings.Keep), + ]); + + private static CompactionTrigger Trigger(CompactionTriggerConfiguration trigger) => trigger switch + { + { Tokens: { } tokens } => CompactionTriggers.TokensExceed(tokens), + { Messages: { } messages } => CompactionTriggers.MessagesExceed(messages), + { Turns: { } turns } => CompactionTriggers.TurnsExceed(turns), + { Groups: { } groups } => CompactionTriggers.GroupsExceed(groups), + _ => throw new ArgumentException( + "the trigger names no condition. AgentCompaction.Compose refuses this before it gets here.", + nameof(trigger)), + }; +} +#pragma warning restore MAAI001 diff --git a/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs b/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs index f71b58e1..92f8c5bd 100644 --- a/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs +++ b/src/AgentCore.Application/Tools/Builtin/BuiltinToolNames.cs @@ -5,4 +5,7 @@ public static class BuiltinToolNames { /// Draws one thing for the caller to look at. public const string Draw = "ui.draw"; + + /// Lets the model provider run a web search of its own. + public const string WebSearch = "web.search"; } diff --git a/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs b/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs index 7346d634..31ef9c0c 100644 --- a/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs +++ b/src/AgentCore.Application/Tools/Builtin/BuiltinToolSource.cs @@ -13,7 +13,10 @@ namespace AgentCore.Application.Tools.Builtin; public sealed class BuiltinToolSource : IToolSource { private static readonly Dictionary Definitions = - new(StringComparer.Ordinal); + new IBuiltinToolDefinition[] + { + new WebSearchToolDefinition(), + }.ToDictionary(definition => definition.Name, StringComparer.Ordinal); private static readonly Dictionary ShippedAgents = new IShippedAgentDefinition[] diff --git a/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs b/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs new file mode 100644 index 00000000..199e8817 --- /dev/null +++ b/src/AgentCore.Application/Tools/Builtin/WebSearchToolDefinition.cs @@ -0,0 +1,20 @@ +using AgentCore.Application.Configuration.Schema; +using Microsoft.Extensions.AI; + +namespace AgentCore.Application.Tools.Builtin; + +/// +/// The uses: web.search builtin: one . +/// +internal sealed class WebSearchToolDefinition : IBuiltinToolDefinition +{ + /// + public string Name => BuiltinToolNames.WebSearch; + + /// + public string DefaultDescription => + "Searches the public web and reads the pages it finds."; + + /// + public AITool Build(ToolConfiguration tool, BuiltinToolPorts ports) => new HostedWebSearchTool(); +} diff --git a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs index 15489331..58a5a204 100644 --- a/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs +++ b/src/AgentCore.Infrastructure/Llm/OpenAI/OpenAiChatClientAdapter.cs @@ -67,6 +67,14 @@ await secrets return WithResponseDefaults(client, entry.ReasoningEffort); } + /// + public bool SupportsHostedWebSearch(LlmProviderConfiguration entry) + { + ArgumentNullException.ThrowIfNull(entry); + + return entry.WebSearch != false; + } + /// Puts store and reasoning_effort on every request this client sends. internal static IChatClient WithResponseDefaults(IChatClient client, string? effort) { diff --git a/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt b/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt index 12921fce..c8ca8d2a 100644 --- a/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Infrastructure/PublicAPI.Unshipped.txt @@ -36,6 +36,7 @@ AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.CreateClientAsync(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.Kind.get -> string! AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.OpenAiChatClientAdapter() -> void +AgentCore.Infrastructure.Llm.OpenAI.OpenAiChatClientAdapter.SupportsHostedWebSearch(AgentCore.Application.Configuration.Schema.LlmProviderConfiguration! entry) -> bool AgentCore.Infrastructure.Secrets.ChainedSecretResolver AgentCore.Infrastructure.Secrets.ChainedSecretResolver.ChainedSecretResolver(System.Collections.Generic.IEnumerable! links) -> void AgentCore.Infrastructure.Secrets.ChainedSecretResolver.Count.get -> int diff --git a/tests/AgentCore.Application.Tests/Compilation/CompactionCompilationTests.cs b/tests/AgentCore.Application.Tests/Compilation/CompactionCompilationTests.cs new file mode 100644 index 00000000..00bf057e --- /dev/null +++ b/tests/AgentCore.Application.Tests/Compilation/CompactionCompilationTests.cs @@ -0,0 +1,240 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Tests.Fakes; +using AgentCore.Application.Tests.Runtime; +using Microsoft.Agents.AI; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Compilation; + +/// +/// The compaction: block reaching a compiled agent's context providers, and the trimming +/// reaching the model. +/// +/// +/// Built from hand-constructed objects, not YAML text: these +/// tests exercise and at +/// the layer that turns a resolved compaction: block into a +/// (or turns a bad trigger into a load error), which needs no schema validation or YAML parsing to +/// reach. takes the parsed record tree directly and never +/// re-runs check 1, which is the same route AgentCompactionTests uses to exercise +/// itself. Schema-level rejection of a bad trigger is covered +/// separately, through , +/// in ConfigurationSchemaValidatorTests. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. +public sealed class CompactionCompilationTests +{ + [Fact] + public void Compile_AgentWithCompaction_GetsAProvider() + { + var providers = Providers(WithCompaction()); + + Assert.Contains(providers, provider => provider is CompactionProvider); + } + + [Fact] + public void Compile_AgentWithoutCompaction_GetsNoProvider() + { + var providers = Providers(WithoutCompaction()); + + Assert.DoesNotContain(providers, provider => provider is CompactionProvider); + } + + [Fact] + public void Compile_BlockOnOneAgentOnly_GivesOnlyThatAgentAProvider() + { + // There is no per-agent opt-out: an omitted block and an explicit null are one value in C#. + // Selective compaction is expressed by declaring the block per agent instead of on defaults. + var (withBlock, withoutBlock) = TwoAgentsOneWithCompaction(); + + Assert.Contains(withBlock, provider => provider is CompactionProvider); + Assert.DoesNotContain(withoutBlock, provider => provider is CompactionProvider); + } + + [Fact] + public void Compile_TriggerNamesTwoConditions_FailsNamingTheAgentAndThePointer() + { + var failure = Assert.Throws(() => CompileOne(TwoTriggerConditions())); + + Assert.Contains("agent 'only'", failure.Message, StringComparison.Ordinal); + Assert.Equal("/agents/items/0/compaction/trigger", Assert.Single(failure.Errors).Pointer); + Assert.Equal(ConfigurationCheck.DocumentSchema, Assert.Single(failure.Errors).Check); + } + + [Fact] + public async Task Compile_CompactionBlock_TrimsWhatTheModelSeesAcrossTurns() + { + // CompactionStrategyFactoryTests.Create_SameWordsTwiceFromEmptyState_Agrees calls the static + // CompactionProvider.CompactAsync directly, from empty state, twice — it never opens a session + // and cannot see the incremental path CompactionProvider actually runs in a compiled agent. This + // one runs a real compiled agent over several turns of one reused session, and reads back what + // the chat client was actually sent. Remove the CompactionProvider from + // AgentContextProviderCompiler.Build and this goes red: the model would then see every message + // the conversation holds, on every turn. + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "compaction-reaches-the-model", + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration + { + Id = "only", + Compaction = new CompactionConfiguration + { + Strategy = CompactionStrategyKind.Truncate, + Trigger = new CompactionTriggerConfiguration { Messages = 4 }, + Keep = 2, + }, + }, + ], + }, + }, + new AgentCompilationContext(new FakeChatClientFactory(reply))); + + var agent = Assert.Single(compiled.Agents.Values); + var token = TestContext.Current.CancellationToken; + var session = await agent.CreateSessionAsync(token); + + // AgentCoreChatHistoryProvider (this agent's ChatHistoryProvider, because SingleAgentRow sets + // SessionCarriesHistory) reads store 1, which nothing here writes to, so it always hands back an + // empty history and never grows the request on its own. The conversation this test measures is + // instead built by hand and re-sent whole on every turn — exactly the shape a resumed call + // replays, which is the case CompactionProvider's incremental path exists for. + List conversation = []; + var sizeBeforeTheLastCompaction = 0; + + const int turns = 6; + for (var turn = 0; turn < turns; turn++) + { + conversation.Add(new ChatMessage(ChatRole.User, $"turn {turn}")); + sizeBeforeTheLastCompaction = conversation.Count; + + var response = await agent.RunAsync(conversation, session, cancellationToken: token); + + conversation.AddRange(response.Messages); + } + + var lastRequestSize = reply.Requests[^1].Count; + + Assert.True( + lastRequestSize < sizeBeforeTheLastCompaction, + $"the model saw {lastRequestSize} messages on the last turn, of a conversation that held " + + $"{sizeBeforeTheLastCompaction} before compaction ran."); + } + + private static AgentCoreConfiguration TwoTriggerConditions() => new() + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "compaction-bad-trigger", + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration + { + Id = "only", + Compaction = new CompactionConfiguration + { + Strategy = CompactionStrategyKind.ToolResult, + Trigger = new CompactionTriggerConfiguration { Tokens = 60000, Messages = 40 }, + }, + }, + ], + }, + }; + + private static AIAgent WithCompaction() => CompileOne(new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "compaction-only", + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration + { + Id = "only", + Compaction = Block(), + }, + ], + }, + }); + + private static AIAgent WithoutCompaction() => CompileOne(new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "no-compaction", + Agents = new AgentsConfiguration + { + Items = [new AgentConfiguration { Id = "only" }], + }, + }); + + private static (IEnumerable WithBlock, IEnumerable WithoutBlock) + TwoAgentsOneWithCompaction() + { + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "compaction-per-agent", + Policy = new PolicyConfiguration + { + Initial = "opening", + Stages = + [ + new StageConfiguration { Id = "opening", Agent = "withBlock" }, + new StageConfiguration { Id = "closing", Agent = "withoutBlock" }, + ], + }, + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration { Id = "withBlock", Compaction = Block() }, + new AgentConfiguration { Id = "withoutBlock" }, + ], + }, + }, + new AgentCompilationContext(new FakeChatClientFactory(reply))); + + return (Providers(compiled.Agents["withBlock"]), Providers(compiled.Agents["withoutBlock"])); + } + + private static CompactionConfiguration Block() => new() + { + Strategy = CompactionStrategyKind.ToolResult, + Trigger = new CompactionTriggerConfiguration { Tokens = 60000 }, + }; + + private static AIAgent CompileOne(AgentCoreConfiguration configuration) + { + using SequencedChatClient reply = new("hello there."); + + var compiled = ConfigurationCompiler.Compile( + configuration, + new AgentCompilationContext(new FakeChatClientFactory(reply))); + + return Assert.Single(compiled.Agents.Values); + } + + private static IEnumerable Providers(AIAgent agent) + { + var inner = agent.GetService(); + Assert.NotNull(inner); + return inner.AIContextProviders ?? []; + } +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Compilation/HostedWebSearchDropTests.cs b/tests/AgentCore.Application.Tests/Compilation/HostedWebSearchDropTests.cs new file mode 100644 index 00000000..ac61308c --- /dev/null +++ b/tests/AgentCore.Application.Tests/Compilation/HostedWebSearchDropTests.cs @@ -0,0 +1,207 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; +using AgentCore.Application.Tests.Runtime; +using AgentCore.Application.Tools.Builtin; +using AgentCore.Application.Tools.Registry; +using AgentCore.TestSupport; +using Microsoft.Agents.AI; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Compilation; + +/// +/// The hosted web-search marker reaching, or not reaching, one compiled agent. +/// +public sealed class HostedWebSearchDropTests +{ + private const string SearchToolId = BuiltinToolNames.WebSearch; + + [Fact] + public void Compile_CapableModel_KeepsTheTool() + { + var tools = Tools(agent: "reply", capable: true); + + Assert.Single(tools.OfType()); + } + + [Fact] + public void Compile_IncapableModel_DropsTheTool() + { + var tools = Tools(agent: "reply", capable: false); + + Assert.Empty(tools.OfType()); + } + + [Fact] + public void Compile_IncapableModel_LogsOneWarning() + { + var (tools, logs) = ToolsAndLogs(agent: "reply", capable: false); + + Assert.Empty(tools.OfType()); + var warning = Assert.Single(logs); + Assert.Contains("reply", warning, StringComparison.Ordinal); + Assert.Contains("web.search", warning, StringComparison.Ordinal); + } + + [Fact] + public void Compile_IncapableModel_DoesNotThrow() + { + // An agent with no web search still answers. This never stops a host. + Assert.Null(Record.Exception(() => Tools(agent: "reply", capable: false))); + } + + [Fact] + public void Compile_TwoAgentsOnDifferentModels_OnlyTheCapableOneKeepsIt() + { + var (capable, incapable) = TwoAgents(); + + Assert.Single(capable.OfType()); + Assert.Empty(incapable.OfType()); + } + + [Fact] + public void Compile_HostSuppliedHostedTool_IsDroppedByTheSameRule() + { + // The check tests the tool type, not the builtin name, so a hosted search tool arriving + // from a host's own IToolSource is covered with no second place to forget. + var tools = ToolsFromHostSource(capable: false); + + Assert.Empty(tools.OfType()); + } + + [Fact] + public async Task Compile_TwoAgentsOnDifferentModels_ThroughTheRealCompiler_OnlyTheCapableOneKeepsIt() + { + // AgentToolCompiler.Build takes the model as a parameter, and the six tests above call it + // directly. None of them exercises the expression that picks that parameter per agent + // (ConfigurationCompiler's item.Model ?? section.Defaults?.Model), so this one goes through + // ConfigurationCompiler.Compile on a document with two agents pinned to two different models, + // and reads back what each agent actually sent its chat client. + const string capableRef = "vendor-a"; + const string incapableRef = "vendor-b"; + + using SequencedChatClient reply = new("hello there."); + var registry = BuildRegistry([new BuiltinToolSource(new BuiltinToolPorts(null))], [SearchTool()]); + + var compiled = ConfigurationCompiler.Compile( + new AgentCoreConfiguration + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "hosted-web-search-two-models", + Tools = [SearchTool()], + Policy = new PolicyConfiguration + { + Initial = "opening", + Stages = + [ + new StageConfiguration { Id = "opening", Agent = "capable" }, + new StageConfiguration { Id = "closing", Agent = "incapable" }, + ], + }, + Agents = new AgentsConfiguration + { + Items = + [ + new AgentConfiguration { Id = "capable", Model = new ModelReference { Ref = capableRef }, Tools = [SearchToolId] }, + new AgentConfiguration { Id = "incapable", Model = new ModelReference { Ref = incapableRef }, Tools = [SearchToolId] }, + ], + }, + }, + new AgentCompilationContext(new RoutingCapabilityChatClientFactory(capableRef, reply)) { Tools = registry }); + + var token = TestContext.Current.CancellationToken; + await compiled.Agents["capable"].RunAsync("hi", cancellationToken: token); + await compiled.Agents["incapable"].RunAsync("hi", cancellationToken: token); + + Assert.Single((reply.Options[0]?.Tools ?? []).OfType()); + Assert.Empty((reply.Options[1]?.Tools ?? []).OfType()); + } + + private static ToolConfiguration SearchTool() + => new() { Id = SearchToolId, Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }; + + private static List Tools(string agent, bool capable) + => BuildAgentTools(agent, model: null, new CapabilityChatClientFactory(capable)); + + private static (List Tools, List Logs) ToolsAndLogs(string agent, bool capable) + { + RecordingLoggerFactory loggers = new(); + var tools = BuildAgentTools(agent, model: null, new CapabilityChatClientFactory(capable), loggers); + return (tools, [.. loggers.Of(18).Select(line => line.Message)]); + } + + private static (List Capable, List Incapable) TwoAgents() + { + const string capableRef = "vendor-a"; + const string incapableRef = "vendor-b"; + + var factory = new RoutingCapabilityChatClientFactory(capableRef); + + var capable = BuildAgentTools("capable", new ModelReference { Ref = capableRef }, factory); + var incapable = BuildAgentTools("incapable", new ModelReference { Ref = incapableRef }, factory); + return (capable, incapable); + } + + private static List ToolsFromHostSource(bool capable) + { + const string hostToolId = "vendor_search"; + + AgentConfiguration item = new() { Id = "reply", Tools = [hostToolId] }; + Dictionary declared = new(StringComparer.Ordinal); + var registry = BuildRegistry([new HostSearchToolSource(hostToolId)], []); + + AgentCompilationContext context = new(new CapabilityChatClientFactory(capable)) { Tools = registry }; + + return AgentToolCompiler.Build(item, model: null, declared, context, "/agents/items/0", static _ => null) ?? []; + } + + private static List BuildAgentTools( + string agentId, ModelReference? model, IChatClientFactory chatClients, RecordingLoggerFactory? loggers = null) + { + var search = SearchTool(); + AgentConfiguration item = new() { Id = agentId, Tools = [SearchToolId] }; + Dictionary declared = new(StringComparer.Ordinal) { [SearchToolId] = search }; + var registry = BuildRegistry([new BuiltinToolSource(new BuiltinToolPorts(null))], [search]); + + AgentCompilationContext context = new(chatClients) { Tools = registry, Loggers = loggers }; + + return AgentToolCompiler.Build(item, model, declared, context, "/agents/items/0", static _ => null) ?? []; + } + + private static ToolRegistry BuildRegistry(IEnumerable sources, IReadOnlyList declared) + { + AgentCoreConfiguration document = new() + { + ApiVersion = AgentCoreConfiguration.SupportedApiVersion, + Name = "hosted-web-search-drop", + Tools = declared, + }; + + return ToolRegistryBuilder.BuildAsync(sources, new ToolSourceContext(document)).AsTask().GetAwaiter().GetResult(); + } + + private sealed class HostSearchToolSource(string id) : IToolSource + { + public ValueTask> ProvideAsync( + ToolSourceContext context, CancellationToken cancellationToken = default) + => ValueTask.FromResult>( + [new ToolRegistration(id, "A vendor's own hosted search.", () => new HostedWebSearchTool())]); + } + + private sealed class CapabilityChatClientFactory(bool capable) : IChatClientFactory + { + public IChatClient GetChatClient(ModelReference? model) => throw new NotSupportedException(); + + public bool SupportsHostedWebSearch(ModelReference? model) => capable; + } + + private sealed class RoutingCapabilityChatClientFactory(string capableRef, IChatClient? client = null) : IChatClientFactory + { + public IChatClient GetChatClient(ModelReference? model) => client ?? throw new NotSupportedException(); + + public bool SupportsHostedWebSearch(ModelReference? model) + => string.Equals(model?.Ref, capableRef, StringComparison.Ordinal); + } +} diff --git a/tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs b/tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs new file mode 100644 index 00000000..06262f40 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Configuration/AgentCompactionTests.cs @@ -0,0 +1,87 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Schema; +using Xunit; + +namespace AgentCore.Application.Tests.Configuration; + +/// +/// : the key-by-key merge of one agent's compaction: block +/// against agents.defaults.compaction. +/// +public sealed class AgentCompactionTests +{ + [Fact] + public void Compose_NoBlockAnywhere_IsNull() + { + Assert.Null(AgentCompaction.Compose(defaults: null, Agent(compaction: null))); + } + + [Fact] + public void Compose_DefaultsOnly_IsInherited() + { + var resolved = AgentCompaction.Compose( + new AgentDefaults { Compaction = Block(CompactionStrategyKind.Truncate) }, + Agent(compaction: null)); + + Assert.NotNull(resolved); + Assert.Equal(CompactionStrategyKind.Truncate, resolved.Strategy); + } + + [Fact] + public void Compose_AgentOverridesDefaults_TakesTheAgent() + { + var resolved = AgentCompaction.Compose( + new AgentDefaults { Compaction = Block(CompactionStrategyKind.Truncate) }, + Agent(Block(CompactionStrategyKind.ToolResult))); + + Assert.NotNull(resolved); + Assert.Equal(CompactionStrategyKind.ToolResult, resolved.Strategy); + } + + [Fact] + public void Compose_UnsetKeys_TakeTheDocumentedDefaults() + { + var resolved = AgentCompaction.Compose( + defaults: null, + Agent(new CompactionConfiguration + { + Strategy = CompactionStrategyKind.ToolResult, + Trigger = new CompactionTriggerConfiguration { Tokens = 60000 }, + })); + + Assert.NotNull(resolved); + Assert.Equal(AgentCompaction.DefaultKeep, resolved.Keep); + Assert.Equal(AgentCompaction.DefaultFoldResultChars, resolved.FoldResultChars); + } + + [Fact] + public void Compose_NoTrigger_Throws() + { + var exception = Assert.Throws(() => AgentCompaction.Compose( + defaults: null, + Agent(new CompactionConfiguration { Strategy = CompactionStrategyKind.Truncate }))); + + Assert.Contains("exactly one", exception.Message, StringComparison.Ordinal); + } + + [Fact] + public void Compose_TwoTriggers_Throws() + { + Assert.Throws(() => AgentCompaction.Compose( + defaults: null, + Agent(new CompactionConfiguration + { + Strategy = CompactionStrategyKind.Truncate, + Trigger = new CompactionTriggerConfiguration { Tokens = 60000, Messages = 40 }, + }))); + } + + private static CompactionConfiguration Block(CompactionStrategyKind strategy) => new() + { + Strategy = strategy, + Trigger = new CompactionTriggerConfiguration { Tokens = 60000 }, + }; + + private static AgentConfiguration Agent(CompactionConfiguration? compaction) => + new() { Id = "reply", Compaction = compaction }; +} diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs index b1c74f80..f88697cf 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationLoaderTests.cs @@ -70,7 +70,7 @@ public void Example_KeepsEveryGuardAsRawJsonLogic() [Fact] public void Example_BindsEveryToolKind() { - Assert.Equal(3, Example.Tools.Count); + Assert.Equal(4, Example.Tools.Count); Assert.Equal(ToolKind.Builtin, Example.Tools[0].Kind); Assert.Equal("ui.draw", Example.Tools[0].Uses); @@ -80,6 +80,9 @@ public void Example_BindsEveryToolKind() Assert.Equal("CreateCase", binding.Binds); Assert.NotNull(binding.Parameters); Assert.Equal("object", binding.Parameters!["type"]!.GetValue()); + + Assert.Equal(ToolKind.Builtin, Example.Tools[3].Kind); + Assert.Equal("web.search", Example.Tools[3].Uses); } [Fact] @@ -149,6 +152,7 @@ public void Example_BindsProviders() Assert.Equal("fill", Example.Providers.Llm[1].As); Assert.Equal("judge", Example.Providers.Llm[2].As); Assert.Equal("cheap", Example.Providers.Llm[3].As); + Assert.Equal(false, Example.Providers.Llm[3].WebSearch); Assert.Equal("telnyx-relay", Example.Providers.Speech!.Stt.Kind); Assert.Equal("telnyx-relay", Example.Providers.Speech.Tts.Kind); Assert.Equal("telnyx", Example.Providers.Telephony!.Kind); diff --git a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs index af77fdc1..6b4edd39 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ConfigurationSchemaValidatorTests.cs @@ -600,4 +600,25 @@ public void ANonBuiltinToolWithParameters_PassesCheckOne(string kind, string dis Assert.Empty(ConfigurationSchemaValidator.Evaluate(parsed)); } + + [Theory] + [InlineData("{}")] + [InlineData("{ tokens: 60000, messages: 40 }")] + public void ACompactionTriggerNotNamingExactlyOneCondition_FailsWithThePointerOfTheTrigger(string trigger) + { + var document = $$""" + apiVersion: agentcore/v1 + name: broken + agents: + defaults: + compaction: + strategy: truncate + trigger: {{trigger}} + """; + + var failure = Assert.Throws(() => ConfigurationLoader.LoadYaml(document)); + + Assert.Equal(ConfigurationCheck.DocumentSchema, failure.Check); + Assert.Contains(failure.Errors, error => error.Pointer == "/agents/defaults/compaction/trigger"); + } } diff --git a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs index 8f689996..7b0ead7b 100644 --- a/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs +++ b/tests/AgentCore.Application.Tests/Configuration/ExampleDocument.cs @@ -108,6 +108,7 @@ internal static class ExampleDocument type: object properties: { summary: { type: string } } required: [ summary ] + - { id: search, kind: builtin, uses: web.search } agents: defaults: @@ -115,13 +116,14 @@ internal static class ExampleDocument instructions: | knowledge: { mode: prefetch, limit: 5, citations: false } + compaction: { strategy: context_window, trigger: { messages: 40 }, keep: 6, foldResultChars: 300 } items: - { id: greeter, instructions: "", tools: [] } - { id: identifier, instructions: "", tools: [ lookup_order ] } - { id: resolver, instructions: "", tools: [] } - { id: escalator, instructions: "", tools: [ create_case ] } - { id: closer, instructions: "", tools: [] } - - { id: analyst, instructions: "", tools: [ lookup_order, create_case ], + - { id: analyst, instructions: "", tools: [ lookup_order, create_case, search ], knowledge: { mode: tool, limit: 8, citations: true, scoped: false } } - { id: webchat, instructions: "", tools: [ lookup_order ], knowledge: { mode: tool, citations: false } } @@ -155,7 +157,7 @@ internal static class ExampleDocument - { kind: openai, model: gpt-4.1-mini, as: reply } # the voice path, chosen on latency - { kind: openai, model: gpt-5.4-nano, as: fill } # the extractor, chosen on null discipline - { kind: openai, model: gpt-4.1, as: judge } # evaluation only, chosen on judgement - - { kind: openai, model: gpt-4.1-nano, as: cheap } # ui.draw only, chosen on price + - { kind: openai, model: gpt-4.1-nano, as: cheap, webSearch: false } # ui.draw only, chosen on price call: { kind: telnyx-relay } # the pipe: who carries the call and owns /v1/call speech: # the ears and the mouth, named one role at a time stt: { kind: telnyx-relay } # recognition. Bundled here, so it matches call @@ -409,6 +411,11 @@ internal static class ExampleDocument "summary" ] } + }, + { + "id": "search", + "kind": "builtin", + "uses": "web.search" } ], "agents": { @@ -422,6 +429,14 @@ internal static class ExampleDocument "mode": "prefetch", "limit": 5, "citations": false + }, + "compaction": { + "strategy": "context_window", + "trigger": { + "messages": 40 + }, + "keep": 6, + "foldResultChars": 300 } }, "items": [ @@ -459,7 +474,8 @@ internal static class ExampleDocument "instructions": "", "tools": [ "lookup_order", - "create_case" + "create_case", + "search" ], "knowledge": { "mode": "tool", @@ -561,7 +577,8 @@ internal static class ExampleDocument { "kind": "openai", "model": "gpt-4.1-nano", - "as": "cheap" + "as": "cheap", + "webSearch": false } ], "call": { diff --git a/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs b/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs new file mode 100644 index 00000000..7f68a0d8 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Llm/HostedWebSearchCapabilityTests.cs @@ -0,0 +1,56 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; +using Xunit; + +namespace AgentCore.Application.Tests.Llm; + +/// +/// Which vendors can run a hosted web search, and the operator's per-entry veto. +/// +public sealed class HostedWebSearchCapabilityTests +{ + [Fact] + public void Adapter_DefaultMember_SaysNo() + { + // A host that wrote an adapter before this member existed keeps compiling, and keeps + // answering no, so its models never meet a tool they cannot call. + IChatClientAdapter adapter = new SilentAdapter(); + + Assert.False(adapter.SupportsHostedWebSearch(Entry(webSearch: null))); + } + + [Fact] + public void Factory_UnknownReference_SaysNo() + { + // A reference the document does not declare must not throw here. The compiler asks this + // question while deciding whether to add a tool, and a missing model is reported elsewhere. + IChatClientFactory factory = new SilentFactory(); + + Assert.False(factory.SupportsHostedWebSearch(new ModelReference { Ref = "absent" })); + } + + private static LlmProviderConfiguration Entry(bool? webSearch) => new() + { + Kind = "silent", + Model = "m", + As = "reply", + WebSearch = webSearch, + }; + + private sealed class SilentAdapter : IChatClientAdapter + { + public string Kind => "silent"; + + public ValueTask CreateClientAsync( + LlmProviderConfiguration entry, + ISecretResolverPort? secrets, + CancellationToken cancellationToken = default) + => throw new NotSupportedException(); + } + + private sealed class SilentFactory : IChatClientFactory + { + public Microsoft.Extensions.AI.IChatClient GetChatClient(ModelReference? model) + => throw new NotSupportedException(); + } +} diff --git a/tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs b/tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs new file mode 100644 index 00000000..7ab05318 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/CappedToolCallFormatterTests.cs @@ -0,0 +1,82 @@ +using AgentCore.Application.Runtime.Compaction; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// : what a folded tool-call group carries forward. MAF's own +/// formatter copies the whole result, which grows the conversation it was asked to shrink. +/// +#pragma warning disable MAAI001 // CompactionMessageGroup and CompactionMessageIndex are the framework's own experimental surface. +public sealed class CappedToolCallFormatterTests +{ + [Fact] + public void Create_LongResult_IsCutToTheCap() + { + var written = CappedToolCallFormatter.Create(50)(Group("lookup", new string('x', 4000))); + + Assert.Contains("lookup", written, StringComparison.Ordinal); + Assert.True(written.Length < 200, $"the fold was {written.Length} characters, expected under 200"); + } + + [Fact] + public void Create_LongResult_SaysItWasCut() + { + var written = CappedToolCallFormatter.Create(50)(Group("lookup", new string('x', 4000))); + + Assert.Contains("…", written, StringComparison.Ordinal); + } + + [Fact] + public void Create_ShortResult_IsKeptWhole() + { + var written = CappedToolCallFormatter.Create(50)(Group("lookup", "sunny")); + + Assert.Contains("sunny", written, StringComparison.Ordinal); + Assert.DoesNotContain("…", written, StringComparison.Ordinal); + } + + [Fact] + public void Create_NoToolCalls_IsEmpty() + { + var group = Group(CompactionGroupKind.User, [new ChatMessage(ChatRole.User, "hello")]); + + Assert.Empty(CappedToolCallFormatter.Create(50)(group)); + } + + [Fact] + public void Create_TwoResultsShareOneCallId_RendersTheLastOneWithoutThrowing() + { + var group = Group( + CompactionGroupKind.ToolCall, + [ + new ChatMessage(ChatRole.Assistant, + [new FunctionCallContent("call-1", "lookup", new Dictionary())]), + new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call-1", "first")]), + new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call-1", "last")]), + ]); + + var written = CappedToolCallFormatter.Create(50)(group); + + Assert.Contains("last", written, StringComparison.Ordinal); + Assert.DoesNotContain("first", written, StringComparison.Ordinal); + } + + // CompactionMessageGroup has no public constructor: its only public members are read-only + // properties, so a group has to come from the index that MAF's own strategies build it + // through. Passing a null tokenizer is fine — AddGroup falls back to an estimate, and this + // formatter never reads TokenCount. + private static CompactionMessageGroup Group(CompactionGroupKind kind, IReadOnlyList messages) => + new CompactionMessageIndex(new List(), null!).AddGroup(kind, messages, turnIndex: null); + + private static CompactionMessageGroup Group(string tool, string result) => Group( + CompactionGroupKind.ToolCall, + [ + new ChatMessage(ChatRole.Assistant, + [new FunctionCallContent("call-1", tool, new Dictionary())]), + new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call-1", result)]), + ]); +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs new file mode 100644 index 00000000..a0b85ac4 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Runtime/CompactionStrategyFactoryTests.cs @@ -0,0 +1,113 @@ +using AgentCore.Application.Configuration.Compilation; +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Runtime.Compaction; +using Microsoft.Agents.AI.Compaction; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Runtime; + +/// +/// : resolved settings to a MAF strategy, and the trimming +/// the 2026-09-09 handoff recorded as unproven. +/// +#pragma warning disable MAAI001 // Compaction is evaluation-only in Microsoft.Agents.AI 1.17.0. +public sealed class CompactionStrategyFactoryTests +{ + [Theory] + [InlineData(CompactionStrategyKind.ToolResult, typeof(ToolResultCompactionStrategy))] + [InlineData(CompactionStrategyKind.Truncate, typeof(TruncationCompactionStrategy))] + [InlineData(CompactionStrategyKind.SlidingWindow, typeof(SlidingWindowCompactionStrategy))] + [InlineData(CompactionStrategyKind.ContextWindow, typeof(PipelineCompactionStrategy))] + public void Create_EachKind_BuildsItsStrategy(CompactionStrategyKind kind, Type expected) + { + Assert.IsType(expected, CompactionStrategyFactory.Create(Resolved(kind, messages: 6))); + } + + [Fact] + public async Task Create_Truncate_RemovesOldestAndKeepsNewest() + { + var history = History(12); + + var compacted = (await CompactionProvider.CompactAsync( + CompactionStrategyFactory.Create(Resolved(CompactionStrategyKind.Truncate, messages: 6)), + history, + cancellationToken: TestContext.Current.CancellationToken)).ToList(); + + Assert.True(compacted.Count < history.Count, $"kept all {history.Count} messages"); + Assert.Equal(history[^1].Text, compacted[^1].Text); + } + + [Fact] + public async Task Create_ToolResult_ShrinksTheText() + { + var history = HistoryWithToolResults(6, resultChars: 4000); + var before = history.Sum(Size); + + var compacted = (await CompactionProvider.CompactAsync( + CompactionStrategyFactory.Create(Resolved(CompactionStrategyKind.ToolResult, messages: 8)), + history, + cancellationToken: TestContext.Current.CancellationToken)).ToList(); + + var after = compacted.Sum(Size); + + // MAF's own formatter grows this number. The capping formatter is what makes it fall. + Assert.True(after < before / 2, $"the fold did not cap: {before} -> {after}"); + } + + [Fact] + public async Task Create_SameWordsTwiceFromEmptyState_Agrees() + { + // The claim the resume design rests on: a resumed call builds a new session, so the provider + // starts empty and re-derives. If two passes disagreed, a resumed call would not match the + // call it resumed, and compaction state would have to be persisted. + var history = HistoryWithToolResults(6, resultChars: 4000); + var settings = Resolved(CompactionStrategyKind.ToolResult, messages: 8); + + var first = (await CompactionProvider.CompactAsync( + CompactionStrategyFactory.Create(settings), history, cancellationToken: TestContext.Current.CancellationToken)).ToList(); + var second = (await CompactionProvider.CompactAsync( + CompactionStrategyFactory.Create(settings), history, cancellationToken: TestContext.Current.CancellationToken)).ToList(); + + Assert.Equal(first.Count, second.Count); + Assert.Equal(first.Select(message => message.Text), second.Select(message => message.Text)); + } + + private static int Size(ChatMessage message) => message.Text.Length + + message.Contents.OfType().Sum(c => c.Result?.ToString()?.Length ?? 0); + + private static ResolvedCompaction Resolved(CompactionStrategyKind kind, int messages) => new( + kind, + new CompactionTriggerConfiguration { Messages = messages }, + Keep: 2, + FoldResultChars: 200); + + private static List History(int count) + { + List messages = []; + for (var index = 0; index < count / 2; index++) + { + messages.Add(new ChatMessage(ChatRole.User, $"question {index}")); + messages.Add(new ChatMessage(ChatRole.Assistant, $"answer {index}")); + } + + return messages; + } + + private static List HistoryWithToolResults(int turns, int resultChars) + { + List messages = []; + for (var index = 0; index < turns; index++) + { + messages.Add(new ChatMessage(ChatRole.User, $"question {index}")); + messages.Add(new ChatMessage(ChatRole.Assistant, + [new FunctionCallContent($"call-{index}", "lookup", new Dictionary())])); + messages.Add(new ChatMessage(ChatRole.Tool, + [new FunctionResultContent($"call-{index}", new string('x', resultChars))])); + messages.Add(new ChatMessage(ChatRole.Assistant, $"answer {index}")); + } + + return messages; + } +} +#pragma warning restore MAAI001 diff --git a/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs b/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs index 3b12dfad..73a8b052 100644 --- a/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs +++ b/tests/AgentCore.Application.Tests/Tools/BuiltinToolTests.cs @@ -14,11 +14,13 @@ namespace AgentCore.Application.Tests.Tools; /// The first tool kind of section 8.1: kind: builtin, which AgentCore ships. /// /// -/// The shipped example's only built-in today is ui.draw, a shipped agent built through -/// and tested in ShippedAgentBuilderTests. AgentCore ships -/// no plain-function built-in right now, so the call path, the section 8.7 error-result shape, -/// description resolution, and cancellation that a plain built-in exercises are untested until one -/// ships again. +/// The shipped example holds two built-ins: ui.draw, a shipped agent built through +/// and tested in ShippedAgentBuilderTests; and +/// web.search, a plain function that builds one HostedWebSearchTool marker and runs +/// no code of its own — see HostedWebSearchDropTests for what reaches a compiled agent. +/// Neither calls anything, so the call path, the section 8.7 error-result shape, description +/// resolution, and cancellation that a plain built-in which actually runs would exercise stay +/// untested until one ships. /// public sealed class BuiltinToolTests { diff --git a/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs b/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs new file mode 100644 index 00000000..f2fa362e --- /dev/null +++ b/tests/AgentCore.Application.Tests/Tools/WebSearchToolDefinitionTests.cs @@ -0,0 +1,37 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Tools.Builtin; +using Microsoft.Extensions.AI; +using Xunit; + +namespace AgentCore.Application.Tests.Tools; + +/// The uses: web.search builtin, which builds a marker and nothing else. +public sealed class WebSearchToolDefinitionTests +{ + [Fact] + public void Name_IsTheDocumentedUsesValue() + { + Assert.Equal("web.search", BuiltinToolNames.WebSearch); + } + + [Fact] + public void Build_ProducesAHostedWebSearchTool() + { + var tool = new WebSearchToolDefinition().Build( + new ToolConfiguration { Id = "search", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }, + new BuiltinToolPorts(ChatClients: null)); + + Assert.IsType(tool); + } + + [Fact] + public void Build_NeedsNoPorts() + { + // The marker carries no behaviour, so an unbound chat client factory is not a failure here. + var exception = Record.Exception(() => new WebSearchToolDefinition().Build( + new ToolConfiguration { Id = "search", Kind = ToolKind.Builtin, Uses = BuiltinToolNames.WebSearch }, + new BuiltinToolPorts(ChatClients: null))); + + Assert.Null(exception); + } +} From 42837b627136c7605386387eb745fe162a11cf80 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 16:37:10 -0600 Subject: [PATCH 2/8] feat(di): register the vocabulary cache so a host can read a slot's values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The cache was a local of the boot, reachable only by the startup steps it was passed to. A host that wants the values a vocabulary slot holds — to gate a knowledge search on the product names the base publishes, say — had no way to reach the instance the refresh services write into. --- .../DependencyInjection/AgentCoreBoot.cs | 5 +++++ .../AgentCoreServiceCollectionExtensions.cs | 1 + .../DependencyInjection/AddAgentCoreTests.cs | 14 ++++++++++++++ 3 files changed, 20 insertions(+) diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index 3e0722d2..ee5006a1 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -86,6 +86,9 @@ public AgentCoreBoot(IOptions options, ILoggerFactory loggers) /// Gets the factory that builds one session per call. internal ICallSessionFactory Sessions => Started.Sessions; + /// Gets the vocabulary every call session reads, and every refresh installs into. + internal VocabularyCache Vocabulary => Started.Vocabulary; + /// Gets the same turn loop, behind the framework's own agent seam. internal AgentCoreAgent Agent => Started.Agent; @@ -261,6 +264,7 @@ await KnowledgeStartup call.Sessions, call.Agent, call.Queue, + vocabulary, seams.Call, seams.Speech, seams.Handler, @@ -387,6 +391,7 @@ private sealed record BootState( ICallSessionFactory Sessions, AgentCoreAgent Agent, QueuedAuditSink AuditQueue, + VocabularyCache Vocabulary, IReadOnlyList? CallAdapters, IReadOnlyList? SpeechAdapters, RequestDelegate? CallHandler, diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs index d54d1e0e..c765e6a2 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs @@ -47,6 +47,7 @@ public static IServiceCollection AddAgentCore( services.AddSingleton(Boot(boot => boot.Tools)); services.AddSingleton(Boot(boot => boot.Calls)); services.AddSingleton(Boot(boot => boot.Sessions)); + services.AddSingleton(Boot(boot => boot.Vocabulary)); services.AddSingleton(Boot(boot => boot.Agent)); services.AddSingleton(Boot(boot => boot.AuditQueue)); diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs index e57b25c2..4cac31e4 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs @@ -25,6 +25,7 @@ using Microsoft.Extensions.AI.Evaluation; using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; +using AgentCore.Application.State; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; using System.Text.Json.Nodes; @@ -359,6 +360,19 @@ public async Task AddAgentCore_RegistersOneSessionFactoryThatBuildsANewSessionFo Assert.NotEqual(first.CallId, second.CallId); } + [Fact] + public async Task AddAgentCore_RegistersTheVocabularyEveryRefreshWritesInto() + { + using var provider = await BuildAsync(OneAgentYaml); + + var vocabulary = provider.GetRequiredService(); + + // The one the refresh services and every call session share. A consumer that reads a slot's + // values — to gate a search on the product names the knowledge base publishes, say — must + // reach that instance and not a fresh one, which would always read empty. + Assert.Same(vocabulary, provider.GetRequiredService()); + } + [Fact] public async Task AddAgentCore_RegistersTheAgentShimAsAProcessSingleton() { From d53973cb3fe59e9b0768f3dccd2082e0ab8899e0 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 16:53:54 -0600 Subject: [PATCH 3/8] fix(vocabulary): let a slot take its domain from knowledge without being scoped by MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two rules assumed a vocabulary: slot exists only to narrow a search, so the domain and the scope had to name the same facets. Check 2 refused a vocabulary: slot that scope.fromState did not name. The gate and the linker are useful on their own — they hold the extractor to values the provider published — and a host may read the domain for itself. Scoping is what fromState declares, and it is a separate decision. The two vocabulary reads then stripped the wildcard sentinel only for facets wildcard.facets names. The sentinel is stored in the collection, so a read of any facet path returns it, and it normalises to nothing — which refused the document one step later. wildcard.facets answers which scope conditions a deployment widens, so it was the wrong question to ask of a read. --- .../Validation/ConfigurationValidator.cs | 20 +++++--------- .../DependencyInjection/AgentCoreBoot.cs | 8 +++--- .../Startup/KnowledgeStartup.cs | 10 ++++--- .../Validation/ConfigurationValidatorTests.cs | 26 +++++++++---------- 4 files changed, 32 insertions(+), 32 deletions(-) diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index ef615820..fbed34b1 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs @@ -699,14 +699,17 @@ private static void CheckKnowledgeScopeSlots( /// Refuses a vocabulary: or ambiguity: block that could not do what it declares. /// /// Unlike , the slot-level rules here do not depend on the - /// slot being named in scope.fromState: a slot may declare vocabulary: without ever - /// being read by the scope, and that mismatch is itself one of the refusals below. + /// slot being named in scope.fromState. A slot may declare vocabulary: and never be + /// scoped by: the gate still holds the extractor to values the provider published, the linker + /// still folds a mention onto one of them, and a host may read the domain for itself — a + /// knowledge search that requires a product name the manuals use, say. Scoping is what + /// fromState declares, and it is a separate decision from where a slot's domain comes + /// from. /// private static void CheckVocabularyAndAmbiguity( AgentCoreConfiguration configuration, List errors, List warnings) { var knowledge = configuration.Providers?.Knowledge; - var fromState = knowledge?.Scope.FromState ?? []; var anyVocabulary = false; foreach (var entry in configuration.State) @@ -738,15 +741,6 @@ private static void CheckVocabularyAndAmbiguity( + "A slot cannot have both.")); } - if (!fromState.Contains(entry.Key, StringComparer.Ordinal)) - { - errors.Add(Reference( - ConfigurationError.AppendPointer(vocabularyPointer, "from"), - $"the slot '{entry.Key}' declares vocabulary.from: knowledge, and " - + "providers.knowledge.scope.fromState does not name it. The gate and the linker " - + "would then hold a domain no turn's scope ever narrows by.")); - } - CheckRange( vocabulary.MaxValues, 2, @@ -843,7 +837,7 @@ private static void CheckVocabularyAndAmbiguity( // A probe drops one of the scope's own facets, so it needs a second one left to search by. // Zero is as unreachable as one, and reaches this line whenever the host supplies every facet. - if (fromState.Count <= 1) + if ((knowledge.Scope.FromState ?? []).Count <= 1) { warnings.Add(Reference( Pointer.Ambiguity, diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index ee5006a1..b0f04a48 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -352,9 +352,11 @@ private void StartVocabularyRefresh( } var path = template.Resolve(slotName); - var wildcardValue = wildcard is not null && wildcard.Facets.Contains(slotName, StringComparer.Ordinal) - ? wildcard.Value - : null; + + // Stripped for every declared wildcard, on the same reasoning as the boot read in + // KnowledgeStartup.ApplyVocabularyAsync: the sentinel is stored in the collection, so a + // refresh reads it back at any facet path, scoped or not. + var wildcardValue = wildcard?.Value; var service = Track(new VocabularyRefreshService( slotName, diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index d40b4f8c..ec6c091b 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs @@ -162,9 +162,13 @@ internal static async ValueTask ApplyVocabularyAsync( var vocab = slot.Vocabulary!; var path = template.Resolve(slotName); var values = await port.ReadAsync(path, vocab.MaxValues, cancellationToken).ConfigureAwait(false); - var wildcardValue = wildcardFacets.Contains(slotName, StringComparer.Ordinal) - ? wildcard!.Value - : null; + + // Every declared wildcard, not only the facets wildcard.facets names. The sentinel is + // a value the collection stores at a facet path, so a read of that path returns it + // whether or not a scope ever widens by it — and it normalises to nothing, so leaving + // it in the domain refuses the document. wildcard.facets answers a different + // question: which scope conditions this deployment widens. + var wildcardValue = wildcard?.Value; try { diff --git a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs index c994b4fa..0f0e696d 100644 --- a/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs +++ b/tests/AgentCore.Application.Tests/Configuration/Validation/ConfigurationValidatorTests.cs @@ -631,12 +631,6 @@ public void Evaluate_SlotDeclaresBothEnumAndVocabulary_Fails() Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); } - /// - /// A writer: const slot can never legitimately sit in fromState (fromState's - /// per-facet check requires writer: extractor), so a slot exercising this row also, - /// unavoidably, trips row 3 (vocabulary.from on a slot fromState does not name). The pair is - /// asserted explicitly rather than isolated away. - /// [Fact] public void Evaluate_SlotDeclaresBothValueAndVocabulary_Fails() { @@ -655,13 +649,21 @@ public void Evaluate_SlotDeclaresBothValueAndVocabulary_Fails() AnExtractor(), ambiguity: AnAmbiguity())); - Assert.Equal(2, result.Errors.Count); - Assert.Contains(result.Errors, e => e.Pointer == "/state/applies_to/value"); - Assert.Contains(result.Errors, e => e.Pointer == "/state/applies_to/vocabulary/from"); + var error = Assert.Single(result.Errors); + Assert.Equal("/state/applies_to/value", error.Pointer); } + /// + /// A slot may take its domain from the knowledge base and never be scoped by. + /// + /// + /// The gate still holds the extractor to values the provider published, and the linker still + /// folds a mention onto one of them. A host may also read the domain for itself — requiring a + /// knowledge search to carry a product name the manuals use, say — which needs the vocabulary + /// and would be actively harmed by narrowing every search to it. + /// [Fact] - public void Evaluate_VocabularySlotAbsentFromFromState_Fails() + public void Evaluate_VocabularySlotAbsentFromFromState_Passes() { var wildcard = new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }; @@ -677,9 +679,7 @@ public void Evaluate_VocabularySlotAbsentFromFromState_Fails() AnExtractor(), ambiguity: AnAmbiguity())); - var error = Assert.Single(result.Errors); - Assert.Equal("/state/applies_to/vocabulary/from", error.Pointer); - Assert.Contains("applies_to", error.Message, StringComparison.Ordinal); + Assert.Empty(result.Errors); } [Fact] From 5c67b461d8c461f8d51fc5c4d103939bb883fe29 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 16:57:39 -0600 Subject: [PATCH 4/8] test(vocabulary): pin the wildcard strip on a slot no scope names --- .../VocabularyStartupTests.cs | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs index 3c8dea9e..9a89421d 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs @@ -23,6 +23,29 @@ namespace AgentCore.AspNetCore.Tests.DependencyInjection; /// public sealed class VocabularyStartupTests { + [Fact] + public async Task ApplyVocabularyAsync_UnscopedSlot_StripsTheWildcardAndKeepsTheRest() + { + // The sentinel is stored in the collection, so a read of any facet path returns it. It + // normalises to nothing, so a domain that keeps it can be neither linked nor gated — and the + // slot need not be scoped by for that to be true. wildcard.facets says which scope conditions + // this deployment widens, which is a different question and cannot answer this one. + var configuration = Configuration( + [("model", Vocabulary(maxValues: 10))], + new KnowledgeWildcardConfiguration { Value = "*", Facets = ["brand"] }, + extraFromState: ["brand"], + scopeVocabularySlots: false); + + var port = new FakeFacetPort().With("facets.model", "lcr-2023", "*", "f63-2019"); + VocabularyCache cache = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, port, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => true); + + Assert.Equal(["lcr-2023", "f63-2019"], cache.Snapshot()["model"].Originals); + } + [Fact] public async Task ApplyVocabularyAsync_ZeroValues_FailsNamingTheSlotAndPath() { @@ -297,7 +320,8 @@ private static SlotVocabularyConfiguration Vocabulary(int maxValues, bool assume private static AgentCoreConfiguration Configuration( (string Slot, SlotVocabularyConfiguration Vocabulary)[]? vocabularySlots = null, KnowledgeWildcardConfiguration? wildcard = null, - IReadOnlyList? extraFromState = null) + IReadOnlyList? extraFromState = null, + bool scopeVocabularySlots = true) { vocabularySlots ??= []; extraFromState ??= []; @@ -318,7 +342,9 @@ private static AgentCoreConfiguration Configuration( state.TryAdd(slot, new StateSlotConfiguration { Type = StateSlotType.String, Writer = StateWriter.Extractor }); } - List fromState = [.. vocabularySlots.Select(entry => entry.Slot), .. extraFromState]; + List fromState = scopeVocabularySlots + ? [.. vocabularySlots.Select(entry => entry.Slot), .. extraFromState] + : [.. extraFromState]; return new AgentCoreConfiguration { From c5696b7082dfcf2976f0542c74749e00d699b949 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 19:53:18 -0600 Subject: [PATCH 5/8] feat(knowledge): ask a store what else it serves, instead of casting to find out MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Search is the one thing every knowledge store owes. Reading a facet vocabulary is a capability only some serve, and the two callers that need it found out by casting — which answers false on a wrapper, because a wrapper does not implement what it wraps. A cache or a log in front of a store would have cost the document its vocabulary, silently. IKnowledgeRetrievalPort.GetService is a default interface method, so no existing store changes: one that wraps nothing is already whatever it implements. A store that wraps another overrides it and forwards what it cannot answer. This is the shape Microsoft.Extensions.AI uses on IChatClient, IEmbeddingGenerator and six more, each with a Delegating base that forwards it, so a consumer already knows it from providers.embeddings. --- .../Ports/IKnowledgeRetrievalPort.cs | 26 +++- .../Ports/KnowledgeRetrievalPortExtensions.cs | 20 +++ .../PublicAPI.Unshipped.txt | 3 + .../DependencyInjection/AgentCoreBoot.cs | 2 +- .../Startup/KnowledgeStartup.cs | 4 +- .../Ports/.editorconfig | 5 + .../Ports/KnowledgeCapabilityTests.cs | 126 ++++++++++++++++++ .../VocabularyStartupTests.cs | 36 +++++ 8 files changed, 218 insertions(+), 4 deletions(-) create mode 100644 src/AgentCore.Application/Ports/KnowledgeRetrievalPortExtensions.cs create mode 100644 tests/AgentCore.Application.Tests/Ports/.editorconfig create mode 100644 tests/AgentCore.Application.Tests/Ports/KnowledgeCapabilityTests.cs diff --git a/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs b/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs index ecb92949..01c21c4f 100644 --- a/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs +++ b/src/AgentCore.Application/Ports/IKnowledgeRetrievalPort.cs @@ -3,8 +3,14 @@ namespace AgentCore.Application.Ports; /// -/// The whole knowledge base, behind one method. +/// The whole knowledge base, behind one method — and a way to ask for the rest. /// +/// +/// Search is the one thing every store owes. Everything beyond it — reading a facet vocabulary, +/// reading whole cards by an exact facet value — is a capability a store may or may not have, and +/// it lives on its own interface that only a store able to serve it implements. A caller asks for +/// one through . +/// public interface IKnowledgeRetrievalPort { /// Finds the cards that answer one query. @@ -14,4 +20,22 @@ public interface IKnowledgeRetrievalPort ValueTask> SearchAsync( string query, CancellationToken cancellationToken = default); + + /// Asks this store for a capability it may also serve. + /// The capability being asked for, such as . + /// Names one of several, when a store serves more than one. Most serve none. + /// The capability, or when this store does not serve it. + /// + /// The default answers for a store that is whatever it implements, which is every store that + /// wraps nothing. A store that wraps another overrides this and forwards what it cannot answer, + /// which is the whole reason this is a method and not a cast: a wrapper does not implement what + /// it wraps, so is loses the inner store's capabilities and this does not. + /// + /// is . + object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + + return serviceKey is null && serviceType.IsInstanceOfType(this) ? this : null; + } } diff --git a/src/AgentCore.Application/Ports/KnowledgeRetrievalPortExtensions.cs b/src/AgentCore.Application/Ports/KnowledgeRetrievalPortExtensions.cs new file mode 100644 index 00000000..1aab5823 --- /dev/null +++ b/src/AgentCore.Application/Ports/KnowledgeRetrievalPortExtensions.cs @@ -0,0 +1,20 @@ +namespace AgentCore.Application.Ports; + +/// +/// Typed helpers over . +/// +public static class KnowledgeRetrievalPortExtensions +{ + /// Asks one store for a capability it may also serve. + /// The capability being asked for. + /// The store to ask. + /// Names one of several, when a store serves more than one. + /// The capability, or when this store does not serve it. + /// is . + public static TService? GetService(this IKnowledgeRetrievalPort port, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(port); + + return port.GetService(typeof(TService), serviceKey) is TService service ? service : default; + } +} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index 2ae805c1..be1a8ff2 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -1021,6 +1021,7 @@ AgentCore.Application.Ports.IEvaluationScorePublisher.PublishAsync(AgentCore.App AgentCore.Application.Ports.IFacetVocabularyPort AgentCore.Application.Ports.IFacetVocabularyPort.ReadAsync(string! path, int limit, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IKnowledgeRetrievalPort +AgentCore.Application.Ports.IKnowledgeRetrievalPort.GetService(System.Type! serviceType, object? serviceKey = null) -> object? AgentCore.Application.Ports.IKnowledgeRetrievalPort.SearchAsync(string! query, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IKnowledgeStoreAdapter AgentCore.Application.Ports.IKnowledgeStoreAdapter.CanScope.get -> bool @@ -1043,6 +1044,7 @@ AgentCore.Application.Ports.IToolSource AgentCore.Application.Ports.IToolSource.ProvideAsync(AgentCore.Application.Tools.Registry.ToolSourceContext! context, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IVendorAdapter AgentCore.Application.Ports.IVendorAdapter.Kind.get -> string! +AgentCore.Application.Ports.KnowledgeRetrievalPortExtensions AgentCore.Application.Providers.VendorAdapterSelector AgentCore.Application.Providers.VendorSeam AgentCore.Application.Providers.VendorSeam.Deconstruct(out string! DocumentPath, out string! Pointer, out string! RegistrationHint, out string! Plural) -> void @@ -1596,6 +1598,7 @@ static AgentCore.Application.Knowledge.KnowledgeCitationFormatterFactory.Resolve static AgentCore.Application.Knowledge.KnowledgePoint.operator !=(AgentCore.Application.Knowledge.KnowledgePoint? left, AgentCore.Application.Knowledge.KnowledgePoint? right) -> bool static AgentCore.Application.Knowledge.KnowledgePoint.operator ==(AgentCore.Application.Knowledge.KnowledgePoint? left, AgentCore.Application.Knowledge.KnowledgePoint? right) -> bool static AgentCore.Application.Llm.CompositeChatClientFactory.CreateAsync(AgentCore.Application.Configuration.Schema.AgentCoreConfiguration! configuration, AgentCore.Application.Ports.ISecretResolverPort? secrets, System.Collections.Generic.IReadOnlyList! adapters, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask +static AgentCore.Application.Ports.KnowledgeRetrievalPortExtensions.GetService(this AgentCore.Application.Ports.IKnowledgeRetrievalPort! port, object? serviceKey = null) -> TService? static AgentCore.Application.Providers.VendorAdapterSelector.Select(string! kind, System.Collections.Generic.IReadOnlyList! adapters, AgentCore.Application.Providers.VendorSeam seam) -> TAdapter static AgentCore.Application.Providers.VendorSeam.operator !=(AgentCore.Application.Providers.VendorSeam left, AgentCore.Application.Providers.VendorSeam right) -> bool static AgentCore.Application.Providers.VendorSeam.operator ==(AgentCore.Application.Providers.VendorSeam left, AgentCore.Application.Providers.VendorSeam right) -> bool diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index b0f04a48..0bb27da5 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -331,7 +331,7 @@ private void StartVocabularyRefresh( VocabularyCache vocabulary, CancellationToken cancellationToken) { - if (knowledge is not IFacetVocabularyPort port) + if (knowledge?.GetService() is not { } port) { return; } diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index ec6c091b..d19364ec 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs @@ -105,7 +105,7 @@ internal static async ValueTask ApplyVocabularyAsync( return; } - if (knowledge is not IFacetVocabularyPort port) + if (knowledge?.GetService() is not { } port) { if (vocabularySlots.Count == 0) { @@ -118,7 +118,7 @@ internal static async ValueTask ApplyVocabularyAsync( var reason = knowledge is null ? "no knowledge port was built, so there is nothing to read a facet vocabulary from" - : $"the built port ({knowledge.GetType().Name}) does not implement {nameof(IFacetVocabularyPort)}"; + : $"the built port ({knowledge.GetType().Name}) does not serve {nameof(IFacetVocabularyPort)}"; throw FailSlots( vocabularySlots.Select(entry => entry.Key), diff --git a/tests/AgentCore.Application.Tests/Ports/.editorconfig b/tests/AgentCore.Application.Tests/Ports/.editorconfig new file mode 100644 index 00000000..3d6eebe7 --- /dev/null +++ b/tests/AgentCore.Application.Tests/Ports/.editorconfig @@ -0,0 +1,5 @@ +[*.cs] + +# CA1707: "Remove the underscores from member name". A test name reads Subject_Behaviour, and the +# underscore is what separates the two halves. +dotnet_diagnostic.CA1707.severity = none diff --git a/tests/AgentCore.Application.Tests/Ports/KnowledgeCapabilityTests.cs b/tests/AgentCore.Application.Tests/Ports/KnowledgeCapabilityTests.cs new file mode 100644 index 00000000..501354ed --- /dev/null +++ b/tests/AgentCore.Application.Tests/Ports/KnowledgeCapabilityTests.cs @@ -0,0 +1,126 @@ +using AgentCore.Application.Ports; +using AgentCore.Domain.Knowledge; + +using Xunit; + +namespace AgentCore.Application.Tests.Ports; + +/// +/// Asking a knowledge store what else it can do. +/// +/// +/// Search is the one thing every store owes. Reading a facet vocabulary, or whole cards by an +/// exact facet value, are capabilities a store may or may not serve, and a caller has to be able +/// to ask. The question goes to the store itself, so one object is the only source of truth and a +/// store cannot claim a capability it does not have. +/// +public sealed class KnowledgeCapabilityTests +{ + [Fact] + public void AStoreServingAnExtension_HandsItBack() + { + IKnowledgeRetrievalPort store = new VocabularyStore(); + + Assert.Same(store, store.GetService(typeof(IFacetVocabularyPort))); + } + + [Fact] + public void AStoreServingNoExtension_AnswersNull() + { + IKnowledgeRetrievalPort store = new SearchOnlyStore(); + + Assert.Null(store.GetService(typeof(IFacetVocabularyPort))); + } + + [Fact] + public void AStoreAskedForItself_HandsItselfBack() + { + IKnowledgeRetrievalPort store = new SearchOnlyStore(); + + Assert.Same(store, store.GetService(typeof(IKnowledgeRetrievalPort))); + } + + [Fact] + public void AKeyedRequest_AnswersNull() + { + // A store that serves no keyed capability answers nothing rather than ignoring the key and + // handing back the unkeyed one, which would be a different object than the caller asked for. + IKnowledgeRetrievalPort store = new VocabularyStore(); + + Assert.Null(store.GetService(typeof(IFacetVocabularyPort), "replica")); + } + + [Fact] + public void ANullType_Throws() + { + IKnowledgeRetrievalPort store = new SearchOnlyStore(); + + Assert.Throws(() => store.GetService(null!)); + } + + [Fact] + public void TheGenericHelper_HandsBackTheTypedExtension() + { + IKnowledgeRetrievalPort store = new VocabularyStore(); + + Assert.Same(store, store.GetService()); + } + + [Fact] + public void TheGenericHelper_AnswersNullWhenTheStoreServesNothing() + { + IKnowledgeRetrievalPort store = new SearchOnlyStore(); + + Assert.Null(store.GetService()); + } + + [Fact] + public void AWrapperThatForwards_FindsTheCapabilityInside() + { + // The whole reason the question goes through a method and not a cast. A wrapper does not + // implement what it wraps, so 'is IFacetVocabularyPort' answers false on one and the + // capability disappears. Forwarding the question finds it. + var inner = new VocabularyStore(); + IKnowledgeRetrievalPort wrapper = new ForwardingStore(inner); + + Assert.False(wrapper is IFacetVocabularyPort); + Assert.Same(inner, wrapper.GetService()); + } + + /// A store that ranks and nothing else. + private sealed class SearchOnlyStore : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + + /// A store that also reads a facet vocabulary. + private sealed class VocabularyStore : IKnowledgeRetrievalPort, IFacetVocabularyPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + + public ValueTask> ReadAsync( + string path, int limit, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + + /// A store wrapped in another, as a cache or a log would wrap one. + private sealed class ForwardingStore(IKnowledgeRetrievalPort inner) : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => inner.SearchAsync(query, cancellationToken); + + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + + return serviceKey is null && serviceType.IsInstanceOfType(this) + ? this + : inner.GetService(serviceType, serviceKey); + } + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs index 9a89421d..b50960e3 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs @@ -46,6 +46,25 @@ await KnowledgeStartup.ApplyVocabularyAsync( Assert.Equal(["lcr-2023", "f63-2019"], cache.Snapshot()["model"].Originals); } + [Fact] + public async Task ApplyVocabularyAsync_AWrappedPort_ReadsTheVocabularyThroughTheWrapper() + { + // The wrapper does not read facets itself, so a cast to IFacetVocabularyPort answers false + // on it and the vocabulary would be refused. Asking the port instead reaches the store + // inside, which is what lets a cache or a log sit in front of a store without silently + // costing the document a feature. + var configuration = Configuration([("brand", Vocabulary(maxValues: 10))]); + var inner = new FakeFacetPort().With("facets.brand", "acme", "globex"); + ForwardingPort wrapper = new(inner); + VocabularyCache cache = new(); + + await KnowledgeStartup.ApplyVocabularyAsync( + configuration, wrapper, cache, NullLogger.Instance, TestContext.Current.CancellationToken, + composesUnicode: () => true); + + Assert.Equal(["acme", "globex"], cache.Snapshot()["brand"].Originals); + } + [Fact] public async Task ApplyVocabularyAsync_ZeroValues_FailsNamingTheSlotAndPath() { @@ -407,6 +426,23 @@ public ValueTask> SearchAsync( => ValueTask.FromResult>([]); } + /// A port wrapped in another, as a cache or a log would wrap one. + private sealed class ForwardingPort(IKnowledgeRetrievalPort inner) : IKnowledgeRetrievalPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => inner.SearchAsync(query, cancellationToken); + + public object? GetService(Type serviceType, object? serviceKey = null) + { + ArgumentNullException.ThrowIfNull(serviceType); + + return serviceKey is null && serviceType.IsInstanceOfType(this) + ? this + : inner.GetService(serviceType, serviceKey); + } + } + /// Stands in for a port options.UseKnowledgeRetrieval named, with no facet read. private sealed class HostBoundPort : IKnowledgeRetrievalPort { From faa742a7ab962a91ff3bdc762ddaa157ffc3f794 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 19:58:51 -0600 Subject: [PATCH 6/8] feat(knowledge): read whole cards by one exact facet value MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A model year is a keyword, not a meaning. Asking a ranked search for the cards of the LCR 2023 returns the 2026 ones first, because two adjacent years read as near-identical to an embedding. A filtered scroll cannot make that mistake. IKnowledgeFacetReadPort is a capability, not a widening of IKnowledgeRetrievalPort: a store that cannot filter simply does not implement it, and a caller asks through GetService. The value is matched exactly and never widened by scope.wildcard — a caller asking for one model year wants that year, not that year plus every card shared across all of them. QdrantKnowledgeStore reached 407 lines with the new method, so the six members that decide what a KnowledgeScope means against a payload moved to QdrantScopeMatcher. They were one responsibility already, read two ways that have to agree: Qdrant applies the filter to a search, and the same rules are applied in process to a card fetched by a see_also link, which never passes that filter. The store is now 346. --- .../Ports/IKnowledgeFacetReadPort.cs | 28 +++++ .../PublicAPI.Unshipped.txt | 2 + .../VectorData/Qdrant/QdrantKnowledgeStore.cs | 111 +++++++---------- .../VectorData/Qdrant/QdrantScopeMatcher.cs | 95 ++++++++++++++ .../VectorData/Qdrant/FacetReadTests.cs | 116 ++++++++++++++++++ .../Qdrant/Fakes/FacetScrollChannel.cs | 43 +++++++ 6 files changed, 328 insertions(+), 67 deletions(-) create mode 100644 src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs create mode 100644 src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs create mode 100644 tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs diff --git a/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs b/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs new file mode 100644 index 00000000..18b73b69 --- /dev/null +++ b/src/AgentCore.Application/Ports/IKnowledgeFacetReadPort.cs @@ -0,0 +1,28 @@ +using AgentCore.Domain.Knowledge; + +namespace AgentCore.Application.Ports; + +/// +/// Reads whole cards by one exact facet value. +/// +/// +/// This is the keyword half of the knowledge base, beside 's +/// similarity half. A value a caller can name exactly — a model year, a section, a brand — is not +/// something ranking answers well: two adjacent years read as near-identical to an embedding, and +/// the wrong one wins. A store that cannot filter does not implement this interface, and a caller +/// asks for it through . +/// +public interface IKnowledgeFacetReadPort +{ + /// Reads the cards carrying one value at one payload path. + /// The payload path, already resolved from scope.template. + /// The value the cards must carry at that path, matched exactly. + /// The most cards to return. + /// Cancels the read. + /// The cards, in no defined order. Empty when nothing carries the value, which is not an error. + ValueTask> ReadByFacetAsync( + string path, + string value, + int limit, + CancellationToken cancellationToken = default); +} diff --git a/src/AgentCore.Application/PublicAPI.Unshipped.txt b/src/AgentCore.Application/PublicAPI.Unshipped.txt index be1a8ff2..2fb07d07 100644 --- a/src/AgentCore.Application/PublicAPI.Unshipped.txt +++ b/src/AgentCore.Application/PublicAPI.Unshipped.txt @@ -1020,6 +1020,8 @@ AgentCore.Application.Ports.IEvaluationScorePublisher AgentCore.Application.Ports.IEvaluationScorePublisher.PublishAsync(AgentCore.Application.Evaluation.EvaluationScore! score, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask AgentCore.Application.Ports.IFacetVocabularyPort AgentCore.Application.Ports.IFacetVocabularyPort.ReadAsync(string! path, int limit, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> +AgentCore.Application.Ports.IKnowledgeFacetReadPort +AgentCore.Application.Ports.IKnowledgeFacetReadPort.ReadByFacetAsync(string! path, string! value, int limit, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> AgentCore.Application.Ports.IKnowledgeRetrievalPort AgentCore.Application.Ports.IKnowledgeRetrievalPort.GetService(System.Type! serviceType, object? serviceKey = null) -> object? AgentCore.Application.Ports.IKnowledgeRetrievalPort.SearchAsync(string! query, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.ValueTask!> diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs index f12cdc51..108f03a6 100644 --- a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantKnowledgeStore.cs @@ -13,13 +13,14 @@ namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; /// /// The whole knowledge base over one Qdrant collection. /// -internal sealed class QdrantKnowledgeStore : IKnowledgeRetrievalPort, IFacetVocabularyPort, IDisposable +internal sealed class QdrantKnowledgeStore + : IKnowledgeRetrievalPort, IFacetVocabularyPort, IKnowledgeFacetReadPort, IDisposable { private readonly IQdrantSearchChannel _channel; private readonly IEmbeddingGenerator> _embeddings; private readonly QdrantKnowledgeStoreOptions _options; private readonly IKnowledgePointMapper _mapper; - private readonly ScopeTemplate? _scopeTemplate; + private readonly QdrantScopeMatcher _scope; /// Binds one channel, one embedder and one collection. public QdrantKnowledgeStore( @@ -34,7 +35,7 @@ public QdrantKnowledgeStore( _channel = channel; _embeddings = embeddings; _options = options; - _scopeTemplate = ScopeTemplate.Parse(options.ScopeTemplate); + _scope = new QdrantScopeMatcher(options, ScopeTemplate.Parse(options.ScopeTemplate)); // A links block with no field names no payload key to read outbound ids from. The adapter // rejects that in the document; this rejects it for a store built in code, where the // alternative is a null dereference on the first search that ranks anything. @@ -142,7 +143,7 @@ public async ValueTask> SearchAsync( foreach (var point in linked) { - if (InScope(point.Payload, scope) + if (_scope.Matches(point.Payload, scope) && Map(point.Id, point.Payload, score: null, viaLink: true) is { } card) { cards.Add(card); @@ -169,10 +170,47 @@ public async ValueTask> ReadAsync( .ConfigureAwait(false); } + /// + /// + /// The value is matched exactly, and never widened by scope.wildcard the way a scoped + /// search widens one. A caller asking for the cards of one model year wants that year, not that + /// year plus every card shared across all of them. + /// + public async ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(path); + ArgumentNullException.ThrowIfNull(value); + ArgumentOutOfRangeException.ThrowIfNegative(limit); + + var filter = new Filter(); + filter.Must.Add(new Condition + { + Field = new FieldCondition { Key = path, Match = new Match { Keyword = value } }, + }); + + var points = await _channel + .ScrollAsync(_options.Collection, filter, (uint)limit, cancellationToken) + .ConfigureAwait(false); + + // A scroll carries no vector, so no score floor applies and every point that matched is a + // card. Score stays null: nothing ranked these. + List cards = []; + foreach (var point in points) + { + if (Map(point.Id, point.Payload, score: null, viaLink: false) is { } card) + { + cards.Add(card); + } + } + + return cards; + } + private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, KnowledgeScope? scope) { var scopeFilter = new Filter(); - foreach (var (facet, value) in Facets(scope)) + foreach (var (facet, value) in QdrantScopeMatcher.Facets(scope)) { scopeFilter.Must.Add(new Condition { @@ -180,7 +218,7 @@ private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, Knowl // struct; a flat key does not. Getting that wrong matches nothing at all, silently, // which is why the template is the deployment's to write and never AgentCore's to // guess. - Field = new FieldCondition { Key = ScopePath(facet), Match = MatchFor(facet, value) }, + Field = new FieldCondition { Key = _scope.Path(facet), Match = _scope.MatchFor(facet, value) }, }); } @@ -225,39 +263,6 @@ private SearchQuery BuildQuery(string query, ReadOnlyMemory vector, Knowl : new SearchQuery(_options.Collection, prefetch, new Query { Fusion = Fusion.Rrf }, (ulong)_options.Limit); } - /// The values one facet accepts: its own, and the wildcard when this facet is named. - private IReadOnlyList Values(string facet, string value) - { - if (_options.ScopeWildcard is not { Length: > 0 } wildcard - || !_options.ScopeWildcardFacets.Contains(facet, StringComparer.Ordinal) - || string.Equals(value, wildcard, StringComparison.Ordinal)) - { - return [value]; - } - - return [.. new[] { value, wildcard }.Order(StringComparer.Ordinal)]; - } - - /// - /// Builds the match one facet condition carries. - /// - /// - /// Keyword and Keywords are different oneof cases, so a single-value Keywords list is a - /// different message from today's. A deployment that configures no wildcard has to emit the - /// message it emits now, or every stored query plan and every filter assertion changes under it. - /// - private Match MatchFor(string facet, string value) - { - var values = Values(facet, value); - - return values.Count == 1 - ? new Match { Keyword = values[0] } - : new Match { Keywords = new RepeatedStrings { Strings = { values } } }; - } - - private static IEnumerable> Facets(KnowledgeScope? scope) => - scope is null ? [] : scope.Facets.OrderBy(entry => entry.Key, StringComparer.Ordinal); - private PrefetchQuery Dense(ReadOnlyMemory vector, Filter filter, ulong depth) { var leg = new PrefetchQuery @@ -332,34 +337,6 @@ private Task> FetchLinkedAsync( _ => Uuid5PointId.For(cardId, _options.LinkNamespace, links.Prefix), }; - /// Whether a card the ranking never chose is still inside the turn's scope. - private bool InScope(MapField payload, KnowledgeScope? scope) => - Facets(scope).All(entry => - Holds(QdrantPayload.Read(payload, ScopePath(entry.Key)), Values(entry.Key, entry.Value))); - - /// Turns one facet key into the payload path this collection keeps it at. - /// - /// Only reached once a scope names a facet, which is why an unset template is an error here and - /// not at startup: a deployment whose agents never scope legitimately names no template. - /// - private string ScopePath(string facet) - => _scopeTemplate is { } template - ? template.Resolve(facet) - : throw new InvalidOperationException( - $"a KnowledgeScope names the facet '{facet}' and providers.knowledge.scope.template is " - + "unset, so AgentCore does not know what payload path that key becomes. " - + ScopeTemplate.WriteOneAdvice); - - /// Mirrors Qdrant keyword matching, where a list facet matches when any element does. - private static bool Holds(Value? facet, IReadOnlyList wanted) => facet switch - { - { KindCase: Value.KindOneofCase.StringValue } value => - wanted.Contains(value.StringValue, StringComparer.Ordinal), - { KindCase: Value.KindOneofCase.ListValue } value => - value.ListValue.Values.Any(item => wanted.Contains(item.StringValue, StringComparer.Ordinal)), - _ => false, - }; - /// Maps one point, letting the mapper skip it, then stamps how it arrived. private KnowledgeCard? Map(PointId id, MapField payload, double? score, bool viaLink) { diff --git a/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs new file mode 100644 index 00000000..ffc9a573 --- /dev/null +++ b/src/AgentCore.Infrastructure/Knowledge/VectorData/Qdrant/QdrantScopeMatcher.cs @@ -0,0 +1,95 @@ +using AgentCore.Application.Configuration.Parsing; +using AgentCore.Domain.Knowledge; + +using Google.Protobuf.Collections; + +using Qdrant.Client.Grpc; + +namespace AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; + +/// +/// What a means against one collection's payload. +/// +/// +/// One scope is asked two different ways, and both have to agree. A search sends Qdrant a filter, +/// and Qdrant decides. A card fetched by a see_also link never passes that filter, so the +/// same decision is made here, in process, against the payload. Splitting those two readings apart +/// is how a linked card ends up in an answer the scope should have kept out. +/// +/// The store's options, for the wildcard value and the facets it covers. +/// +/// The parsed scope.template, or when the document names none. +/// +internal sealed class QdrantScopeMatcher(QdrantKnowledgeStoreOptions options, ScopeTemplate? template) +{ + /// The facets one scope names, in a fixed order. + /// The turn's scope, or when nothing is scoped. + /// The facets, by key, ordinally ordered so one scope always builds one filter. + public static IEnumerable> Facets(KnowledgeScope? scope) => + scope is null ? [] : scope.Facets.OrderBy(entry => entry.Key, StringComparer.Ordinal); + + /// Turns one facet key into the payload path this collection keeps it at. + /// The facet key, as a scope names it. + /// The payload path. + /// + /// Only reached once a scope names a facet, which is why an unset template is an error here and + /// not at startup: a deployment whose agents never scope legitimately names no template. + /// + /// No scope.template was configured. + public string Path(string facet) + => template is { } resolved + ? resolved.Resolve(facet) + : throw new InvalidOperationException( + $"a KnowledgeScope names the facet '{facet}' and providers.knowledge.scope.template is " + + "unset, so AgentCore does not know what payload path that key becomes. " + + ScopeTemplate.WriteOneAdvice); + + /// Builds the match one facet condition carries. + /// The facet key. + /// The value the turn's scope holds for it. + /// The match message. + /// + /// Keyword and Keywords are different oneof cases, so a single-value Keywords list is a + /// different message from today's. A deployment that configures no wildcard has to emit the + /// message it emits now, or every stored query plan and every filter assertion changes under it. + /// + public Match MatchFor(string facet, string value) + { + var values = Values(facet, value); + + return values.Count == 1 + ? new Match { Keyword = values[0] } + : new Match { Keywords = new RepeatedStrings { Strings = { values } } }; + } + + /// Whether a card the ranking never chose is still inside the turn's scope. + /// The point's payload. + /// The turn's scope, or when nothing is scoped. + /// when every facet the scope names is satisfied. + public bool Matches(MapField payload, KnowledgeScope? scope) => + Facets(scope).All(entry => + Holds(QdrantPayload.Read(payload, Path(entry.Key)), Values(entry.Key, entry.Value))); + + /// The values one facet accepts: its own, and the wildcard when this facet is named. + private IReadOnlyList Values(string facet, string value) + { + if (options.ScopeWildcard is not { Length: > 0 } wildcard + || !options.ScopeWildcardFacets.Contains(facet, StringComparer.Ordinal) + || string.Equals(value, wildcard, StringComparison.Ordinal)) + { + return [value]; + } + + return [.. new[] { value, wildcard }.Order(StringComparer.Ordinal)]; + } + + /// Mirrors Qdrant keyword matching, where a list facet matches when any element does. + private static bool Holds(Value? facet, IReadOnlyList wanted) => facet switch + { + { KindCase: Value.KindOneofCase.StringValue } value => + wanted.Contains(value.StringValue, StringComparer.Ordinal), + { KindCase: Value.KindOneofCase.ListValue } value => + value.ListValue.Values.Any(item => wanted.Contains(item.StringValue, StringComparer.Ordinal)), + _ => false, + }; +} diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs new file mode 100644 index 00000000..91061aea --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/FacetReadTests.cs @@ -0,0 +1,116 @@ +using AgentCore.Application.Configuration.Schema; +using AgentCore.Application.Ports; +using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; +using AgentCore.Infrastructure.Tests.Fakes; +using AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; + +using Qdrant.Client.Grpc; + +using Xunit; + +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant; + +/// +/// Reading whole cards by one exact facet value, which is what a model year needs: a keyword match, +/// never a similarity. +/// +/// +/// Two adjacent model years read as near-identical to an embedding, so a ranked search for one +/// returns the other. A filtered scroll cannot make that mistake: a card carries the value or it +/// does not. +/// +public sealed class FacetReadTests +{ + [Fact] + public async Task ReadByFacetAsync_ReturnsTheCardsTheScrollAnswered() + { + var channel = new FacetScrollChannel(Card("lcr-2023-model-overview"), Card("lcr-2023-belt-tension")); + + var cards = await Store(channel).ReadByFacetAsync( + "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); + + Assert.Equal( + ["lcr-2023-belt-tension", "lcr-2023-model-overview"], + cards.Select(card => card.CardId).Order(StringComparer.Ordinal)); + } + + [Fact] + public async Task ReadByFacetAsync_FiltersOnThePathVerbatim() + { + var channel = new FacetScrollChannel(Card("lcr-2023-model-overview")); + + await Store(channel).ReadByFacetAsync( + "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); + + var condition = Assert.Single(channel.LastFilter!.Must).Field; + Assert.Equal("facets.model", condition.Key); + Assert.Equal("lcr-2023", condition.Match.Keyword); + } + + [Fact] + public async Task ReadByFacetAsync_PassesTheLimitThrough() + { + var channel = new FacetScrollChannel(Card("lcr-2023-model-overview")); + + await Store(channel).ReadByFacetAsync( + "facets.model", "lcr-2023", 7, TestContext.Current.CancellationToken); + + Assert.Equal(7u, channel.LastLimit); + } + + [Fact] + public async Task ReadByFacetAsync_AnUnknownValueIsEmptyAndNotAnError() + { + var cards = await Store(new FacetScrollChannel()).ReadByFacetAsync( + "facets.model", "nope-1999", 50, TestContext.Current.CancellationToken); + + Assert.Empty(cards); + } + + [Fact] + public async Task ReadByFacetAsync_NeverRanks() + { + // FacetScrollChannel throws on every method but ScrollAsync. Reaching this assertion is the + // proof that no vector was built and no embedding was generated. + var cards = await Store(new FacetScrollChannel(Card("lcr-2023-model-overview"))).ReadByFacetAsync( + "facets.model", "lcr-2023", 50, TestContext.Current.CancellationToken); + + Assert.Null(Assert.Single(cards).Score); + } + + [Fact] + public async Task ReadByFacetAsync_RejectsANegativeLimit() + { + await Assert.ThrowsAsync( + async () => await Store(new FacetScrollChannel()).ReadByFacetAsync( + "facets.model", "lcr-2023", -1, TestContext.Current.CancellationToken)); + } + + [Fact] + public void TheStoreServesTheFacetReadAsACapability() + { + // What a caller asks before it reads. The store answers for itself here; a wrapper would + // forward the same question inward. + IKnowledgeRetrievalPort store = Store(new FacetScrollChannel()); + + Assert.Same(store, store.GetService()); + } + + private static RetrievedPoint Card(string cardId) + { + var point = new RetrievedPoint { Id = new PointId { Uuid = Guid.NewGuid().ToString() } }; + point.Payload["card_id"] = cardId; + point.Payload["body"] = $"{cardId} body"; + return point; + } + + private static QdrantKnowledgeStore Store(IQdrantSearchChannel channel) => new( + channel, + new FakeEmbeddingGenerator([1f, 0f, 0f, 0f]), + new QdrantKnowledgeStoreOptions + { + Collection = "kb", + Scoped = false, + Fields = new KnowledgeFieldsConfiguration { Id = "card_id", Body = "body" }, + }); +} diff --git a/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs new file mode 100644 index 00000000..173830bd --- /dev/null +++ b/tests/AgentCore.Infrastructure.Tests/Knowledge/VectorData/Qdrant/Fakes/FacetScrollChannel.cs @@ -0,0 +1,43 @@ +using AgentCore.Infrastructure.Knowledge.VectorData.Qdrant; + +using Qdrant.Client.Grpc; + +namespace AgentCore.Infrastructure.Tests.Knowledge.VectorData.Qdrant.Fakes; + +/// +/// A channel that answers one scripted result and records the filter and +/// limit it was called with. +/// +/// +/// Every other method throws. A facet read that ranks, retrieves by key or reads distinct values is +/// not a facet read, and the throw is what proves it: no embedding is generated and no vector is sent. +/// +internal sealed class FacetScrollChannel(params RetrievedPoint[] points) : IQdrantSearchChannel +{ + private readonly IReadOnlyList _points = points; + + /// Gets the filter the last scroll carried, or when none has run. + public Filter? LastFilter { get; private set; } + + /// Gets the limit the last scroll carried. + public uint LastLimit { get; private set; } + + public Task> QueryAsync(SearchQuery query, CancellationToken cancellationToken) => + throw new NotSupportedException("a facet read never ranks."); + + public Task> RetrieveAsync( + string collection, IReadOnlyList ids, CancellationToken cancellationToken) => + throw new NotSupportedException("a facet read never fetches by key."); + + public Task> ScrollAsync( + string collection, Filter filter, uint limit, CancellationToken cancellationToken) + { + LastFilter = filter; + LastLimit = limit; + return Task.FromResult(_points); + } + + public Task> FacetAsync( + string collection, string key, ulong limit, CancellationToken cancellationToken) => + throw new NotSupportedException("a facet read never reads distinct values."); +} From 2dc24ab1c2aeedbf534df37fa0db03e85095fcb0 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 20:01:22 -0600 Subject: [PATCH 7/8] feat(di): resolve the knowledge port from the container A consumer resolves the one port and asks it for the capability it needs. Each capability is deliberately not registered beside it: that would hand out a second service for the same store, and a store serving none would have to be registered as null anyway. --- .../DependencyInjection/AgentCoreBoot.cs | 10 ++++ .../AgentCoreServiceCollectionExtensions.cs | 1 + .../DependencyInjection/AddAgentCoreTests.cs | 48 +++++++++++++++++++ 3 files changed, 59 insertions(+) diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index 0bb27da5..f4d9ee28 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -89,6 +89,14 @@ public AgentCoreBoot(IOptions options, ILoggerFactory loggers) /// Gets the vocabulary every call session reads, and every refresh installs into. internal VocabularyCache Vocabulary => Started.Vocabulary; + /// Gets the knowledge base, or when no agent reads one. + /// + /// One object for the whole store. A capability beyond search — reading a facet vocabulary, or + /// whole cards by an exact facet value — is asked of this port through + /// , never registered beside it. + /// + internal IKnowledgeRetrievalPort? Knowledge => Started.Knowledge; + /// Gets the same turn loop, behind the framework's own agent seam. internal AgentCoreAgent Agent => Started.Agent; @@ -265,6 +273,7 @@ await KnowledgeStartup call.Agent, call.Queue, vocabulary, + knowledge, seams.Call, seams.Speech, seams.Handler, @@ -394,6 +403,7 @@ private sealed record BootState( AgentCoreAgent Agent, QueuedAuditSink AuditQueue, VocabularyCache Vocabulary, + IKnowledgeRetrievalPort? Knowledge, IReadOnlyList? CallAdapters, IReadOnlyList? SpeechAdapters, RequestDelegate? CallHandler, diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs index c765e6a2..d2e22a71 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreServiceCollectionExtensions.cs @@ -59,6 +59,7 @@ public static IServiceCollection AddAgentCore( // returns null makes GetService answer null — which is what a caller of an optional seam // reads them with. services.AddSingleton(Boot(boot => boot.Telemetry!)); + services.AddSingleton(Boot(boot => boot.Knowledge!)); services.AddSingleton(Boot(boot => boot.CallAdapters!)); services.AddSingleton(Boot(boot => boot.SpeechAdapters!)); diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs index 4cac31e4..ef3b4c2c 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs @@ -360,6 +360,42 @@ public async Task AddAgentCore_RegistersOneSessionFactoryThatBuildsANewSessionFo Assert.NotEqual(first.CallId, second.CallId); } + [Fact] + public async Task AddAgentCore_RegistersTheKnowledgePortTheHostBound() + { + FacetCapablePort port = new(); + + using var provider = await BuildAsync( + OneAgentYaml, options => options.UseKnowledgeRetrieval(_ => port)); + + Assert.Same(port, provider.GetRequiredService()); + } + + [Fact] + public async Task AddAgentCore_TheResolvedPortAnswersWhatElseItServes() + { + // What a consumer actually does with it: resolve the one port, then ask that port for the + // capability it needs. Registering each capability separately would hand out a second + // object for the same store, and a store that serves none would have to be registered as + // null anyway. + FacetCapablePort port = new(); + + using var provider = await BuildAsync( + OneAgentYaml, options => options.UseKnowledgeRetrieval(_ => port)); + + var knowledge = provider.GetRequiredService(); + + Assert.Same(port, knowledge.GetService()); + } + + [Fact] + public async Task AddAgentCore_ADocumentThatReadsNoKnowledge_ResolvesNoPort() + { + using var provider = await BuildAsync(OneAgentYaml); + + Assert.Null(provider.GetService()); + } + [Fact] public async Task AddAgentCore_RegistersTheVocabularyEveryRefreshWritesInto() { @@ -1364,6 +1400,18 @@ public ValueTask CreateSearchAsync( } /// A knowledge port that answers with nothing and tracks whether it was closed. + /// A knowledge port that also reads whole cards by an exact facet value. + private sealed class FacetCapablePort : IKnowledgeRetrievalPort, IKnowledgeFacetReadPort + { + public ValueTask> SearchAsync( + string query, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + + public ValueTask> ReadByFacetAsync( + string path, string value, int limit, CancellationToken cancellationToken = default) + => ValueTask.FromResult>([]); + } + private sealed class DisposeTrackingKnowledgePort : IKnowledgeRetrievalPort, IDisposable { /// Gets whether this port was closed. From 492f37d75d2debc2029e161f5c473348868472e5 Mon Sep 17 00:00:00 2001 From: MatthewHsu1 Date: Wed, 9 Sep 2026 20:29:31 -0600 Subject: [PATCH 8/8] refactor: remove unnecessary remarks from ConfigurationValidator and AgentCoreBoot --- .../Validation/ConfigurationValidator.cs | 33 ------------------- .../DependencyInjection/AgentCoreBoot.cs | 9 ----- .../Startup/KnowledgeStartup.cs | 7 ++-- 3 files changed, 2 insertions(+), 47 deletions(-) diff --git a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index fbed34b1..6619c657 100644 --- a/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs +++ b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs @@ -9,24 +9,6 @@ namespace AgentCore.Application.Configuration.Validation; /// /// Checks 2 to 8 of section 8.5, over one bound document. /// -/// -/// -/// Check 1 runs in , before the document binds. This type -/// runs every later check and reports all of them at once, so one load names every defect. -/// -/// -/// MAF performs none of these checks. This validator is what makes graph: as safe as -/// policy:, and it is therefore what lets AgentCore expose both. -/// -/// -/// Decision 15 splits check 2 in two. runs every check that does not -/// depend on which tools MCP discovery ends up serving, so a YAML typo never costs a round trip to -/// every MCP server. resolves tool ids afterwards, against -/// whatever the tool registry actually serves. and still -/// run both passes together, against the ids tools: declares, so every caller that predates MCP -/// keeps its current meaning. -/// -/// public static class ConfigurationValidator { /// @@ -358,12 +340,6 @@ private static void AddUnknownGuard(GuardReference? guard, string pointer, Decla } /// Resolves one model reference against the as: names of providers.llm. - /// - /// An absent providers: section, or an absent providers.llm, declares no model - /// name, so every reference into it is unknown. That is how check 2 already reads an absent - /// tools: and an absent agents:, and a model reference is the sixth reference kind. - /// A document that names no model declares nothing to resolve and stays clean. - /// private static void AddUnknownModel(ModelReference? model, string pointer, DeclaredNames names, List errors) { if (model is { } reference && !names.Models.Contains(reference.Ref)) @@ -697,15 +673,6 @@ private static void CheckKnowledgeScopeSlots( // --------------------------------------------------------------------------------------------- /// Refuses a vocabulary: or ambiguity: block that could not do what it declares. - /// - /// Unlike , the slot-level rules here do not depend on the - /// slot being named in scope.fromState. A slot may declare vocabulary: and never be - /// scoped by: the gate still holds the extractor to values the provider published, the linker - /// still folds a mention onto one of them, and a host may read the domain for itself — a - /// knowledge search that requires a product name the manuals use, say. Scoping is what - /// fromState declares, and it is a separate decision from where a slot's domain comes - /// from. - /// private static void CheckVocabularyAndAmbiguity( AgentCoreConfiguration configuration, List errors, List warnings) { diff --git a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index f4d9ee28..949de46c 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs @@ -53,10 +53,6 @@ public AgentCoreBoot(IOptions options, ILoggerFactory loggers) internal ResolvedSecrets Secrets => Started.Secrets; /// Gets the bindings the host registered by name. - /// - /// Readable before the boot runs: a host filled it, so no document had to be loaded for it to - /// hold what it holds. - /// internal ToolBindingRegistry Bindings => _options.Bindings; /// Gets the registry that compiled the document, and would compile it again. @@ -90,11 +86,6 @@ public AgentCoreBoot(IOptions options, ILoggerFactory loggers) internal VocabularyCache Vocabulary => Started.Vocabulary; /// Gets the knowledge base, or when no agent reads one. - /// - /// One object for the whole store. A capability beyond search — reading a facet vocabulary, or - /// whole cards by an exact facet value — is asked of this port through - /// , never registered beside it. - /// internal IKnowledgeRetrievalPort? Knowledge => Started.Knowledge; /// Gets the same turn loop, behind the framework's own agent seam. diff --git a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index d19364ec..ccb5574f 100644 --- a/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs +++ b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs @@ -160,14 +160,11 @@ internal static async ValueTask ApplyVocabularyAsync( foreach (var (slotName, slot) in vocabularySlots) { var vocab = slot.Vocabulary!; + var path = template.Resolve(slotName); + var values = await port.ReadAsync(path, vocab.MaxValues, cancellationToken).ConfigureAwait(false); - // Every declared wildcard, not only the facets wildcard.facets names. The sentinel is - // a value the collection stores at a facet path, so a read of that path returns it - // whether or not a scope ever widens by it — and it normalises to nothing, so leaving - // it in the domain refuses the document. wildcard.facets answers a different - // question: which scope conditions this deployment widens. var wildcardValue = wildcard?.Value; try