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: 0 additions & 15 deletions AgentCore.sln
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,6 @@ 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 @@ -189,18 +187,6 @@ 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 @@ -218,6 +204,5 @@ 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
28 changes: 28 additions & 0 deletions demo/AgentCore.Demo/config/example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -406,6 +406,34 @@ providers:
# condition on that facet at all, and every value of it would be in reach before the caller has
# said anything.

filterable:
- key: applies_to
description: "The machine the question is about, as one tag, such as ct900 or f63-2019."
# The facets a mode: tool agent may narrow its own search by. Each entry becomes one choice in
# the search tool's filters argument, and the description is the only thing the model reads
# before it picks a value — so write it for the model, not for the deployer. Adding a facet
# here is the whole job: no host writes code for one.
#
# A filter can only ever narrow. A facet the host opened or the extractor filled is left
# exactly as it was, because those two are who is asking and what they said; only a facet
# holding the wildcard, or one the scope does not carry at all, is open for the model to write.
# So this is safe to name a reach facet in, and still never a way out of an isolation facet.
#
# A filter that clears no card at all is dropped and the search runs once more without it. The
# model's filter is its guess at the subject, and a wrong guess must not become "nothing is
# documented". That costs one extra search only on a filtered search that found nothing.
#
# A key whose name matches a vocabulary: slot is matched through that slot's fold, so a mention
# written "the 2023 LCR" reaches the stored lcr-2023 rather than filtering on a string no card
# carries, and a value the collection has never held is dropped rather than searched for. A key
# with no such slot is matched exactly as the model wrote it.
#
# Prefer a key that HAS such a slot. Without one nothing checks what the model invents, so it
# filters on values no card carries and the retry pays for a second search most times out.
# A facet worth filtering by is usually worth a vocabulary: slot of its own.
#
# Prefetch agents ignore this block: they advertise no function, so there is no argument to fill.

links:
field: see_also
lookup: uuid5 # uuid5 | direct | filter
Expand Down
1 change: 0 additions & 1 deletion src/AgentCore.Application/AgentCore.Application.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,6 @@

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

Expand Down
8 changes: 1 addition & 7 deletions src/AgentCore.Application/Calls/CallClarificationState.cs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
namespace AgentCore.Application.Calls;

/// <summary>What one slot's ambiguity channels have already spent of their ask budget (§7, §8).</summary>
/// <summary>What one slot's knowledge probe has already spent of its ask budget (§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
Expand All @@ -10,10 +10,4 @@ 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; }
}
4 changes: 2 additions & 2 deletions src/AgentCore.Application/Calls/CallSessionState.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ 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>
/// <summary>The slots of a call whose knowledge probe asked about none.</summary>
private static readonly IReadOnlyDictionary<string, CallClarificationState> NoClarifications =
ReadOnlyDictionary<string, CallClarificationState>.Empty;

Expand All @@ -36,7 +36,7 @@ public sealed record CallSessionState
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
/// Gets what each slot's knowledge probe has spent of its ask budget, by slot name. A slot
/// nothing has asked about is absent.
/// </summary>
public IReadOnlyDictionary<string, CallClarificationState> Clarifications { get; init; } = NoClarifications;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,28 +18,20 @@ internal static class AgentContextProviderCompiler
private static readonly SourceLocatorCitationFormatter DefaultCitations = new();

/// <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.
/// Builds the context providers of one agent. <paramref name="clarification"/> is the document's
/// ambiguity wiring (§8), the same for every agent — built once by the caller rather than
/// re-derived per agent.
/// </summary>
public static List<AIContextProvider> Build(
AgentDefaults? defaults,
AgentConfiguration item,
AgentCompilationContext context,
string pointer,
ResolvedClarification clarification,
ClarificationProvider? clarificationProvider)
KnowledgeScopeConfiguration? scope)
{
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 Down Expand Up @@ -92,16 +84,17 @@ public static List<AIContextProvider> Build(
+ $"{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.
// The document-level wiring, 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));
context.Loggers,
scope));

return providers;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -196,13 +196,6 @@ private static Dictionary<string, AIAgent> BuildAgents(

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 @@ -272,7 +265,12 @@ private static Dictionary<string, AIAgent> BuildAgents(
},
ChatHistoryProvider = history,
AIContextProviders = AgentContextProviderCompiler.Build(
section.Defaults, item, context, pointer, clarification, clarificationProvider),
section.Defaults,
item,
context,
pointer,
clarification,
configuration.Providers?.Knowledge?.Scope),
});
path.RemoveAt(path.Count - 1);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,12 @@
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.
/// The document-level ambiguity wiring the knowledge probe needs (§8), 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.
/// letting each agent re-derive it.
/// </remarks>
public sealed record ResolvedClarification
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,19 @@ public sealed record KnowledgeScopeConfiguration

/// <summary>Gets the state slots the turn's scope is built from. Each name becomes one facet key.</summary>
public IReadOnlyList<string> FromState { get; init; } = [];

/// <summary>Gets the facets a tool-mode agent may narrow its own search by. Empty offers none.</summary>
public IReadOnlyList<KnowledgeFilterableFacetConfiguration> Filterable { get; init; } = [];
}

/// <summary>One facet the model may name in the search tool's <c>filters</c> argument.</summary>
public sealed record KnowledgeFilterableFacetConfiguration
{
/// <summary>Gets the facet key, which <c>scope.template</c> turns into the payload path.</summary>
public required string Key { get; init; }

/// <summary>Gets what this facet means, in the words the model reads before it picks a value.</summary>
public required string Description { get; init; }
}

/// <summary>Which facets a card may opt out of, and the value it opts out with.</summary>
Expand Down Expand Up @@ -197,8 +210,7 @@ public sealed record KnowledgeProviderConfiguration

/// <summary>
/// How the knowledge search asks the caller which machine they meant, when the scope narrows to more
/// than one and the search itself came back empty. See section 4 of the ambiguity-and-vocabulary
/// design.
/// than one and the search itself came back empty. See section 4 of the ambiguity design.
/// </summary>
public sealed record KnowledgeAmbiguityConfiguration
{
Expand All @@ -218,8 +230,7 @@ public sealed record KnowledgeAmbiguityConfiguration
public int MaxCandidates { get; init; } = DefaultMaxCandidates;

/// <summary>
/// Gets the cap on each of a slot's two ask counters. <c>0</c> means never ask: the vocabulary
/// and the gate still work.
/// Gets the cap on a slot's probe ask counter. <c>0</c> means never ask: the gate still works.
/// </summary>
public int MaxAsks { get; init; } = DefaultMaxAsks;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -68,48 +68,4 @@ public sealed record StateSlotConfiguration

/// <summary>Gets the fixed value of the slot. It is set when the writer is <see cref="StateWriter.Const"/>.</summary>
public JsonNode? Value { get; init; }

/// <summary>
/// Gets the declaration that this slot's domain is read from a provider rather than hand-written
/// as <see cref="EnumValues"/>, or <see langword="null"/> when this document names none.
/// </summary>
public SlotVocabularyConfiguration? Vocabulary { get; init; }
}

/// <summary>
/// A slot's domain, read from a provider at boot instead of written by hand as <c>enum:</c>. See
/// section 4 of the ambiguity-and-vocabulary design.
/// </summary>
public sealed record SlotVocabularyConfiguration
{
/// <summary>The linker name used when the document names none.</summary>
public const string DefaultLinker = "exact";

/// <summary>The refresh interval used when the document sets none, in seconds. Boot only.</summary>
public const int DefaultRefreshSeconds = 0;

/// <summary>The read limit used when the document sets none.</summary>
public const int DefaultMaxValues = 2000;

/// <summary>Gets the provider the domain is read from. <c>knowledge</c> is the only member.</summary>
public required string From { get; init; }

/// <summary>Gets the <c>IStateValueLinker</c> name. Only <c>exact</c> ships.</summary>
public string Linker { get; init; } = DefaultLinker;

/// <summary>Gets how often the domain is re-read, in seconds. <c>0</c> means boot only.</summary>
public int RefreshSeconds { get; init; } = DefaultRefreshSeconds;

/// <summary>
/// Gets the limit passed to the facet read. A read returning exactly this many fails startup: it
/// cannot be told from a truncation.
/// </summary>
public int MaxValues { get; init; } = DefaultMaxValues;

/// <summary>
/// Gets whether every id in the collection, and every mention the extractor emits, is already
/// NFC. Lifts the refusal on a runtime that cannot compose Unicode, and carries the obligation
/// that every id and every mention really is already normalised.
/// </summary>
public bool AssumeNormalized { get; init; }
}
Original file line number Diff line number Diff line change
Expand Up @@ -198,43 +198,6 @@
},
"value": {
"description": "writer: const. The fixed value of the slot."
},
"vocabulary": {
"type": "object",
"description": "Declares that this slot's domain is read from a provider at boot, rather than hand-written as enum:. Absent by default.",
"additionalProperties": false,
"required": [
"from"
],
"properties": {
"from": {
"enum": [
"knowledge"
],
"description": "The provider to read the domain from. knowledge is the only member."
},
"linker": {
"type": "string",
"minLength": 1,
"default": "exact",
"description": "The IStateValueLinker name. Only exact ships."
},
"refreshSeconds": {
"type": "integer",
"default": 0,
"description": "How often the domain is re-read. 0 means boot only."
},
"maxValues": {
"type": "integer",
"default": 2000,
"description": "The limit passed to the facet read. A read returning exactly this many fails startup: it cannot be told from a truncation."
},
"assumeNormalized": {
"type": "boolean",
"default": false,
"description": "Declares that every id in the collection, and every mention the extractor emits, is already NFC. Lifts the refusal on a runtime that cannot compose Unicode."
}
}
}
},
"allOf": [
Expand Down Expand Up @@ -1244,6 +1207,27 @@
"type": "array",
"items": { "type": "string", "minLength": 1 },
"description": "The state slots the turn's scope is built from. Each becomes one facet key."
},
"filterable": {
"type": "array",
"description": "The facets a tool-mode agent may narrow its own search by. Each becomes one choice in the search tool's filters argument. A facet the host or the extractor already answered is never overwritten by one.",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["key", "description"],
"properties": {
"key": {
"type": "string",
"minLength": 1,
"description": "The facet key, which scope.template turns into the payload path."
},
"description": {
"type": "string",
"minLength": 1,
"description": "What this facet means, in the words the model reads before it picks a value."
}
}
}
}
}
},
Expand All @@ -1260,7 +1244,7 @@
"maxAsks": {
"type": "integer",
"default": 2,
"description": "The cap on each of a slot's two ask counters. 0 means never ask: the vocabulary and the gate still work."
"description": "The cap on each of a slot's two ask counters. 0 means never ask: the gate still works."
},
"probeDeadlineSeconds": {
"type": "integer",
Expand Down
Loading
Loading