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
14 changes: 14 additions & 0 deletions demo/AgentCore.Demo/config/example.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,10 @@ tools:
# ISecretResolverPort resolves it at startup through the four-step chain in D22.
headers: { Authorization: "Bearer ${secret:orders-api-key}" }

# A binds: name is registered one of two ways, and the way decides who writes the schema.
#
# options.Bind("CreateCase", (json, ct) => ...) reads the arguments as one JSON object, so the
# declaration writes parameters: below and the host digs the values out by hand.
- id: create_case
kind: binding
binds: CreateCase
Expand All @@ -172,6 +176,16 @@ tools:
properties: { summary: { type: string } }
required: [ summary ]

# options.Bind("CloseCase", (string caseId, string reason) => ...) registers a typed method
# instead. Its parameters are the arguments, and their schema, so this declaration writes no
# parameters: at all. Writing one anyway is a boot failure: the two would drift apart.
# A [Description] attribute on a parameter is what the model reads about it.
#
# - id: close_case
# kind: binding
# binds: CloseCase
# description: Close a service case once the customer is happy.

# kind: agent is agent-as-tool, and it is not handoff. The outer agent calls the inner agent,
# reads the reply, and keeps control. graph: with pattern: handoff transfers control instead,
# so the two do not overlap. The compiler wraps the inner agent with AsAIFunction(), and the
Expand Down
2 changes: 2 additions & 0 deletions src/AgentCore.Application/PublicAPI.Unshipped.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1199,8 +1199,10 @@ AgentCore.Application.Tools.Binding.ToolBindingRegistry.Contains(string! name) -
AgentCore.Application.Tools.Binding.ToolBindingRegistry.Count.get -> int
AgentCore.Application.Tools.Binding.ToolBindingRegistry.Names.get -> System.Collections.Generic.IReadOnlyCollection<string!>!
AgentCore.Application.Tools.Binding.ToolBindingRegistry.Register(string! name, AgentCore.Application.Tools.Binding.ToolBinding! binding) -> AgentCore.Application.Tools.Binding.ToolBindingRegistry!
AgentCore.Application.Tools.Binding.ToolBindingRegistry.Register(string! name, System.Delegate! method) -> AgentCore.Application.Tools.Binding.ToolBindingRegistry!
AgentCore.Application.Tools.Binding.ToolBindingRegistry.ToolBindingRegistry() -> void
AgentCore.Application.Tools.Binding.ToolBindingRegistry.TryGetBinding(string! name, out AgentCore.Application.Tools.Binding.ToolBinding? binding) -> bool
AgentCore.Application.Tools.Binding.ToolBindingRegistry.TryGetMethod(string! name, out System.Delegate? method) -> bool
AgentCore.Application.Tools.Builtin.BuiltinToolNames
AgentCore.Application.Tools.Builtin.BuiltinToolPorts
AgentCore.Application.Tools.Builtin.BuiltinToolPorts.<Clone>$() -> AgentCore.Application.Tools.Builtin.BuiltinToolPorts!
Expand Down
22 changes: 21 additions & 1 deletion src/AgentCore.Application/Tools/Binding/BindingToolSource.cs
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@ public BindingToolSource(ToolBindingRegistry registry)
}

/// <inheritdoc />
/// <exception cref="ConfigurationLoadException">A <c>binds:</c> name is missing or not registered.</exception>
/// <exception cref="ConfigurationLoadException">
/// A <c>binds:</c> name is missing, is not registered, or names a typed method while the
/// declaration also writes <c>parameters:</c>.
/// </exception>
public ValueTask<IReadOnlyList<ToolRegistration>> ProvideAsync(
ToolSourceContext context, CancellationToken cancellationToken = default)
{
Expand All @@ -36,6 +39,23 @@ public ValueTask<IReadOnlyList<ToolRegistration>> ProvideAsync(
throw ToolSourceError.Fail($"the tool '{declared.Id}' is kind: binding and names no binds:.");
}

if (_registry.TryGetMethod(name, out var method) && method is not null)
{
if (declared.Parameters is not null)
{
throw ToolSourceError.Fail(
$"the tool '{declared.Id}' binds to '{name}', which the host registered as a typed "
+ "method, and it also declares parameters:. The method signature is the schema, so "
+ "the two disagree the moment either one changes. Take the parameters: off the "
+ "declaration, or register the name as a ToolBinding instead.");
}

var typed = method;
registrations.Add(new ToolRegistration(
declared.Id, declared.Description ?? string.Empty, () => new TypedBindingTool(declared, typed)));
continue;
}

if (!_registry.TryGetBinding(name, out var binding) || binding is null)
{
throw ToolSourceError.Fail(
Expand Down
74 changes: 60 additions & 14 deletions src/AgentCore.Application/Tools/Binding/ToolBindingRegistry.cs
Original file line number Diff line number Diff line change
Expand Up @@ -17,33 +17,41 @@ namespace AgentCore.Application.Tools.Binding;
/// </summary>
public sealed class ToolBindingRegistry
{
private readonly Dictionary<string, ToolBinding> _bindings = new(StringComparer.Ordinal);
private readonly Dictionary<string, Delegate> _bindings = new(StringComparer.Ordinal);

/// <summary>Gets the number of names the host registered.</summary>
public int Count => _bindings.Count;

/// <summary>Gets the names the host registered.</summary>
public IReadOnlyCollection<string> Names => _bindings.Keys;

/// <summary>Registers one host delegate.</summary>
/// <summary>Registers one host delegate that reads the arguments as JSON.</summary>
/// <param name="name">The name a <c>binds:</c> field writes.</param>
/// <param name="binding">The delegate the tool calls.</param>
/// <returns>This registry, so a host chains its registrations.</returns>
/// <exception cref="ArgumentException">The name is already registered.</exception>
public ToolBindingRegistry Register(string name, ToolBinding binding)
{
ArgumentException.ThrowIfNullOrEmpty(name);
ArgumentNullException.ThrowIfNull(binding);
return Add(name, binding);
}

if (!_bindings.TryAdd(name, binding))
{
throw new ArgumentException($"the binding '{name}' is already registered.", nameof(name));
}

return this;
/// <summary>Registers one host method, and its parameters become the tool's arguments.</summary>
/// <param name="name">The name a <c>binds:</c> field writes.</param>
/// <param name="method">
/// The method the tool calls. Its parameters are the arguments the model fills, and their JSON
/// Schema, so the declaration this name serves must write no <c>parameters:</c>. A
/// <see cref="System.ComponentModel.DescriptionAttribute"/> on a parameter reaches the model.
/// </param>
/// <returns>This registry, so a host chains its registrations.</returns>
/// <exception cref="ArgumentException">The name is already registered.</exception>
public ToolBindingRegistry Register(string name, Delegate method)
{
ArgumentNullException.ThrowIfNull(method);
return Add(name, method);
}

/// <summary>Reports whether one name is registered.</summary>
/// <summary>Reports whether one name is registered, either way.</summary>
/// <param name="name">The name a <c>binds:</c> field writes.</param>
/// <returns><see langword="true"/> when the host registered the name.</returns>
public bool Contains(string name)
Expand All @@ -52,13 +60,51 @@ public bool Contains(string name)
return _bindings.ContainsKey(name);
}

/// <summary>Reads the delegate one name points at.</summary>
/// <summary>Reads the JSON delegate one name points at.</summary>
/// <param name="name">The name a <c>binds:</c> field writes.</param>
/// <param name="binding">The delegate, when the name is registered.</param>
/// <returns><see langword="true"/> when the host registered the name.</returns>
/// <param name="binding">The delegate, when the host registered this name as a JSON delegate.</param>
/// <returns>
/// <see langword="true"/> when the host registered the name as a <see cref="ToolBinding"/>. A
/// name the host registered as a typed method answers <see langword="false"/>; read it with
/// <see cref="TryGetMethod"/>.
/// </returns>
public bool TryGetBinding(string name, out ToolBinding? binding)
{
ArgumentNullException.ThrowIfNull(name);
return _bindings.TryGetValue(name, out binding);

binding = _bindings.TryGetValue(name, out var registered) ? registered as ToolBinding : null;

return binding is not null;
}

/// <summary>Reads the typed method one name points at.</summary>
/// <param name="name">The name a <c>binds:</c> field writes.</param>
/// <param name="method">The method, when the host registered this name as a typed method.</param>
/// <returns>
/// <see langword="true"/> when the host registered the name as a typed method. A name the host
/// registered as a <see cref="ToolBinding"/> answers <see langword="false"/>; read it with
/// <see cref="TryGetBinding"/>.
/// </returns>
public bool TryGetMethod(string name, out Delegate? method)
{
ArgumentNullException.ThrowIfNull(name);

method = _bindings.TryGetValue(name, out var registered) && registered is not ToolBinding
? registered
: null;

return method is not null;
}

private ToolBindingRegistry Add(string name, Delegate registered)
{
ArgumentException.ThrowIfNullOrEmpty(name);

if (!_bindings.TryAdd(name, registered))
{
throw new ArgumentException($"the binding '{name}' is already registered.", nameof(name));
}

return this;
}
}
28 changes: 28 additions & 0 deletions src/AgentCore.Application/Tools/Binding/TypedBindingTool.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
using System.Text.Json;
using AgentCore.Application.Configuration.Schema;
using Microsoft.Extensions.AI;

namespace AgentCore.Application.Tools.Binding;

/// <summary>
/// One <c>kind: binding</c> tool whose arguments come from a host method's signature.
/// </summary>
internal sealed class TypedBindingTool : DeclaredTool
{
private readonly AIFunction _inner;

internal TypedBindingTool(ToolConfiguration tool, Delegate method)
: base(tool)
=> _inner = AIFunctionFactory.Create(method, tool.Id, tool.Description);

/// <summary>
/// Gets the schema the host method's parameters describe. It replaces the base schema, which
/// reads the document's <c>parameters:</c>, because a typed binding declares none.
/// </summary>
public override JsonElement JsonSchema => _inner.JsonSchema;

protected override ValueTask<object?> CallAsync(
AIFunctionArguments arguments,
CancellationToken cancellationToken)
=> _inner.InvokeAsync(arguments, cancellationToken);
}
14 changes: 14 additions & 0 deletions src/AgentCore.AspNetCore/DependencyInjection/AgentCoreOptions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -303,4 +303,18 @@ public AgentCoreOptions Bind(string name, ToolBinding binding)
Bindings.Register(name, binding);
return this;
}

/// <summary>Registers one host method behind a <c>binds:</c> name.</summary>
/// <param name="name">The name a <c>binds:</c> field writes, such as <c>CreateCase</c>.</param>
/// <param name="method">
/// The method the tool calls. Its parameters are the arguments the model fills, and their JSON
/// Schema, so the declaration writes no <c>parameters:</c>.
/// </param>
/// <returns>These options, so a host chains its calls.</returns>
/// <exception cref="ArgumentException">The name is already registered.</exception>
public AgentCoreOptions Bind(string name, Delegate method)
{
Bindings.Register(name, method);
return this;
}
}
1 change: 1 addition & 0 deletions src/AgentCore.AspNetCore/PublicAPI.Unshipped.txt
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.AddToolSource(System.Func<AgentCore.AspNetCore.DependencyInjection.AgentCoreStartup!, AgentCore.Application.Ports.IToolSource!>! toolSource) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions!
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.AgentCoreOptions() -> void
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Bind(string! name, AgentCore.Application.Tools.Binding.ToolBinding! binding) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions!
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Bind(string! name, System.Delegate! method) -> AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions!
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Bindings.get -> AgentCore.Application.Tools.Binding.ToolBindingRegistry!
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Configuration.get -> AgentCore.Application.Configuration.Schema.AgentCoreConfiguration?
AgentCore.AspNetCore.DependencyInjection.AgentCoreOptions.Configuration.set -> void
Expand Down
Loading
Loading