Registry / llm-agents / agent-framework-orchestrations

agent-framework-orchestrations

JSON →
library1.0.0rc3pypypi✓ verified 85d ago

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`.

pip install agent-framework-orchestrations
INSTALL
IMPORT
SIG · AGENT-FRAMEWORK-OR
A
agent-framework-orchestrations
llm-agentspythonv1.0.0rc3
Install
19.0s avg
Import
911ms
Disk
832MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.0rc3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
4/8 runs
✓ 21.33s
py 3.11
4/8 runs
✓ 21.26s
py 3.12
4/8 runs
✓ 17.06s
py 3.13
4/8 runs
✓ 16.51s
py 3.9
✕ build_error
✕ build_error
832MB installed
● package 832MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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())
Debug
Known issues
breakingMicrosoft 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.
affects: <1.0.0 for Semantic Kernel/AutoGen users
gotchaThe 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.
affects: All
gotchaIn 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.
affects: All
gotchaAgentic 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.
affects: All
gotchaHandling 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.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'agent_framework.orchestrations'
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>
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
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.
Upgrade
Version history
1.0.0rc3latest on PyPI · released Jun 4, 2026
Audit
Dependencies
agent-frameworkrequiredThis package is a sub-package of the main Microsoft Agent Framework.
python-dotenvoptionalCommonly used for loading environment variables in local development, particularly for samples and quickstarts.
azure-identityoptionalUsed for Azure authentication, common in samples using Azure AI Foundry or Azure OpenAI clients.
Agent activity
72 hits · last 30 days
node
64
OpenAI (training)
1
Resources
agent-framework-orchestrations — pip install agent-framework-orchestrations · libregistry