Agent Framework Orchestrations

Common errors

• ModuleNotFoundError: No module named 'agent_framework.orchestrations'

  cause The `agent-framework-orchestrations` package is not installed, or the `agent-framework` umbrella package (which includes orchestrations) is missing.
  fix `pip install agent-framework-orchestrations` or `pip install agent-framework`

• Failed to create FoundryChatClient: <specific_error_message>

  cause Environment variables for `FOUNDRY_PROJECT_ENDPOINT` or `AZURE_AI_MODEL_DEPLOYMENT_NAME` are missing or incorrect, or Azure CLI authentication (`az login`) has not been performed.
  fix Ensure `FOUNDRY_PROJECT_ENDPOINT` and `AZURE_AI_MODEL_DEPLOYMENT_NAME` are set in your environment variables or `.env` file. Run `az login` to authenticate with Azure if using `AzureCliCredential`.

• Agent enters infinite loop or produces repetitive output

  cause Poorly defined termination conditions, ambiguous agent instructions, or issues with shared context leading agents to repeatedly attempt the same action.
  fix Refine agent instructions to be precise, implement explicit termination criteria in the workflow, and review how context is shared or mutated between agents to prevent circular reasoning.

Warnings

• breaking Microsoft Agent Framework is the direct successor and unified platform for both Semantic Kernel and AutoGen. Users of these older frameworks will need to migrate their existing agent and workflow implementations to the new Agent Framework APIs.
  Fix: Refer to the official migration guides provided by Microsoft for transitioning from Semantic Kernel or AutoGen to Microsoft Agent Framework. Expect API changes and refactoring of agent and orchestration code.
• gotcha The framework's `WorkflowBuilder` and specialized builders (like `SequentialBuilder`) define graph-based, explicit execution paths. This differs from dynamic, LLM-driven agent interactions and requires upfront design.
  Fix: Understand when to use explicit workflows (for predictable, auditable, long-running processes) versus single `ChatAgent` for ad-hoc, conversational tasks. Embrace the graph topology of executors and edges for complex processes.
• gotcha In multi-agent systems, unmanaged shared memory can lead to 'context pollution' where agents overwrite or misinterpret shared state, making workflows unreliable and hard to debug.
  Fix: Implement proper isolation for agent contexts, use explicit data passing mechanisms, or leverage the framework's built-in state management features carefully. Avoid a single, global memory object without clear boundaries.
• gotcha Agentic workflows can incur unexpected cloud costs if not properly designed. Inefficient agent calls, loops, and redundant LLM interactions can rapidly increase token consumption and expenses.
  Fix: Implement robust termination conditions, monitor token usage, and optimize workflow logic to minimize unnecessary LLM calls. Utilize checkpointing and observability tools to identify and address cost inefficiencies.
• gotcha Handling long-running tasks, particularly those requiring human intervention or spanning extended periods, necessitates explicit checkpointing and state persistence to ensure recovery from interruptions.
  Fix: Design workflows with checkpointing mechanisms using `with_checkpointing()` where available, or manually persist and hydrate workflow state to resume operations after pauses or failures.

Install

• pip install agent-framework-orchestrations Install specific package
• pip install agent-framework Install full framework (includes orchestrations)

Imports

• SequentialBuilder

  from agent_framework.orchestrations import SequentialBuilder

• ConcurrentBuilder

  from agent_framework.orchestrations import ConcurrentBuilder

• HandoffBuilder

  from agent_framework.orchestrations import HandoffBuilder

• GroupChatBuilder

  from agent_framework.orchestrations import GroupChatBuilder

• MagenticBuilder

  from agent_framework import MagenticBuilder

  Unlike other builders, MagenticBuilder is directly under the top-level 'agent_framework' package.
• WorkflowBuilder

  from agent_framework import WorkflowBuilder

  A general-purpose builder for graph-based workflows, which can implement various orchestration patterns.

Quickstart

This quickstart demonstrates how to set up a basic sequential workflow using `SequentialBuilder`. It defines two agents (a 'writer' and a 'reviewer') and orchestrates them to process a task in a linear fashion, passing the conversation history between them. It uses `FoundryChatClient` requiring Azure AI Foundry credentials via environment variables and Azure CLI authentication.

import asyncio
import os
from dotenv import load_dotenv
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential

load_dotenv() # Load environment variables from .env file

async def main():
    # Ensure environment variables are set for FoundryChatClient
    foundry_endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT", "")
    model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

    if not foundry_endpoint or not model_deployment_name:
        print("Please set FOUNDRY_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.")
        print("Also ensure you are authenticated via 'az login' if using AzureCliCredential.")
        return

    # 1) Create a chat client (e.g., FoundryChatClient for Azure AI Foundry)
    try:
        client = FoundryChatClient(
            project_endpoint=foundry_endpoint,
            model=model_deployment_name,
            credential=AzureCliCredential(),
        )
    except Exception as e:
        print(f"Failed to create FoundryChatClient: {e}")
        print("Ensure 'az login' is performed and environment variables are correctly configured.")
        return

    # 2) Define your agents
    writer = Agent(
        client=client,
        instructions="You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt.",
        name="writer",
    )
    reviewer = Agent(
        client=client,
        instructions="You are a thoughtful reviewer. Give brief feedback on the previous assistant message.",
        name="reviewer",
    )

    # 3) Build a sequential workflow (writer -> reviewer)
    workflow = SequentialBuilder(participants=[writer, reviewer]).build()

    # 4) Run the workflow
    print("\n--- Running Sequential Workflow ---")
    async for event in workflow.run_stream("Write a tagline for a budget-friendly eBike."):
        if event.type == "output":
            print("\nFinal Conversation History:")
            for message in event.data:
                print(f"  {message.role.capitalize()}: {message.content}")

if __name__ == "__main__":
    asyncio.run(main())