How to Build an AI Agent in Microsoft Foundry (Portal and Python) for AI-901

Agents are the headline feature of modern AI platforms, and AI-901 includes two agent skills: create and test a single-agent solution in the Foundry portal, and create a lightweight client application for an agent. This lesson covers both.

What is an AI agent?

An agent is an AI application that can reason about a goal and take actions to reach it. A basic agent has three parts:

1. Model: the generative model that does the reasoning (for example a GPT model you deployed).
2. Instructions: the system prompt that defines its role, goals, rules and tone.
3. Tools: capabilities that let it fetch knowledge or take actions.

Agents can also keep conversation state across turns and may include memory and guardrails. In Microsoft Foundry, the Foundry Agent Service hosts agents, runs their tools and stores their conversations, so you don't have to build that plumbing yourself.

Common agent tools

Exam tip: knowledge from documents → file search; calculations or data analysis → code interpreter; taking an action in your system → function / OpenAPI tool; up-to-date public information → web search.

Build an agent in the Foundry portal

1. In your Foundry project, open Agents (in the Build area) and choose Create agent.
2. Give it a name, such as travel-agent.
3. Choose the model deployment it should use.
4. Write the instructions, for example:

You are a travel assistant for Contoso Travel.
Help customers with questions about our tours using the uploaded brochures.
If the brochures don't contain the answer, say so and suggest contacting support.
Be friendly and keep answers under 120 words.

5. Add tools. For this example, add file search and upload a few brochure PDFs.
6. Test in the agent playground: ask about a tour in the brochure, then something unrelated, then a follow-up question. Check that answers are grounded and cite the documents.
7. Iterate on the instructions and tools until the behaviour is right. Agents are versioned, so each change can be saved as a new version.

Call the agent from a Python client

Install the SDK:

pip install "azure-ai-projects>=2.0" azure-identity

Create (or update) the agent in code and chat with it:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

project = AIProjectClient(
    endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    credential=DefaultAzureCredential(),
)

# Create the agent, or a new version of it if it already exists
agent = project.agents.create_version(
    agent_name="travel-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a friendly travel assistant for Contoso Travel.",
    ),
)
print(f"Agent {agent.name}, version {agent.version}")

# An OpenAI client bound to the agent
openai = project.get_openai_client(agent_name="travel-agent")

# A conversation keeps the chat history for multi-turn chat
conversation = openai.conversations.create()

response = openai.responses.create(conversation=conversation.id, input="Which tours do you offer in Turkey?")
print(response.output_text)

response = openai.responses.create(conversation=conversation.id, input="How long is the second one?")
print(response.output_text)

What's happening:

• create_version defines the agent: model + instructions (tools can be added to the definition too). If you already built the agent in the portal, you can skip this and just use its name.
• get_openai_client(agent_name=...) gives a client whose requests go to that agent.
• conversations.create() starts a conversation (a thread). Each responses.create with the same conversation ID adds a turn, so the follow-up "the second one" makes sense.
• output_text is the agent's answer, produced after it has run any tools it decided to use.

Make it interactive

while (text := input("You: ")) != "quit":
    reply = openai.responses.create(conversation=conversation.id, input=text)
    print("Agent:", reply.output_text)

Agent vs plain chat app

Responsible agents

Agents act, so their mistakes have consequences. Good practice:

• Give agents the least privilege they need, and use a separate identity for each agent
• Require human approval for high-impact actions such as payments
• Keep content filters and prompt shields on, especially when agents read external content that might contain hidden instructions (indirect prompt injection)
• Evaluate and monitor agent runs, including which tools were called

Key takeaways

• Agent = model + instructions + tools (+ conversation state).
• Match tools to needs: file search, code interpreter, web search, functions/OpenAPI, MCP.
• In the portal: create agent → choose model → write instructions → add tools → test → iterate.
• In code: agents.create_version(...), get_openai_client(agent_name=...), conversations.create(), responses.create(conversation=..., input=...).

Next lesson: text analysis with Azure Language.