{"id":7902,"library":"agent-framework-orchestrations","title":"Agent Framework Orchestrations","description":"This library, part of the broader Microsoft Agent Framework, provides high-level orchestration patterns for coordinating AI agents and executors. It includes builders for sequential, concurrent, handoff, group chat, and Magentic workflows, enabling developers to create structured multi-agent systems. The framework unifies concepts from Semantic Kernel and AutoGen, focusing on robust and auditable AI automation. The main framework recently reached version 1.0, with this sub-package being actively developed, currently at `1.0.0b260409`.","status":"active","version":"1.0.0b260409","language":"en","source_language":"en","source_url":"https://github.com/microsoft/agent-framework","tags":["AI agents","orchestration","multi-agent systems","Microsoft","workflow","LLM"],"install":[{"cmd":"pip install agent-framework-orchestrations","lang":"bash","label":"Install specific package"},{"cmd":"pip install agent-framework","lang":"bash","label":"Install full framework (includes orchestrations)"}],"dependencies":[{"reason":"This package is a sub-package of the main Microsoft Agent Framework.","package":"agent-framework","optional":false},{"reason":"Commonly used for loading environment variables in local development, particularly for samples and quickstarts.","package":"python-dotenv","optional":true},{"reason":"Used for Azure authentication, common in samples using Azure AI Foundry or Azure OpenAI clients.","package":"azure-identity","optional":true}],"imports":[{"symbol":"SequentialBuilder","correct":"from agent_framework.orchestrations import SequentialBuilder"},{"symbol":"ConcurrentBuilder","correct":"from agent_framework.orchestrations import ConcurrentBuilder"},{"symbol":"HandoffBuilder","correct":"from agent_framework.orchestrations import HandoffBuilder"},{"symbol":"GroupChatBuilder","correct":"from agent_framework.orchestrations import GroupChatBuilder"},{"note":"Unlike other builders, MagenticBuilder is directly under the top-level 'agent_framework' package.","symbol":"MagenticBuilder","correct":"from agent_framework import MagenticBuilder"},{"note":"A general-purpose builder for graph-based workflows, which can implement various orchestration patterns.","symbol":"WorkflowBuilder","correct":"from agent_framework import WorkflowBuilder"}],"quickstart":{"code":"import asyncio\nimport os\nfrom dotenv import load_dotenv\nfrom agent_framework import Agent\nfrom agent_framework.foundry import FoundryChatClient\nfrom agent_framework.orchestrations import SequentialBuilder\nfrom azure.identity import AzureCliCredential\n\nload_dotenv() # Load environment variables from .env file\n\nasync def main():\n    # Ensure environment variables are set for FoundryChatClient\n    foundry_endpoint = os.environ.get(\"FOUNDRY_PROJECT_ENDPOINT\", \"\")\n    model_deployment_name = os.environ.get(\"AZURE_AI_MODEL_DEPLOYMENT_NAME\", \"\")\n\n    if not foundry_endpoint or not model_deployment_name:\n        print(\"Please set FOUNDRY_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME environment variables.\")\n        print(\"Also ensure you are authenticated via 'az login' if using AzureCliCredential.\")\n        return\n\n    # 1) Create a chat client (e.g., FoundryChatClient for Azure AI Foundry)\n    try:\n        client = FoundryChatClient(\n            project_endpoint=foundry_endpoint,\n            model=model_deployment_name,\n            credential=AzureCliCredential(),\n        )\n    except Exception as e:\n        print(f\"Failed to create FoundryChatClient: {e}\")\n        print(\"Ensure 'az login' is performed and environment variables are correctly configured.\")\n        return\n\n    # 2) Define your agents\n    writer = Agent(\n        client=client,\n        instructions=\"You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt.\",\n        name=\"writer\",\n    )\n    reviewer = Agent(\n        client=client,\n        instructions=\"You are a thoughtful reviewer. Give brief feedback on the previous assistant message.\",\n        name=\"reviewer\",\n    )\n\n    # 3) Build a sequential workflow (writer -> reviewer)\n    workflow = SequentialBuilder(participants=[writer, reviewer]).build()\n\n    # 4) Run the workflow\n    print(\"\\n--- Running Sequential Workflow ---\")\n    async for event in workflow.run_stream(\"Write a tagline for a budget-friendly eBike.\"):\n        if event.type == \"output\":\n            print(\"\\nFinal Conversation History:\")\n            for message in event.data:\n                print(f\"  {message.role.capitalize()}: {message.content}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 for Semantic Kernel/AutoGen users"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Handling long-running tasks, particularly those requiring human intervention or spanning extended periods, necessitates explicit checkpointing and state persistence to ensure recovery from interruptions.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"`pip install agent-framework-orchestrations` or `pip install agent-framework`","cause":"The `agent-framework-orchestrations` package is not installed, or the `agent-framework` umbrella package (which includes orchestrations) is missing.","error":"ModuleNotFoundError: No module named 'agent_framework.orchestrations'"},{"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`.","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.","error":"Failed to create FoundryChatClient: <specific_error_message>"},{"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.","cause":"Poorly defined termination conditions, ambiguous agent instructions, or issues with shared context leading agents to repeatedly attempt the same action.","error":"Agent enters infinite loop or produces repetitive output"}]}