Adding Agent Instructions

In the previous chapter, you created your first basic agent and started a conversation with it.
Now, we'll take a step further by learning about system prompts and why they're essential for shaping your agent's behavior.

What Is a System Prompt?

A system prompt is a set of instructions you provide to the model when creating an agent.
Think of it as the personality and rulebook for your agent: it defines how the agent should respond, what tone it should use, and what limitations it should follow.

Without a system prompt, your agent may respond in a generic way. By adding clear instructions, you can tailor it to your needs.

System prompts:

• Ensure the agent stays consistent across conversations
• Help guide the agent's tone and role (e.g., friendly teacher, strict code reviewer, technical support bot)
• Reduce the risk of the agent giving irrelevant or off-topic answers
• Allow you to encode rules the agent must follow (e.g., "always answer in JSON")

Adding Instructions to Your Agent

When creating an agent, you can pass the instructions parameter in the PromptAgentDefinition.
Here's an example:

agent = project_client.agents.create_version(
    agent_name="hello-world-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions="You are a helpful support assistant for Microsoft Foundry. Always provide concise, step-by-step answers.",
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

Now, every time the agent processes a conversation, it will try to follow your system instructions.

Using an External Instructions File

Instead of hardcoding instructions in your Python script, it's often better to store them in a separate text file.
This makes them easier to edit and maintain.

First, create a file called instructions.txt in the workshop folder with the following content:

You are Contoso PizzaBot, an AI assistant that helps users order pizza.

Your primary role is to assist users in ordering pizza, checking menus, and tracking order status.

## guidelines
When interacting with users, follow these guidelines:
1. Be friendly, helpful, and concise in your responses.
1. When users want to order pizza, make sure to gather all necessary information (pizza type, options).
1. Contoso Pizza has stores in multiple locations. Before making an order, check to see if the user has specified the store to order from. 
   If they have not, assume they are ordering from the San Francisco, USA store.
1. Your tools will provide prices in USD. 
   When providing prices to the user, convert to the currency appropriate to the store the user is ordering from.
1. Your tools will provide pickup times in UTC. 
   When providing pickup times to the user, convert to the time zone appropriate to the store the user is ordering from.
1. When users ask about the menu, provide the available options clearly. List at most 5 menu entries at a time, and ask the user if they'd like to hear more.
1. If users ask about order status, help them check using their order ID.
1. If you're uncertain about any information, ask clarifying questions.
1. Always confirm orders before placing them to ensure accuracy.
1. Do not talk about anything else then Pizza
1. If you do not have a UserId and Name, always start with requesting that.

## Tools & Data Access
- Use the **Contoso Pizza Store Information Vector Store** to search get information about stores, like address and opening times.
    - **Tool:** `file_search`
    - Only return information found in the vector store or uploaded files.
    - If the information is ambiguous or not found, ask the user for clarification.

## Response
You will interact with users primarily through voice, so your responses should be natural, short and conversational. 
1. **Only use plain text**
2. No emoticons, No markup, No markdown, No html, only plain text.
3. Use short and conversational language.

When customers ask about how much pizza they need for a group, use the pizza calculator function to provide helpful recommendations based on the number of people and their appetite level.

Modifying the Agent Code

Now, update your agent.py to load these instructions:

Find the code

agent = project_client.agents.create_version(
    agent_name="hello-world-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
    ),
)

Replace this code with

agent = project_client.agents.create_version(
    agent_name="hello-world-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions=open("instructions.txt").read(),
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

By doing this:

• The agent will follow the PizzaBot instructions from your instructions.txt.

Run the Agent

Try out the Agent:

python agent.py

Try modifying your instructions.txt and rerun the agent. You'll see how the system instructions directly influence the personality and behavior of the agent.

You can now chat with your agent directly in the terminal. Type exit or quit to stop the conversation.

Recap

In this chapter, you have:

• Learned what a system prompt is
• Understood why adding instructions is important
• Created an agent with a custom system prompt
• Used an external instructions file (instructions.txt)

Final code sample

import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

load_dotenv()

## Configure Project Client
project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai_client = project_client.get_openai_client()


## Create a Foundry Agent
agent = project_client.agents.create_version(
    agent_name="hello-world-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions=open("instructions.txt").read(),
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")


## Create a conversation for the agent interaction
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")

## Chat with the agent

while True:
    # Get the user input
    user_input = input("You: ")

    if user_input.lower() in ["exit", "quit"]:
        print("Exiting the chat.")
        break

    # Get the agent response
    response = openai_client.responses.create(
        conversation=conversation.id,
        input=user_input,
        extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
    )

    # Print the agent response
    print(f"Assistant: {response.output_text}")