{"id":1515,"date":"2026-03-29T07:30:42","date_gmt":"2026-03-29T07:30:42","guid":{"rendered":"https:\/\/bogdanburuiana.com\/?p=1515"},"modified":"2026-04-30T07:50:05","modified_gmt":"2026-04-30T07:50:05","slug":"the-microsoft-agent-framework-when-you-need-code-level-control","status":"publish","type":"post","link":"https:\/\/bogdanburuiana.com\/index.php\/2026\/03\/29\/the-microsoft-agent-framework-when-you-need-code-level-control\/","title":{"rendered":"The Microsoft Agent Framework: When You Need Code-Level Control"},"content":{"rendered":"\n

<\/p>\n\n\n\n

The Foundry portal and its visual workflow builder are excellent tools. But there comes a point in every serious AI project where you need to step beyond the visual layer and write code. The Microsoft Agent Framework is where you go when that moment arrives.
It’s a Python SDK that gives you programmatic control over everything – agent creation, conversation management, tool integration, and multi-agent orchestration. If the Foundry portal is the configuration layer, the Agent Framework is the engineering layer.
Let me walk you through the core components and how they fit together.<\/p>\n\n\n\n

The Five Core Components<\/strong><\/p>\n\n\n\n

The framework is built around five well-defined abstractions. Understand these and the rest follows naturally.<\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Setting Up Your First Agent (Code Walkthrough)<\/strong><\/p>\n\n\n\n

Here’s the minimal setup to create a working agent with the framework:<\/p>\n\n\n\n

from azure.ai.agents import AzureAIAgentClient, ChatAgent, AgentThread\nfrom azure.identity import AzureCliCredential\n\n# Step 1: Authenticate with Azure\ncredential = AzureCliCredential()\n\n# Step 2: Connect to your Foundry project\nclient = AzureAIAgentClient(\n    endpoint=\"https:\/\/your-project.openai.azure.com\/\",\n    credential=credential\n)\n\n# Step 3: Define your agent\nagent = ChatAgent(\n    client=client,\n    model=\"gpt-4.1\",\n    instructions=\"\"\"You are a cloud cost optimisation advisor \n    for enterprise Azure environments. Analyse resource usage \n    patterns and recommend specific cost-saving actions with \n    estimated monthly savings. Always quantify recommendations \n    when possible.\"\"\",\n    tools=[get_resource_costs, get_usage_metrics]  # custom tools\n)\n\n# Step 4: Create a conversation thread\nthread = AgentThread()\n\n# Step 5: Send a message and get a response\nresponse = await agent.send_message(\n    thread=thread,\n    message=\"Analyse our storage account usage for the last 30 days\"\n)\n\nprint(response.content)<\/code><\/pre>\n\n\n\n
Five steps. That’s the full agent lifecycle – authentication, connection, configuration, thread creation, and conversation.
The AgentThread <\/strong>is what manages conversation state. Messages accumulate in the thread across turns, so the agent remembers the full context of the conversation. You create one thread per user session and pass it into every subsequent message.<\/p>\n\n\n\n
Adding Custom Tools: The @tool Decorator Pattern<\/strong><\/p>\n\n\n\n
I covered the @tool <\/strong>decorator in the tools article, but let me show the complete pattern here in the context of the framework:<\/p>\n\n\n\n
from azure.ai.agents import tool\nimport json\n\n@tool\ndef get_azure_resource_costs(\n    resource_group: str,\n    time_period_days: int = 30\n) -> dict:\n    \"\"\"\n    Retrieve cost breakdown for an Azure resource group.\n    \n    Use this when the user asks about costs, spend, or billing\n    for a specific resource group or environment.\n    \n    Args:\n        resource_group: The Azure resource group name\n        time_period_days: Number of days to analyse (default 30)\n        \n    Returns:\n        Dictionary with cost by resource type and total\n    \"\"\"\n    # Your Azure Cost Management API call\n    costs = cost_management_client.query_costs(\n        resource_group=resource_group,\n        days=time_period_days\n    )\n    return costs.to_dict()\n\n# Register with the agent\nagent = ChatAgent(\n    client=client,\n    model=\"gpt-4.1\",\n    instructions=\"...\",\n    tools=[get_azure_resource_costs]  # Pass function reference\n)<\/code><\/pre>\n\n\n\n
Critical things to get right:<\/p>\n\n\n\n
    \n
  • The docstring<\/strong> is the tool’s self-description. The LLM reads it. Write it clearly. <\/li>\n\n\n\n
  • Type annotations<\/strong> tell the framework what parameters to expect and validate <\/li>\n\n\n\n
  • Return type<\/strong> – return structured data (dicts, lists) not raw strings <\/li>\n\n\n\n
  • Error handling inside the function<\/strong> – the agent receives whatever you return, including errors<\/li>\n<\/ul>\n\n\n\n
    AgentThread: Understanding Conversation State<\/strong><\/p>\n\n\n\n
    This is a concept worth spending time on because it’s different from how most developers think about API calls.<\/p>\n\n\n\n
    STATELESS API CALL (traditional):\nRequest 1: \"What is X?\" \u2192 Response 1\nRequest 2: \"Tell me more\" \u2192 ??? (no memory of Request 1)\n\nAGENT THREAD (stateful):\nThread created\nMessage 1: \"What is X?\" \u2192 Response 1\nMessage 2: \"Tell me more\" \u2192 Response 2 (knows context from M1)\nMessage 3: \"And in comparison to Y?\" \u2192 Response 3 (knows M1 + M2)<\/code><\/pre>\n\n\n\n
    The thread stores the full message history. Every subsequent message to the same thread includes all previous context. This is how multi-turn conversations work without you manually managing history.
    <\/p>\n\n\n\n
    For enterprise applications, the implications are:<\/p>\n\n\n\n
      \n
    • Each user session should have its own thread<\/li>\n\n\n\n
    • Threads have a token limit – very long conversations will eventually hit it<\/li>\n\n\n\n
    • Thread persistence (saving thread ID to database, resuming later) lets users continue conversations across sessions<\/li>\n\n\n\n
    • Thread data may contain sensitive information – apply appropriate access controls<\/li>\n<\/ul>\n\n\n\n
      Chat Providers: Swapping the Underlying Model<\/strong><\/p>\n\n\n\n
      One of the framework’s design strengths is the BaseAgent abstraction. All chat providers implement the same interface, which means you can swap the underlying model without changing your agent logic.<\/p>\n\n\n\n
      # Using Azure OpenAI\nfrom azure.ai.agents.providers import AzureOpenAIProvider\n\n# Using another provider\nfrom azure.ai.agents.providers import AzureAIInferenceProvider\n\n# The agent interface is identical regardless\nagent = ChatAgent(\n    client=client,  # Different client, same ChatAgent\n    model=\"claude-sonnet-4-6\",  # Or any supported model\n    instructions=\"...\",\n    tools=[...]\n)<\/code><\/pre>\n\n\n\n
      In practice, this means you can:<\/p>\n\n\n\n
        \n
      • Start development with one model and switch for cost\/performance reasons<\/li>\n\n\n\n
      • A\/B test different models against the same agent configuration<\/li>\n\n\n\n
      • Use different models for different agents in a multi-agent system (a cheaper model for simple routing, a more capable model for complex reasoning)<\/li>\n<\/ul>\n\n\n\n
        Built-In Tools in the Framework<\/strong><\/p>\n\n\n\n
        Beyond custom tools, the framework exposes the same built-in capabilities as the Foundry portal:<\/p>\n\n\n\n
        from azure.ai.agents.tools import CodeInterpreterTool, FileSearchTool\n\nagent = ChatAgent(\n    client=client,\n    model=\"gpt-4.1\",\n    instructions=\"...\",\n    tools=[\n        CodeInterpreterTool(),      # Execute Python for analysis\n        FileSearchTool(             # Search your document index\n            vector_store_ids=[\"vs_abc123\"]\n        ),\n        get_crm_data,               # Custom function tool\n        send_slack_notification     # Another custom tool\n    ]\n)<\/code><\/pre>\n\n\n\n
        Mix and match built-in and custom tools in the same agent. The framework handles the routing.<\/p>\n\n\n\n
        \"\"<\/figure>\n\n\n\n
        My recommendation: Use the portal for initial agent configuration and testing. Migrate to the framework when you need complex tool logic, multi-agent orchestration, or proper production deployment with version control.<\/p>\n\n\n\n
        What Makes the Framework Production-Ready<\/strong><\/p>\n\n\n\n
        Beyond the core features, the framework includes:<\/p>\n\n\n\n
          \n
        • Streaming responses – stream tokens to the user as they’re generated rather than waiting for the full response<\/li>\n\n\n\n
        • Structured outputs – force the agent to return JSON matching a defined schema (essential for downstream processing)<\/li>\n\n\n\n
        • Retry logic – built-in exponential backoff for transient failures<\/li>\n\n\n\n
        • Telemetry hooks – emit custom metrics to your observability platform<\/li>\n\n\n\n
        • Async support – full async\/await support for high-concurrency applications<\/li>\n<\/ul>\n\n\n\n
          These aren’t features you’ll need for a proof-of-concept. They’re features you’ll need before going to production.<\/p>\n\n\n\n
          Next: I’ll cover the five multi-agent orchestration patterns – concurrent, sequential, group chat, handoff, and Magentic – with real use cases for each.<\/em><\/p>\n\n\n\n
          <\/p>\n","protected":false},"excerpt":{"rendered":"
          The Foundry portal and its visual workflow builder are excellent tools. But there comes a point in every serious AI project where you need to step beyond the visual layer and write code. The Microsoft Agent Framework is where you go when that moment arrives.It’s a Python SDK that gives you programmatic control over everything […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"_links":{"self":[{"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/posts\/1515"}],"collection":[{"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/comments?post=1515"}],"version-history":[{"count":1,"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/posts\/1515\/revisions"}],"predecessor-version":[{"id":1518,"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/posts\/1515\/revisions\/1518"}],"wp:attachment":[{"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/media?parent=1515"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/categories?post=1515"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bogdanburuiana.com\/index.php\/wp-json\/wp\/v2\/tags?post=1515"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}