Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions AgentCore.sln
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AgentCore.TestSupport", "te
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AgentCore.AspNetCore", "src\AgentCore.AspNetCore\AgentCore.AspNetCore.csproj", "{DB5D8634-2691-4048-A6F7-FFA9F6016FE2}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AgentCore.Application.Unicode.Tests", "tests\AgentCore.Application.Unicode.Tests\AgentCore.Application.Unicode.Tests.csproj", "{5586509D-101A-4F39-8161-15ED573E7EC9}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Expand Down Expand Up @@ -187,6 +189,18 @@ Global
{DB5D8634-2691-4048-A6F7-FFA9F6016FE2}.Release|x64.Build.0 = Release|Any CPU
{DB5D8634-2691-4048-A6F7-FFA9F6016FE2}.Release|x86.ActiveCfg = Release|Any CPU
{DB5D8634-2691-4048-A6F7-FFA9F6016FE2}.Release|x86.Build.0 = Release|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|Any CPU.Build.0 = Debug|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x64.ActiveCfg = Debug|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x64.Build.0 = Debug|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x86.ActiveCfg = Debug|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Debug|x86.Build.0 = Debug|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Release|Any CPU.ActiveCfg = Release|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Release|Any CPU.Build.0 = Release|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x64.ActiveCfg = Release|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x64.Build.0 = Release|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x86.ActiveCfg = Release|Any CPU
{5586509D-101A-4F39-8161-15ED573E7EC9}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
Expand All @@ -204,5 +218,6 @@ Global
{DE0D9F78-60D2-4A95-B71C-E01480048CA0} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
{E70C6362-5778-4498-9BA9-7FED110762AE} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
{DB5D8634-2691-4048-A6F7-FFA9F6016FE2} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{5586509D-101A-4F39-8161-15ED573E7EC9} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
EndGlobalSection
EndGlobal
53 changes: 47 additions & 6 deletions demo/AgentCore.Demo/config/example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,20 @@ state:
# AgentCore coerces the value, and leaves the slot at its default when coercion fails.
orderStatus: { type: string, writer: tool, from: lookup_order.status }

# writer: extractor, and also named in providers.knowledge.scope.fromState below, which is what
# turns these two into the turn's knowledge facets. A fromState slot has to be this exact shape —
# writer: extractor, type: string, an enum:, and no default — and the boot check says which of the
# four is missing rather than failing the load with no pointer. enum: is enforced on every write,
# not merely requested of the model: a value outside it is refused and the slot keeps its previous
# value, so a resumed call whose stored blob carries a value the corpus was never tagged with comes
# back with that slot unfilled rather than scoped to a typo.
#
# applies_to breaks this file's camelCase slot naming on purpose. A fromState slot name IS the
# facet key, and scope.template turns it straight into the payload path, so these two names have to
# be spelled the way the collection spells them rather than the way the schema spells its own keys.
brand: { type: string, writer: extractor, description: "The brand of the caller's machine.", enum: [sole, spirit] }
applies_to: { type: string, writer: extractor, description: "The model, as printed on the machine.", enum: [f63, f65, f80] }

# writer: counter. The slot increments whenever the increment rule is true.
failedResolveTurns:
type: integer
Expand Down Expand Up @@ -322,10 +336,34 @@ providers:

scope:
template: "facets.{key}"
# How one facet key becomes a payload path. There is no default, because a template is a claim
# about where one collection keeps its facets. Flat facets are "{key}"; facets nested under one
# struct are "facets.{key}". Required as soon as ANY agent declares scoped: true — which is the
# default, so most documents need it.
# How one facet key becomes a payload path. There is no default, because a template is a claim
# about where one collection keeps its facets. Flat facets are "{key}"; facets nested under one
# struct are "facets.{key}". Required as soon as ANY agent declares scoped: true — which is the
# default, so most documents need it.

wildcard:
value: "*"
facets: [brand, applies_to]
# How a card opts out of exact-match scoping, one facet at a time — never the whole scope. A
# card tagged facets.brand: "*" is reachable from a scope open on any brand, which is where
# opening hours, returns and warranty terms belong: they are true of no single machine. Name
# only the REACH facets here, and never an isolation facet such as a customer id — a wildcard
# on that would serve one mis-tagged card to every caller on every call, silently. The block is
# opt-in: leave it out and the emitted filter is byte-identical to a document that has never
# heard of it.
#
# Configure the wildcard first, and tag the corpus after. Re-tagging a company-wide card to
# facets.brand: "*" while this block is still absent means exact match keeps refusing it for
# the whole re-tag window; flipped first, the same tag starts working the moment it lands, and
# an untagged corpus answers exactly as it did before the block existed.

fromState: [brand, applies_to]
# The state slots the turn's scope is built from, on top of whatever the host itself opens.
# Each name must point at a slot declared under state: above with writer: extractor,
# type: string, an enum:, and no default. A slot nothing has filled yet still appears in the
# scope, holding the wildcard, rather than being left out — leaving it out would put no
# condition on that facet at all, and every value of it would be in reach before the caller has
# said anything.

links:
field: see_also
Expand Down Expand Up @@ -356,8 +394,11 @@ providers:
# on the card, including fields no role above names. Registering under this same name replaces
# the shipped wording for every agent without touching this document.

scoreFloor: 0.25
# The smallest fused score a card may carry, 0 to 1.
scoreFloor: 0.35
# The cosine similarity a card must score strictly above, 0 to 1. Qdrant applies it on the
# dense prefetch, so a question the corpus does not answer returns nothing instead of its three
# nearest cards. On text-embedding-3-small, 0.25 was too low to tell the two apart; 0.35 was not.
# 0 disables the floor.

# mapper: my-mapper
# An IKnowledgePointMapper registered with options.UseKnowledgePointMappers. Named, it owns the
Expand Down
1 change: 1 addition & 0 deletions src/AgentCore.Application/AgentCore.Application.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@

<ItemGroup>
<InternalsVisibleTo Include="AgentCore.Application.Tests" />
<InternalsVisibleTo Include="AgentCore.Application.Unicode.Tests" />
<InternalsVisibleTo Include="AgentCore.AspNetCore.Tests" />
</ItemGroup>

Expand Down
19 changes: 19 additions & 0 deletions src/AgentCore.Application/Calls/CallClarificationState.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
namespace AgentCore.Application.Calls;

/// <summary>What one slot's ambiguity channels have already spent of their ask budget (§7, §8).</summary>
/// <remarks>
/// Carried on <see cref="CallSessionState"/> so a caller who drops and reconnects mid-call is not
/// asked the same clarification a second <c>maxAsks</c> times. What was last named to the caller is
/// deliberately absent: it belongs to a turn the reconnected caller is no longer in.
/// </remarks>
public sealed record CallClarificationState
{
/// <summary>Gets how many times the knowledge probe has offered this slot (§8, K22).</summary>
public int ProbeAsks { get; init; }

/// <summary>Gets how many times the clarification instruction has named this slot (§7).</summary>
public int NamedAsks { get; init; }

/// <summary>Gets whether §7 step 3's one counter reset has already been spent.</summary>
public bool ResetSpent { get; init; }
}
10 changes: 10 additions & 0 deletions src/AgentCore.Application/Calls/CallSessionState.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ public sealed record CallSessionState
private static readonly IReadOnlyDictionary<string, JsonNode?> NoSlots =
ReadOnlyDictionary<string, JsonNode?>.Empty;

/// <summary>The slots of a call whose ambiguity channels asked about none.</summary>
private static readonly IReadOnlyDictionary<string, CallClarificationState> NoClarifications =
ReadOnlyDictionary<string, CallClarificationState>.Empty;

/// <summary>The shape this version of the library writes.</summary>
public const int CurrentVersion = 1;

Expand All @@ -30,4 +34,10 @@ public sealed record CallSessionState

/// <summary>Gets the declared slots a writer had filled, by name. An unfilled slot is absent.</summary>
public IReadOnlyDictionary<string, JsonNode?> Slots { get; init; } = NoSlots;

/// <summary>
/// Gets what each slot's ambiguity channels have spent of their ask budget, by slot name. A slot
/// nothing has asked about is absent.
/// </summary>
public IReadOnlyDictionary<string, CallClarificationState> Clarifications { get; init; } = NoClarifications;
}
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,14 @@ namespace AgentCore.Application.Configuration.Compilation;
/// <param name="Limit">How many cards to retrieve.</param>
/// <param name="Citations">Whether the model sees the source label.</param>
/// <param name="Scoped">Whether this agent's searches are confined to a scope.</param>
public sealed record ResolvedKnowledge(KnowledgeMode Mode, int Limit, bool Citations, bool Scoped);
public sealed record ResolvedKnowledge(KnowledgeMode Mode, int Limit, bool Citations, bool Scoped)
{
/// <summary>
/// Gets the document-level ambiguity wiring the search side reads, or
/// <see cref="ResolvedClarification.None"/> where the document configures none.
/// </summary>
public ResolvedClarification Clarification { get; init; } = ResolvedClarification.None;
}

/// <summary>
/// Composes one agent's <c>knowledge:</c> block from <c>agents.defaults.knowledge</c> and the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,12 @@ namespace AgentCore.Application.Configuration.Compilation;
/// </remarks>
public static class ConfigurationCompiler
{
/// <summary>
/// The formatter an agent cites through when the host bound none. Stateless, so every agent in
/// every document reads the one instance.
/// </summary>
private static readonly SourceLocatorCitationFormatter DefaultCitations = new();

/// <summary>Picks the row of the compile table one document selects.</summary>
/// <param name="configuration">The loaded document.</param>
/// <returns>The row.</returns>
Expand Down Expand Up @@ -194,6 +200,15 @@ private static Dictionary<string, AIAgent> BuildAgents(
return agents;
}

var clarification = ResolvedClarification.From(configuration);

// Nothing on this provider is per agent: its three fields are the document's own wiring, and
// every other value it reads comes off the turn's ambients. The framework only ever calls
// into it, passing the agent and the session as arguments, so one instance serves them all.
var clarificationProvider = clarification.Ambiguity is { } documentAmbiguity
? new ClarificationProvider(documentAmbiguity, clarification.FromState, clarification.SlotDescriptions)
: null;

Dictionary<string, ToolConfiguration> tools = new(StringComparer.Ordinal);
foreach (var tool in configuration.Tools)
{
Expand Down Expand Up @@ -262,7 +277,8 @@ private static Dictionary<string, AIAgent> BuildAgents(
Tools = BuildTools(item, tools, context, pointer, Resolve),
},
ChatHistoryProvider = history,
AIContextProviders = BuildContextProviders(section.Defaults, item, context, pointer),
AIContextProviders = BuildContextProviders(
section.Defaults, item, context, pointer, clarification, clarificationProvider),
});
path.RemoveAt(path.Count - 1);

Expand All @@ -275,15 +291,29 @@ private static Dictionary<string, AIAgent> BuildAgents(
}
}

/// <summary>Builds the context providers of one agent.</summary>
/// <summary>
/// Builds the context providers of one agent. <paramref name="clarification"/> and
/// <paramref name="clarificationProvider"/> are the document's ambiguity wiring (§7), the same
/// for every agent — built once by the caller rather than re-derived per agent.
/// </summary>
private static List<AIContextProvider> BuildContextProviders(
AgentDefaults? defaults,
AgentConfiguration item,
AgentCompilationContext context,
string pointer)
string pointer,
ResolvedClarification clarification,
ClarificationProvider? clarificationProvider)
{
List<AIContextProvider> 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)
Expand All @@ -298,7 +328,7 @@ private static List<AIContextProvider> BuildContextProviders(
providers.Add(SkillsProviderFactory.Create(catalog, item.Skills, context.Loggers));
}

if (AgentKnowledge.Compose(defaults, item) is not { } knowledge)
if (AgentKnowledge.Compose(defaults, item) is not { } composed)
{
return providers;
}
Expand All @@ -313,11 +343,15 @@ private static List<AIContextProvider> BuildContextProviders(
+ $"{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 ?? new SourceLocatorCitationFormatter(),
context.Citations ?? DefaultCitations,
context.Loggers));

return providers;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
using System.Collections.ObjectModel;
using AgentCore.Application.Configuration.Parsing;
using AgentCore.Application.Configuration.Schema;

namespace AgentCore.Application.Configuration.Compilation;

/// <summary>
/// The document-level ambiguity wiring §7 needs, read once from <c>providers.knowledge</c> and the
/// declared <c>state:</c> slots.
/// </summary>
/// <remarks>
/// The same for every agent, so <see cref="ConfigurationCompiler"/> builds it once rather than
/// letting each agent re-derive it, and both channels — the clarification provider and the agent's
/// own search — read the one instance.
/// </remarks>
public sealed record ResolvedClarification
{
/// <summary>The wiring of a document that configures no ambiguity: nothing to probe, nothing to ask.</summary>
public static readonly ResolvedClarification None = new();

/// <summary>
/// Gets how the knowledge search asks the caller which value they meant, or <see langword="null"/>
/// when <c>providers.knowledge.ambiguity</c> is absent — neither the probe nor the clarification
/// ever runs.
/// </summary>
public KnowledgeAmbiguityConfiguration? Ambiguity { get; init; }

/// <summary>
/// Gets the <c>providers.knowledge.scope.fromState</c> slots, in declaration order, or empty when
/// the document names none.
/// </summary>
public IReadOnlyList<string> FromState { get; init; } = [];

/// <summary>
/// Gets each <see cref="FromState"/> slot's <c>description</c>, keyed by slot name.
/// </summary>
/// <remarks>
/// Every <see cref="FromState"/> slot has a key here. The value is <see langword="null"/> both
/// where <c>state:</c> declares that slot without a <c>description</c> and where it declares no
/// such slot at all; readers fall back to the slot name for either.
/// </remarks>
public IReadOnlyDictionary<string, string?> SlotDescriptions { get; init; } =
ReadOnlyDictionary<string, string?>.Empty;

/// <summary>
/// Gets the payload value that satisfies any scope on a wildcard facet, or <see langword="null"/>
/// when <c>providers.knowledge.scope.wildcard</c> is absent.
/// </summary>
public string? WildcardValue { get; init; }

/// <summary>
/// Gets the facet keys <see cref="WildcardValue"/> widens, or empty when
/// <c>providers.knowledge.scope.wildcard</c> is absent.
/// </summary>
public IReadOnlyList<string> WildcardFacets { get; init; } = [];

/// <summary>
/// Gets the payload path each facet key becomes, or <see langword="null"/> when
/// <c>providers.knowledge.scope.template</c> is absent.
/// </summary>
/// <remarks>
/// The probe walks the resolved path to read a dropped facet's value off a returned card's
/// <c>Extras</c> (§8 step 5). Boot and the store resolve their own paths from the same document
/// value through <see cref="ScopeTemplate"/>, which owns the one resolution rule.
/// </remarks>
public ScopeTemplate? Template { get; init; }

/// <summary>Reads the wiring out of one bound document.</summary>
/// <param name="configuration">The bound document.</param>
/// <returns>The wiring, or <see cref="None"/> when the document configures no knowledge scope.</returns>
/// <exception cref="ArgumentNullException"><paramref name="configuration"/> is <see langword="null"/>.</exception>
public static ResolvedClarification From(AgentCoreConfiguration configuration)
{
ArgumentNullException.ThrowIfNull(configuration);

var knowledge = configuration.Providers?.Knowledge;
if (knowledge is null)
{
return None;
}

var fromState = knowledge.Scope.FromState;

Dictionary<string, string?> descriptions = new(StringComparer.Ordinal);
foreach (var slot in fromState)
{
descriptions[slot] = configuration.State.TryGetValue(slot, out var declared)
? declared.Description
: null;
}

return new ResolvedClarification
{
Ambiguity = knowledge.Ambiguity,
FromState = fromState,
SlotDescriptions = descriptions,
WildcardValue = knowledge.Scope.Wildcard?.Value,
WildcardFacets = knowledge.Scope.Wildcard?.Facets ?? [],
Template = ScopeTemplate.Parse(knowledge.Scope.Template),
};
}
}
Loading
Loading