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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#9,918 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
1/5
Tiempo estimado
Menos de una hora
Aptitud para principiantes
72/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
csharp
Área
documentation

Línea de trabajo

El vacío está en el comentario de documentación XML de FunctionInvocationDelegatingAgentBuilderExtensions.Use, que solo indica que el delegado devuelve una tarea que representa el resultado de la invocación de la función. Lee ese comentario y el tipo FunctionInvocationContext para confirmar que no existe una propiedad Result. Después añade una frase que diga que la continuación produce un JsonElement con el resultado serializado de la herramienta y que devolver un valor serializable reemplaza lo que ve el modelo. Está terminado cuando el comentario de documentación indica el tipo en tiempo de ejecución y la documentación de API generada lo refleja.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

.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
Lenguaje dominante
Python
Estrellas
14.3k
Forks
2.5k
Merge medio
2 d 16 h
PR fusionados (30 d)
342

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de microsoft/agent-framework

Todos los issues de microsoft/agent-framework

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.