Skip to content

Commit 60dc19b

Browse files
committed
.NET: render host-tool schemas only when they describe parameters
1 parent 50d7266 commit 60dc19b

5 files changed

Lines changed: 172 additions & 54 deletions

File tree

‎dotnet/src/Microsoft.Agents.AI.Hyperlight/Internal/InstructionBuilder.cs‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -76,16 +76,22 @@ public static string BuildExecuteCodeDescription(
7676

7777
sb.AppendLine();
7878

79-
// Surface the host tool's existing parameter schema so the model can see
80-
// names, requiredness, descriptions, enums, and nested shapes.
81-
// JSON Schema roots are objects or booleans (true/false); reject other kinds.
8279
JsonElement schema = tool.JsonSchema;
83-
if (schema.ValueKind is JsonValueKind.Object or JsonValueKind.True or JsonValueKind.False)
80+
if (schema.ValueKind is JsonValueKind.Object
81+
&& schema.TryGetProperty("properties", out var properties)
82+
&& properties.ValueKind is JsonValueKind.Object)
8483
{
85-
sb.AppendLine(" Parameters (JSON Schema):");
86-
sb.Append(" ");
87-
sb.Append(schema.GetRawText());
88-
sb.AppendLine();
84+
if (properties.EnumerateObject().MoveNext())
85+
{
86+
sb.AppendLine(" Parameters (JSON Schema):");
87+
sb.Append(" ");
88+
sb.Append(schema.GetRawText());
89+
sb.AppendLine();
90+
}
91+
else
92+
{
93+
sb.AppendLine(" Parameters: none.");
94+
}
8995
}
9096
}
9197
}

‎dotnet/src/Microsoft.Agents.AI.Hyperlight/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,24 @@ Both surfaces support:
2525
* Snapshot/restore per run so the guest starts from a known clean state
2626
every invocation.
2727

28+
## Host tool parameter schemas
29+
30+
The `execute_code` description lists each provider-owned tool with its existing
31+
`AIFunction.JsonSchema`, so the model can see parameter names, requiredness,
32+
descriptions, enums, and nested shapes and call `call_tool(...)` correctly.
33+
Tools that do not describe their input are listed by name only.
34+
35+
Two things to keep in mind:
36+
37+
* Parameter names, descriptions, defaults, and enum values are **model-visible**.
38+
Do not put credentials, tenant identifiers, or other secrets in them.
39+
* C# enums serialize as integers by default, so their member names do not reach
40+
the schema. Apply `JsonStringEnumConverter` to the enum if the model should see
41+
the allowed values.
42+
43+
This does not change `execute_code`'s own input schema, which remains the single
44+
`code` parameter.
45+
2846
## Requirements
2947

3048
* The `Hyperlight.HyperlightSandbox.Api` NuGet package, published from the
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using Microsoft.Extensions.AI;
4+
5+
namespace Microsoft.Agents.AI.Hyperlight.UnitTests;
6+
7+
public sealed class HyperlightExecuteCodeFunctionTests
8+
{
9+
[Fact]
10+
public void Description_WithParameterizedTool_CarriesHostToolSchema()
11+
{
12+
// Arrange
13+
var tool = AIFunctionFactory.Create((string query) => "ok", name: "lookup");
14+
15+
// Act
16+
using var function = new HyperlightExecuteCodeFunction(new HyperlightCodeActProviderOptions
17+
{
18+
Tools = [tool],
19+
});
20+
21+
// Assert
22+
Assert.Contains("query", function.Description);
23+
}
24+
25+
[Fact]
26+
public void JsonSchema_WithParameterizedTool_StaysCodeOnly()
27+
{
28+
// Arrange
29+
var tool = AIFunctionFactory.Create((string query) => "ok", name: "lookup");
30+
31+
// Act
32+
using var function = new HyperlightExecuteCodeFunction(new HyperlightCodeActProviderOptions
33+
{
34+
Tools = [tool],
35+
});
36+
var inputSchema = function.JsonSchema.GetRawText();
37+
38+
// Assert — host-tool schemas are documentation inside the description only; they
39+
// must never widen execute_code's own input contract.
40+
Assert.Contains("\"code\"", inputSchema);
41+
Assert.DoesNotContain("query", inputSchema);
42+
}
43+
}

‎dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/InstructionBuilderTests.cs‎

Lines changed: 58 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,16 @@
22

33
using System.Collections.Generic;
44
using System.ComponentModel;
5-
using System.Linq;
65
using System.Text.Json;
6+
using System.Threading;
77
using System.Threading.Tasks;
88
using Microsoft.Agents.AI.Hyperlight.Internal;
99
using Microsoft.Extensions.AI;
10-
using Moq;
1110

1211
namespace Microsoft.Agents.AI.Hyperlight.UnitTests;
1312

1413
public sealed class InstructionBuilderTests
1514
{
16-
private static readonly AIAgent s_mockAgent = new Mock<AIAgent>().Object;
17-
1815
[Fact]
1916
public void BuildContextInstructions_HiddenTools_MentionsCallTool()
2017
{
@@ -77,11 +74,9 @@ public void BuildExecuteCodeDescription_WithTools_IncludesToolNames()
7774
}
7875

7976
[Fact]
80-
public async Task BuildExecuteCodeDescription_WithParameterizedTools_IncludesHostToolJsonSchemaAsync()
77+
public void BuildExecuteCodeDescription_WithToolParameters_IncludesParameterMetadata()
8178
{
82-
// Arrange — zero-parameter tools already have coverage above; this locks the
83-
// host-tool JsonSchema gap tracked by microsoft/agent-framework#8446.
84-
// Stick to reflection-friendly primitives so AOT/source-gen test hosts can build the schema.
79+
// Arrange
8580
static string Lookup(
8681
[Description("Search text")] string query,
8782
[Description("Maximum results")] int limit = 10) => $"{query}:{limit}";
@@ -98,44 +93,62 @@ static string Lookup(
9893
allowedDomains: [],
9994
hasHostInputDirectory: false);
10095

101-
// Assert — model-facing description must carry the host tool parameter schema.
96+
// Assert
10297
Assert.Contains("lookup", text);
103-
Assert.Contains("Look up an item.", text);
104-
Assert.Contains("Parameters (JSON Schema)", text);
105-
Assert.Contains(tool.JsonSchema.GetRawText(), text);
10698
Assert.Contains("query", text);
10799
Assert.Contains("Search text", text);
108-
Assert.Contains("limit", text);
109100
Assert.Contains("Maximum results", text);
110101

111-
// Host schemas are documentation only; they must not replace execute_code's code-only input.
112-
using var executeCode = new HyperlightExecuteCodeFunction(new HyperlightCodeActProviderOptions
113-
{
114-
Tools = [tool],
115-
});
116-
Assert.Contains("\"code\"", executeCode.JsonSchema.GetRawText());
117-
Assert.DoesNotContain("\"query\"", executeCode.JsonSchema.GetRawText());
118-
Assert.DoesNotContain("\"limit\"", executeCode.JsonSchema.GetRawText());
102+
// Requiredness and defaults separate the two parameters.
103+
Assert.Contains("\"required\":[\"query\"]", text);
104+
Assert.Contains("\"default\":10", text);
105+
}
119106

120-
using var provider = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
121-
{
122-
Tools = [tool],
123-
});
124-
var context = await provider.InvokingAsync(
125-
new AIContextProvider.InvokingContext(s_mockAgent, session: null, new AIContext()));
126-
var providerFn = Assert.IsAssignableFrom<AIFunction>(context!.Tools!.First());
127-
Assert.Contains("\"code\"", providerFn.JsonSchema.GetRawText());
128-
Assert.DoesNotContain("\"query\"", providerFn.JsonSchema.GetRawText());
129-
Assert.DoesNotContain("\"limit\"", providerFn.JsonSchema.GetRawText());
107+
[Fact]
108+
public void BuildExecuteCodeDescription_WithZeroParameterTool_ReportsNoParameters()
109+
{
110+
// Arrange
111+
var tool = AIFunctionFactory.Create(() => "ok", name: "ping", description: "Pings.");
112+
113+
// Act
114+
var text = InstructionBuilder.BuildExecuteCodeDescription(
115+
tools: [tool],
116+
fileMounts: [],
117+
allowedDomains: [],
118+
hasHostInputDirectory: false);
119+
120+
// Assert
121+
Assert.Contains("Parameters: none.", text);
122+
Assert.DoesNotContain("Parameters (JSON Schema)", text);
123+
Assert.DoesNotContain("\"properties\":{}", text);
124+
}
125+
126+
[Fact]
127+
public void BuildExecuteCodeDescription_WithUnconstrainedSchema_OmitsParameterBlock()
128+
{
129+
// Arrange
130+
var tool = new StubTool("legacy_tool", "A tool that does not describe its input.");
131+
132+
// Act
133+
var text = InstructionBuilder.BuildExecuteCodeDescription(
134+
tools: [tool],
135+
fileMounts: [],
136+
allowedDomains: [],
137+
hasHostInputDirectory: false);
138+
139+
// Assert
140+
Assert.Contains("legacy_tool", text);
141+
Assert.DoesNotContain("Parameters", text);
142+
Assert.DoesNotContain("{}", text);
130143
}
131144

132-
[Theory]
133-
[InlineData("true")]
134-
[InlineData("false")]
135-
public void BuildExecuteCodeDescription_WithBooleanJsonSchema_IncludesBooleanRoot(string schemaJson)
145+
[Fact]
146+
public void BuildExecuteCodeDescription_WithBooleanSchemaRoot_OmitsParameterBlock()
136147
{
137-
// Arrange — boolean JSON Schema roots are valid and must surface to the model.
138-
var tool = new BooleanSchemaTool("gate", "Always-on gate.", schemaJson);
148+
// Arrange — `true` is a valid JSON Schema root, and carries exactly as much
149+
// parameter information as `{}`: none.
150+
using var document = JsonDocument.Parse("true");
151+
var tool = new StubTool("gate", "Always-on gate.", document.RootElement);
139152

140153
// Act
141154
var text = InstructionBuilder.BuildExecuteCodeDescription(
@@ -146,8 +159,7 @@ public void BuildExecuteCodeDescription_WithBooleanJsonSchema_IncludesBooleanRoo
146159

147160
// Assert
148161
Assert.Contains("gate", text);
149-
Assert.Contains("Parameters (JSON Schema)", text);
150-
Assert.Contains(schemaJson, text);
162+
Assert.DoesNotContain("Parameters", text);
151163
}
152164

153165
[Fact]
@@ -187,26 +199,26 @@ public void BuildExecuteCodeDescription_WithAllowedDomains_IncludesNetworkSectio
187199
Assert.Contains("POST", text);
188200
}
189201

190-
private sealed class BooleanSchemaTool : AIFunction
202+
/// <summary>An <see cref="AIFunction"/> with a caller-supplied schema, or none at all.</summary>
203+
private sealed class StubTool : AIFunction
191204
{
192-
private readonly JsonDocument _schemaDocument;
205+
private readonly JsonElement? _schema;
193206

194-
public BooleanSchemaTool(string name, string description, string schemaJson)
207+
public StubTool(string name, string description, JsonElement? schema = null)
195208
{
196209
this.Name = name;
197210
this.Description = description;
198-
this._schemaDocument = JsonDocument.Parse(schemaJson);
211+
this._schema = schema;
199212
}
200213

201214
public override string Name { get; }
202215

203216
public override string Description { get; }
204217

205-
public override JsonElement JsonSchema => this._schemaDocument.RootElement;
218+
public override JsonElement JsonSchema => this._schema ?? base.JsonSchema;
206219

207220
protected override ValueTask<object?> InvokeCoreAsync(
208221
AIFunctionArguments arguments,
209-
System.Threading.CancellationToken cancellationToken) =>
210-
new((object?)null);
222+
CancellationToken cancellationToken) => new((object?)null);
211223
}
212224
}

‎dotnet/tests/Microsoft.Agents.AI.Hyperlight.UnitTests/ProvideAIContextTests.cs‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,45 @@ public async Task ProvideAIContextAsync_SandboxOptionMutation_ChangesSnapshotFin
192192
Assert.NotEqual(firstFingerprint, secondFingerprint);
193193
}
194194

195+
[Fact]
196+
public async Task ProvideAIContextAsync_WithParameterizedTool_CarriesHostToolSchemaAsync()
197+
{
198+
// Arrange
199+
var tool = AIFunctionFactory.Create((string query) => "ok", name: "lookup");
200+
using var provider = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
201+
{
202+
Tools = [tool],
203+
});
204+
205+
// Act
206+
var context = await provider.InvokingAsync(NewInvokingContext());
207+
var function = Assert.IsType<AIFunction>(context!.Tools!.First(), exactMatch: false);
208+
209+
// Assert — Description is what the model actually sees.
210+
Assert.Contains("query", function.Description);
211+
}
212+
213+
[Fact]
214+
public async Task ProvideAIContextAsync_WithParameterizedTool_KeepsCodeOnlyInputSchemaAsync()
215+
{
216+
// Arrange
217+
var tool = AIFunctionFactory.Create((string query) => "ok", name: "lookup");
218+
using var provider = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
219+
{
220+
Tools = [tool],
221+
});
222+
223+
// Act
224+
var context = await provider.InvokingAsync(NewInvokingContext());
225+
var function = Assert.IsType<AIFunction>(context!.Tools!.First(), exactMatch: false);
226+
var inputSchema = function.JsonSchema.GetRawText();
227+
228+
// Assert — host-tool schemas are documentation inside the description only; they
229+
// must never widen execute_code's own input contract.
230+
Assert.Contains("\"code\"", inputSchema);
231+
Assert.DoesNotContain("query", inputSchema);
232+
}
233+
195234
private static void AssertFingerprintsChanged(List<string> fingerprints)
196235
{
197236
for (var index = 1; index < fingerprints.Count; index++)

0 commit comments

Comments
 (0)