Session 7: Building Your First Agent

What makes an agent (model + instructions + tools + knowledge), how to create and test a single-agent solution in the Foundry portal, which tools to add (file search, code interpreter, custom functions), how to call the agent from a lightweight Python client, and how agents differ from chat apps.

Anatomy of an agent

                 ┌──────────────── Agent ────────────────┐
User goal ─────► │  Model        (reasoning engine)       │
                 │  Instructions (role, rules, steps)     │ ──► Answer
                 │  Tools        (file search, code,      │     + actions taken
                 │                functions, APIs, web)   │
                 │  Knowledge    (uploaded files, indexes)│
                 └────────────────────────────────────────┘
                     ▲ conversation (thread) keeps state

The Foundry Agent Service hosts the agent: it runs the model–tool loop for you, stores conversations and applies content safety.

Create and test an agent in the portal

1. In your Foundry project, open Agents → Create agent (or + New agent).
2. Give it a name (for example support-agent) and choose a model deployment.
3. Write the instructions:

You are the customer support agent for Contoso Bank.
- Answer questions about fees, cards and account rules using ONLY the attached policy document.
- Quote the relevant section name in your answer.
- If the policy does not cover the question, say so and offer to raise a ticket.
- Never ask for OTPs, PINs or full card numbers.

4. Add tools / knowledge: - File search: upload contoso-bank-policy.pdf. Foundry chunks it, creates embeddings and stores them in a vector store that the agent searches. - Code interpreter: lets the agent run Python, for example to calculate EMI or summarise a CSV of transactions. - Function / OpenAPI / MCP tools: describe your own operations (for example create_ticket(customer_id, issue)) so the agent can request them.
5. Select Try in playground and test: an answerable question, a calculation, an out-of-scope question and a prompt-injection attempt. Open the run details / trace to see which tool the agent used and why.
6. Save. Each save creates an agent version, so you can change instructions safely and roll back.

🎯 Exam tip. File search = answer from your documents. Code interpreter = run code / do maths / analyse files. Function calling = the model asks your code to perform an action, and your code returns the result.

A lightweight Python client for the agent

Install pip install "azure-ai-projects>=2.3.0" azure-identity and sign in with az login.

Create (or update) the agent in code

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()
project = AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], credential=DefaultAzureCredential())

agent = project.agents.create_version(
    agent_name="support-agent",
    definition=PromptAgentDefinition(
        model=os.environ["FOUNDRY_MODEL_NAME"],
        instructions="You are Contoso Bank's support agent. Be brief and polite.",
    ),
)
print(f"Agent {agent.name}, version {agent.version}")

Chat with the agent (multi-turn)

openai = project.get_openai_client(agent_name="support-agent")   # client bound to the agent
conversation = openai.conversations.create()                      # holds the chat history

for question in ["What is the annual fee on the Platinum card?",
                 "Can it be waived?"]:
    response = openai.responses.create(conversation=conversation.id, input=question)
    print("You:  ", question)
    print("Agent:", response.output_text)

The conversation stores every message, so the second question (“Can it be waived?”) is understood in context. The agent created in the portal, with its file search knowledge, can be called the same way by name.

Agents vs chat apps

Check yourself