Building Microsoft Foundry Agents: Part 1 - Creating Your First Simple SDK Agent

In the rapidly evolving world of artificial intelligence, the industry is moving beyond simple Large Language Model (LLM) calls toward agentic behavior. While a traditional LLM interaction is a single exchange, an agent represents an interaction loop capable of taking action and making decisions.

This series uses Microsoft Agent Framework to run agents backed by Azure AI Foundry Agent Service (via AzureAIAgentClient). The framework is a unified, open-source library that simplifies building these systems by providing a high-level abstraction for orchestration.

What is an Agent?

At its core, an agent can be broken down into three simple categories: inputs, outputs, and tool calls. Unlike traditional Retrieval-Augmented Generation (RAG) where all context is provided up-front, an agent may start with only a system prompt and discover the necessary context and tools through its own journey.

The Microsoft Agent Framework allows you to build these agents as code, offering local debuggability and the ability to step through tool calls to trace tool calls / execution steps.

Prerequisites

To follow this guide, you will need:

• Python 3.10 or later (or .NET 8.0 if you prefer C#).
• An Azure AI Foundry project endpoint.
• Azure CLI installed and authenticated (az login).
• The Agent Framework library: pip install agent-framework --pre
• Set your two required environment variables: AZURE_AI_PROJECT_ENDPOINT AZURE_AI_MODEL_DEPLOYMENT_NAME

Step 1: Secure Authentication

A standout feature of the Microsoft Agent Framework is its security-first mindset. Instead of leaking API keys in environment files, it uses Identity to authenticate. By using AzureCliCredential, the agent runs using your identity on your machine and can transition to a production system's identity without code changes.

from azure.identity.aio import AzureCliCredential
from agent_framework.azure import AzureAIAgentClient

# Authenticate securely without API keys
credential = AzureCliCredential()

Step 2: Define Your Agent

Creating an agent involves defining its instructions (the system prompt) and giving it a name. The name is crucial for observability and when you eventually compose multiple agents into a multi-agent swarm.

It is important to note that creating an agent and running an agent are separate steps. This allows your application to instantiate the agent resources once and reuse them for multiple requests within the same process/context.

# Create the client and the agent
async with AzureAIAgentClient(credential=credential).as_agent(
        name="TravelGuide",
        instructions="You are a luxury travel concierge. Recommend hidden gems."
    ) as agent:

Step 3: Running the Agent

Once the agent is defined, you can invoke it using the run method. The framework handles the low-level API communication, allowing you to focus on the input and the resulting output.

# Run and wait for result
result = await agent.run("Suggest top 3 places to go to in Galle, Sri Lanka.")

# Print messages
print(result.text)

Optional: Real-time Streaming

For a better user experience, you can use run_stream to receive updates as they are generated rather than waiting for the full response.

async for update in agent.run_stream("Suggest top 3 places to go to in Galle, Sri Lanka."):
  if update.text:
    print(update.text, end="", flush=True)

Putting it all together

Now that we’ve explored the components individually, let’s see how they fit into a complete, executable Python script.

To run this, we wrap our logic in an async function. This is necessary because the Azure AI Agent Service operates asynchronously to handle real-time streaming and long-running tool calls without blocking your application.

import asyncio
from azure.identity.aio import AzureCliCredential
from agent_framework.azure import AzureAIAgentClient

async def main():
    # Authenticate securely without API keys
    credential = AzureCliCredential()

    # Create the client and the agent
    async with AzureAIAgentClient(credential=credential).as_agent(
        name="TravelGuide",
        instructions="You are a luxury travel concierge. Recommend hidden gems."
    ) as agent:

        # Run and wait for result
        result = await agent.run("Suggest top 3 places to go to in Galle, Sri Lanka.")

        # Print messages
        print(result.text)

    # Cleanup
    await credential.close()

if __name__ == "__main__":
    # This is the crucial part that executes the async loop
    asyncio.run(main())

Why Build Agents as Code?

You might wonder why you would choose a code-first approach over low-code platforms like Copilot Studio. The primary reasons are:

1. Customization and Control: Code gives you the power to manipulate low-level tool calls and agent discovery.
2. Portability: You can run the framework in restricted or on-premise environments while calling cloud-based LLMs.
3. Local Experimentation: You can run agents locally on your laptop to understand formatting, response behavior, and state management.

Looking Ahead

We have now successfully built a basic agent that follows instructions using the Microsoft Agent Framework. However, this agent is currently isolated from the outside world; it only knows what the LLM knows.

Part 2: add a tool + MCP server so the agent can call real functions / local data.

---

Note on the Framework: Agent Framework is in public preview; APIs may evolve.