Step 1

Run Your First Agent

On this page

Exercise 1 — Create and Run Your First Agent

Phase	Difficulty	Time Estimate
1 — Foundations	⭐ Beginner	15–20 min

Learning Objectives

By the end of this exercise you will be able to:

Create an FoundryChatClient backed by Entra ID credentials
Use .as_agent() to define an agent with a name and instructions
Call agent.run() with a user prompt and read the response via result.text

Prerequisites

Requirement	How to verify
Environment setup complete	`python3 -c "import agent_framework; print(agent_framework.__version__)"`
Azure CLI logged in	`az account show` (should return your subscription)
`.env` configured	Ensure `FOUNDRY_PROJECT_ENDPOINT` and `FOUNDRY_MODEL` are set in the repo-root `.env`

Background

The 3-Layer Architecture

┌──────────────────────────────────┐
│  Microsoft Foundry Project        │  ← Cloud resource (models, connections, storage)
├──────────────────────────────────┤
│  Environment Variables (.env)    │  ← FOUNDRY_PROJECT_ENDPOINT,
│                                  │    FOUNDRY_MODEL
├──────────────────────────────────┤
│  Your Python Code                │  ← FoundryChatClient → agent → run()
└──────────────────────────────────┘

Key Concepts

FoundryChatClient — The client that connects to your Microsoft Foundry project. It reads FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL from environment variables automatically.
.as_agent(name=..., instructions=...) — Creates a hosted agent with a persona. The name identifies the agent; instructions define its system-level behaviour.
agent.run(prompt) — Sends a user message to the agent and returns a result object. Access the agent’s text reply via result.text.

Note: Both the credential and the agent client are async resources. Always use async with to ensure they are properly closed.

Your Task

Open starter.py in this directory. You will see three TODO markers inside async def main(). Fill them in:

Step 1 — Create an `AzureCliCredential` (TODO 1)

Create an async context manager for AzureCliCredential:

async with AzureCliCredential() as cred:

This authenticates against Azure using the CLI token from az login.

Step 2 — Create the Agent (TODO 2)

Inside the credential block, create an agent using FoundryChatClient:

async with FoundryChatClient(credential=cred).as_agent(
    name="venue_specialist",
    instructions="You are the Venue Specialist, an expert in venue research and recommendation.",
) as agent:

credential=cred passes the Entra ID credential to the client.
.as_agent() creates a hosted agent on Foundry with the given name and instructions.
The async with block ensures the agent is cleaned up when done.

Step 3 — Run the Agent (TODO 3)

Call agent.run() with a prompt and print the result:

result = await agent.run(
    "Plan a corporate holiday party for 50 people on December 6th, 2026 in Seattle"
)
print("Result:\n")
print(result.text)

Hints

Work through the hints progressively — try on your own first!

💡 Hint 1 — High-level approach

Both `AzureCliCredential()` and the agent must be used as `async with` context managers. Nest them inside `main()`: ```python async with as cred: async with .as_agent(...) as agent: result = await agent.run(...) ``` </details>

💡 Hint 2 — Client and agent creation

`FoundryChatClient` takes a `credential=` parameter. You then chain `.as_agent()` on it to create the agent: ```python FoundryChatClient(credential=cred).as_agent( name="venue_specialist", instructions="You are the Venue Specialist, ...", ) ``` No need to pass the endpoint or model name — those are read from environment variables automatically.

💡 Hint 3 — Near-complete solution

```python async with AzureCliCredential() as cred: async with FoundryChatClient(credential=cred).as_agent( name="venue_specialist", instructions="You are the Venue Specialist, an expert in venue research and recommendation.", ) as agent: result = await agent.run( "Plan a corporate holiday party for 50 people on December 6th, 2026 in Seattle" ) print("Result:\n") print(result.text) ```

--- ## Validate Your Work ### 1. Run the check script (offline — no Azure needed) ```bash bash workshop/exercises/ex1_run_agent/check.sh ``` This verifies syntax, required code patterns, and that all TODOs are resolved. ### 2. Run against Azure ```bash python3 -u workshop/exercises/ex1_run_agent/starter.py ``` **Expected behaviour:** - The script connects to your Foundry project. - The agent generates a party-planning response (venue suggestions, logistics, etc.). - You see `Result:` followed by the agent's text output. - If OpenTelemetry is available, `[AGENT]` span lines appear showing the agent invocation. --- ## Bonus Challenges 1. **Change the agent name and instructions** — Try `name="travel_advisor"` with travel-themed instructions. How does the response change? 2. **Try different prompts** — Ask for a different scenario (e.g., "Plan a 3-day team offsite in Tokyo for 20 engineers"). 3. **Observe OpenTelemetry spans** — Look at the `[AGENT]` and `[TOOL]` lines in the output. What information do they capture? --- ## Troubleshooting | Symptom | Likely Cause | Fix | |---------|-------------|-----| | `DefaultAzureCredential` / auth error | Not logged in to Azure CLI | Run `az login` and retry | | `Cannot resolve ... host via DNS` | Foundry project uses private networking | Use a public endpoint or run from a network that can resolve the private DNS | | `FOUNDRY_MODEL` missing | `.env` not configured | Copy `.env.example` to `.env` and set the deployment name to match your Foundry project | | `RuntimeError: Required environment variable ...` | Missing or empty env var | Check `.env` at the repo root — ensure values are not empty strings | | `ModuleNotFoundError: agent_framework` | Dependencies not installed | Run `pip install -r requirements.txt` | --- ## Solution Reference See the complete working solution at: **`src/demo1_run_agent.py`**

← → to navigate between steps