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/Configuration/Validation/ConfigurationValidator.cs b/src/AgentCore.Application/Configuration/Validation/ConfigurationValidator.cs index ef615820..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,16 +673,10 @@ 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. - /// 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 +708,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 +804,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.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/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/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 f22050c2..2fb07d07 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 @@ -968,7 +1020,10 @@ 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!> AgentCore.Application.Ports.IKnowledgeStoreAdapter AgentCore.Application.Ports.IKnowledgeStoreAdapter.CanScope.get -> bool @@ -991,6 +1046,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 @@ -1297,6 +1353,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 +1418,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 +1448,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 +1459,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 +1497,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 @@ -1533,6 +1600,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 @@ -1637,6 +1705,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 +1741,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.AspNetCore/DependencyInjection/AgentCoreBoot.cs b/src/AgentCore.AspNetCore/DependencyInjection/AgentCoreBoot.cs index 3e0722d2..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. @@ -86,6 +82,12 @@ 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 knowledge base, or when no agent reads one. + internal IKnowledgeRetrievalPort? Knowledge => Started.Knowledge; + /// Gets the same turn loop, behind the framework's own agent seam. internal AgentCoreAgent Agent => Started.Agent; @@ -261,6 +263,8 @@ await KnowledgeStartup call.Sessions, call.Agent, call.Queue, + vocabulary, + knowledge, seams.Call, seams.Speech, seams.Handler, @@ -327,7 +331,7 @@ private void StartVocabularyRefresh( VocabularyCache vocabulary, CancellationToken cancellationToken) { - if (knowledge is not IFacetVocabularyPort port) + if (knowledge?.GetService() is not { } port) { return; } @@ -348,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, @@ -387,6 +393,8 @@ private sealed record BootState( ICallSessionFactory Sessions, 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 d54d1e0e..d2e22a71 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)); @@ -58,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/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs b/src/AgentCore.AspNetCore/DependencyInjection/Startup/KnowledgeStartup.cs index d40b4f8c..ccb5574f 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), @@ -160,11 +160,12 @@ 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); - var wildcardValue = wildcardFacets.Contains(slotName, StringComparer.Ordinal) - ? wildcard!.Value - : null; + + var wildcardValue = wildcard?.Value; try { 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/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/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] 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/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.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); + } +} diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/AddAgentCoreTests.cs index e57b25c2..ef3b4c2c 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,55 @@ 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() + { + 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() { @@ -1350,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. diff --git a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs index 3c8dea9e..b50960e3 100644 --- a/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs +++ b/tests/AgentCore.AspNetCore.Tests/DependencyInjection/VocabularyStartupTests.cs @@ -23,6 +23,48 @@ 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_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() { @@ -297,7 +339,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 +361,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 { @@ -381,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 { 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."); +}