Skip to main content

How to Add Instructions to One Microsoft Agent Framework Agent Run in C#

· 6 min read
Jagdish Kumawat
Founder @ Dewiride

An agent's instructions go with every run. Sometimes one run needs something extra, such as a different tone or language, without changing the agent. ChatClientAgentRunOptions does that: extra instructions for one run, on top of the agent's own.

Syntax​

Syntax
ChatClientAgentRunOptions <options> = new(new ChatOptions { Instructions = "<extra instructions>" });

AgentResponse <response> = await <agent>.RunAsync(<message>, options: <options>);
PartWhat it is
ChatOptionsSettings for one call to the model, from Microsoft.Extensions.AI
Instructions = "<extra instructions>"The instructions to add for this run
ChatClientAgentRunOptionsRun options for a ChatClientAgent, the kind of agent AsAIAgent creates. Its constructor takes the ChatOptions
options: <options>Passes the options to this one run

Microsoft's guide to running agents says these ChatOptions are merged with any agent level options before being passed to the IChatClient. The example shows what that means for instructions.

The Example​

An agent answers questions about the planets in one sentence. It's asked How big is Jupiter? three times: normally, with the extra instruction Talk like a pirate., and normally again. Each answer shows the input tokens it took.

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.
  • The .NET 10 SDK (dotnet --version prints a version that starts with 10.0) and the Azure CLI, signed in with az login.

Step 1: Create a Console App​

Terminal
dotnet new console -n PlanetFacts
cd PlanetFacts
dotnet add package Microsoft.Agents.AI.Foundry --version 1.28.0-preview.261106.1
dotnet add package Azure.Identity --version 1.21.0

Microsoft.Agents.AI.Foundry turns a model in a Foundry project into an agent, and brings in Agent Framework and Microsoft.Extensions.AI. Azure.Identity signs the app in with your Azure CLI sign-in. Open the folder in VS Code, or PlanetFacts.csproj in Visual Studio.

Step 2: Run with and without Extra Instructions​

Replace everything in Program.cs:

Program.cs
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent agent = new AIProjectClient(
new Uri("https://foundry-devblogs-exp.services.ai.azure.com/api/projects/proj-devblogs-exp"),
new AzureCliCredential())
.AsAIAgent(model: "gpt-5.6-luna", instructions: "You answer questions about the planets in one sentence.", name: "PlanetFacts");

// 1. A normal run: only the agent's own instructions.
Print("A normal run", await agent.RunAsync("How big is Jupiter?"));

// 2. Extra instructions for this one run, on top of the agent's own.
ChatClientAgentRunOptions likeAPirate = new(new ChatOptions { Instructions = "Talk like a pirate." });
Print("With extra instructions", await agent.RunAsync("How big is Jupiter?", options: likeAPirate));

// 3. The next run is normal again: run options belong to one run.
Print("The next run", await agent.RunAsync("How big is Jupiter?"));

static void Print(string title, AgentResponse response)
{
Console.WriteLine($"--- {title} ({response.Usage?.InputTokenCount} tokens in) ---");
Console.WriteLine(response.Text);
Console.WriteLine();
}
  • The agent's instructions ask for one sentence. That rule is how you'll see whether they still apply in the second run.
  • likeAPirate holds the extra instruction, and only the second RunAsync gets it.
  • Print shows each answer with its input tokens, the tokens that went to the model.

Use your own Foundry project endpoint and model deployment.

Step 3: Run It​

Run dotnet run in VS Code's terminal, or press Ctrl+F5 in Visual Studio:

Output
--- A normal run (25 tokens in) ---
Jupiter is the largest planet, with a diameter of about 139,820 kilometers (86,881 miles).

--- With extra instructions (30 tokens in) ---
Jupiter be the largest planet, with a diameter of about 86,881 miles (139,820 kilometers), arrr!

--- The next run (25 tokens in) ---
Jupiter is the largest planet, with a diameter of about 139,820 kilometers (86,881 miles).

macOS-style terminal window titled Terminal — PlanetFacts showing three answers to How big is Jupiter?: a normal run with 25 tokens in, a run with extra instructions with 30 tokens in that answers like a pirate in one sentence ending with arrr!, and the next run with 25 tokens in that answers normally again

  • The extra instruction worked: the second answer talks like a pirate.
  • The agent's own instruction still applied: it's still one sentence.
  • The tokens show they were added, not swapped in: 25 tokens without the extra instruction, 30 with it. If the run's instructions had replaced the agent's, the count would have gone down.
  • The next run was normal again, at 25 tokens: the options belonged to that one run.

A second run of the app gave the same counts, 25, 30 and 25, with a different pirate sentence.

The Complete File​

macOS-style code window titled Program.cs showing the PlanetFacts agent with the instructions You answer questions about the planets in one sentence., a normal RunAsync, a RunAsync with options set to a ChatClientAgentRunOptions whose ChatOptions add the instruction Talk like a pirate., a last normal RunAsync, and the Print method that writes each answer with its input token count

Program.cs from Step 2 is the whole program.

Common Mistakes​

MistakeWhat happensDo this instead
Creating the options but not passing themThe run has only the agent's instructionsPass them as options: to that RunAsync
Repeating the agent's instructions in the run'sThey're sent twice, and cost twicePut only the extra instructions in the run's options
Using run options for a lasting changeEvery run has to repeat themChange the agent's own instructions, or create another agent
Putting a user's text in ChatOptions.InstructionsUser input gets the weight of your own instructionsKeep instructions in your own words, and user text in messages

FAQ​

Do run options work with every agent?​

They work with agents created from a model, such as AsAIAgent creates. Microsoft's migration guide puts it this way: Not all AIAgents support ChatClientAgentRunOptions. ChatClientAgent is provided to build agents based on underlying inference services, and therefore supports inference options like MaxOutputTokens.

What else can a run change?​

Anything ChatOptions holds that the model supports, such as MaxOutputTokens. Microsoft's guide to running agents also shows a run that adds a tool with ChatOptions.Tools.

Conclusion​

To give one run extra instructions, create ChatClientAgentRunOptions with new ChatOptions { Instructions = "…" } and pass it to RunAsync with options:. Agent Framework adds them to the agent's own instructions, as the token counts show, and the next run without options is back to normal.

Additional Resources​