Skip to main content

How to See an Agent's Tool Calls in an AG-UI Stream

· 15 min read
Jagdish Kumawat
Founder @ Dewiride

When an agent answers over AG-UI, the text isn't the only thing in the stream: every function tool the agent calls shows up too, as four events, before the answer. This guide builds the smallest agent with one tool, a die roller, and reads each event from a real Microsoft Agent Framework stream, first with one call and then with two calls in the same turn.

The Four Tool Events​

A function tool is a method in your app that the AI model may ask to run. When an agent built with Microsoft Agent Framework is served over AG-UI with MapAGUIServer, the hosting package turns each tool call into protocol events. Microsoft's Backend Tool Rendering with AG-UI puts it this way: FunctionCallContent is emitted as AG-UI TOOL_CALL_START, TOOL_CALL_ARGS, and TOOL_CALL_END events. FunctionResultContent is emitted as a TOOL_CALL_RESULT event.

So between RUN_STARTED and the first TEXT_MESSAGE_START, a stream can tell you which tool the model picked, what arguments it chose, and what your code returned. The example is an agent that rolls dice for board game players: one tool, one number, nothing else in the way.

Prerequisites​

  • A model deployment in a Microsoft Foundry project, and the Foundry User role on the Foundry resource for your account: the app calls the model as you. Microsoft's Role-based access control for Microsoft Foundry lists the roles.
  • The .NET 10 SDK (dotnet --version prints a version that starts with 10.0) and the Azure CLI, signed in with az login.
  • VS Code with the REST Client extension, or Visual Studio, to send the requests in a .http file.

Step 1: Create the App and Add the Packages​

Open a terminal in the folder where you keep your projects: VS Code's terminal, or View > Terminal in Visual Studio. Create an empty ASP.NET Core app and move into it:

Terminal
dotnet new web -n DiceAgent
cd DiceAgent
Output (first command)
The template "ASP.NET Core Empty" was created successfully.

Processing post-creation actions...
Restoring /Users/you/source/DiceAgent/DiceAgent.csproj:
Restore succeeded.

Then add three packages:

Terminal
dotnet add package Microsoft.Agents.AI.Foundry --version 1.28.0-preview.261106.1
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --version 1.28.0-preview.261106.1
dotnet add package Azure.Identity --version 1.21.0
PackageWhat it gives the app
Microsoft.Agents.AI.FoundryAsAIAgent, which turns a model in a Foundry project into an agent
Microsoft.Agents.AI.Hosting.AGUI.AspNetCoreAddAGUIServer and MapAGUIServer, the AG-UI endpoint
Azure.IdentityAzureCliCredential, which signs the app in to Foundry with your Azure CLI sign-in

The Foundry and hosting packages of Microsoft Agent Framework 1.28.0 ship as previews, so each needs its exact --version. The project file now lists the three:

DiceAgent.csproj
<Project Sdk="Microsoft.NET.Sdk.Web">

<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Azure.Identity" Version="1.21.0" />
<PackageReference Include="Microsoft.Agents.AI.Foundry" Version="1.28.0-preview.261106.1" />
<PackageReference Include="Microsoft.Agents.AI.Hosting.AGUI.AspNetCore" Version="1.28.0-preview.261106.1" />
</ItemGroup>

</Project>

Open the project in your editor:

Select File > Open Folder and open the DiceAgent folder.

Step 2: Give an Agent One Tool and Serve It over AG-UI​

Replace everything in Program.cs with:

Program.cs
using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.Extensions.AI;

// Your Foundry project endpoint and the name of your model deployment.
const string ProjectEndpoint = "https://<your-foundry-resource>.services.ai.azure.com/api/projects/<your-project>";
const string ModelDeployment = "gpt-5.6-luna";

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUIServer();

// An agent with one tool: it can roll dice, which a language model can't do by itself.
AIAgent agent = new AIProjectClient(new Uri(ProjectEndpoint), new AzureCliCredential())
.AsAIAgent(
model: ModelDeployment,
instructions: "You roll dice for board game players. Use the roll_dice tool for every roll.",
tools: [AIFunctionFactory.Create(RollDice, name: "roll_dice")]);

var app = builder.Build();
app.MapAGUIServer("/", agent);
app.Run();

[Description("Rolls one die and returns the number it lands on.")]
static int RollDice([Description("How many sides the die has, such as 6 or 20.")] int sides) =>
Random.Shared.Next(1, sides + 1);

macOS-style code window titled Program.cs: an AIProjectClient with AzureCliCredential turned into an agent with AsAIAgent, the instructions You roll dice for board game players, a tools list with AIFunctionFactory.Create(RollDice, name: roll_dice), MapAGUIServer on the path slash, and a static RollDice method with Description attributes that returns Random.Shared.Next(1, sides + 1)

Put your own values in the two constants: the project endpoint from your Foundry project's Overview page, and the name of your model deployment. Then the pieces:

CodeWhat it does
AddAGUIServer() and MapAGUIServer("/", agent)Serve the agent over AG-UI at the app's root address, as in Microsoft's Getting Started with AG-UI
AIFunctionFactory.Create(RollDice, name: "roll_dice")Turns the RollDice method into a tool named roll_dice
[Description(...)]The text the model reads to decide when to call the tool and what to pass
RollDiceThe tool itself: a random whole number from 1 to sides

How to Add a Function Tool to a Microsoft Agent Framework Agent in C# explains AIFunctionFactory.Create and the Description attributes in detail. For this guide, what matters is that the model can't run RollDice itself: it can only ask for it, and every ask is visible in the stream.

Step 3: Give the App a Fixed Address​

The template picks a random port. Open Properties/launchSettings.json and change two lines of the http profile, so the requests below always find the app and Visual Studio doesn't open a browser on start:

Properties/launchSettings.json (the http profile)
"http": {
"commandName": "Project",
"dotnetRunMessages": true,
"launchBrowser": false,
"applicationUrl": "http://localhost:5320",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
}
},

Step 4: Run the App​

In VS Code's terminal, in the DiceAgent folder, run:

Terminal
dotnet run
Output
Using launch settings from /Users/you/source/DiceAgent/Properties/launchSettings.json...
Building...
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5320
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: /Users/you/source/DiceAgent

Leave the app running.

Step 5: Ask for One Roll​

Create a file named DiceAgent.http in the DiceAgent folder, with two requests (How to Send API Requests from a .http File in VS Code and Visual Studio covers the format):

DiceAgent.http
@baseUrl = http://localhost:5320

# Ask for one roll. The agent calls roll_dice once, then answers.
POST {{baseUrl}}/
Content-Type: application/json
Accept: text/event-stream

{
"threadId": "thread-1",
"runId": "run-1",
"messages": [
{
"id": "message-1",
"role": "user",
"content": "Roll a 20-sided die for me."
}
]
}

###

# Ask for two rolls at once. The agent calls roll_dice twice in the same turn.
POST {{baseUrl}}/
Content-Type: application/json
Accept: text/event-stream

{
"threadId": "thread-2",
"runId": "run-1",
"messages": [
{
"id": "message-1",
"role": "user",
"content": "Roll a 6-sided die and a 20-sided die."
}
]
}

Send the first request — Send Request above its POST line, in either editor. The response is a stream of events. Here it is, with each rawEvent shortened to {…} and most of the text left out:

Response (shortened)
HTTP/1.1 200 - OK
cache-control: no-cache,no-store
content-encoding: identity
content-type: text/event-stream
date: Fri, 20 Nov 2026 09:15:18 GMT
pragma: no-cache
server: Kestrel
transfer-encoding: chunked

data: {"type":"RUN_STARTED","threadId":"thread-1","runId":"run-1"}

data: {"type":"TOOL_CALL_START","toolCallId":"call_okOb9sGIDtVF9mo3fr2GNq9m","toolCallName":"roll_dice","rawEvent":{…}}

data: {"type":"TOOL_CALL_ARGS","toolCallId":"call_okOb9sGIDtVF9mo3fr2GNq9m","delta":"{\"sides\":20}","rawEvent":{…}}

data: {"type":"TOOL_CALL_END","toolCallId":"call_okOb9sGIDtVF9mo3fr2GNq9m","rawEvent":{…}}

data: {"type":"TOOL_CALL_RESULT","messageId":"call_okOb9sGIDtVF9mo3fr2GNq9m","toolCallId":"call_okOb9sGIDtVF9mo3fr2GNq9m","content":"7","rawEvent":{…}}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg_0e60d991…","role":"assistant","rawEvent":{…}}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_0e60d991…","delta":"You","rawEvent":{…}}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_0e60d991…","delta":" rolled","rawEvent":{…}}

… 4 more TEXT_MESSAGE_CONTENT events …

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg_0e60d991…","delta":".","rawEvent":{…}}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg_0e60d991…"}

data: {"type":"RUN_FINISHED","threadId":"thread-1","runId":"run-1","outcome":{"type":"success"},"usage":[{"model":"gpt-5.6-luna-2026-07-09","inputTokens":225,"outputTokens":31,"totalTokens":256,"reasoningTokens":0,"cachedInputTokens":0}]}

Put together, the text reads You rolled a **7**.: the 7 from the tool. The four tool events, field by field:

EventFieldsWhat they say in this run
TOOL_CALL_STARTtoolCallId, toolCallNameThe model asked for roll_dice. The ID, call_okOb…, ties the next three events to this call
TOOL_CALL_ARGStoolCallId, deltaThe arguments the model chose, as JSON text: {"sides":20}
TOOL_CALL_ENDtoolCallIdThe arguments are complete
TOOL_CALL_RESULTmessageId, toolCallId, contentWhat RollDice returned, as JSON text: "7". Its messageId is the same as the toolCallId

Two things happen between these events that the stream doesn't show. After TOOL_CALL_END, your server ran RollDice. After TOOL_CALL_RESULT, the agent called the model a second time, now with the result. That loop is FunctionInvokingChatClient: By default, ChatClientAgent wraps the provided chat client with function-calling support, says Microsoft's agent pipeline architecture, and that client's reference explains that it might perform that invocation and send the results back to the inner client in a new request. Only then did the answer start.

Step 6: Ask for Two Rolls in One Turn​

Send the second request. This time the model asked for both rolls at once. The stream, from RUN_STARTED to the start of the answer:

Response (from RUN_STARTED to the answer)
data: {"type":"RUN_STARTED","threadId":"thread-2","runId":"run-1"}

data: {"type":"TOOL_CALL_START","toolCallId":"call_4s1fDU1rc9VVbzyK8kfvP5nD","toolCallName":"roll_dice","rawEvent":{…}}

data: {"type":"TOOL_CALL_ARGS","toolCallId":"call_4s1fDU1rc9VVbzyK8kfvP5nD","delta":"{\"sides\":6}","rawEvent":{…}}

data: {"type":"TOOL_CALL_END","toolCallId":"call_4s1fDU1rc9VVbzyK8kfvP5nD","rawEvent":{…}}

data: {"type":"TOOL_CALL_START","toolCallId":"call_GwK4D3OjO5vsz9K4n1pobiqf","toolCallName":"roll_dice","rawEvent":{…}}

data: {"type":"TOOL_CALL_ARGS","toolCallId":"call_GwK4D3OjO5vsz9K4n1pobiqf","delta":"{\"sides\":20}","rawEvent":{…}}

data: {"type":"TOOL_CALL_END","toolCallId":"call_GwK4D3OjO5vsz9K4n1pobiqf","rawEvent":{…}}

data: {"type":"TOOL_CALL_RESULT","messageId":"call_4s1fDU1rc9VVbzyK8kfvP5nD","toolCallId":"call_4s1fDU1rc9VVbzyK8kfvP5nD","content":"2","rawEvent":{…}}

data: {"type":"TOOL_CALL_RESULT","messageId":"call_GwK4D3OjO5vsz9K4n1pobiqf","toolCallId":"call_GwK4D3OjO5vsz9K4n1pobiqf","content":"8","rawEvent":{…}}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg_0e4d9f69…","role":"assistant","rawEvent":{…}}

Both calls come first, each as START, ARGS and END with its own toolCallId. Then both results, in the same order. Match a result to its call by toolCallId, never by position: call_4s1f… asked for 6 sides and got 2, call_GwK4… asked for 20 and got 8. The answer that followed:

The answer, put together
6-sided die: **2**
20-sided die: **8**

The two RollDice calls ran one after the other. The reference for FunctionInvokingChatClient.AllowConcurrentInvocation says: By default, such function calls are processed serially.

Step 7: Watch the Same Events from a Terminal​

You can send the same question from a terminal, without the .http file:

Terminal
curl -N http://localhost:5320/ \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{"threadId":"thread-3","runId":"run-1","messages":[{"id":"message-1","role":"user","content":"Roll a 20-sided die for me."}]}'

-N turns off curl's output buffer, so each event prints as it arrives.

Both printed the same sequence as Step 5: RUN_STARTED, the four tool events, the text events and RUN_FINISHED, with a different roll each time.

What the rawEvent Carries​

Each tool event also has a rawEvent: the Agent Framework update it came from. For the call in Step 5, the rawEvent of TOOL_CALL_START held a functionCall with the name, the arguments and the call ID, plus Foundry's responseId, conversationId and the exact modelId. The rawEvent of TOOL_CALL_RESULT held the functionResult, 7.

That is useful for debugging, and more than a browser needs. Microsoft's documentation adds that tool results are model-facing values that AG-UI also exposes to the client: whatever a tool returns to the model, an AG-UI client receives too. If a browser talks to your agent through your own server, that server can drop the tool events and every rawEvent before they leave, as How to Filter AG-UI Events Before They Reach the Browser shows.

Common Mistakes​

MistakeWhat happensDo this instead
Matching results to calls by their orderWith several calls, the wrong result can end up with the wrong callMatch by toolCallId
Reading the arguments from the TOOL_CALL_START eventTOOL_CALL_START names the tool but carries no argumentsRead delta from TOOL_CALL_ARGS
Treating content in TOOL_CALL_RESULT as a number or an objectIt is JSON text: "7", not 7Parse it as JSON
Passing a browser's stream straight from the agentThe browser receives every tool result and the model provider's data in rawEventFilter the events in your own server first

Troubleshooting​

SymptomLikely causeFix
The stream has no TOOL_CALL_STARTThe model answered without the toolMake the instructions and the [Description] text say when to use it
curl: (7) Failed to connect to localhost port 5320 … Couldn't connect to serverThe app isn't running, or runs on another portStart it, and check applicationUrl in launchSettings.json
The only event is RUN_ERROR with An error occurred while streaming the agent response., and the app's terminal shows nothingThe model call failed. I got this with a deployment name that doesn't existCheck the two constants in Program.cs, and that az login is done

FAQ​

Do the arguments always arrive in one TOOL_CALL_ARGS event?​

In these runs, each call's arguments came in one event. The Python section of Microsoft's Backend Tool Rendering with AG-UI describes TOOL_CALL_ARGS as Tool arguments (may stream in chunks), so a client should join the delta values of one toolCallId until its TOOL_CALL_END.

Does a client have to do anything with the tool events?​

No. The tool ran on the server, and the answer arrives as text either way. A client can use the events to show progress, such as Rolling a die…, or ignore them.

Do I need a session store for this?​

No. Without one, each request gets a new conversation, which is all these single questions need. How to Keep Conversation History in a Microsoft Agent Framework AG-UI Server adds one.

Conclusion​

An AG-UI stream from a Microsoft Agent Framework agent shows every backend tool call before the answer: TOOL_CALL_START names the tool, TOOL_CALL_ARGS carries the model's arguments, TOOL_CALL_END closes them, and TOOL_CALL_RESULT carries what your code returned, all tied together by one toolCallId. When the model asks for several tools in one turn, all the calls come first and the results after them. Read the events from a .http file or a terminal to debug, and decide in your own server which of them a browser may see.

Additional Resources​