feat: add asynchronous tool registration and examples

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

examples/agent-framework/DotnetAgent.cs

@@ -54,12 +54,18 @@
         _ => throw new ArgumentException($"Unknown operation: {args.Operation}"),
     });
 
-codeTool.RegisterTool<FetchDataArgs, string>("fetch_data",
-    args => args.Source switch
+// Async tool — simulates fetching from an external service.
+codeTool.RegisterToolAsync<FetchDataArgs, string>("fetch_data",
+    async args =>
     {
-        "weather" => """{"temperature": 22, "condition": "sunny"}""",
-        "stock" => """{"symbol": "MSFT", "price": 425.50}""",
-        _ => """{"error": "unknown source"}""",
+        // In real system this would be an actual HTTP/DB call.
+        await Task.Delay(1).ConfigureAwait(false);
+        return args.Source switch
+        {
+            "weather" => """{"temperature": 22, "condition": "sunny"}""",
+            "stock" => """{"symbol": "MSFT", "price": 425.50}""",
+            _ => """{"error": "unknown source"}""",
+        };
     });
 
 // --- Create IChatClient with function invocation ---

examples/copilot-sdk/DotnetCopilotSdk.cs

@@ -43,12 +43,18 @@
         _ => throw new ArgumentException($"Unknown op: {args.Operation}"),
     });
 
-codeTool.RegisterTool<FetchDataArgs, string>("fetch_data",
-    args => args.Source switch
+// Async tool — simulates fetching from an external service.
+codeTool.RegisterToolAsync<FetchDataArgs, string>("fetch_data",
+    async args =>
     {
-        "weather" => """{"temperature": 22, "condition": "sunny"}""",
-        "stock" => """{"symbol": "MSFT", "price": 425.50}""",
-        _ => """{"error": "unknown source"}""",
+        // In real system this would be an actual HTTP/DB call.
+        await Task.Delay(1).ConfigureAwait(false);
+        return args.Source switch
+        {
+            "weather" => """{"temperature": 22, "condition": "sunny"}""",
+            "stock" => """{"symbol": "MSFT", "price": 425.50}""",
+            _ => """{"error": "unknown source"}""",
+        };
     });
 
 codeTool.AllowDomain("https://httpbin.org", ["GET"]);

src/sdk/dotnet/core/Api/Sandbox.cs

@@ -191,6 +191,35 @@ public void RegisterTool<TArgs, TResult>(string name, Func<TArgs, TResult> handl
         } // lock
     }
 
+    /// <summary>
+    /// Registers a typed tool whose handler is asynchronous.
+    /// </summary>
+    /// <typeparam name="TArgs">
+    /// The argument type. Public properties define the tool's parameter schema.
+    /// </typeparam>
+    /// <typeparam name="TResult">
+    /// The return type. Serialized to JSON for the guest.
+    /// </typeparam>
+    /// <param name="name">Tool name (must be unique).</param>
+    /// <param name="handler">
+    /// Async function invoked when the guest calls this tool. Receives
+    /// deserialized arguments. The return value is serialized to JSON for
+    /// the guest.
+    /// </param>
+    /// <remarks>
+    /// <para>
+    /// The underlying FFI callback is synchronous — the async handler is
+    /// blocked on at the interop boundary via <c>GetAwaiter().GetResult()</c>.
+    /// This is safe because FFI callbacks run on threads without a
+    /// <see cref="System.Threading.SynchronizationContext"/>.
+    /// </para>
+    /// </remarks>
+    public void RegisterToolAsync<TArgs, TResult>(string name, Func<TArgs, Task<TResult>> handler)
+    {
+        // Wrap the async handler into a sync handler that blocks at the FFI boundary.
+        RegisterTool<TArgs, TResult>(name, args => handler(args).GetAwaiter().GetResult());
+    }
+
     /// <summary>
     /// Registers a tool with raw JSON input/output.
     /// </summary>
@@ -236,6 +265,28 @@ public void RegisterTool(string name, Func<string, string> handler)
         } // lock
     }
 
+    /// <summary>
+    /// Registers a raw JSON tool whose handler is asynchronous.
+    /// </summary>
+    /// <param name="name">Tool name.</param>
+    /// <param name="handler">
+    /// Async function receiving a JSON string and returning a JSON string.
+    /// Return <c>{"error": "message"}</c> to signal an error to the guest.
+    /// </param>
+    /// <remarks>
+    /// <para>
+    /// The underlying FFI callback is synchronous — the async handler is
+    /// blocked on at the interop boundary via <c>GetAwaiter().GetResult()</c>.
+    /// This is safe because FFI callbacks run on threads without a
+    /// <see cref="System.Threading.SynchronizationContext"/>.
+    /// </para>
+    /// </remarks>
+    public void RegisterToolAsync(string name, Func<string, Task<string>> handler)
+    {
+        // Wrap the async handler into a sync handler that blocks at the FFI boundary.
+        RegisterTool(name, (string json) => handler(json).GetAwaiter().GetResult());
+    }
+
     // -----------------------------------------------------------------------
     // Code execution
     // -----------------------------------------------------------------------

src/sdk/dotnet/core/Examples/ToolRegistrationExample/Program.cs

@@ -30,6 +30,13 @@
     return """{"result": "not found"}""";
 });
 
+// --- Register an async typed tool (e.g. simulating an external API call) ---
+sandbox.RegisterToolAsync<MathArgs, double>("add_async", async args =>
+{
+    await Task.Delay(10).ConfigureAwait(false); // Simulate I/O latency
+    return args.A + args.B;
+});
+
 // --- Test 1: Typed tool dispatch ---
 Console.WriteLine("═══ Test 1: Typed tool dispatch ═══");
 var result = sandbox.Run("""
@@ -57,6 +64,16 @@
 
 Console.WriteLine($"stdout:\n{result.Stdout}");
 
+// --- Test 3: Async tool dispatch ---
+Console.WriteLine("═══ Test 3: Async tool dispatch ═══");
+
+result = sandbox.Run("""
+    async_sum = call_tool("add_async", a=100, b=200)
+    print(f"Async 100 + 200 = {async_sum}")
+    """);
+
+Console.WriteLine($"stdout:\n{result.Stdout}");
+
 Console.WriteLine("✅ Tool registration example finished successfully!");
 return 0;
 

src/sdk/dotnet/core/Extensions.AI/CodeExecutionTool.cs

@@ -81,6 +81,31 @@ public void RegisterTool(string name, Func<string, string> handler)
         }
     }
 
+    /// <summary>
+    /// Registers a typed tool whose handler is asynchronous.
+    /// Must be called before the first <see cref="Execute"/>.
+    /// </summary>
+    public void RegisterToolAsync<TArgs, TResult>(string name, Func<TArgs, Task<TResult>> handler)
+    {
+        lock (_gate)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            _sandbox.RegisterToolAsync(name, handler);
+        }
+    }
+
+    /// <summary>
+    /// Registers a raw JSON tool whose handler is asynchronous.
+    /// </summary>
+    public void RegisterToolAsync(string name, Func<string, Task<string>> handler)
+    {
+        lock (_gate)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            _sandbox.RegisterToolAsync(name, handler);
+        }
+    }
+
     /// <summary>
     /// Adds a domain to the network allowlist.
     /// </summary>

src/sdk/dotnet/core/Tests/HyperlightSandbox.Tests/IntegrationTests.cs

@@ -280,6 +280,83 @@ public async Task Integration_RunAsync_WorksFromDifferentThread()
         Assert.Contains("async hello", result.Stdout, StringComparison.Ordinal);
     }
 
+    // -----------------------------------------------------------------------
+    // Async tool dispatch
+    // -----------------------------------------------------------------------
+
+    [Fact]
+    public void Integration_ToolDispatch_AsyncTypedTool_Works()
+    {
+        using var sandbox = TryCreateSandbox();
+        if (sandbox == null) return;
+
+        // Register a tool with an async handler (e.g. simulating a DB/HTTP call).
+        sandbox.RegisterToolAsync<AddArgs, double>("add_async", async args =>
+        {
+            await Task.Delay(10).ConfigureAwait(false); // Simulate I/O
+            return args.a + args.b;
+        });
+
+        var result = sandbox.Run("""
+            result = call_tool("add_async", a=50, b=25)
+            print(f"result={result}")
+            """);
+
+        Assert.True(result.Success);
+        Assert.Contains("result=75", result.Stdout, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Integration_ToolDispatch_AsyncRawJsonTool_Works()
+    {
+        using var sandbox = TryCreateSandbox();
+        if (sandbox == null) return;
+
+        // Register a raw JSON tool with an async handler.
+        sandbox.RegisterToolAsync("fetch_async", async (string json) =>
+        {
+            await Task.Delay(10).ConfigureAwait(false); // Simulate I/O
+            return json.Contains("weather", StringComparison.Ordinal)
+                ? """{"data": "sunny"}"""
+                : """{"data": "unknown"}""";
+        });
+
+        var result = sandbox.Run("""
+            r = call_tool("fetch_async", key="weather")
+            print(r)
+            """);
+
+        Assert.True(result.Success);
+        Assert.Contains("sunny", result.Stdout, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Integration_ToolDispatch_MixedSyncAndAsyncTools_Works()
+    {
+        using var sandbox = TryCreateSandbox();
+        if (sandbox == null) return;
+
+        // Sync tool.
+        sandbox.RegisterTool<AddArgs, double>("add", args => args.a + args.b);
+
+        // Async tool.
+        sandbox.RegisterToolAsync<AddArgs, double>("multiply_async", async args =>
+        {
+            await Task.Delay(10).ConfigureAwait(false);
+            return args.a * args.b;
+        });
+
+        var result = sandbox.Run("""
+            s = call_tool("add", a=3, b=4)
+            p = call_tool("multiply_async", a=6, b=7)
+            print(f"{s} {p}")
+            """);
+
+        Assert.True(result.Success);
+        Assert.Contains("7", result.Stdout, StringComparison.Ordinal);
+        Assert.Contains("42", result.Stdout, StringComparison.Ordinal);
+    }
+
     // -----------------------------------------------------------------------
     // Helper types
     // -----------------------------------------------------------------------