Skip to main content

Instructions, Messages and Run Options

An agent's answer depends on three things you control: the instructions it follows in every run, the messages you send it in a run, and the run options that change a single run. This tutorial uses all three on one small agent, and the token counts show what each one sends to the model.

Three Places to Shape an Answer​

Instructions belong to the agent. You give them once, when you create it, and they go with every run. Microsoft's reference describes them as the system instructions that guide the agent's behavior during conversations, which are typically provided to the AI model as system messages. Put in them what the agent is and the rules it always follows.

Messages belong to a run. Microsoft's guide to running agents says Callers can choose to supply zero, one, or many input messages. A string, as in the previous tutorials, becomes one message: The provided text will be wrapped in a ChatMessage with the User role. For more than one, you build the ChatMessage objects yourself, each with a role:

RoleWho says it
ChatRole.UserThe person using the agent
ChatRole.AssistantThe agent, earlier in the conversation
ChatRole.SystemYou, the developer, with instructions

Microsoft's reference adds a warning about the last one: System-role messages must be developer-controlled and should never contain end-user input.

Run options also belong to a run. An agent created from a model, a ChatClientAgent, takes a ChatClientAgentRunOptions with ChatOptions in it. The guide explains what happens to them: they are merged with any agent level options before being passed to the IChatClient. So a run can add to what the agent already has, for that run only.

The Example​

A console app called WordCoach has an agent that explains English words to learners, with three rules: simple words, one example sentence, and Keep practising! at the end of every answer. That last rule is easy to spot, which makes it easy to see when the agent's instructions apply. The app runs the agent four times: with one message, with several messages, with run options, and once more without them.

Prerequisites​

  • The agent from Streaming, and the setup it uses: the .NET 10 SDK, the Azure CLI signed in, a Foundry project endpoint, a model deployment and the Foundry User role.

Step 1: Create a Console App​

In a terminal, in the folder where you keep your projects, run:

Terminal
dotnet new console -n WordCoach
cd WordCoach
dotnet add package Microsoft.Agents.AI.Foundry --version 1.28.0-preview.261106.1
dotnet add package Azure.Identity --version 1.21.0
Output (the important lines)
The template "Console App" was created successfully.

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

info : PackageReference for package 'Microsoft.Agents.AI.Foundry' version '1.28.0-preview.261106.1' added to file '/Users/you/source/WordCoach/WordCoach.csproj'.
log : Restored /Users/you/source/WordCoach/WordCoach.csproj (in 1.75 sec).
info : PackageReference for package 'Azure.Identity' version '1.21.0' added to file '/Users/you/source/WordCoach/WordCoach.csproj'.
log : Restored /Users/you/source/WordCoach/WordCoach.csproj (in 1.29 sec).

The same two packages as in the previous tutorials. Open the WordCoach folder in VS Code, or WordCoach.csproj in Visual Studio.

Step 2: Write the Instructions, and Send One Message​

Replace everything in Program.cs:

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

// 1. Instructions: who the agent is, and the rules it follows in every run.
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 explain English words to people who are learning English.
Use simple words, and give one example sentence.
End every answer with this line: Keep practising!
""",
name: "WordCoach");

// 2. One message: a string becomes a single message from the user.
Print("One message", await agent.RunAsync("What does 'reluctant' mean?"));

static void Print(string title, AgentResponse response)
{
Console.WriteLine($"--- {title} ({response.Usage?.InputTokenCount} tokens in) ---");
Console.WriteLine(response.Text);
Console.WriteLine();
}
  • instructions holds the agent's three rules, in a raw string literal ("""), which keeps the lines readable. Short, direct sentences work best: the model reads them before every run.
  • using Microsoft.Extensions.AI brings in ChatMessage, ChatRole and ChatOptions, which the next steps use. Agent Framework uses these types from Microsoft.Extensions.AI for its messages.
  • Print shows each answer under a title, with the number of input tokens, the tokens that went to the model. It's the easiest way to see how much each step sends.

Use your own project endpoint and model deployment. Run it:

In the terminal, in the WordCoach folder, run:

Terminal
dotnet run
Output
--- One message (50 tokens in) ---
**Reluctant** means not wanting to do something.

**Example:** She was reluctant to speak in front of the class.

Keep practising!

The agent followed all three rules: simple words, one example sentence, and the last line. The 50 input tokens are the instructions and the question together. The ** around some words is Markdown that the model chose, which a chat page would show in bold.

Step 3: Send Several Messages​

One message asks a question. Several messages can also show the agent what a good answer looks like: a short example exchange, before the real question. Add this after the first run, before static void Print:

Program.cs (add before static void Print)
// 3. Several messages: an example exchange to copy, then the real question.
List<ChatMessage> messages =
[
new(ChatRole.User, "What does 'eager' mean?"),
new(ChatRole.Assistant, """
eager (adjective): wanting very much to do something.
Example: She was eager to start her new job.
Keep practising!
"""),
new(ChatRole.User, "What does 'reluctant' mean?"),
];
Print("Several messages", await agent.RunAsync(messages));
  • The first two messages are an exchange that never happened: a question from the user, and an answer from the agent in the exact format you want, with the word type in brackets and no bold.
  • The last message is the real question.
  • RunAsync(messages) sends all three. The model reads them as the conversation so far, and answers the last one.

Run it. The first answer is the same kind as before, and then:

Output (the new part)
--- Several messages (95 tokens in) ---
reluctant (adjective): not wanting to do something; unsure or unwilling.

Example: He was reluctant to speak in front of the class.

Keep practising!

The answer copied the example: the word, its type in brackets, a plain definition and no bold, which no instruction asked for. Showing one answer is often clearer to a model than describing it. It isn't free: the example took the input from 50 tokens to 95, and it's sent with every run that includes it.

Step 4: Change One Run with Run Options​

Now ask for one answer in Spanish, without changing the agent. Add:

Program.cs (add before static void Print)
// 4. Run options: extra instructions for this one run only.
ChatClientAgentRunOptions inSpanish = new(new ChatOptions { Instructions = "Answer in Spanish." });
Print("One run in Spanish", await agent.RunAsync("What does 'reluctant' mean?", options: inSpanish));

// 5. The next run is back to normal: run options don't stay with the agent.
Print("The next run", await agent.RunAsync("What does 'curious' mean?"));
  • ChatOptions holds settings for a model call. Here it has one: Instructions, an extra instruction for this run.
  • ChatClientAgentRunOptions wraps those settings for a ChatClientAgent, the kind of agent AsAIAgent creates.
  • options: inSpanish passes them to this one RunAsync. The last run has no options.

Run it:

Output (the new part)
--- One run in Spanish (54 tokens in) ---
**Reluctant** significa **reacio**, **poco dispuesto** o **que no quiere hacer algo**.

**Ejemplo:** *She was reluctant to speak in public.*
**Traducción:** Ella era reacia a hablar en público.

Keep practising!

--- The next run (49 tokens in) ---
**Curious** means wanting to know or learn something.

**Example:** I am curious about how airplanes fly.

Keep practising!

macOS-style terminal window titled Terminal — WordCoach showing four answers: One message, 50 tokens in, explaining reluctant with an example and Keep practising!; Several messages, 95 tokens in, in the format of the example; One run in Spanish, 54 tokens in, explaining reluctant in Spanish and still ending with Keep practising!; and The next run, 49 tokens in, explaining curious in English

Two things show how run options work:

  • They're added to the agent's instructions, not swapped in. The Spanish answer still ends with Keep practising!, a rule from the agent's own instructions. And the token counts agree: the same question took 50 tokens without options and 54 with them, four more for Answer in Spanish. If the run's instructions had replaced the agent's, the count would have dropped, not grown.
  • They last for one run. The next run, with no options, is back in English. Nothing about the agent changed.

That's the guide's merged with any agent level options in practice. A second run of the app gave the same token counts: 50, 95, 54 and 49.

The Complete File​

macOS-style code window titled Program.cs showing the WordCoach agent with three instructions in a raw string literal, a run with one string message, a run with a list of ChatMessage objects that holds an example exchange from ChatRole.User and ChatRole.Assistant before the real question, a run with ChatClientAgentRunOptions whose ChatOptions add the instruction Answer in Spanish, a last run without options, and the Print method that writes each answer with its input token count

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

// 1. Instructions: who the agent is, and the rules it follows in every run.
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 explain English words to people who are learning English.
Use simple words, and give one example sentence.
End every answer with this line: Keep practising!
""",
name: "WordCoach");

// 2. One message: a string becomes a single message from the user.
Print("One message", await agent.RunAsync("What does 'reluctant' mean?"));

// 3. Several messages: an example exchange to copy, then the real question.
List<ChatMessage> messages =
[
new(ChatRole.User, "What does 'eager' mean?"),
new(ChatRole.Assistant, """
eager (adjective): wanting very much to do something.
Example: She was eager to start her new job.
Keep practising!
"""),
new(ChatRole.User, "What does 'reluctant' mean?"),
];
Print("Several messages", await agent.RunAsync(messages));

// 4. Run options: extra instructions for this one run only.
ChatClientAgentRunOptions inSpanish = new(new ChatOptions { Instructions = "Answer in Spanish." });
Print("One run in Spanish", await agent.RunAsync("What does 'reluctant' mean?", options: inSpanish));

// 5. The next run is back to normal: run options don't stay with the agent.
Print("The next run", await agent.RunAsync("What does 'curious' mean?"));

static void Print(string title, AgentResponse response)
{
Console.WriteLine($"--- {title} ({response.Usage?.InputTokenCount} tokens in) ---");
Console.WriteLine(response.Text);
Console.WriteLine();
}

What You Can Do Now​

  • Give an agent instructions that apply to every run, and check that it follows them.
  • Send one message as a string, or several as ChatMessage objects with roles.
  • Show an agent an example answer to copy, and weigh it against the tokens it adds to every run.
  • Add settings to a single run with ChatClientAgentRunOptions, knowing they're merged with the agent's own and last for that run only.

The four runs sent 248 input tokens in total, about $0.00005 at gpt-5.6-luna's price of $0.20 per million input tokens. The answers, and the model's reasoning before it writes, are output tokens at $1.20 per million on top.

Common Mistakes​

MistakeWhat happensDo this instead
Putting the person's text in a ChatRole.System messageUser input gets the weight of your own instructions, and can change the rulesPut user input only in ChatRole.User messages
Repeating the agent's instructions in every run's optionsEvery run sends them twiceKeep lasting rules in the agent's instructions, and use run options for exceptions
Expecting run options to change the agentThe next run is back to normalCreate another agent when the change should last
Long example exchanges in every runEvery run pays for them in input tokensKeep examples short, and only where the format matters

Troubleshooting​

SymptomLikely causeFix
error CS0246: The type or namespace name 'ChatMessage' could not be found (are you missing a using directive or an assembly reference?), and the same for ChatOptionsusing Microsoft.Extensions.AI; is missingAdd it at the top of Program.cs
The agent ignores a rule in its instructionsThe rule is vague, or another message contradicts itMake the rule short and direct, and check your example messages
A run's options seem to do nothingThe options were created but not passedPass them as options: to that RunAsync

Frequently Asked Questions​

Instructions or a system message: which should I use?​

For the agent's own rules, instructions. They're set once, in one place, and go with every run. A ChatRole.System message in a run's messages is for the rare case where you, not the user, need to add instructions for that run only, and never with text that came from the user.

Do the example messages become part of the agent?​

No. They're part of the run you send them with. A run without them gets the agent's usual answers, as the last run in this tutorial shows.

What else can run options change?​

Anything ChatOptions holds that the model supports, such as the most tokens an answer may use, with MaxOutputTokens. Microsoft's guide also shows a run that adds a tool, with ChatOptions.Tools. Tools have their own tutorial in this track.

Why did the answers use Markdown?​

Nothing in the instructions said not to. The agent in the IT Service Desk series, written for a chat page, has a rule for it: Write plain text. Do not use Markdown formatting such as ** or #.

Conclusion​

Instructions, messages and run options shape an agent's answers at three levels. Instructions go with every run, and set who the agent is and its rules. Messages carry what one run sends: one question, or an example exchange to copy before the question. Run options add settings to a single run: ChatClientAgentRunOptions with ChatOptions, merged with the agent's own, and gone by the next run.

Next: Sessions — keep a conversation going across several runs, so the agent remembers what was said.

Additional Resources​