.NET: [Issue]: Function invocation middleware receives tool results as JsonElement, which the docs do not mention

未关闭 适合新手
  • 哪里不对？
#9,918 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

@LHB0317 已经在做这个了。

开始于 2026年11月2日。

评估

难度
1/5
预计耗时
1 小时以内
新手友好度
72/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
csharp
领域
documentation

调研方向

缺口在于 FunctionInvocationDelegatingAgentBuilderExtensions.Use 的 XML 文档注释，它只说明委托返回一个表示函数调用结果的任务。阅读该注释和 FunctionInvocationContext 类型，确认不存在 Result 属性，然后添加一句话，说明延续会产生一个 JsonElement，其中包含序列化后的工具结果，并且返回可序列化的值会替换模型看到的内容。当文档注释说明运行时类型，且生成的 API 文档体现了这一点时，即视为完成。

由索引模型根据 Issue 内容生成。

描述

.NET triage
Category

Documentation

Problem

AIAgentBuilder.Use(...) function-invocation middleware receives every tool result as a JsonElement, whatever the tool declares, and no documentation says so. The only statement is on FunctionInvocationDelegatingAgentBuilderExtensions.Use: the delegate "returns a task representing the result of the function invocation". The runtime type is not mentioned anywhere, so the natural implementation of a middleware that inspects or rewrites a result silently does nothing.

Evidence

Measured with Microsoft.Agents.AI.Harness 1.27.0, one tool per shape, reading result.GetType().Name inside the middleware:

tool returns middleware receives
string JsonElement containing "a plain string"
int JsonElement containing 42
a record Poco(string Name, int Value) JsonElement containing {"name":"x","value":1}
int[] JsonElement containing [1,2,3]

The guard a developer writes first therefore never fires:

.Use((AIAgent _, FunctionInvocationContext ctx,
       Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
       CancellationToken ct) =>
{
    var result = await next(ctx, ct);
    if (result is not string text || text.Length <= cap) return result;  // never truncates
    return Truncate(text);
})

Rewriting does work once the type is known: returning a string from the middleware reached the provider as 22 characters instead of 868,893, on both the streaming and non-streaming paths. FunctionInvocationContext also exposes no Result property, so the value exists only as the continuation's return value.

The underlying behaviour looks deliberate, serialising once instead of deserialising and re-serialising, so this is reported as a documentation gap rather than a defect in the pipeline.

Desired Outcome

The Use documentation should state what the continuation returns: a JsonElement holding the serialized tool result, and that returning a serializable value from the middleware replaces what the model sees. One sentence is enough; a typed helper such as ctx.GetResult<T>() would be nicer but is not what this issue asks for.

Language

.NET

Acknowledgements
  • I searched existing issues and did not find a duplicate.
  • I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

AI assistance. The analysis, the probe program and this report were prepared with an AI coding assistant. The type table above was produced by running the probe against the published package; nothing is inferred. API names and versions were checked against the package and the repository's main branch.

Verification. Measured locally before filing:

  • OS: Windows 10.0.26300.9711
  • SDK: .NET SDK 10.0.402, runtime 10.0.9
  • Package: Microsoft.Agents.AI.Harness 1.27.0
  • How: dotnet run on a console project that registers one tool per shape, runs a scripted IChatClient, and prints the runtime type of the middleware's continuation result
  • Output: JsonElement for all four shapes, as tabulated above
主要语言
Python
星标
14.5k
派生
2.6k
平均合并
2 天 13 小时
30 天内合并 PR
343

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

microsoft/agent-framework 的其他 Issue

查看 microsoft/agent-framework 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。