agent/agent-framework
1
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

[BREAKING] Python: Refactor orchestrations (#3023)

Browse Source 
* Group chat refactoring Part 1; Next: HIL and handoff

* Add agent approval flow; next samples

* WIP: samples

* WIP: HIL samples

* Group chat HIL working; next: handoff

* Fix group chat tool approval sample

* WIP: refactor handoff; next handoff handling

* Handoff done; next handoff samples and concurrent and sequential

* Handoff samples, concurrent, and sequential done; next Magentic

* WIP: magentic; next test with samples + HIL

* Magentic Working; next fix all samples and tests

* Fix handoff samples; next tests

* WIP: fixing tests; some orchestration as agent samples are failing

* Group chat unit tests done

* Handoff  unit tests done

* Remove old orchestration_request_info and fix related tests

* Magentic unit tests done

* Fix samples

* Fix test

* Fix test 2

* mypy

* Address comments

* Update readme

* Address comments

* Address comments 2

* Replace display name
This commit is contained in:
Tao Chen
2026-01-13 10:40:26 -08:00
committed by GitHub
Unverified
parent 3e97425245
commit 0b152418b6
54 changed files with 5106 additions and 10245 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/samples/getting_started/workflows/README.md
+3 -7
View File
@@ -115,18 +115,14 @@ For additional observability samples in Agent Framework, see the [observability
| Concurrent Orchestration (Custom Aggregator) | [orchestration/concurrent_custom_aggregator.py](./orchestration/concurrent_custom_aggregator.py) | Override aggregator via callback; summarize results with an LLM |
| Concurrent Orchestration (Custom Agent Executors) | [orchestration/concurrent_custom_agent_executors.py](./orchestration/concurrent_custom_agent_executors.py) | Child executors own ChatAgents; concurrent fan-out/fan-in via ConcurrentBuilder |
| Concurrent Orchestration (Participant Factory) | [orchestration/concurrent_participant_factory.py](./orchestration/concurrent_participant_factory.py) | Use participant factories for state isolation between workflow instances |
| Group Chat with Agent Manager | [orchestration/group_chat_agent_manager.py](./orchestration/group_chat_agent_manager.py) | Agent-based manager using `set_manager()` to select next speaker |
| Group Chat with Agent Manager | [orchestration/group_chat_agent_manager.py](./orchestration/group_chat_agent_manager.py) | Agent-based manager using `with_agent_orchestrator()` to select next speaker |
| Group Chat Philosophical Debate | [orchestration/group_chat_philosophical_debate.py](./orchestration/group_chat_philosophical_debate.py) | Agent manager moderates long-form, multi-round debate across diverse participants |
| Group Chat with Simple Function Selector | [orchestration/group_chat_simple_selector.py](./orchestration/group_chat_simple_selector.py) | Group chat with a simple function selector for next speaker |
| Handoff (Simple) | [orchestration/handoff_simple.py](./orchestration/handoff_simple.py) | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response |
| Handoff (Specialist-to-Specialist) | [orchestration/handoff_specialist_to_specialist.py](./orchestration/handoff_specialist_to_specialist.py) | Multi-tier routing: specialists can hand off to other specialists using `.add_handoff()` fluent API |
| Handoff (Return-to-Previous) | [orchestration/handoff_return_to_previous.py](./orchestration/handoff_return_to_previous.py) | Return-to-previous routing: after user input, routes back to the previous specialist instead of coordinator using `.enable_return_to_previous()` |
| Handoff (Autonomous) | [orchestration/handoff_autonomous.py](./orchestration/handoff_autonomous.py) | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_interaction_mode("autonomous", autonomous_turn_limit=N)` |
| Handoff (Autonomous) | [orchestration/handoff_autonomous.py](./orchestration/handoff_autonomous.py) | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` |
| Handoff (Participant Factory) | [orchestration/handoff_participant_factory.py](./orchestration/handoff_participant_factory.py) | Use participant factories for state isolation between workflow instances |
| Magentic Workflow (Multi-Agent) | [orchestration/magentic.py](./orchestration/magentic.py) | Orchestrate multiple agents with Magentic manager and streaming |
| Magentic + Human Plan Review | [orchestration/magentic_human_plan_update.py](./orchestration/magentic_human_plan_update.py) | Human reviews/updates the plan before execution |
| Magentic + Human Stall Intervention | [orchestration/magentic_human_replan.py](./orchestration/magentic_human_replan.py) | Human intervenes when workflow stalls with `with_human_input_on_stall()` |
| Magentic + Agent Clarification | [orchestration/magentic_agent_clarification.py](./orchestration/magentic_agent_clarification.py) | Agents ask clarifying questions via `ask_user` tool with `@ai_function(approval_mode="always_require")` |
| Magentic + Human Plan Review | [orchestration/magentic_human_plan_review.py](./orchestration/magentic_human_plan_review.py) | Human reviews/updates the plan before execution |
| Magentic + Checkpoint Resume | [orchestration/magentic_checkpoint.py](./orchestration/magentic_checkpoint.py) | Resume Magentic orchestration from saved checkpoints |
| Sequential Orchestration (Agents) | [orchestration/sequential_agents.py](./orchestration/sequential_agents.py) | Chain agents sequentially with shared conversation context |
| Sequential Orchestration (Custom Executor) | [orchestration/sequential_custom_executors.py](./orchestration/sequential_custom_executors.py) | Mix agents with a summarizer that appends a compact summary |
python/samples/getting_started/workflows/agents/group_chat_workflow_as_agent.py
+10 -9
View File
@@ -1,20 +1,16 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from agent_framework import ChatAgent, GroupChatBuilder
from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
logging.basicConfig(level=logging.INFO)
"""
Sample: Group Chat Orchestration (manager-directed)
Sample: Group Chat Orchestration
What it does:
- Demonstrates the generic GroupChatBuilder with a language-model manager directing two agents.
- The manager coordinates a researcher (chat completions) and a writer (responses API) to solve a task.
- Uses the default group chat orchestration pipeline shared with Magentic.
- Demonstrates the generic GroupChatBuilder with a agent orchestrator directing two agents.
- The orchestrator coordinates a researcher (chat completions) and a writer (responses API) to solve a task.
Prerequisites:
- OpenAI environment variables configured for `OpenAIChatClient` and `OpenAIResponsesClient`.
@@ -38,8 +34,13 @@ async def main() -> None:
workflow = (
GroupChatBuilder()
.set_manager(manager=OpenAIChatClient().create_agent(), display_name="Coordinator")
.participants(researcher=researcher, writer=writer)
.with_agent_orchestrator(
OpenAIChatClient().create_agent(
name="Orchestrator",
instructions="You coordinate a team conversation to solve the user's task.",
)
)
.participants([researcher, writer])
.build()
)
python/samples/getting_started/workflows/agents/handoff_workflow_as_agent.py
+140 -146
View File
@@ -1,230 +1,224 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from collections.abc import Mapping
from typing import Any
from typing import Annotated
from agent_framework import (
AgentRunResponse,
ChatAgent,
ChatMessage,
FunctionCallContent,
FunctionResultContent,
HandoffAgentUserRequest,
HandoffBuilder,
HandoffUserInputRequest,
Role,
WorkflowAgent,
ai_function,
)
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
"""
Sample: Handoff Workflow as Agent with Human-in-the-Loop
"""Sample: Handoff Workflow as Agent with Human-in-the-Loop.
Purpose:
This sample demonstrates how to use a HandoffBuilder workflow as an agent via
`.as_agent()`, enabling human-in-the-loop interactions through the standard
agent interface. The handoff pattern routes user requests through a triage agent
to specialist agents, with the workflow requesting user input as needed.
This sample demonstrates how to use a handoff workflow as an agent, enabling
human-in-the-loop interactions through the agent interface.
When using a handoff workflow as an agent:
1. The workflow emits `HandoffUserInputRequest` when it needs user input
2. `WorkflowAgent` converts this to a `FunctionCallContent` named "request_info"
3. The caller extracts `HandoffUserInputRequest` from the function call arguments
4. The caller provides a response via `FunctionResultContent`
This differs from running the workflow directly:
- Direct workflow: Use `workflow.run_stream()` and `workflow.send_responses_streaming()`
- As agent: Use `agent.run()` with `FunctionCallContent`/`FunctionResultContent` messages
Key Concepts:
- HandoffBuilder: Creates triage-to-specialist routing workflows
- WorkflowAgent: Wraps workflows to expose them as standard agents
- HandoffUserInputRequest: Contains conversation context and the awaiting agent
- FunctionCallContent/FunctionResultContent: Standard agent interface for HITL
A handoff workflow defines a pattern that assembles agents in a mesh topology, allowing
them to transfer control to each other based on the conversation context.
Prerequisites:
- `az login` (Azure CLI authentication)
- Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
- `az login` (Azure CLI authentication)
- Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
Key Concepts:
- Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools
for each participant, allowing the coordinator to transfer control to specialists
- Termination condition: Controls when the workflow stops requesting user input
- Request/response cycle: Workflow requests input, user responds, cycle continues
"""
@ai_function
def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
"""Simulated function to process a refund for a given order number."""
return f"Refund processed successfully for order {order_number}."
@ai_function
def check_order_status(order_number: Annotated[str, "Order number to check status for"]) -> str:
"""Simulated function to check the status of a given order number."""
return f"Order {order_number} is currently being processed and will ship in 2 business days."
@ai_function
def process_return(order_number: Annotated[str, "Order number to process return for"]) -> str:
"""Simulated function to process a return for a given order number."""
return f"Return initiated successfully for order {order_number}. You will receive return instructions via email."
def create_agents(chat_client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAgent, ChatAgent, ChatAgent]:
"""Create and configure the triage and specialist agents.
The triage agent dispatches requests to the appropriate specialist.
Specialists handle their domain-specific queries.
Args:
chat_client: The AzureOpenAIChatClient to use for creating agents.
Returns:
Tuple of (triage_agent, refund_agent, order_agent, support_agent)
Tuple of (triage_agent, refund_agent, order_agent, return_agent)
"""
triage = chat_client.create_agent(
# Triage agent: Acts as the frontline dispatcher
triage_agent = chat_client.create_agent(
instructions=(
"You are frontline support triage. Read the latest user message and decide whether "
"to hand off to refund_agent, order_agent, or support_agent. Provide a brief natural-language "
"response for the user. When delegation is required, call the matching handoff tool "
"(`handoff_to_refund_agent`, `handoff_to_order_agent`, or `handoff_to_support_agent`)."
"You are frontline support triage. Route customer issues to the appropriate specialist agents "
"based on the problem described."
),
name="triage_agent",
)
refund = chat_client.create_agent(
instructions=(
"You handle refund workflows. Ask for any order identifiers you require and outline the refund steps."
),
# Refund specialist: Handles refund requests
refund_agent = chat_client.create_agent(
instructions="You process refund requests.",
name="refund_agent",
# In a real application, an agent can have multiple tools; here we keep it simple
tools=[process_refund],
)
order = chat_client.create_agent(
instructions=(
"You resolve shipping and fulfillment issues. Clarify the delivery problem and describe the actions "
"you will take to remedy it."
),
# Order/shipping specialist: Resolves delivery issues
order_agent = chat_client.create_agent(
instructions="You handle order and shipping inquiries.",
name="order_agent",
# In a real application, an agent can have multiple tools; here we keep it simple
tools=[check_order_status],
)
support = chat_client.create_agent(
instructions=(
"You are a general support agent. Offer empathetic troubleshooting and gather missing details if the "
"issue does not match other specialists."
),
name="support_agent",
# Return specialist: Handles return requests
return_agent = chat_client.create_agent(
instructions="You manage product return requests.",
name="return_agent",
# In a real application, an agent can have multiple tools; here we keep it simple
tools=[process_return],
)
return triage, refund, order, support
return triage_agent, refund_agent, order_agent, return_agent
def extract_handoff_request(
response_messages: list[ChatMessage],
) -> tuple[FunctionCallContent, HandoffUserInputRequest]:
"""Extract the HandoffUserInputRequest from agent response messages.
def handle_response_and_requests(response: AgentRunResponse) -> dict[str, HandoffAgentUserRequest]:
"""Process agent response messages and extract any user requests.
When a handoff workflow running as an agent needs user input, it emits a
FunctionCallContent with name="request_info" containing the HandoffUserInputRequest.
This function inspects the agent response and:
- Displays agent messages to the console
- Collects HandoffAgentUserRequest instances for response handling
Args:
response_messages: Messages from the agent response
response: The AgentRunResponse from the agent run call.
Returns:
Tuple of (function_call, handoff_request)
Raises:
ValueError: If no request_info function call is found or payload is invalid
A dictionary mapping request IDs to HandoffAgentUserRequest instances.
"""
for message in response_messages:
pending_requests: dict[str, HandoffAgentUserRequest] = {}
for message in response.messages:
if message.text:
print(f"- {message.author_name or message.role.value}: {message.text}")
for content in message.contents:
if isinstance(content, FunctionCallContent) and content.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:
# Parse the function arguments to extract the HandoffUserInputRequest
args = content.arguments
if isinstance(args, str):
request_args = WorkflowAgent.RequestInfoFunctionArgs.from_json(args)
elif isinstance(args, Mapping):
request_args = WorkflowAgent.RequestInfoFunctionArgs.from_dict(dict(args))
if isinstance(content, FunctionCallContent):
if isinstance(content.arguments, dict):
request = WorkflowAgent.RequestInfoFunctionArgs.from_dict(content.arguments)
elif isinstance(content.arguments, str):
request = WorkflowAgent.RequestInfoFunctionArgs.from_json(content.arguments)
else:
raise ValueError("Unexpected argument type for request_info function call.")
payload: Any = request_args.data
if not isinstance(payload, HandoffUserInputRequest):
raise ValueError(
f"Expected HandoffUserInputRequest in request_info payload, got {type(payload).__name__}"
)
return content, payload
raise ValueError("No request_info function call found in response messages.")
def print_conversation(request: HandoffUserInputRequest) -> None:
"""Display the conversation history from a HandoffUserInputRequest."""
print("\n=== Conversation History ===")
for message in request.conversation:
speaker = message.author_name or message.role.value
print(f" [{speaker}]: {message.text}")
print(f" [Awaiting]: {request.awaiting_agent_id}")
print("============================")
raise ValueError("Invalid arguments type. Expecting a request info structure for this sample.")
if isinstance(request.data, HandoffAgentUserRequest):
pending_requests[request.request_id] = request.data
return pending_requests
async def main() -> None:
"""Main entry point demonstrating handoff workflow as agent.
"""Main entry point for the handoff workflow demo.
This demo:
1. Builds a handoff workflow with triage and specialist agents
2. Converts it to an agent using .as_agent()
3. Runs a multi-turn conversation with scripted user responses
4. Demonstrates the FunctionCallContent/FunctionResultContent pattern for HITL
This function demonstrates:
1. Creating triage and specialist agents
2. Building a handoff workflow with custom termination condition
3. Running the workflow with scripted user responses
4. Processing events and handling user input requests
The workflow uses scripted responses instead of interactive input to make
the demo reproducible and testable. In a production application, you would
replace the scripted_responses with actual user input collection.
"""
print("Starting Handoff Workflow as Agent Demo")
print("=" * 55)
# Initialize the Azure OpenAI chat client
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
# Create agents
# Create all agents: triage + specialists
triage, refund, order, support = create_agents(chat_client)
# Build the handoff workflow and convert to agent
# Termination condition: stop after 4 user messages
# Build the handoff workflow
# - participants: All agents that can participate in the workflow
# - with_start_agent: The triage agent is designated as the start agent, which means
# it receives all user input first and orchestrates handoffs to specialists
# - with_termination_condition: Custom logic to stop the request/response loop.
# Without this, the default behavior continues requesting user input until max_turns
# is reached. Here we use a custom condition that checks if the conversation has ended
# naturally (when one of the agents says something like "you're welcome").
agent = (
HandoffBuilder(
name="customer_support_handoff",
participants=[triage, refund, order, support],
)
.set_coordinator("triage_agent")
.with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role.value == "user") >= 4)
.with_start_agent(triage)
.with_termination_condition(
# Custom termination: Check if one of the agents has provided a closing message.
# This looks for the last message containing "welcome", which indicates the
# conversation has concluded naturally.
lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
)
.build()
.as_agent() # Convert workflow to agent interface
)
# Scripted user responses for reproducible demo
# In a console application, replace this with:
# user_input = input("Your response: ")
# or integrate with a UI/chat interface
scripted_responses = [
"My order 1234 arrived damaged and the packaging was destroyed.",
"Yes, I'd like a refund if that's possible.",
"Thanks for your help!",
"My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.",
"Please also process a refund for order 1234.",
"Thanks for resolving this.",
]
# Start the conversation
print("\n[User]: Hello, I need assistance with my recent purchase.")
response = await agent.run("Hello, I need assistance with my recent purchase.")
# Start the workflow with the initial user message
print("[Starting workflow with initial user message...]\n")
initial_message = "Hello, I need assistance with my recent purchase."
print(f"- User: {initial_message}")
response = await agent.run(initial_message)
pending_requests = handle_response_and_requests(response)
# Process conversation turns until workflow completes or responses exhausted
while True:
# Check if the agent is requesting user input
try:
function_call, handoff_request = extract_handoff_request(response.messages)
except ValueError:
# No request_info call found - workflow has completed
print("\n[Workflow completed - no pending requests]")
if response.messages:
final_text = response.messages[-1].text
if final_text:
print(f"[Final response]: {final_text}")
break
# Process the request/response cycle
# The workflow will continue requesting input until:
# 1. The termination condition is met, OR
# 2. We run out of scripted responses
while pending_requests:
for request in pending_requests.values():
for message in request.agent_response.messages:
if message.text:
print(f"- {message.author_name or message.role.value}: {message.text}")
# Display the conversation context
print_conversation(handoff_request)
# Get the next scripted response
if not scripted_responses:
print("\n[No more scripted responses - ending conversation]")
break
# No more scripted responses; terminate the workflow
responses = {req_id: HandoffAgentUserRequest.terminate() for req_id in pending_requests}
else:
# Get the next scripted response
user_response = scripted_responses.pop(0)
print(f"\n- User: {user_response}")
user_input = scripted_responses.pop(0)
# Send response(s) to all pending requests
# In this demo, there's typically one request per cycle, but the API supports multiple
responses = {req_id: HandoffAgentUserRequest.create_response(user_response) for req_id in pending_requests}
print(f"\n[User responding]: {user_input}")
# Create the function result to send back to the agent
# The result is the user's text response which gets converted to ChatMessage
function_result = FunctionResultContent(
call_id=function_call.call_id,
result=user_input,
)
# Send the response back to the agent
response = await agent.run(ChatMessage(role=Role.TOOL, contents=[function_result]))
print("\n" + "=" * 55)
print("Demo completed!")
function_results = [
FunctionResultContent(call_id=req_id, result=response) for req_id, response in responses.items()
]
response = await agent.run(ChatMessage(role=Role.TOOL, contents=function_results))
pending_requests = handle_response_and_requests(response)
if __name__ == "__main__":
print("Initializing Handoff Workflow as Agent Sample...")
asyncio.run(main())
python/samples/getting_started/workflows/agents/magentic_workflow_as_agent.py
+3 -21
View File
@@ -1,20 +1,14 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from agent_framework import (
MAGENTIC_EVENT_TYPE_AGENT_DELTA,
MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
ChatAgent,
HostedCodeInterpreterTool,
MagenticBuilder,
)
from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
"""
Sample: Build a Magentic orchestration and wrap it as an agent.
@@ -60,7 +54,7 @@ async def main() -> None:
workflow = (
MagenticBuilder()
.participants(researcher=researcher_agent, coder=coder_agent)
.participants([researcher_agent, coder_agent])
.with_standard_manager(
agent=manager_agent,
max_round_count=10,
@@ -87,20 +81,8 @@ async def main() -> None:
print("\nWrapping workflow as an agent and running...")
workflow_agent = workflow.as_agent(name="MagenticWorkflowAgent")
async for response in workflow_agent.run_stream(task):
# AgentRunResponseUpdate objects contain the streaming agent data
# Check metadata to understand event type
props = response.additional_properties
event_type = props.get("magentic_event_type") if props else None
if event_type == MAGENTIC_EVENT_TYPE_ORCHESTRATOR:
kind = props.get("orchestrator_message_kind", "") if props else ""
print(f"\n[ORCHESTRATOR:{kind}] {response.text}")
elif event_type == MAGENTIC_EVENT_TYPE_AGENT_DELTA:
if response.text:
print(response.text, end="", flush=True)
elif response.text:
# Fallback for any other events with text
print(response.text, end="", flush=True)
# Fallback for any other events with text
print(response.text, end="", flush=True)
except Exception as e:
print(f"Workflow execution failed: {e}")
python/samples/getting_started/workflows/composition/sub_workflow_basics.py
+1 -1
View File
@@ -12,7 +12,7 @@ from agent_framework import (
handler,
)
from typing_extensions import Never
"""
Sample: Sub-Workflows (Basics)
python/samples/getting_started/workflows/human-in-the-loop/concurrent_request_info.py
+36 -28
View File
@@ -4,17 +4,17 @@
Sample: Request Info with ConcurrentBuilder
This sample demonstrates using the `.with_request_info()` method to pause a
ConcurrentBuilder workflow AFTER all parallel agents complete but BEFORE
aggregation, allowing human review and modification of the combined results.
ConcurrentBuilder workflow for specific agents, allowing human review and
modification of individual agent outputs before aggregation.
Purpose:
Show how to use the request info API that pauses after concurrent agents run,
allowing review and steering of results before they are aggregated.
Show how to use the request info API that pauses for selected concurrent agents,
allowing review and steering of their results.
Demonstrate:
- Configuring request info with `.with_request_info()`
- Reviewing outputs from multiple concurrent agents
- Injecting human guidance after agents execute but before aggregation
- Configuring request info with `.with_request_info()` for specific agents
- Reviewing output from individual agents during concurrent execution
- Injecting human guidance for specific agents before aggregation
Prerequisites:
- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
@@ -25,7 +25,7 @@ import asyncio
from typing import Any
from agent_framework import (
AgentInputRequest,
AgentRequestInfoResponse,
ChatMessage,
ConcurrentBuilder,
RequestInfoEvent,
@@ -131,12 +131,13 @@ async def main() -> None:
ConcurrentBuilder()
.participants([technical_analyst, business_analyst, user_experience_analyst])
.with_aggregator(aggregate_with_synthesis)
.with_request_info()
# Only enable request info for the technical analyst agent
.with_request_info(agents=["technical_analyst"])
.build()
)
# Run the workflow with human-in-the-loop
pending_responses: dict[str, str] | None = None
pending_responses: dict[str, AgentRequestInfoResponse] | None = None
workflow_complete = False
print("Starting multi-perspective analysis workflow...")
@@ -155,26 +156,34 @@ async def main() -> None:
# Process events
async for event in stream:
if isinstance(event, RequestInfoEvent):
if isinstance(event.data, AgentInputRequest):
# Display pre-execution context for steering concurrent agents
if isinstance(event.data, AgentExecutorResponse):
# Display agent output for review and potential modification
print("\n" + "-" * 40)
print("INPUT REQUESTED (BEFORE CONCURRENT AGENTS)")
print("-" * 40)
print(f"About to call agents: {event.data.target_agent_id}")
print("Conversation context:")
recent = (
event.data.conversation[-2:] if len(event.data.conversation) > 2 else event.data.conversation
print("INPUT REQUESTED")
print(
f"Agent {event.source_executor_id} just responded with: '{event.data.agent_run_response.text}'. "
"Please provide your feedback."
)
for msg in recent:
role = msg.role.value if msg.role else "unknown"
text = (msg.text or "")[:150]
print(f" [{role}]: {text}...")
print("-" * 40)
if event.data.full_conversation:
print("Conversation context:")
recent = (
event.data.full_conversation[-2:]
if len(event.data.full_conversation) > 2
else event.data.full_conversation
)
for msg in recent:
name = msg.author_name or msg.role.value
text = (msg.text or "")[:150]
print(f" [{name}]: {text}...")
print("-" * 40)
# Get human input to steer all agents
user_input = input("Your guidance for the analysts (or 'skip' to continue): ") # noqa: ASYNC250
# Get human input to steer this agent's contribution
user_input = input("Your guidance for the analysts (or 'skip' to approve): ") # noqa: ASYNC250
if user_input.lower() == "skip":
user_input = "Please analyze objectively from your unique perspective."
user_input = AgentRequestInfoResponse.approve()
else:
user_input = AgentRequestInfoResponse.from_strings([user_input])
pending_responses = {event.request_id: user_input}
print("(Resuming workflow...)")
@@ -189,9 +198,8 @@ async def main() -> None:
print(event.data)
workflow_complete = True
elif isinstance(event, WorkflowStatusEvent):
if event.state == WorkflowRunState.IDLE:
workflow_complete = True
elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
workflow_complete = True
if __name__ == "__main__":
python/samples/getting_started/workflows/human-in-the-loop/group_chat_request_info.py
+27 -25
View File
@@ -25,7 +25,9 @@ Prerequisites:
import asyncio
from agent_framework import (
AgentInputRequest,
AgentExecutorResponse,
AgentRequestInfoResponse,
AgentRunResponse,
AgentRunUpdateEvent,
ChatMessage,
GroupChatBuilder,
@@ -69,18 +71,17 @@ async def main() -> None:
),
)
# Manager orchestrates the discussion
manager = chat_client.create_agent(
name="manager",
# Orchestrator coordinates the discussion
orchestrator = chat_client.create_agent(
name="orchestrator",
instructions=(
"You are a discussion manager coordinating a team conversation between optimist, "
"pragmatist, and creative. Your job is to select who speaks next.\n\n"
"You are a discussion manager coordinating a team conversation between participants. "
"Your job is to select who speaks next.\n\n"
"RULES:\n"
"1. Rotate through ALL participants - do not favor any single participant\n"
"2. Each participant should speak at least once before any participant speaks twice\n"
"3. If human feedback redirects the topic, acknowledge it and continue rotating\n"
"4. Continue for at least 5 participant turns before concluding\n"
"5. Do NOT select the same participant twice in a row"
"3. Continue for at least 5 rounds before ending the discussion\n"
"4. Do NOT select the same participant twice in a row"
),
)
@@ -88,7 +89,7 @@ async def main() -> None:
# Using agents= filter to only pause before pragmatist speaks (not every turn)
workflow = (
GroupChatBuilder()
.set_manager(manager=manager, display_name="Discussion Manager")
.with_agent_orchestrator(orchestrator)
.participants([optimist, pragmatist, creative])
.with_max_rounds(6)
.with_request_info(agents=[pragmatist]) # Only pause before pragmatist speaks
@@ -96,7 +97,7 @@ async def main() -> None:
)
# Run the workflow with human-in-the-loop
pending_responses: dict[str, str] | None = None
pending_responses: dict[str, AgentRequestInfoResponse] | None = None
workflow_complete = False
current_agent: str | None = None # Track current streaming agent
@@ -130,28 +131,28 @@ async def main() -> None:
elif isinstance(event, RequestInfoEvent):
current_agent = None # Reset for next agent
if isinstance(event.data, AgentInputRequest):
if isinstance(event.data, AgentExecutorResponse):
# Display pre-agent context for human input
print("\n" + "-" * 40)
print("INPUT REQUESTED")
print(f"About to call agent: {event.data.target_agent_id}")
print(f"About to call agent: {event.source_executor_id}")
print("-" * 40)
print("Conversation context:")
recent = (
event.data.conversation[-3:] if len(event.data.conversation) > 3 else event.data.conversation
)
agent_run_response: AgentRunResponse = event.data.agent_run_response
messages: list[ChatMessage] = agent_run_response.messages
recent: list[ChatMessage] = messages[-3:] if len(messages) > 3 else messages # type: ignore
for msg in recent:
role = msg.role.value if msg.role else "unknown"
name = msg.author_name or "unknown"
text = (msg.text or "")[:100]
print(f" [{role}]: {text}...")
print(f" [{name}]: {text}...")
print("-" * 40)
# Get human input to steer the agent
user_input = input("Steer the discussion (or 'skip' to continue): ") # noqa: ASYNC250
user_input = input(f"Feedback for {event.source_executor_id} (or 'skip' to approve): ") # noqa: ASYNC250
if user_input.lower() == "skip":
user_input = "Please continue the discussion naturally."
pending_responses = {event.request_id: user_input}
pending_responses = {event.request_id: AgentRequestInfoResponse.approve()}
else:
pending_responses = {event.request_id: AgentRequestInfoResponse.from_strings([user_input])}
print("(Resuming discussion...)")
elif isinstance(event, WorkflowOutputEvent):
@@ -160,11 +161,12 @@ async def main() -> None:
print("=" * 60)
print("Final conversation:")
if event.data:
messages: list[ChatMessage] = event.data[-4:]
messages: list[ChatMessage] = event.data
for msg in messages:
role = msg.role.value if msg.role else "unknown"
role = msg.role.value.capitalize()
name = msg.author_name or "unknown"
text = (msg.text or "")[:200]
print(f"[{role}]: {text}...")
print(f"[{role}][{name}]: {text}...")
workflow_complete = True
elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
python/samples/getting_started/workflows/human-in-the-loop/sequential_request_info.py
+37 -22
View File
@@ -4,11 +4,11 @@
Sample: Request Info with SequentialBuilder
This sample demonstrates using the `.with_request_info()` method to pause a
SequentialBuilder workflow BEFORE each agent runs, allowing external input
(e.g., human steering) before the agent responds.
SequentialBuilder workflow AFTER each agent runs, allowing external input
(e.g., human feedback) for review and optional iteration.
Purpose:
Show how to use the request info API that pauses before every agent response,
Show how to use the request info API that pauses after every agent response,
using the standard request_info pattern for consistency.
Demonstrate:
@@ -24,7 +24,8 @@ Prerequisites:
import asyncio
from agent_framework import (
AgentInputRequest,
AgentExecutorResponse,
AgentRequestInfoResponse,
ChatMessage,
RequestInfoEvent,
SequentialBuilder,
@@ -48,7 +49,7 @@ async def main() -> None:
editor = chat_client.create_agent(
name="editor",
instructions=(
"You are an editor. Review the draft and suggest improvements. "
"You are an editor. Review the draft and make improvements. "
"Incorporate any human feedback that was provided."
),
)
@@ -61,11 +62,17 @@ async def main() -> None:
),
)
# Build workflow with request info enabled (pauses before each agent)
workflow = SequentialBuilder().participants([drafter, editor, finalizer]).with_request_info().build()
# Build workflow with request info enabled (pauses after each agent responds)
workflow = (
SequentialBuilder()
.participants([drafter, editor, finalizer])
# Only enable request info for the editor agent
.with_request_info(agents=["editor"])
.build()
)
# Run the workflow with request info handling
pending_responses: dict[str, str] | None = None
pending_responses: dict[str, AgentRequestInfoResponse] | None = None
workflow_complete = False
print("Starting document review workflow...")
@@ -84,26 +91,34 @@ async def main() -> None:
# Process events
async for event in stream:
if isinstance(event, RequestInfoEvent):
if isinstance(event.data, AgentInputRequest):
# Display pre-agent context for steering
if isinstance(event.data, AgentExecutorResponse):
# Display agent response and conversation context for review
print("\n" + "-" * 40)
print("REQUEST INFO: INPUT REQUESTED")
print(f"About to call agent: {event.data.target_agent_id}")
print("-" * 40)
print("Conversation context:")
recent = (
event.data.conversation[-2:] if len(event.data.conversation) > 2 else event.data.conversation
print(
f"Agent {event.source_executor_id} just responded with: '{event.data.agent_run_response.text}'. "
"Please provide your feedback."
)
for msg in recent:
role = msg.role.value if msg.role else "unknown"
text = (msg.text or "")[:150]
print(f" [{role}]: {text}...")
print("-" * 40)
if event.data.full_conversation:
print("Conversation context:")
recent = (
event.data.full_conversation[-2:]
if len(event.data.full_conversation) > 2
else event.data.full_conversation
)
for msg in recent:
name = msg.author_name or msg.role.value
text = (msg.text or "")[:150]
print(f" [{name}]: {text}...")
print("-" * 40)
# Get input to steer the agent
user_input = input("Your guidance (or 'skip' to continue): ") # noqa: ASYNC250
# Get feedback on the agent's response (approve or request iteration)
user_input = input("Your guidance (or 'skip' to approve): ") # noqa: ASYNC250
if user_input.lower() == "skip":
user_input = "Please continue naturally."
user_input = AgentRequestInfoResponse.approve()
else:
user_input = AgentRequestInfoResponse.from_strings([user_input])
pending_responses = {event.request_id: user_input}
print("(Resuming workflow...)")
python/samples/getting_started/workflows/orchestration/group_chat_agent_manager.py
+43 -38
View File
@@ -1,8 +1,6 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from typing import cast
from agent_framework import (
AgentRunUpdateEvent,
@@ -15,8 +13,6 @@ from agent_framework import (
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
logging.basicConfig(level=logging.INFO)
"""
Sample: Group Chat with Agent-Based Manager
@@ -29,50 +25,54 @@ Prerequisites:
- OpenAI environment variables configured for OpenAIChatClient
"""
def _get_chat_client() -> AzureOpenAIChatClient:
return AzureOpenAIChatClient(credential=AzureCliCredential())
async def main() -> None:
# Create coordinator agent with structured output for speaker selection
# Note: response_format is enforced to ManagerSelectionResponse by set_manager()
coordinator = ChatAgent(
name="Coordinator",
description="Coordinates multi-agent collaboration by selecting speakers",
instructions="""
ORCHESTRATOR_AGENT_INSTRUCTIONS = """
You coordinate a team conversation to solve the user's task.
Review the conversation history and select the next participant to speak.
Guidelines:
- Start with Researcher to gather information
- Then have Writer synthesize the final answer
- Only finish after both have contributed meaningfully
- Allow for multiple rounds of information gathering if needed
""",
chat_client=_get_chat_client(),
"""
async def main() -> None:
# Create a chat client using Azure OpenAI and Azure CLI credentials for all agents
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
# Orchestrator agent that manages the conversation
# Note: This agent (and the underlying chat client) must support structured outputs.
# The group chat workflow relies on this to parse the orchestrator's decisions.
# `response_format` is set internally by the GroupChat workflow when the agent is invoked.
orchestrator_agent = ChatAgent(
name="Orchestrator",
description="Coordinates multi-agent collaboration by selecting speakers",
instructions=ORCHESTRATOR_AGENT_INSTRUCTIONS,
chat_client=chat_client,
)
# Participant agents
researcher = ChatAgent(
name="Researcher",
description="Collects relevant background information",
instructions="Gather concise facts that help a teammate answer the question.",
chat_client=_get_chat_client(),
chat_client=chat_client,
)
writer = ChatAgent(
name="Writer",
description="Synthesizes polished answers from gathered information",
instructions="Compose clear and structured answers using any notes provided.",
chat_client=_get_chat_client(),
chat_client=chat_client,
)
# Build the group chat workflow
workflow = (
GroupChatBuilder()
.set_manager(coordinator, display_name="Orchestrator")
.with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 2)
.with_agent_orchestrator(orchestrator_agent)
.participants([researcher, writer])
# Set a hard termination condition: stop after 4 assistant messages
# The agent orchestrator will intelligently decide when to end before this limit but just in case
.with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 4)
.build()
)
@@ -82,30 +82,35 @@ Guidelines:
print(f"TASK: {task}\n")
print("=" * 80)
final_conversation: list[ChatMessage] = []
# Keep track of the last executor to format output nicely in streaming mode
last_executor_id: str | None = None
output_event: WorkflowOutputEvent | None = None
async for event in workflow.run_stream(task):
if isinstance(event, AgentRunUpdateEvent):
eid = event.executor_id
if eid != last_executor_id:
if last_executor_id is not None:
print()
print("\n")
print(f"{eid}:", end=" ", flush=True)
last_executor_id = eid
print(event.data, end="", flush=True)
elif isinstance(event, WorkflowOutputEvent):
final_conversation = cast(list[ChatMessage], event.data)
output_event = event
if final_conversation and isinstance(final_conversation, list):
print("\n\n" + "=" * 80)
print("FINAL CONVERSATION")
print("=" * 80)
for msg in final_conversation:
author = getattr(msg, "author_name", "Unknown")
text = getattr(msg, "text", str(msg))
print(f"\n[{author}]")
print(text)
print("-" * 80)
# The output of the workflow is the full list of messages exchanged
if output_event:
if not isinstance(output_event.data, list) or not all(
isinstance(msg, ChatMessage)
for msg in output_event.data # type: ignore
):
raise RuntimeError("Unexpected output event data format.")
print("\n" + "=" * 80)
print("\nFINAL OUTPUT (The conversation history)\n")
for msg in output_event.data: # type: ignore
assert isinstance(msg, ChatMessage)
print(f"{msg.author_name or msg.role}: {msg.text}\n")
else:
raise RuntimeError("Workflow did not produce a final output event.")
if __name__ == "__main__":
python/samples/getting_started/workflows/orchestration/group_chat_philosophical_debate.py
+4 -48
View File
@@ -211,7 +211,7 @@ Share your perspective authentically. Feel free to:
workflow = (
GroupChatBuilder()
.set_manager(moderator, display_name="Moderator")
.with_agent_orchestrator(moderator)
.participants([farmer, developer, teacher, activist, spiritual_leader, artist, immigrant, doctor])
.with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 10)
.build()
@@ -241,13 +241,11 @@ Share your perspective authentically. Feel free to:
async for event in workflow.run_stream(f"Please begin the discussion on: {topic}"):
if isinstance(event, AgentRunUpdateEvent):
speaker_id = event.executor_id.replace("groupchat_agent:", "")
if speaker_id != current_speaker:
if event.executor_id != current_speaker:
if current_speaker is not None:
print("\n")
print(f"[{speaker_id}]", flush=True)
current_speaker = speaker_id
print(f"[{event.executor_id}]", flush=True)
current_speaker = event.executor_id
print(event.data, end="", flush=True)
@@ -286,10 +284,6 @@ Share your perspective authentically. Feel free to:
DISCUSSION BEGINS
================================================================================
[Moderator]
{"selected_participant":"Farmer","instruction":"Please start by sharing what living a good life means to you,
especially from your perspective living in a rural area in Southeast Asia.","finish":false,"final_message":null}
[Farmer]
To me, a good life is deeply intertwined with the rhythm of the land and the nurturing of relationships with my
family and community. It means cultivating crops that respect our environment, ensuring sustainability for future
@@ -298,11 +292,6 @@ Share your perspective authentically. Feel free to:
wealth. It's the simple moments, like sharing stories with my children under the stars, that truly define a good
life. What good is progress if it isolates us from those we love and the land that sustains us?
[Moderator]
{"selected_participant":"Developer","instruction":"Given the insights shared by the Farmer, please discuss what a
good life means to you as a software developer in an urban setting in the United States and how it might contrast
with or complement the Farmer's view.","finish":false,"final_message":null}
[Developer]
As a software developer in an urban environment, a good life for me hinges on the intersection of innovation,
creativity, and balance. It's about having the freedom to explore new technologies that can solve real-world
@@ -312,11 +301,6 @@ Share your perspective authentically. Feel free to:
rich personal experiences. The challenge is finding harmony between technological progress and preserving the
intimate human connections that truly enrich our lives.
[Moderator]
{"selected_participant":"SpiritualLeader","instruction":"Reflect on both the Farmer's and Developer's perspectives
and share your view of what constitutes a good life, particularly from your spiritual and cultural standpoint in
the Middle East.","finish":false,"final_message":null}
[SpiritualLeader]
From my spiritual perspective, a good life embodies a balance between personal fulfillment and service to others,
rooted in compassion and community. In our teachings, we emphasize that true happiness comes from helping those in
@@ -326,11 +310,6 @@ Share your perspective authentically. Feel free to:
with those around us. Ultimately, as we align our personal beliefs with our communal responsibilities, we cultivate
a richness that transcends material wealth.
[Moderator]
{"selected_participant":"Activist","instruction":"Add to the discussion by sharing your perspective on what a good
life entails, particularly from your background as a young activist in South America.","finish":false,
"final_message":null}
[Activist]
As a young activist in South America, a good life for me is about advocating for social justice and environmental
sustainability. It means living in a society where everyone's rights are respected and where marginalized voices,
@@ -341,11 +320,6 @@ Share your perspective authentically. Feel free to:
not just lived for oneself but is deeply tied to the well-being of our communities and the health of our
environment. How can we, regardless of our backgrounds, collaborate to foster these essential changes?
[Moderator]
{"selected_participant":"Teacher","instruction":"Considering the views shared so far, tell us how your experience
as a retired history teacher from Eastern Europe shapes your understanding of a good life, perhaps reflecting on
lessons from the past and their impact on present-day life choices.","finish":false,"final_message":null}
[Teacher]
As a retired history teacher from Eastern Europe, my understanding of a good life is deeply rooted in the lessons
drawn from history and the struggle for freedom and dignity. Historical events, such as the fall of the Iron
@@ -357,11 +331,6 @@ Share your perspective authentically. Feel free to:
contributions to the rich tapestry of our shared humanity. How can we ensure that the lessons of history inform a
more compassionate and just society moving forward?
[Moderator]
{"selected_participant":"Artist","instruction":"Expound on the themes and perspectives discussed so far by sharing
how, as an artist from Africa, you define a good life and how art plays a role in that vision.","finish":false,
"final_message":null}
[Artist]
As an artist from Africa, I define a good life as one steeped in cultural expression, storytelling, and the
celebration of our collective memories. Art is a powerful medium through which we capture our histories, struggles,
@@ -373,19 +342,6 @@ Share your perspective authentically. Feel free to:
collective good, fostering empathy and understanding among diverse communities. How can we harness art to bridge
differences and amplify marginalized voices in our pursuit of a good life?
[Moderator]
{"selected_participant":null,"instruction":null,"finish":true,"final_message":"As our discussion unfolds, several
key themes have gracefully emerged, reflecting the richness of diverse perspectives on what constitutes a good life.
From the rural farmer's integration with the land to the developer's search for balance between technology and
personal connection, each viewpoint validates that fulfillment, at its core, transcends material wealth. The
spiritual leader and the activist highlight the importance of community and social justice, while the history
teacher and the artist remind us of the lessons and narratives that shape our cultural and personal identities.
Ultimately, the good life seems to revolve around meaningful relationships, honoring our legacies while striving for
progress, and nurturing both our inner selves and external communities. This dialogue demonstrates that despite our
varied backgrounds and experiences, the quest for a good life binds us together, urging cooperation and empathy in
our shared human journey."}
================================================================================
DISCUSSION SUMMARY
================================================================================
python/samples/getting_started/workflows/orchestration/group_chat_simple_selector.py
+97 -76
View File
@@ -1,113 +1,134 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from typing import cast
from agent_framework import ChatAgent, ChatMessage, GroupChatBuilder, GroupChatStateSnapshot, WorkflowOutputEvent
from agent_framework.openai import OpenAIChatClient
logging.basicConfig(level=logging.INFO)
from agent_framework import (
AgentRunUpdateEvent,
ChatAgent,
ChatMessage,
GroupChatBuilder,
GroupChatState,
WorkflowOutputEvent,
)
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
"""
Sample: Group Chat with Simple Speaker Selector Function
Sample: Group Chat with a round-robin speaker selector
What it does:
- Demonstrates the set_select_speakers_func() API for GroupChat orchestration
- Demonstrates the with_select_speaker_func() API for GroupChat orchestration
- Uses a pure Python function to control speaker selection based on conversation state
- Alternates between researcher and writer agents in a simple round-robin pattern
- Shows how to access conversation history, round index, and participant metadata
Key pattern:
def select_next_speaker(state: GroupChatStateSnapshot) -> str | None:
# state contains: task, participants, conversation, history, round_index
# Return participant name to continue, or None to finish
...
Prerequisites:
- OpenAI environment variables configured for OpenAIChatClient
"""
def select_next_speaker(state: GroupChatStateSnapshot) -> str | None:
"""Simple speaker selector that alternates between researcher and writer.
def round_robin_selector(state: GroupChatState) -> str:
"""A round-robin selector function that picks the next speaker based on the current round index."""
This function demonstrates the core pattern:
1. Examine the current state of the group chat
2. Decide who should speak next
3. Return participant name or None to finish
Args:
state: Immutable snapshot containing:
- task: ChatMessage - original user task
- participants: dict[str, str] - participant names → descriptions
- conversation: tuple[ChatMessage, ...] - full conversation history
- history: tuple[GroupChatTurn, ...] - turn-by-turn with speaker attribution
- round_index: int - number of selection rounds so far
- pending_agent: str | None - currently active agent (if any)
Returns:
Name of next speaker, or None to finish the conversation
"""
round_idx = state["round_index"]
history = state["history"]
# Finish after 4 turns (researcher → writer → researcher → writer)
if round_idx >= 4:
return None
# Get the last speaker from history
last_speaker = history[-1].speaker if history else None
# Simple alternation: researcher → writer → researcher → writer
if last_speaker == "Researcher":
return "Writer"
return "Researcher"
participant_names = list(state.participants.keys())
return participant_names[state.current_round % len(participant_names)]
async def main() -> None:
researcher = ChatAgent(
name="Researcher",
description="Collects relevant background information.",
instructions="Gather concise facts that help answer the question. Be brief.",
chat_client=OpenAIChatClient(model_id="gpt-4o-mini"),
# Create a chat client using Azure OpenAI and Azure CLI credentials for all agents
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
# Participant agents
expert = ChatAgent(
name="PythonExpert",
instructions=(
"You are an expert in Python in a workgroup. "
"Your job is to answer Python related questions and refine your answer "
"based on feedback from all the other participants."
),
chat_client=chat_client,
)
writer = ChatAgent(
name="Writer",
description="Synthesizes a polished answer using the gathered notes.",
instructions="Compose a clear, structured answer using any notes provided.",
chat_client=OpenAIChatClient(model_id="gpt-4o-mini"),
verifier = ChatAgent(
name="AnswerVerifier",
instructions=(
"You are a programming expert in a workgroup. "
f"Your job is to review the answer provided by {expert.name} and point "
"out statements that are technically true but practically dangerous."
"If there is nothing woth pointing out, respond with 'The answer looks good to me.'"
),
chat_client=chat_client,
)
# Two ways to specify participants:
# 1. List form - uses agent.name attribute: .participants([researcher, writer])
# 2. Dict form - explicit names: .participants(researcher=researcher, writer=writer)
clarifier = ChatAgent(
name="AnswerClarifier",
instructions=(
"You are an accessibility expert in a workgroup. "
f"Your job is to review the answer provided by {expert.name} and point "
"out jargons or complex terms that may be difficult for a beginner to understand."
"If there is nothing worth pointing out, respond with 'The answer looks clear to me.'"
),
chat_client=chat_client,
)
skeptic = ChatAgent(
name="Skeptic",
instructions=(
"You are a devil's advocate in a workgroup. "
f"Your job is to review the answer provided by {expert.name} and point "
"out caveats, exceptions, and alternative perspectives."
"If there is nothing worth pointing out, respond with 'I have no further questions.'"
),
chat_client=chat_client,
)
# Build the group chat workflow
workflow = (
GroupChatBuilder()
.set_select_speakers_func(select_next_speaker, display_name="Orchestrator")
.participants([researcher, writer]) # Uses agent.name for participant names
.participants([expert, verifier, clarifier, skeptic])
.with_select_speaker_func(round_robin_selector)
# Set a hard termination condition: stop after 6 messages (user task + one full rounds + 1)
# One round is expert -> verifier -> clarifier -> skeptic, after which the expert gets to respond again.
# This will end the conversation after the expert has spoken 2 times (one iteration loop)
# Note: it's possible that the expert gets it right the first time and the other participants
# have nothing to add, but for demo purposes we want to see at least one full round of interaction.
.with_termination_condition(lambda conversation: len(conversation) >= 6)
.build()
)
task = "What are the key benefits of using async/await in Python?"
task = "How does Python’s Protocol differ from abstract base classes?"
print("\nStarting Group Chat with Simple Speaker Selector...\n")
print("\nStarting Group Chat with round-robin speaker selector...\n")
print(f"TASK: {task}\n")
print("=" * 80)
# Keep track of the last executor to format output nicely in streaming mode
last_executor_id: str | None = None
output_event: WorkflowOutputEvent | None = None
async for event in workflow.run_stream(task):
if isinstance(event, WorkflowOutputEvent):
conversation = cast(list[ChatMessage], event.data)
if isinstance(conversation, list):
print("\n===== Final Conversation =====\n")
for msg in conversation:
author = getattr(msg, "author_name", "Unknown")
text = getattr(msg, "text", str(msg))
print(f"[{author}]\n{text}\n")
print("-" * 80)
if isinstance(event, AgentRunUpdateEvent):
eid = event.executor_id
if eid != last_executor_id:
if last_executor_id is not None:
print("\n")
print(f"{eid}:", end=" ", flush=True)
last_executor_id = eid
print(event.data, end="", flush=True)
elif isinstance(event, WorkflowOutputEvent):
output_event = event
print("\nWorkflow completed.")
# The output of the workflow is the full list of messages exchanged
if output_event:
if not isinstance(output_event.data, list) or not all(
isinstance(msg, ChatMessage)
for msg in output_event.data # type: ignore
):
raise RuntimeError("Unexpected output event data format.")
print("\n" + "=" * 80)
print("\nFINAL OUTPUT (The conversation history)\n")
for msg in output_event.data: # type: ignore
assert isinstance(msg, ChatMessage)
print(f"{msg.author_name or msg.role}: {msg.text}\n")
else:
raise RuntimeError("Workflow did not produce a final output event.")
if __name__ == "__main__":
python/samples/getting_started/workflows/orchestration/handoff_autonomous.py
+20 -9
View File
@@ -13,6 +13,7 @@ from agent_framework import (
HostedWebSearchTool,
WorkflowEvent,
WorkflowOutputEvent,
resolve_agent_id,
)
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
@@ -21,7 +22,7 @@ logging.basicConfig(level=logging.ERROR)
"""Sample: Autonomous handoff workflow with agent iteration.
This sample demonstrates `with_interaction_mode("autonomous")`, where agents continue
This sample demonstrates `.with_autonomous_mode()`, where agents continue
iterating on their task until they explicitly invoke a handoff tool. This allows
specialists to perform long-running autonomous work (research, coding, analysis)
without prematurely returning control to the coordinator or user.
@@ -35,7 +36,7 @@ Prerequisites:
Key Concepts:
- Autonomous interaction mode: agents iterate until they handoff
- Turn limits: use `with_interaction_mode("autonomous", autonomous_turn_limit=N)` to cap total iterations
- Turn limits: use `.with_autonomous_mode(turn_limits={agent_name: N})` to cap iterations per agent
"""
@@ -53,7 +54,7 @@ def create_agents(
research_agent = chat_client.create_agent(
instructions=(
"You are a research specialist that explores topics thoroughly on the Microsoft Learn Site."
"You are a research specialist that explores topics thoroughly using web search. "
"When given a research task, break it down into multiple aspects and explore each one. "
"Continue your research across multiple responses - don't try to finish everything in one "
"response. After each response, think about what else needs to be explored. When you have "
@@ -112,11 +113,21 @@ async def main() -> None:
name="autonomous_iteration_handoff",
participants=[coordinator, research_agent, summary_agent],
)
.set_coordinator(coordinator)
.with_start_agent(coordinator)
.add_handoff(coordinator, [research_agent, summary_agent])
.add_handoff(research_agent, coordinator) # Research can hand back to coordinator
.add_handoff(summary_agent, coordinator)
.with_interaction_mode("autonomous", autonomous_turn_limit=15)
.add_handoff(research_agent, [coordinator]) # Research can hand back to coordinator
.add_handoff(summary_agent, [coordinator])
.with_autonomous_mode(
# You can set turn limits per agent to allow some agents to go longer.
# If a limit is not set, the agent will get an default limit: 50.
# Internally, handoff prefers agent names as the agent identifiers if set.
# Otherwise, it falls back to agent IDs.
turn_limits={
resolve_agent_id(coordinator): 5,
resolve_agent_id(research_agent): 10,
resolve_agent_id(summary_agent): 5,
}
)
.with_termination_condition(
# Terminate after coordinator provides 5 assistant responses
lambda conv: sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role.value == "assistant")
@@ -133,10 +144,10 @@ async def main() -> None:
"""
Expected behavior:
- Coordinator routes to research_agent.
- Research agent iterates multiple times, exploring different aspects of renewable energy.
- Research agent iterates multiple times, exploring different aspects of Microsoft Agent Framework.
- Each iteration adds to the conversation without returning to coordinator.
- After thorough research, research_agent calls handoff to coordinator.
- Coordinator provides final summary.
- Coordinator routes to summary_agent for final summary.
In autonomous mode, agents continue working until they invoke a handoff tool,
allowing the research_agent to perform 3-4+ responses before handing off.
python/samples/getting_started/workflows/orchestration/handoff_participant_factory.py
+68 -57
View File
@@ -2,28 +2,30 @@
import asyncio
import logging
from collections.abc import AsyncIterable
from typing import cast
from typing import Annotated, cast
from agent_framework import (
AgentRunEvent,
AgentRunResponse,
ChatAgent,
ChatMessage,
HandoffAgentUserRequest,
HandoffBuilder,
HandoffUserInputRequest,
HandoffSentEvent,
RequestInfoEvent,
Role,
Workflow,
WorkflowEvent,
WorkflowOutputEvent,
WorkflowRunState,
WorkflowStatusEvent,
ai_function,
)
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
from typing import Annotated
logging.basicConfig(level=logging.ERROR)
"""Sample: Autonomous handoff workflow with agent factory.
"""Sample: Handoff workflow with participant factories for state isolation.
This sample demonstrates how to use participant factories in HandoffBuilder to create
agents dynamically.
@@ -33,7 +35,7 @@ instances created by the same builder. This is particularly useful when you need
requests or tasks in parallel with stateful participants.
Routing Pattern:
User -> Coordinator -> Specialist (iterates N times) -> Handoff -> Final Output
User -> Triage Agent -> Specialist (Refund/Order Status/Return) -> User
Prerequisites:
- `az login` (Azure CLI authentication)
@@ -41,6 +43,7 @@ Prerequisites:
Key Concepts:
- Participant factories: create agents via factory functions for isolation
- State isolation: each workflow instance gets its own agent instances
"""
@@ -103,21 +106,6 @@ def create_return_agent() -> ChatAgent:
)
async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]:
"""Collect all events from an async stream into a list.
This helper drains the workflow's event stream so we can process events
synchronously after each workflow step completes.
Args:
stream: Async iterable of WorkflowEvent
Returns:
List of all events from the stream
"""
return [event async for event in stream]
def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
"""Process workflow events and extract any pending user input requests.
@@ -136,75 +124,98 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
requests: list[RequestInfoEvent] = []
for event in events:
# AgentRunEvent: Contains messages generated by agents during their turn
if isinstance(event, AgentRunEvent):
for message in event.data.messages:
if not message.text:
# Skip messages without text (e.g., tool calls)
continue
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
# HandoffSentEvent: Indicates a handoff has been initiated
if isinstance(event, HandoffSentEvent):
print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
# WorkflowStatusEvent: Indicates workflow state changes
if isinstance(event, WorkflowStatusEvent) and event.state in {
WorkflowRunState.IDLE,
WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
}:
print(f"\n[Workflow Status] {event.state.name}")
# WorkflowOutputEvent: Contains the final conversation when workflow terminates
if isinstance(event, WorkflowOutputEvent):
elif isinstance(event, WorkflowOutputEvent):
conversation = cast(list[ChatMessage], event.data)
if isinstance(conversation, list):
print("\n=== Final Conversation Snapshot ===")
for message in conversation:
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
print("===================================")
# RequestInfoEvent: Workflow is requesting user input
elif isinstance(event, RequestInfoEvent):
if isinstance(event.data, HandoffUserInputRequest):
_print_agent_responses_since_last_user_message(event.data)
if isinstance(event.data, HandoffAgentUserRequest):
_print_handoff_agent_user_request(event.data.agent_response)
requests.append(event)
return requests
def _print_agent_responses_since_last_user_message(request: HandoffUserInputRequest) -> None:
"""Display agent responses since the last user message in a handoff request.
def _print_handoff_agent_user_request(response: AgentRunResponse) -> None:
"""Display the agent's response messages when requesting user input.
The HandoffUserInputRequest contains the full conversation history so far,
allowing the user to see what's been discussed before providing their next input.
This will happen when an agent generates a response that doesn't trigger
a handoff, i.e., the agent is asking the user for more information.
Args:
request: The user input request containing conversation and prompt
response: The AgentRunResponse from the agent requesting user input
"""
if not request.conversation:
raise RuntimeError("HandoffUserInputRequest missing conversation history.")
if not response.messages:
raise RuntimeError("Cannot print agent responses: response has no messages.")
# Reverse iterate to collect agent responses since last user message
agent_responses: list[ChatMessage] = []
for message in request.conversation[::-1]:
if message.role == Role.USER:
break
agent_responses.append(message)
print("\n[Agent is requesting your input...]")
# Print agent responses in original order
agent_responses.reverse()
for message in agent_responses:
# Print agent responses
for message in response.messages:
if not message.text:
# Skip messages without text (e.g., tool calls)
continue
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
async def _run_Workflow(workflow: Workflow, user_inputs: list[str]) -> None:
async def _run_workflow(workflow: Workflow, user_inputs: list[str]) -> None:
"""Run the workflow with the given user input and display events."""
print(f"- User: {user_inputs[0]}")
events = await _drain(workflow.run_stream(user_inputs[0]))
pending_requests = _handle_events(events)
workflow_result = await workflow.run(user_inputs[0])
pending_requests = _handle_events(workflow_result)
# Process the request/response cycle
# The workflow will continue requesting input until:
# 1. The termination condition is met (4 user messages in this case), OR
# 2. We run out of scripted responses
while pending_requests and user_inputs[1:]:
# Get the next scripted response
user_response = user_inputs.pop(1)
print(f"\n- User: {user_response}")
while pending_requests:
if user_inputs[1:]:
# Get the next scripted response
user_response = user_inputs.pop(1)
print(f"\n- User: {user_response}")
# Send response(s) to all pending requests
# In this demo, there's typically one request per cycle, but the API supports multiple
responses = {req.request_id: user_response for req in pending_requests}
# Send response(s) to all pending requests
# In this demo, there's typically one request per cycle, but the API supports multiple
responses = {
req.request_id: HandoffAgentUserRequest.create_response(user_response) for req in pending_requests
}
else:
# No more scripted responses; terminate the workflow
responses = {req.request_id: HandoffAgentUserRequest.terminate() for req in pending_requests}
# Send responses and get new events
# We use send_responses_streaming() to get events as they occur, allowing us to
# display agent responses in real-time and handle new requests as they arrive
events = await _drain(workflow.send_responses_streaming(responses))
pending_requests = _handle_events(events)
workflow_result = await workflow.send_responses(responses)
pending_requests = _handle_events(workflow_result)
async def main() -> None:
@@ -220,7 +231,7 @@ async def main() -> None:
"return": create_return_agent,
},
)
.set_coordinator("triage")
.with_start_agent("triage")
.with_termination_condition(
# Custom termination: Check if the triage agent has provided a closing message.
# This looks for the last message being from triage_agent and containing "welcome",
@@ -244,14 +255,14 @@ async def main() -> None:
workflow_a = workflow_builder.build()
print("=== Running workflow_a ===")
await _run_Workflow(workflow_a, list(user_inputs))
await _run_workflow(workflow_a, list(user_inputs))
workflow_b = workflow_builder.build()
print("=== Running workflow_b ===")
# Only provide the last two inputs to workflow_b to demonstrate state isolation
# The agents in this workflow have no prior context thus should not have knowledge of
# order 1234 or previous interactions.
await _run_Workflow(workflow_b, user_inputs[2:])
await _run_workflow(workflow_b, user_inputs[2:])
"""
Expected behavior:
- workflow_a and workflow_b maintain separate states for their participants.
python/samples/getting_started/workflows/orchestration/handoff_return_to_previous.py
-294
View File
@@ -1,294 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from collections.abc import AsyncIterable
from typing import cast
from agent_framework import (
ChatAgent,
HandoffBuilder,
HandoffUserInputRequest,
RequestInfoEvent,
WorkflowEvent,
WorkflowOutputEvent,
)
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
"""Sample: Handoff workflow with return-to-previous routing enabled.
This interactive sample demonstrates the return-to-previous feature where user inputs
route directly back to the specialist currently handling their request, rather than
always going through the coordinator for re-evaluation.
Routing Pattern (with return-to-previous enabled):
User -> Coordinator -> Technical Support -> User -> Technical Support -> ...
Routing Pattern (default, without return-to-previous):
User -> Coordinator -> Technical Support -> User -> Coordinator -> Technical Support -> ...
This is useful when a specialist needs multiple turns with the user to gather
information or resolve an issue, avoiding unnecessary coordinator involvement.
Specialist-to-Specialist Handoff:
When a user's request changes to a topic outside the current specialist's domain,
the specialist can hand off DIRECTLY to another specialist without going back through
the coordinator:
User -> Coordinator -> Technical Support -> User -> Technical Support (billing question)
-> Billing -> User -> Billing ...
Example Interaction:
1. User reports a technical issue
2. Coordinator routes to technical support specialist
3. Technical support asks clarifying questions
4. User provides details (routes directly back to technical support)
5. Technical support continues troubleshooting with full context
6. Issue resolved, user asks about billing
7. Technical support hands off DIRECTLY to billing specialist
8. Billing specialist helps with payment
9. User continues with billing (routes directly to billing)
Prerequisites:
- `az login` (Azure CLI authentication)
- Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
Usage:
Run the script and interact with the support workflow by typing your requests.
Type 'exit' or 'quit' to end the conversation.
Key Concepts:
- Return-to-previous: Direct routing to current agent handling the conversation
- Current agent tracking: Framework remembers which agent is actively helping the user
- Context preservation: Specialist maintains full conversation context
- Domain switching: Specialists can hand back to coordinator when topic changes
"""
def create_agents(chat_client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAgent, ChatAgent, ChatAgent]:
"""Create and configure the coordinator and specialist agents.
Returns:
Tuple of (coordinator, technical_support, account_specialist, billing_agent)
"""
coordinator = chat_client.create_agent(
instructions=(
"You are a customer support coordinator. Analyze the user's request and route to "
"the appropriate specialist:\n"
"- technical_support for technical issues, troubleshooting, repairs, hardware/software problems\n"
"- account_specialist for account changes, profile updates, settings, login issues\n"
"- billing_agent for payments, invoices, refunds, charges, billing questions\n"
"\n"
"When you receive a request, immediately call the matching handoff tool without explaining. "
"Read the most recent user message to determine the correct specialist."
),
name="coordinator",
)
technical_support = chat_client.create_agent(
instructions=(
"You provide technical support. Help users troubleshoot technical issues, "
"arrange repairs, and answer technical questions. "
"Gather information through conversation. "
"If the user asks about billing, payments, invoices, or refunds, hand off to billing_agent. "
"If the user asks about account settings or profile changes, hand off to account_specialist."
),
name="technical_support",
)
account_specialist = chat_client.create_agent(
instructions=(
"You handle account management. Help with profile updates, account settings, "
"and preferences. Gather information through conversation. "
"If the user asks about technical issues or troubleshooting, hand off to technical_support. "
"If the user asks about billing, payments, invoices, or refunds, hand off to billing_agent."
),
name="account_specialist",
)
billing_agent = chat_client.create_agent(
instructions=(
"You handle billing only. Process payments, explain invoices, handle refunds. "
"If the user asks about technical issues or troubleshooting, hand off to technical_support. "
"If the user asks about account settings or profile changes, hand off to account_specialist."
),
name="billing_agent",
)
return coordinator, technical_support, account_specialist, billing_agent
def handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
"""Process events and return pending input requests."""
pending_requests: list[RequestInfoEvent] = []
for event in events:
if isinstance(event, RequestInfoEvent):
pending_requests.append(event)
request_data = cast(HandoffUserInputRequest, event.data)
print(f"\n{'=' * 60}")
print(f"AWAITING INPUT FROM: {request_data.awaiting_agent_id.upper()}")
print(f"{'=' * 60}")
for msg in request_data.conversation[-3:]:
author = msg.author_name or msg.role.value
prefix = ">>> " if author == request_data.awaiting_agent_id else " "
print(f"{prefix}[{author}]: {msg.text}")
elif isinstance(event, WorkflowOutputEvent):
print(f"\n{'=' * 60}")
print("[WORKFLOW COMPLETE]")
print(f"{'=' * 60}")
return pending_requests
async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]:
"""Drain an async iterable into a list."""
events: list[WorkflowEvent] = []
async for event in stream:
events.append(event)
return events
async def main() -> None:
"""Demonstrate return-to-previous routing in a handoff workflow."""
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
coordinator, technical, account, billing = create_agents(chat_client)
print("Handoff Workflow with Return-to-Previous Routing")
print("=" * 60)
print("\nThis interactive demo shows how user inputs route directly")
print("to the specialist handling your request, avoiding unnecessary")
print("coordinator re-evaluation on each turn.")
print("\nSpecialists can hand off directly to other specialists when")
print("your request changes topics (e.g., from technical to billing).")
print("\nType 'exit' or 'quit' to end the conversation.\n")
# Configure handoffs with return-to-previous enabled
# Specialists can hand off directly to other specialists when topic changes
workflow = (
HandoffBuilder(
name="return_to_previous_demo",
participants=[coordinator, technical, account, billing],
)
.set_coordinator(coordinator)
.add_handoff(coordinator, [technical, account, billing]) # Coordinator routes to all specialists
.add_handoff(technical, [billing, account]) # Technical can route to billing or account
.add_handoff(account, [technical, billing]) # Account can route to technical or billing
.add_handoff(billing, [technical, account]) # Billing can route to technical or account
.enable_return_to_previous(True) # Enable the `return to previous handoff` feature
.with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role.value == "user") >= 10)
.build()
)
# Get initial user request
initial_request = input("You: ").strip() # noqa: ASYNC250
if not initial_request or initial_request.lower() in ["exit", "quit"]:
print("Goodbye!")
return
# Start workflow with initial message
events = await _drain(workflow.run_stream(initial_request))
pending_requests = handle_events(events)
# Interactive loop: keep prompting for user input
while pending_requests:
user_input = input("\nYou: ").strip() # noqa: ASYNC250
if not user_input or user_input.lower() in ["exit", "quit"]:
print("\nEnding conversation. Goodbye!")
break
responses = {req.request_id: user_input for req in pending_requests}
events = await _drain(workflow.send_responses_streaming(responses))
pending_requests = handle_events(events)
print("\n" + "=" * 60)
print("Conversation ended.")
"""
Sample Output:
Handoff Workflow with Return-to-Previous Routing
============================================================
This interactive demo shows how user inputs route directly
to the specialist handling your request, avoiding unnecessary
coordinator re-evaluation on each turn.
Specialists can hand off directly to other specialists when
your request changes topics (e.g., from technical to billing).
Type 'exit' or 'quit' to end the conversation.
You: I need help with my bill, I was charged twice by mistake.
============================================================
AWAITING INPUT FROM: BILLING_AGENT
============================================================
[user]: I need help with my bill, I was charged twice by mistake.
[coordinator]: You will be connected to a billing agent who can assist you with the double charge on your bill.
>>> [billing_agent]: I'm here to help with billing concerns! I'm sorry you were charged twice. Could you
please provide the invoice number or your account email so I can look into this and begin processing a refund?
You: Invoice 1234
============================================================
AWAITING INPUT FROM: BILLING_AGENT
============================================================
>>> [billing_agent]: I'm here to help with billing concerns! I'm sorry you were charged twice.
Could you please provide the invoice number or your account email so I can look into this and begin
processing a refund?
[user]: Invoice 1234
>>> [billing_agent]: Thank you for providing the invoice number (1234). I will review the details and work
on processing a refund for the duplicate charge.
Can you confirm which payment method you used for this bill (e.g., credit card, PayPal)?
This helps ensure your refund is processed to the correct account.
You: I used my credit card, which is on autopay.
============================================================
AWAITING INPUT FROM: BILLING_AGENT
============================================================
>>> [billing_agent]: Thank you for providing the invoice number (1234). I will review the details and work on
processing a refund for the duplicate charge.
Can you confirm which payment method you used for this bill (e.g., credit card, PayPal)? This helps ensure
your refund is processed to the correct account.
[user]: I used my credit card, which is on autopay.
>>> [billing_agent]: Thank you for confirming your payment method. I will look into invoice 1234 and
process a refund for the duplicate charge to your credit card.
You will receive a notification once the refund is completed. If you have any further questions about your billing
or need an update, please let me know!
You: Actually I also can't turn on my modem. It reset and now won't turn on.
============================================================
AWAITING INPUT FROM: TECHNICAL_SUPPORT
============================================================
[user]: Actually I also can't turn on my modem. It reset and now won't turn on.
[billing_agent]: I'm connecting you with technical support for assistance with your modem not turning on after
the reset. They'll be able to help troubleshoot and resolve this issue.
At the same time, technical support will also handle your refund request for the duplicate charge on invoice 1234
to your credit card on autopay.
You will receive updates from the appropriate teams shortly.
>>> [technical_support]: Thanks for letting me know about your modem issue! To help you further, could you tell me:
1. Is there any light showing on the modem at all, or is it completely off?
2. Have you tried unplugging the modem from power and plugging it back in?
3. Do you hear or feel anything (like a slight hum or vibration) when the modem is plugged in?
Let me know, and I'll guide you through troubleshooting or arrange a repair if needed.
You: exit
Ending conversation. Goodbye!
============================================================
Conversation ended.
"""
if __name__ == "__main__":
asyncio.run(main())
python/samples/getting_started/workflows/orchestration/handoff_simple.py
+65 -81
View File
@@ -1,16 +1,17 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
from collections.abc import AsyncIterable
from typing import Annotated, cast
from agent_framework import (
AgentRunEvent,
AgentRunResponse,
ChatAgent,
ChatMessage,
HandoffAgentUserRequest,
HandoffBuilder,
HandoffUserInputRequest,
HandoffSentEvent,
RequestInfoEvent,
Role,
WorkflowEvent,
WorkflowOutputEvent,
WorkflowRunState,
@@ -20,27 +21,16 @@ from agent_framework import (
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
"""Sample: Simple handoff workflow with single-tier triage-to-specialist routing.
"""Sample: Simple handoff workflow.
This sample demonstrates the basic handoff pattern where only the triage agent can
route to specialists. Specialists cannot hand off to other specialists - after any
specialist responds, control returns to the user (via the triage agent) for the next input.
Routing Pattern:
User → Triage Agent → Specialist → Triage Agent → User → Triage Agent → ...
This is the simplest handoff configuration, suitable for straightforward support
scenarios where a triage agent dispatches to domain specialists, and each specialist
works independently.
For multi-tier specialist-to-specialist handoffs, see handoff_specialist_to_specialist.py.
A handoff workflow defines a pattern that assembles agents in a mesh topology, allowing
them to transfer control to each other based on the conversation context.
Prerequisites:
- `az login` (Azure CLI authentication)
- Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
Key Concepts:
- Single-tier routing: Only triage agent has handoff capabilities
- Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools
for each participant, allowing the coordinator to transfer control to specialists
- Termination condition: Controls when the workflow stops requesting user input
@@ -69,14 +59,8 @@ def process_return(order_number: Annotated[str, "Order number to process return
def create_agents(chat_client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAgent, ChatAgent, ChatAgent]:
"""Create and configure the triage and specialist agents.
The triage agent is responsible for:
- Receiving all user input first
- Deciding whether to handle the request directly or hand off to a specialist
- Signaling handoff by calling one of the explicit handoff tools exposed to it
Specialist agents are invoked only when the triage agent explicitly hands off to them.
After a specialist responds, control returns to the triage agent, which then prompts
the user for their next message.
Args:
chat_client: The AzureOpenAIChatClient to use for creating agents.
Returns:
Tuple of (triage_agent, refund_agent, order_agent, return_agent)
@@ -117,21 +101,6 @@ def create_agents(chat_client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAg
return triage_agent, refund_agent, order_agent, return_agent
async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]:
"""Collect all events from an async stream into a list.
This helper drains the workflow's event stream so we can process events
synchronously after each workflow step completes.
Args:
stream: Async iterable of WorkflowEvent
Returns:
List of all events from the stream
"""
return [event async for event in stream]
def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
"""Process workflow events and extract any pending user input requests.
@@ -150,6 +119,19 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
requests: list[RequestInfoEvent] = []
for event in events:
# AgentRunEvent: Contains messages generated by agents during their turn
if isinstance(event, AgentRunEvent):
for message in event.data.messages:
if not message.text:
# Skip messages without text (e.g., tool calls)
continue
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
# HandoffSentEvent: Indicates a handoff has been initiated
if isinstance(event, HandoffSentEvent):
print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
# WorkflowStatusEvent: Indicates workflow state changes
if isinstance(event, WorkflowStatusEvent) and event.state in {
WorkflowRunState.IDLE,
@@ -164,40 +146,37 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
print("\n=== Final Conversation Snapshot ===")
for message in conversation:
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
print("===================================")
# RequestInfoEvent: Workflow is requesting user input
elif isinstance(event, RequestInfoEvent):
if isinstance(event.data, HandoffUserInputRequest):
_print_agent_responses_since_last_user_message(event.data)
if isinstance(event.data, HandoffAgentUserRequest):
_print_handoff_agent_user_request(event.data.agent_response)
requests.append(event)
return requests
def _print_agent_responses_since_last_user_message(request: HandoffUserInputRequest) -> None:
"""Display agent responses since the last user message in a handoff request.
def _print_handoff_agent_user_request(response: AgentRunResponse) -> None:
"""Display the agent's response messages when requesting user input.
The HandoffUserInputRequest contains the full conversation history so far,
allowing the user to see what's been discussed before providing their next input.
This will happen when an agent generates a response that doesn't trigger
a handoff, i.e., the agent is asking the user for more information.
Args:
request: The user input request containing conversation and prompt
response: The AgentRunResponse from the agent requesting user input
"""
if not request.conversation:
raise RuntimeError("HandoffUserInputRequest missing conversation history.")
if not response.messages:
raise RuntimeError("Cannot print agent responses: response has no messages.")
# Reverse iterate to collect agent responses since last user message
agent_responses: list[ChatMessage] = []
for message in request.conversation[::-1]:
if message.role == Role.USER:
break
agent_responses.append(message)
print("\n[Agent is requesting your input...]")
# Print agent responses in original order
agent_responses.reverse()
for message in agent_responses:
# Print agent responses
for message in response.messages:
if not message.text:
# Skip messages without text (e.g., tool calls)
continue
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
@@ -223,25 +202,23 @@ async def main() -> None:
# Build the handoff workflow
# - participants: All agents that can participate in the workflow
# - set_coordinator: The triage agent is designated as the coordinator, which means
# - with_start_agent: The triage agent is designated as the start agent, which means
# it receives all user input first and orchestrates handoffs to specialists
# - with_termination_condition: Custom logic to stop the request/response loop.
# Without this, the default behavior continues requesting user input until max_turns
# is reached. Here we use a custom condition that checks if the conversation has ended
# naturally (when triage agent says something like "you're welcome").
# naturally (when one of the agents says something like "you're welcome").
workflow = (
HandoffBuilder(
name="customer_support_handoff",
participants=[triage, refund, order, support],
)
.set_coordinator(triage)
.with_start_agent(triage)
.with_termination_condition(
# Custom termination: Check if the triage agent has provided a closing message.
# This looks for the last message being from triage_agent and containing "welcome",
# which indicates the conversation has concluded naturally.
lambda conversation: len(conversation) > 0
and conversation[-1].author_name == "triage_agent"
and "welcome" in conversation[-1].text.lower()
# Custom termination: Check if one of the agents has provided a closing message.
# This looks for the last message containing "welcome", which indicates the
# conversation has concluded naturally.
lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
)
.build()
)
@@ -252,6 +229,7 @@ async def main() -> None:
# or integrate with a UI/chat interface
scripted_responses = [
"My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.",
"Please also process a refund for order 1234.",
"Thanks for resolving this.",
]
@@ -260,26 +238,32 @@ async def main() -> None:
print("[Starting workflow with initial user message...]\n")
initial_message = "Hello, I need assistance with my recent purchase."
print(f"- User: {initial_message}")
events = await _drain(workflow.run_stream(initial_message))
pending_requests = _handle_events(events)
workflow_result = await workflow.run(initial_message)
pending_requests = _handle_events(workflow_result)
# Process the request/response cycle
# The workflow will continue requesting input until:
# 1. The termination condition is met (4 user messages in this case), OR
# 1. The termination condition is met, OR
# 2. We run out of scripted responses
while pending_requests and scripted_responses:
# Get the next scripted response
user_response = scripted_responses.pop(0)
print(f"\n- User: {user_response}")
while pending_requests:
if not scripted_responses:
# No more scripted responses; terminate the workflow
responses = {req.request_id: HandoffAgentUserRequest.terminate() for req in pending_requests}
else:
# Get the next scripted response
user_response = scripted_responses.pop(0)
print(f"\n- User: {user_response}")
# Send response(s) to all pending requests
# In this demo, there's typically one request per cycle, but the API supports multiple
responses = {req.request_id: user_response for req in pending_requests}
# Send response(s) to all pending requests
# In this demo, there's typically one request per cycle, but the API supports multiple
responses = {
req.request_id: HandoffAgentUserRequest.create_response(user_response) for req in pending_requests
}
# Send responses and get new events
# We use send_responses_streaming() to get events as they occur, allowing us to
# display agent responses in real-time and handle new requests as they arrive
events = await _drain(workflow.send_responses_streaming(responses))
# We use send_responses() to get events from the workflow, allowing us to
# display agent responses and handle new requests as they arrive
events = await workflow.send_responses(responses)
pending_requests = _handle_events(events)
"""
python/samples/getting_started/workflows/orchestration/handoff_specialist_to_specialist.py
-284
View File
@@ -1,284 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
"""Sample: Multi-tier handoff workflow with specialist-to-specialist routing.
This sample demonstrates advanced handoff routing where specialist agents can hand off
to other specialists, enabling complex multi-tier workflows. Unlike the simple handoff
pattern (see handoff_simple.py), specialists here can delegate to other specialists
without returning control to the user until the specialist chain completes.
Routing Pattern:
User → Triage → Specialist A → Specialist B → Back to User
This pattern is useful for complex support scenarios where different specialists need
to collaborate or escalate to each other before returning to the user. For example:
- Replacement agent needs shipping info → hands off to delivery agent
- Technical support needs billing info → hands off to billing agent
- Level 1 support escalates to Level 2 → hands off to escalation agent
Configuration uses `.add_handoff()` to explicitly define the routing graph.
Prerequisites:
- `az login` (Azure CLI authentication)
- Environment variables configured for AzureOpenAIChatClient
"""
import asyncio
from collections.abc import AsyncIterable
from typing import cast
from agent_framework import (
ChatMessage,
HandoffBuilder,
HandoffUserInputRequest,
RequestInfoEvent,
WorkflowEvent,
WorkflowOutputEvent,
WorkflowRunState,
WorkflowStatusEvent,
)
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential
def create_agents(chat_client: AzureOpenAIChatClient):
"""Create triage and specialist agents with multi-tier handoff capabilities.
Returns:
Tuple of (triage_agent, replacement_agent, delivery_agent, billing_agent)
"""
triage = chat_client.create_agent(
instructions=(
"You are a customer support triage agent. Assess the user's issue and route appropriately:\n"
"- For product replacement issues: call handoff_to_replacement_agent\n"
"- For delivery/shipping inquiries: call handoff_to_delivery_agent\n"
"- For billing/payment issues: call handoff_to_billing_agent\n"
"Be concise and friendly."
),
name="triage_agent",
)
replacement = chat_client.create_agent(
instructions=(
"You handle product replacement requests. Ask for order number and reason for replacement.\n"
"If the user also needs shipping/delivery information, call handoff_to_delivery_agent to "
"get tracking details. Otherwise, process the replacement and confirm with the user.\n"
"Be concise and helpful."
),
name="replacement_agent",
)
delivery = chat_client.create_agent(
instructions=(
"You handle shipping and delivery inquiries. Provide tracking information, estimated "
"delivery dates, and address any delivery concerns.\n"
"If billing issues come up, call handoff_to_billing_agent.\n"
"Be concise and clear."
),
name="delivery_agent",
)
billing = chat_client.create_agent(
instructions=(
"You handle billing and payment questions. Help with refunds, payment methods, "
"and invoice inquiries. Be concise."
),
name="billing_agent",
)
return triage, replacement, delivery, billing
async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]:
"""Collect all events from an async stream into a list."""
return [event async for event in stream]
def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
"""Process workflow events and extract pending user input requests."""
requests: list[RequestInfoEvent] = []
for event in events:
if isinstance(event, WorkflowStatusEvent) and event.state in {
WorkflowRunState.IDLE,
WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
}:
print(f"[status] {event.state.name}")
elif isinstance(event, WorkflowOutputEvent):
conversation = cast(list[ChatMessage], event.data)
if isinstance(conversation, list):
print("\n=== Final Conversation ===")
for message in conversation:
# Filter out messages with no text (tool calls)
if not message.text.strip():
continue
speaker = message.author_name or message.role.value
print(f"- {speaker}: {message.text}")
print("==========================")
elif isinstance(event, RequestInfoEvent):
if isinstance(event.data, HandoffUserInputRequest):
_print_handoff_request(event.data)
requests.append(event)
return requests
def _print_handoff_request(request: HandoffUserInputRequest) -> None:
"""Display a user input request with conversation context."""
print("\n=== User Input Requested ===")
# Filter out messages with no text for cleaner display
messages_with_text = [msg for msg in request.conversation if msg.text.strip()]
print(f"Last {len(messages_with_text)} messages in conversation:")
for message in messages_with_text[-5:]: # Show last 5 for brevity
speaker = message.author_name or message.role.value
text = message.text[:100] + "..." if len(message.text) > 100 else message.text
print(f" {speaker}: {text}")
print("============================")
async def main() -> None:
"""Demonstrate specialist-to-specialist handoffs in a multi-tier support scenario.
This sample shows:
1. Triage agent routes to replacement specialist
2. Replacement specialist hands off to delivery specialist
3. Delivery specialist can hand off to billing if needed
4. All transitions are seamless without returning to user until complete
The workflow configuration explicitly defines which agents can hand off to which others:
- triage_agent → replacement_agent, delivery_agent, billing_agent
- replacement_agent → delivery_agent, billing_agent
- delivery_agent → billing_agent
"""
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
triage, replacement, delivery, billing = create_agents(chat_client)
# Configure multi-tier handoffs using fluent add_handoff() API
# This allows specialists to hand off to other specialists
workflow = (
HandoffBuilder(
name="multi_tier_support",
participants=[triage, replacement, delivery, billing],
)
.set_coordinator(triage)
.add_handoff(triage, [replacement, delivery, billing]) # Triage can route to any specialist
.add_handoff(replacement, [delivery, billing]) # Replacement can delegate to delivery or billing
.add_handoff(delivery, billing) # Delivery can escalate to billing
# Termination condition: Stop when more than 3 user messages exist.
# This allows agents to respond to the 3rd user message before the 4th triggers termination.
# In this sample: initial message + 3 scripted responses = 4 messages, then workflow ends.
.with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role.value == "user") > 3)
.build()
)
# Scripted user responses simulating a multi-tier handoff scenario
# Note: The initial run_stream() call sends the first user message,
# then these scripted responses are sent in sequence (total: 4 user messages).
# A 5th response triggers termination after agents respond to the 4th message.
scripted_responses = [
"I need help with order 12345. I want a replacement and need to know when it will arrive.",
"The item arrived damaged. I'd like a replacement shipped to the same address.",
"Great! Can you confirm the shipping cost won't be charged again?",
"Thank you!", # Final response to trigger termination after billing agent answers
]
print("\n" + "=" * 80)
print("SPECIALIST-TO-SPECIALIST HANDOFF DEMONSTRATION")
print("=" * 80)
print("\nScenario: Customer needs replacement + shipping info + billing confirmation")
print("Expected flow: User → Triage → Replacement → Delivery → Billing → User")
print("=" * 80 + "\n")
# Start workflow with initial message
print(f"[User]: {scripted_responses[0]}\n")
events = await _drain(workflow.run_stream(scripted_responses[0]))
pending_requests = _handle_events(events)
# Process scripted responses
response_index = 1
while pending_requests and response_index < len(scripted_responses):
user_response = scripted_responses[response_index]
print(f"\n[User]: {user_response}\n")
responses = {req.request_id: user_response for req in pending_requests}
events = await _drain(workflow.send_responses_streaming(responses))
pending_requests = _handle_events(events)
response_index += 1
"""
Sample Output:
================================================================================
SPECIALIST-TO-SPECIALIST HANDOFF DEMONSTRATION
================================================================================
Scenario: Customer needs replacement + shipping info + billing confirmation
Expected flow: User → Triage → Replacement → Delivery → Billing → User
================================================================================
[User]: I need help with order 12345. I want a replacement and need to know when it will arrive.
=== User Input Requested ===
Last 5 messages in conversation:
user: I need help with order 12345. I want a replacement and need to know when it will arrive.
triage_agent: I am connecting you to our replacement agent to assist with your replacement request and to our deli...
replacement_agent: I have connected you to our agents who will assist with your replacement request for order 12345 and...
delivery_agent: For your replacement request and delivery details regarding order 12345, I'll connect you to the app...
billing_agent: I don’t have access to order details. Please contact the seller or customer service directly for rep...
============================
[status] IDLE_WITH_PENDING_REQUESTS
[User]: The item arrived damaged. I'd like a replacement shipped to the same address.
=== User Input Requested ===
Last 8 messages in conversation:
delivery_agent: For your replacement request and delivery details regarding order 12345, I'll connect you to the app...
billing_agent: I don’t have access to order details. Please contact the seller or customer service directly for rep...
user: The item arrived damaged. I'd like a replacement shipped to the same address.
triage_agent: I'm connecting you to our replacement agent who will assist you with getting a replacement shipped t...
replacement_agent: Thank you for the info. I'll start the replacement process for your damaged item on order 12345 and ...
============================
[status] IDLE_WITH_PENDING_REQUESTS
[User]: Great! Can you confirm the shipping cost won't be charged again?
=== User Input Requested ===
Last 11 messages in conversation:
triage_agent: I'm connecting you to our replacement agent who will assist you with getting a replacement shipped t...
replacement_agent: Thank you for the info. I'll start the replacement process for your damaged item on order 12345 and ...
user: Great! Can you confirm the shipping cost won't be charged again?
triage_agent: I'm connecting you to our billing agent who can confirm whether the shipping cost will be charged ag...
billing_agent: Replacements for damaged items are typically shipped at no extra shipping cost. I recommend confirmi...
============================
[status] IDLE_WITH_PENDING_REQUESTS
[User]: Thank you!
=== Final Conversation ===
- user: I need help with order 12345. I want a replacement and need to know when it will arrive.
- triage_agent: I am connecting you to our replacement agent to assist with your replacement request and to our delivery agent who can provide information on the arrival of your replacement. They will help you shortly!
- replacement_agent: I have connected you to our agents who will assist with your replacement request for order 12345 and provide shipping and delivery information. They will help you with the details shortly. If you have any other questions, feel free to ask!
- delivery_agent: For your replacement request and delivery details regarding order 12345, I'll connect you to the appropriate agent who can assist with both billing and delivery concerns. They will provide you with the estimated arrival date and replacement process. Is there anything else you'd like to know meanwhile?
- billing_agent: I don’t have access to order details. Please contact the seller or customer service directly for replacement and delivery info on order 12345. If you need help with billing, refunds, or payments, I can assist!
- user: The item arrived damaged. I'd like a replacement shipped to the same address.
- triage_agent: I'm connecting you to our replacement agent who will assist you with getting a replacement shipped to the same address for the damaged item. They will help you shortly!
- replacement_agent: Thank you for the info. I'll start the replacement process for your damaged item on order 12345 and arrange to ship it to the same address. Please hold on a moment while I proceed.
Thank you for providing the reason. I will process a replacement for the damaged item from order 12345 and arrange the shipment to the same address. Please hold on a moment while I take care of this.
- user: Great! Can you confirm the shipping cost won't be charged again?
- triage_agent: I'm connecting you to our billing agent who can confirm whether the shipping cost will be charged again for the replacement of your damaged item. They will assist you shortly!
- billing_agent: Replacements for damaged items are typically shipped at no extra shipping cost. I recommend confirming with the replacements or billing department to be sure. Let me know if you’d like me to connect you!
- user: Thank you!
==========================
[status] IDLE
""" # noqa: E501
if __name__ == "__main__":
asyncio.run(main())
python/samples/getting_started/workflows/orchestration/handoff_with_code_interpreter_file.py
+5 -20
View File
@@ -32,8 +32,8 @@ from contextlib import asynccontextmanager
from agent_framework import (
AgentRunUpdateEvent,
ChatAgent,
HandoffAgentUserRequest,
HandoffBuilder,
HandoffUserInputRequest,
HostedCodeInterpreterTool,
HostedFileContent,
RequestInfoEvent,
@@ -68,21 +68,10 @@ def _handle_events(events: list[WorkflowEvent]) -> tuple[list[RequestInfoEvent],
print(f"[status] {event.state.name}")
elif isinstance(event, RequestInfoEvent):
if isinstance(event.data, HandoffUserInputRequest):
print("\n=== Conversation So Far ===")
for msg in event.data.conversation:
speaker = msg.author_name or msg.role.value
text = msg.text or ""
txt = text[:200] + "..." if len(text) > 200 else text
print(f"- {speaker}: {txt}")
print("===========================\n")
requests.append(event)
elif isinstance(event, AgentRunUpdateEvent):
update = event.data
if update is None:
continue
for content in update.contents:
for content in event.data.contents:
if isinstance(content, HostedFileContent):
file_ids.append(content.file_id)
print(f"[Found HostedFileContent: file_id={content.file_id}]")
@@ -137,11 +126,7 @@ async def create_agents_v2(credential: AzureCliCredential) -> AsyncIterator[tupl
):
triage = triage_client.create_agent(
name="TriageAgent",
instructions=(
"You are a triage agent. Your ONLY job is to route requests to the appropriate specialist. "
"For code or file creation requests, call handoff_to_CodeSpecialist immediately. "
"Do NOT try to complete tasks yourself. Just hand off."
),
instructions="You are a triage agent. Your ONLY job is to route requests to the appropriate specialist.",
)
code_specialist = code_client.create_agent(
@@ -170,7 +155,7 @@ async def main() -> None:
workflow = (
HandoffBuilder()
.participants([triage, code_specialist])
.set_coordinator(triage)
.with_start_agent(triage)
.with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role.value == "user") >= 2)
.build()
)
@@ -195,7 +180,7 @@ async def main() -> None:
user_input = user_inputs[input_index]
print(f"\nUser: {user_input}")
responses = {request.request_id: user_input}
responses = {request.request_id: HandoffAgentUserRequest.create_response(user_input)}
events = await _drain(workflow.send_responses_streaming(responses))
requests, file_ids = _handle_events(events)
all_file_ids.extend(file_ids)
python/samples/getting_started/workflows/orchestration/magentic.py
+44 -40
View File
@@ -1,17 +1,19 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import json
import logging
from typing import cast
from agent_framework import (
MAGENTIC_EVENT_TYPE_AGENT_DELTA,
MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
AgentRunUpdateEvent,
ChatAgent,
ChatMessage,
GroupChatRequestSentEvent,
HostedCodeInterpreterTool,
MagenticBuilder,
MagenticOrchestratorEvent,
MagenticProgressLedger,
WorkflowOutputEvent,
)
from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
@@ -75,13 +77,9 @@ async def main() -> None:
print("\nBuilding Magentic Workflow...")
# State used by on_agent_stream callback
last_stream_agent_id: str | None = None
stream_line_open: bool = False
workflow = (
MagenticBuilder()
.participants(researcher=researcher_agent, coder=coder_agent)
.participants([researcher_agent, coder_agent])
.with_standard_manager(
agent=manager_agent,
max_round_count=10,
@@ -103,43 +101,49 @@ async def main() -> None:
print(f"\nTask: {task}")
print("\nStarting workflow execution...")
try:
output: str | None = None
async for event in workflow.run_stream(task):
if isinstance(event, AgentRunUpdateEvent):
props = event.data.additional_properties if event.data else None
event_type = props.get("magentic_event_type") if props else None
# Keep track of the last executor to format output nicely in streaming mode
last_message_id: str | None = None
output_event: WorkflowOutputEvent | None = None
async for event in workflow.run_stream(task):
if isinstance(event, AgentRunUpdateEvent):
message_id = event.data.message_id
if message_id != last_message_id:
if last_message_id is not None:
print("\n")
print(f"- {event.executor_id}:", end=" ", flush=True)
last_message_id = message_id
print(event.data, end="", flush=True)
if event_type == MAGENTIC_EVENT_TYPE_ORCHESTRATOR:
kind = props.get("orchestrator_message_kind", "") if props else ""
text = event.data.text if event.data else ""
print(f"\n[ORCH:{kind}]\n\n{text}\n{'-' * 26}")
elif event_type == MAGENTIC_EVENT_TYPE_AGENT_DELTA:
agent_id = props.get("agent_id", event.executor_id) if props else event.executor_id
if last_stream_agent_id != agent_id or not stream_line_open:
if stream_line_open:
print()
print(f"\n[STREAM:{agent_id}]: ", end="", flush=True)
last_stream_agent_id = agent_id
stream_line_open = True
if event.data and event.data.text:
print(event.data.text, end="", flush=True)
elif event.data and event.data.text:
print(event.data.text, end="", flush=True)
elif isinstance(event, WorkflowOutputEvent):
output_messages = cast(list[ChatMessage], event.data)
if output_messages:
output = output_messages[-1].text
elif isinstance(event, MagenticOrchestratorEvent):
print(f"\n[Magentic Orchestrator Event] Type: {event.event_type.name}")
if isinstance(event.data, ChatMessage):
print(f"Please review the plan:\n{event.data.text}")
elif isinstance(event.data, MagenticProgressLedger):
print(f"Please review progress ledger:\n{json.dumps(event.data.to_dict(), indent=2)}")
else:
print(f"Unknown data type in MagenticOrchestratorEvent: {type(event.data)}")
if stream_line_open:
print()
stream_line_open = False
# Block to allow user to read the plan/progress before continuing
# Note: this is for demonstration only and is not the recommended way to handle human interaction.
# Please refer to `with_plan_review` for proper human interaction during planning phases.
await asyncio.get_event_loop().run_in_executor(None, input, "Press Enter to continue...")
if output is not None:
print(f"Workflow completed with result:\n\n{output}")
elif isinstance(event, GroupChatRequestSentEvent):
print(f"\n[REQUEST SENT ({event.round_index})] to agent: {event.participant_name}")
except Exception as e:
print(f"Workflow execution failed: {e}")
elif isinstance(event, WorkflowOutputEvent):
output_event = event
if not output_event:
raise RuntimeError("Workflow did not produce a final output event.")
print("\n\nWorkflow completed!")
print("Final Output:")
# The output of the Magentic workflow is a list of ChatMessages with only one final message
# generated by the orchestrator.
output_messages = cast(list[ChatMessage], output_event.data)
if output_messages:
output = output_messages[-1].text
print(output)
if __name__ == "__main__":
python/samples/getting_started/workflows/orchestration/magentic_agent_clarification.py
-230
View File
@@ -1,230 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from typing import Annotated, cast
from agent_framework import (
MAGENTIC_EVENT_TYPE_AGENT_DELTA,
MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
AgentRunUpdateEvent,
ChatAgent,
ChatMessage,
MagenticBuilder,
MagenticHumanInterventionDecision,
MagenticHumanInterventionKind,
MagenticHumanInterventionReply,
MagenticHumanInterventionRequest,
RequestInfoEvent,
WorkflowOutputEvent,
ai_function,
)
from agent_framework.openai import OpenAIChatClient
logging.basicConfig(level=logging.WARNING)
logger = logging.getLogger(__name__)
"""
Sample: Agent Clarification via Tool Calls in Magentic Workflows
This sample demonstrates how agents can ask clarifying questions to users during
execution via the HITL (Human-in-the-Loop) mechanism.
Scenario: "Onboard Jessica Smith"
- User provides an ambiguous task: "Onboard Jessica Smith"
- The onboarding agent recognizes missing information and uses the ask_user tool
- The ask_user call surfaces as a TOOL_APPROVAL request via RequestInfoEvent
- User provides the answer (e.g., "Engineering, Software Engineer")
- The answer is fed back to the agent as a FunctionResultContent
- Agent continues execution with the clarified information
How it works:
1. Agent has an `ask_user` tool decorated with `@ai_function(approval_mode="always_require")`
2. When agent calls `ask_user`, it surfaces as a FunctionApprovalRequestContent
3. MagenticAgentExecutor converts this to a MagenticHumanInterventionRequest(kind=TOOL_APPROVAL)
4. User provides answer via MagenticHumanInterventionReply with response_text
5. The response_text becomes the function result fed back to the agent
6. Agent receives the result and continues processing
Prerequisites:
- OpenAI credentials configured for `OpenAIChatClient`.
"""
@ai_function(approval_mode="always_require")
def ask_user(question: Annotated[str, "The question to ask the user for clarification"]) -> str:
"""Ask the user a clarifying question to gather missing information.
Use this tool when you need additional information from the user to complete
your task effectively. The user's response will be returned so you can
continue with your work.
Args:
question: The question to ask the user
Returns:
The user's response to the question
"""
# This function body is a placeholder - the actual interaction happens via HITL.
# When the agent calls this tool:
# 1. The tool call surfaces as a FunctionApprovalRequestContent
# 2. MagenticAgentExecutor detects this and emits a HITL request
# 3. The user provides their answer
# 4. The answer is fed back as the function result
return f"User was asked: {question}"
async def main() -> None:
# Create an onboarding agent that asks clarifying questions
onboarding_agent = ChatAgent(
name="OnboardingAgent",
description="HR specialist who handles employee onboarding",
instructions=(
"You are an HR Onboarding Specialist. Your job is to onboard new employees.\n\n"
"IMPORTANT: When given an onboarding request, you MUST gather the following "
"information before proceeding:\n"
"1. Department (e.g., Engineering, Sales, Marketing)\n"
"2. Role/Title (e.g., Software Engineer, Account Executive)\n"
"3. Start date (if not specified)\n"
"4. Manager's name (if known)\n\n"
"Use the ask_user tool to request ANY missing information. "
"Do not proceed with onboarding until you have at least the department and role.\n\n"
"Once you have the information, create an onboarding plan."
),
chat_client=OpenAIChatClient(model_id="gpt-4o"),
tools=[ask_user], # Tool decorated with @ai_function(approval_mode="always_require")
)
# Create a manager agent
manager_agent = ChatAgent(
name="MagenticManager",
description="Orchestrator that coordinates the onboarding workflow",
instructions="You coordinate a team to complete HR tasks efficiently.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
print("\nBuilding Magentic Workflow with Agent Clarification...")
workflow = (
MagenticBuilder()
.participants(onboarding=onboarding_agent)
.with_standard_manager(
agent=manager_agent,
max_round_count=10,
max_stall_count=3,
max_reset_count=2,
)
.build()
)
# Ambiguous task - agent should ask for clarification
task = "Onboard Jessica Smith"
print(f"\nTask: {task}")
print("(This is intentionally vague - the agent should ask for more details)")
print("\nStarting workflow execution...")
print("=" * 60)
try:
pending_request: RequestInfoEvent | None = None
pending_responses: dict[str, object] | None = None
completed = False
workflow_output: str | None = None
last_stream_agent_id: str | None = None
stream_line_open: bool = False
while not completed:
if pending_responses is not None:
stream = workflow.send_responses_streaming(pending_responses)
else:
stream = workflow.run_stream(task)
async for event in stream:
if isinstance(event, AgentRunUpdateEvent):
props = event.data.additional_properties if event.data else None
event_type = props.get("magentic_event_type") if props else None
if event_type == MAGENTIC_EVENT_TYPE_ORCHESTRATOR:
kind = props.get("orchestrator_message_kind", "") if props else ""
text = event.data.text if event.data else ""
if stream_line_open:
print()
stream_line_open = False
print(f"\n[ORCHESTRATOR: {kind}]\n{text}\n{'-' * 40}")
elif event_type == MAGENTIC_EVENT_TYPE_AGENT_DELTA:
agent_id = props.get("agent_id", "unknown") if props else "unknown"
if last_stream_agent_id != agent_id or not stream_line_open:
if stream_line_open:
print()
print(f"\n[{agent_id}]: ", end="", flush=True)
last_stream_agent_id = agent_id
stream_line_open = True
if event.data and event.data.text:
print(event.data.text, end="", flush=True)
elif isinstance(event, RequestInfoEvent) and event.request_type is MagenticHumanInterventionRequest:
if stream_line_open:
print()
stream_line_open = False
pending_request = event
req = cast(MagenticHumanInterventionRequest, event.data)
if req.kind == MagenticHumanInterventionKind.TOOL_APPROVAL:
print("\n" + "=" * 60)
print("AGENT ASKING FOR CLARIFICATION")
print("=" * 60)
print(f"\nAgent: {req.agent_id}")
print(f"Question: {req.prompt}")
if req.context:
print(f"Details: {req.context}")
print()
elif isinstance(event, WorkflowOutputEvent):
if stream_line_open:
print()
stream_line_open = False
workflow_output = event.data if event.data else None
completed = True
if stream_line_open:
print()
stream_line_open = False
pending_responses = None
if pending_request is not None:
req = cast(MagenticHumanInterventionRequest, pending_request.data)
if req.kind == MagenticHumanInterventionKind.TOOL_APPROVAL:
# Agent is asking for clarification
print("Please provide your answer:")
answer = input("> ").strip() # noqa: ASYNC250
if answer.lower() == "exit":
print("Exiting workflow...")
return
# Send the answer back - it will be fed to the agent as the function result
reply = MagenticHumanInterventionReply(
decision=MagenticHumanInterventionDecision.APPROVE,
response_text=answer if answer else "No additional information provided.",
)
pending_responses = {pending_request.request_id: reply}
pending_request = None
print("\n" + "=" * 60)
print("WORKFLOW COMPLETED")
print("=" * 60)
if workflow_output:
messages = cast(list[ChatMessage], workflow_output)
if messages:
final_msg = messages[-1]
print(f"\nFinal Result:\n{final_msg.text}")
except Exception as e:
print(f"Workflow execution failed: {e}")
logger.exception("Workflow exception", exc_info=e)
if __name__ == "__main__":
asyncio.run(main())
python/samples/getting_started/workflows/orchestration/magentic_checkpoint.py
+21 -21
View File
@@ -3,15 +3,14 @@
import asyncio
import json
from pathlib import Path
from typing import cast
from agent_framework import (
ChatAgent,
ChatMessage,
FileCheckpointStorage,
MagenticBuilder,
MagenticHumanInterventionDecision,
MagenticHumanInterventionKind,
MagenticHumanInterventionReply,
MagenticHumanInterventionRequest,
MagenticPlanReviewRequest,
RequestInfoEvent,
WorkflowCheckpoint,
WorkflowOutputEvent,
@@ -82,7 +81,7 @@ def build_workflow(checkpoint_storage: FileCheckpointStorage):
# stores the checkpoint backend so the runtime knows where to persist snapshots.
return (
MagenticBuilder()
.participants(researcher=researcher, writer=writer)
.participants([researcher, writer])
.with_plan_review()
.with_standard_manager(
agent=manager_agent,
@@ -110,19 +109,16 @@ async def main() -> None:
# Run the workflow until the first RequestInfoEvent is surfaced. The event carries the
# request_id we must reuse on resume. In a real system this is where the UI would present
# the plan for human review.
plan_review_request_id: str | None = None
plan_review_request: MagenticPlanReviewRequest | None = None
async for event in workflow.run_stream(TASK):
if isinstance(event, RequestInfoEvent) and event.request_type is MagenticHumanInterventionRequest:
request = event.data
if isinstance(request, MagenticHumanInterventionRequest):
if request.kind == MagenticHumanInterventionKind.PLAN_REVIEW:
plan_review_request_id = event.request_id
print(f"Captured plan review request: {plan_review_request_id}")
if isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
plan_review_request = event.data
print(f"Captured plan review request: {event.request_id}")
if isinstance(event, WorkflowStatusEvent) and event.state is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS:
break
if plan_review_request_id is None:
if plan_review_request is None:
print("No plan review request emitted; nothing to resume.")
return
@@ -142,19 +138,19 @@ async def main() -> None:
if checkpoint_path.exists():
with checkpoint_path.open() as f:
snapshot = json.load(f)
request_map = snapshot.get("executor_states", {}).get("magentic_plan_review", {}).get("request_events", {})
request_map = snapshot.get("pending_request_info_events", {})
print(f"Pending plan-review requests persisted in checkpoint: {list(request_map.keys())}")
print("\n=== Stage 2: resume from checkpoint and approve plan ===")
resumed_workflow = build_workflow(checkpoint_storage)
# Construct an approval reply to supply when the plan review request is re-emitted.
approval = MagenticHumanInterventionReply(decision=MagenticHumanInterventionDecision.APPROVE)
approval = plan_review_request.approve()
# Resume execution and capture the re-emitted plan review request.
request_info_event: RequestInfoEvent | None = None
async for event in resumed_workflow.run_stream(checkpoint_id=resume_checkpoint.checkpoint_id):
if isinstance(event, RequestInfoEvent) and isinstance(event.data, MagenticHumanInterventionRequest):
if isinstance(event, RequestInfoEvent) and isinstance(event.data, MagenticPlanReviewRequest):
request_info_event = event
if request_info_event is None:
@@ -178,9 +174,11 @@ async def main() -> None:
if not result:
print("No result data from workflow.")
return
text = getattr(result, "text", None) or str(result)
output_messages = cast(list[ChatMessage], result)
print("\n=== Final Answer ===")
print(text)
# The output of the Magentic workflow is a list of ChatMessages with only one final message
# generated by the orchestrator.
print(output_messages[-1].text)
# ------------------------------------------------------------------
# Stage 3: demonstrate resuming from a later checkpoint (post-plan)
@@ -233,7 +231,7 @@ async def main() -> None:
if not post_emitted_events:
print("No new events were emitted; checkpoint already captured a completed run.")
print("\n=== Final Answer (post-plan resume) ===")
print(text)
print(output_messages[-1].text)
return
print("Workflow did not complete after post-plan resume.")
return
@@ -243,9 +241,11 @@ async def main() -> None:
print("No result data from post-plan resume.")
return
post_text = getattr(post_result, "text", None) or str(post_result)
output_messages = cast(list[ChatMessage], post_result)
print("\n=== Final Answer (post-plan resume) ===")
print(post_text)
# The output of the Magentic workflow is a list of ChatMessages with only one final message
# generated by the orchestrator.
print(output_messages[-1].text)
"""
Sample Output:
python/samples/getting_started/workflows/orchestration/magentic_human_plan_review.py
+145
View File
@@ -0,0 +1,145 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import json
from typing import cast
from agent_framework import (
AgentRunUpdateEvent,
ChatAgent,
ChatMessage,
MagenticBuilder,
MagenticPlanReviewRequest,
RequestInfoEvent,
WorkflowOutputEvent,
)
from agent_framework.openai import OpenAIChatClient
"""
Sample: Magentic Orchestration with Human Plan Review
This sample demonstrates how humans can review and provide feedback on plans
generated by the Magentic workflow orchestrator. When plan review is enabled,
the workflow requests human approval or revision before executing each plan.
Key concepts:
- with_plan_review(): Enables human review of generated plans
- MagenticPlanReviewRequest: The event type for plan review requests
- Human can choose to: approve the plan or provide revision feedback
Plan review options:
- approve(): Accept the proposed plan and continue execution
- revise(feedback): Provide textual feedback to modify the plan
Prerequisites:
- OpenAI credentials configured for `OpenAIChatClient`.
"""
async def main() -> None:
researcher_agent = ChatAgent(
name="ResearcherAgent",
description="Specialist in research and information gathering",
instructions="You are a Researcher. You find information and gather facts.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
analyst_agent = ChatAgent(
name="AnalystAgent",
description="Data analyst who processes and summarizes research findings",
instructions="You are an Analyst. You analyze findings and create summaries.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
manager_agent = ChatAgent(
name="MagenticManager",
description="Orchestrator that coordinates the workflow",
instructions="You coordinate a team to complete tasks efficiently.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
print("\nBuilding Magentic Workflow with Human Plan Review...")
workflow = (
MagenticBuilder()
.participants([researcher_agent, analyst_agent])
.with_standard_manager(
agent=manager_agent,
max_round_count=10,
max_stall_count=1,
max_reset_count=2,
)
.with_plan_review() # Request human input for plan review
.build()
)
task = "Research sustainable aviation fuel technology and summarize the findings."
print(f"\nTask: {task}")
print("\nStarting workflow execution...")
print("=" * 60)
pending_request: RequestInfoEvent | None = None
pending_responses: dict[str, object] | None = None
output_event: WorkflowOutputEvent | None = None
while not output_event:
if pending_responses is not None:
stream = workflow.send_responses_streaming(pending_responses)
else:
stream = workflow.run_stream(task)
last_message_id: str | None = None
async for event in stream:
if isinstance(event, AgentRunUpdateEvent):
message_id = event.data.message_id
if message_id != last_message_id:
if last_message_id is not None:
print("\n")
print(f"- {event.executor_id}:", end=" ", flush=True)
last_message_id = message_id
print(event.data, end="", flush=True)
elif isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
pending_request = event
elif isinstance(event, WorkflowOutputEvent):
output_event = event
pending_responses = None
# Handle plan review request if any
if pending_request is not None:
event_data = cast(MagenticPlanReviewRequest, pending_request.data)
print("\n\n[Magentic Plan Review Request]")
if event_data.current_progress is not None:
print("Current Progress Ledger:")
print(json.dumps(event_data.current_progress.to_dict(), indent=2))
print()
print(f"Proposed Plan:\n{event_data.plan.text}\n")
print("Please provide your feedback (press Enter to approve):")
reply = await asyncio.get_event_loop().run_in_executor(None, input, "> ")
if reply.strip() == "":
print("Plan approved.\n")
pending_responses = {pending_request.request_id: event_data.approve()}
else:
print("Plan revised by human.\n")
pending_responses = {pending_request.request_id: event_data.revise(reply)}
pending_request = None
print("\n" + "=" * 60)
print("WORKFLOW COMPLETED")
print("=" * 60)
print("Final Output:")
# The output of the Magentic workflow is a list of ChatMessages with only one final message
# generated by the orchestrator.
output_messages = cast(list[ChatMessage], output_event.data)
if output_messages:
output = output_messages[-1].text
print(output)
if __name__ == "__main__":
asyncio.run(main())
python/samples/getting_started/workflows/orchestration/magentic_human_plan_update.py
-223
View File
@@ -1,223 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from typing import cast
from agent_framework import (
MAGENTIC_EVENT_TYPE_AGENT_DELTA,
MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
AgentRunUpdateEvent,
ChatAgent,
HostedCodeInterpreterTool,
MagenticBuilder,
MagenticHumanInterventionDecision,
MagenticHumanInterventionKind,
MagenticHumanInterventionReply,
MagenticHumanInterventionRequest,
RequestInfoEvent,
WorkflowOutputEvent,
)
from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
"""
Sample: Magentic Orchestration + Human Plan Review
What it does:
- Builds a Magentic workflow with two agents and enables human plan review.
A human approves or edits the plan via `RequestInfoEvent` before execution.
- researcher: ChatAgent backed by OpenAIChatClient (web/search-capable model)
- coder: ChatAgent backed by OpenAIAssistantsClient with the Hosted Code Interpreter tool
Key behaviors demonstrated:
- with_plan_review(): requests a PlanReviewRequest before coordination begins
- Event loop that waits for RequestInfoEvent[PlanReviewRequest], prints the plan, then
replies with PlanReviewReply (here we auto-approve, but you can edit/collect input)
- Callbacks: on_agent_stream (incremental chunks), on_agent_response (final messages),
on_result (final answer), and on_exception
- Workflow completion when idle
Prerequisites:
- OpenAI credentials configured for `OpenAIChatClient` and `OpenAIResponsesClient`.
"""
async def main() -> None:
researcher_agent = ChatAgent(
name="ResearcherAgent",
description="Specialist in research and information gathering",
instructions=(
"You are a Researcher. You find information without additional computation or quantitative analysis."
),
# This agent requires the gpt-4o-search-preview model to perform web searches.
# Feel free to explore with other agents that support web search, for example,
# the `OpenAIResponseAgent` or `AzureAgentProtocol` with bing grounding.
chat_client=OpenAIChatClient(model_id="gpt-4o-search-preview"),
)
coder_agent = ChatAgent(
name="CoderAgent",
description="A helpful assistant that writes and executes code to process and analyze data.",
instructions="You solve questions using code. Please provide detailed analysis and computation process.",
chat_client=OpenAIResponsesClient(),
tools=HostedCodeInterpreterTool(),
)
# Create a manager agent for the orchestration
manager_agent = ChatAgent(
name="MagenticManager",
description="Orchestrator that coordinates the research and coding workflow",
instructions="You coordinate a team to complete complex tasks efficiently.",
chat_client=OpenAIChatClient(),
)
# Callbacks
def on_exception(exception: Exception) -> None:
print(f"Exception occurred: {exception}")
logger.exception("Workflow exception", exc_info=exception)
last_stream_agent_id: str | None = None
stream_line_open: bool = False
print("\nBuilding Magentic Workflow...")
workflow = (
MagenticBuilder()
.participants(researcher=researcher_agent, coder=coder_agent)
.with_standard_manager(
agent=manager_agent,
max_round_count=10,
max_stall_count=3,
max_reset_count=2,
)
.with_plan_review()
.build()
)
task = (
"I am preparing a report on the energy efficiency of different machine learning model architectures. "
"Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 "
"on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). "
"Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 "
"VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model "
"per task type (image classification, text classification, and text generation)."
)
print(f"\nTask: {task}")
print("\nStarting workflow execution...")
try:
pending_request: RequestInfoEvent | None = None
pending_responses: dict[str, MagenticHumanInterventionReply] | None = None
completed = False
workflow_output: str | None = None
while not completed:
# Use streaming for both initial run and response sending
if pending_responses is not None:
stream = workflow.send_responses_streaming(pending_responses)
else:
stream = workflow.run_stream(task)
# Collect events from the stream
async for event in stream:
if isinstance(event, AgentRunUpdateEvent):
props = event.data.additional_properties if event.data else None
event_type = props.get("magentic_event_type") if props else None
if event_type == MAGENTIC_EVENT_TYPE_ORCHESTRATOR:
kind = props.get("orchestrator_message_kind", "") if props else ""
text = event.data.text if event.data else ""
print(f"\n[ORCH:{kind}]\n\n{text}\n{'-' * 26}")
elif event_type == MAGENTIC_EVENT_TYPE_AGENT_DELTA:
agent_id = props.get("agent_id", "unknown") if props else "unknown"
if last_stream_agent_id != agent_id or not stream_line_open:
if stream_line_open:
print()
print(f"\n[STREAM:{agent_id}]: ", end="", flush=True)
last_stream_agent_id = agent_id
stream_line_open = True
if event.data and event.data.text:
print(event.data.text, end="", flush=True)
elif isinstance(event, RequestInfoEvent) and event.request_type is MagenticHumanInterventionRequest:
request = cast(MagenticHumanInterventionRequest, event.data)
if request.kind == MagenticHumanInterventionKind.PLAN_REVIEW:
pending_request = event
if request.plan_text:
print(f"\n=== PLAN REVIEW REQUEST ===\n{request.plan_text}\n")
elif isinstance(event, WorkflowOutputEvent):
# Capture workflow output during streaming
workflow_output = str(event.data) if event.data else None
completed = True
if stream_line_open:
print()
stream_line_open = False
pending_responses = None
# Handle pending plan review request
if pending_request is not None:
# Get human input for plan review decision
print("Plan review options:")
print("1. approve - Approve the plan as-is")
print("2. approve with comments - Approve with feedback for the manager")
print("3. revise - Request revision with your feedback")
print("4. edit - Directly edit the plan text")
print("5. exit - Exit the workflow")
while True:
choice = input("Enter your choice (1-5): ").strip().lower() # noqa: ASYNC250
if choice in ["approve", "1"]:
reply = MagenticHumanInterventionReply(decision=MagenticHumanInterventionDecision.APPROVE)
break
if choice in ["approve with comments", "2"]:
comments = input("Enter your comments for the manager: ").strip() # noqa: ASYNC250
reply = MagenticHumanInterventionReply(
decision=MagenticHumanInterventionDecision.APPROVE,
comments=comments if comments else None,
)
break
if choice in ["revise", "3"]:
comments = input("Enter feedback for revising the plan: ").strip() # noqa: ASYNC250
reply = MagenticHumanInterventionReply(
decision=MagenticHumanInterventionDecision.REVISE,
comments=comments if comments else None,
)
break
if choice in ["edit", "4"]:
print("Enter your edited plan (end with an empty line):")
lines = []
while True:
line = input() # noqa: ASYNC250
if line == "":
break
lines.append(line)
edited_plan = "\n".join(lines)
reply = MagenticHumanInterventionReply(
decision=MagenticHumanInterventionDecision.REVISE,
edited_plan_text=edited_plan if edited_plan else None,
)
break
if choice in ["exit", "5"]:
print("Exiting workflow...")
return
print("Invalid choice. Please enter a number 1-5.")
pending_responses = {pending_request.request_id: reply}
pending_request = None
# Show final result from captured workflow output
if workflow_output:
print(f"Workflow completed with result:\n\n{workflow_output}")
except Exception as e:
print(f"Workflow execution failed: {e}")
on_exception(e)
if __name__ == "__main__":
asyncio.run(main())
python/samples/getting_started/workflows/orchestration/magentic_human_replan.py
-213
View File
@@ -1,213 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
import logging
from typing import cast
from agent_framework import (
MAGENTIC_EVENT_TYPE_AGENT_DELTA,
MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
AgentRunUpdateEvent,
ChatAgent,
ChatMessage,
MagenticBuilder,
MagenticHumanInterventionDecision,
MagenticHumanInterventionKind,
MagenticHumanInterventionReply,
MagenticHumanInterventionRequest,
RequestInfoEvent,
WorkflowOutputEvent,
)
from agent_framework.openai import OpenAIChatClient
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
"""
Sample: Magentic Orchestration with Human Stall Intervention
This sample demonstrates how humans can intervene when a Magentic workflow stalls.
When agents stop making progress, the workflow requests human input instead of
automatically replanning.
Key concepts:
- with_human_input_on_stall(): Enables human intervention when workflow detects stalls
- MagenticHumanInterventionKind.STALL: The request kind for stall interventions
- Human can choose to: continue, trigger replan, or provide guidance
Stall intervention options:
- CONTINUE: Reset stall counter and continue with current plan
- REPLAN: Trigger automatic replanning by the manager
- GUIDANCE: Provide text guidance to help agents get back on track
Prerequisites:
- OpenAI credentials configured for `OpenAIChatClient`.
NOTE: it is sometimes difficult to get the agents to actually stall depending on the task.
"""
async def main() -> None:
researcher_agent = ChatAgent(
name="ResearcherAgent",
description="Specialist in research and information gathering",
instructions="You are a Researcher. You find information and gather facts.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
analyst_agent = ChatAgent(
name="AnalystAgent",
description="Data analyst who processes and summarizes research findings",
instructions="You are an Analyst. You analyze findings and create summaries.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
manager_agent = ChatAgent(
name="MagenticManager",
description="Orchestrator that coordinates the workflow",
instructions="You coordinate a team to complete tasks efficiently.",
chat_client=OpenAIChatClient(model_id="gpt-4o"),
)
print("\nBuilding Magentic Workflow with Human Stall Intervention...")
workflow = (
MagenticBuilder()
.participants(researcher=researcher_agent, analyst=analyst_agent)
.with_standard_manager(
agent=manager_agent,
max_round_count=10,
max_stall_count=1, # Stall detection after 1 round without progress
max_reset_count=2,
)
.with_human_input_on_stall() # Request human input when stalled (instead of auto-replan)
.build()
)
task = "Research sustainable aviation fuel technology and summarize the findings."
print(f"\nTask: {task}")
print("\nStarting workflow execution...")
print("=" * 60)
try:
pending_request: RequestInfoEvent | None = None
pending_responses: dict[str, object] | None = None
completed = False
workflow_output: str | None = None
last_stream_agent_id: str | None = None
stream_line_open: bool = False
while not completed:
if pending_responses is not None:
stream = workflow.send_responses_streaming(pending_responses)
else:
stream = workflow.run_stream(task)
async for event in stream:
if isinstance(event, AgentRunUpdateEvent):
props = event.data.additional_properties if event.data else None
event_type = props.get("magentic_event_type") if props else None
if event_type == MAGENTIC_EVENT_TYPE_ORCHESTRATOR:
kind = props.get("orchestrator_message_kind", "") if props else ""
text = event.data.text if event.data else ""
if stream_line_open:
print()
stream_line_open = False
print(f"\n[ORCHESTRATOR: {kind}]\n{text}\n{'-' * 40}")
elif event_type == MAGENTIC_EVENT_TYPE_AGENT_DELTA:
agent_id = props.get("agent_id", "unknown") if props else "unknown"
if last_stream_agent_id != agent_id or not stream_line_open:
if stream_line_open:
print()
print(f"\n[{agent_id}]: ", end="", flush=True)
last_stream_agent_id = agent_id
stream_line_open = True
if event.data and event.data.text:
print(event.data.text, end="", flush=True)
elif isinstance(event, RequestInfoEvent) and event.request_type is MagenticHumanInterventionRequest:
if stream_line_open:
print()
stream_line_open = False
pending_request = event
req = cast(MagenticHumanInterventionRequest, event.data)
if req.kind == MagenticHumanInterventionKind.STALL:
print("\n" + "=" * 60)
print("STALL INTERVENTION REQUESTED")
print("=" * 60)
print(f"\nWorkflow appears stalled after {req.stall_count} rounds")
print(f"Reason: {req.stall_reason}")
if req.last_agent:
print(f"Last active agent: {req.last_agent}")
if req.plan_text:
print(f"\nCurrent plan:\n{req.plan_text}")
print()
elif isinstance(event, WorkflowOutputEvent):
if stream_line_open:
print()
stream_line_open = False
workflow_output = event.data if event.data else None
completed = True
if stream_line_open:
print()
stream_line_open = False
pending_responses = None
# Handle stall intervention request
if pending_request is not None:
req = cast(MagenticHumanInterventionRequest, pending_request.data)
reply: MagenticHumanInterventionReply | None = None
if req.kind == MagenticHumanInterventionKind.STALL:
print("Stall intervention options:")
print("1. continue - Continue with current plan (reset stall counter)")
print("2. replan - Trigger automatic replanning")
print("3. guidance - Provide guidance to help agents")
print("4. exit - Exit the workflow")
while True:
choice = input("Enter your choice (1-4): ").strip().lower() # noqa: ASYNC250
if choice in ["continue", "1"]:
reply = MagenticHumanInterventionReply(decision=MagenticHumanInterventionDecision.CONTINUE)
break
if choice in ["replan", "2"]:
reply = MagenticHumanInterventionReply(decision=MagenticHumanInterventionDecision.REPLAN)
break
if choice in ["guidance", "3"]:
guidance = input("Enter your guidance: ").strip() # noqa: ASYNC250
reply = MagenticHumanInterventionReply(
decision=MagenticHumanInterventionDecision.GUIDANCE,
comments=guidance if guidance else None,
)
break
if choice in ["exit", "4"]:
print("Exiting workflow...")
return
print("Invalid choice. Please enter a number 1-4.")
if reply is not None:
pending_responses = {pending_request.request_id: reply}
pending_request = None
print("\n" + "=" * 60)
print("WORKFLOW COMPLETED")
print("=" * 60)
if workflow_output:
messages = cast(list[ChatMessage], workflow_output)
if messages:
final_msg = messages[-1]
print(f"\nFinal Result:\n{final_msg.text}")
except Exception as e:
print(f"Workflow execution failed: {e}")
logger.exception("Workflow exception", exc_info=e)
if __name__ == "__main__":
asyncio.run(main())
python/samples/getting_started/workflows/orchestration/sequential_custom_executors.py
+21 -13
View File
@@ -4,6 +4,7 @@ import asyncio
from typing import Any
from agent_framework import (
AgentExecutorResponse,
ChatMessage,
Executor,
Role,
@@ -20,18 +21,13 @@ Sample: Sequential workflow mixing agents and a custom summarizer executor
This demonstrates how SequentialBuilder chains participants with a shared
conversation context (list[ChatMessage]). An agent produces content; a custom
executor appends a compact summary to the conversation. The workflow completes
when idle, and the final output contains the complete conversation.
after all participants have executed in sequence, and the final output contains
the complete conversation.
Custom executor contract:
- Provide at least one @handler accepting list[ChatMessage] and a WorkflowContext[list[ChatMessage]]
- Provide at least one @handler accepting AgentExecutorResponse and a WorkflowContext[list[ChatMessage]]
- Emit the updated conversation via ctx.send_message([...])
Note on internal adapters:
- You may see adapter nodes in the event stream such as "input-conversation",
"to-conversation:<participant>", and "complete". These provide consistent typing,
conversion of agent responses into the shared conversation, and a single point
for completion—similar to concurrent's dispatcher/aggregator.
Prerequisites:
- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
"""
@@ -41,11 +37,23 @@ class Summarizer(Executor):
"""Simple summarizer: consumes full conversation and appends an assistant summary."""
@handler
async def summarize(self, conversation: list[ChatMessage], ctx: WorkflowContext[list[ChatMessage]]) -> None:
users = sum(1 for m in conversation if m.role == Role.USER)
assistants = sum(1 for m in conversation if m.role == Role.ASSISTANT)
async def summarize(self, agent_response: AgentExecutorResponse, ctx: WorkflowContext[list[ChatMessage]]) -> None:
"""Append a summary message to a copy of the full conversation.
Note: A custom executor must be able to handle the message type from the prior participant, and produce
the message type expected by the next participant. In this case, the prior participant is an agent thus
the input is AgentExecutorResponse (an agent will be wrapped in an AgentExecutor, which produces
`AgentExecutorResponse`). If the next participant is also an agent or this is the final participant,
the output must be `list[ChatMessage]`.
"""
if not agent_response.full_conversation:
await ctx.send_message([ChatMessage(role=Role.ASSISTANT, text="No conversation to summarize.")])
return
users = sum(1 for m in agent_response.full_conversation if m.role == Role.USER)
assistants = sum(1 for m in agent_response.full_conversation if m.role == Role.ASSISTANT)
summary = ChatMessage(role=Role.ASSISTANT, text=f"Summary -> users:{users} assistants:{assistants}")
final_conversation = list(conversation) + [summary]
final_conversation = list(agent_response.full_conversation) + [summary]
await ctx.send_message(final_conversation)
@@ -61,7 +69,7 @@ async def main() -> None:
summarizer = Summarizer(id="summarizer")
workflow = SequentialBuilder().participants([content, summarizer]).build()
# 3) Run and print final conversation
# 3) Run workflow and extract final conversation
events = await workflow.run("Explain the benefits of budget eBikes for commuters.")
outputs = events.get_outputs()
python/samples/getting_started/workflows/tool-approval/concurrent_builder_tool_approval.py
+70 -60
View File
@@ -10,8 +10,6 @@ from agent_framework import (
FunctionApprovalResponseContent,
RequestInfoEvent,
WorkflowOutputEvent,
WorkflowRunState,
WorkflowStatusEvent,
ai_function,
)
from agent_framework.openai import OpenAIChatClient
@@ -25,19 +23,18 @@ approval will pause the workflow until the human responds.
This sample works as follows:
1. A ConcurrentBuilder workflow is created with two agents running in parallel.
2. One agent has a tool requiring approval (financial transaction).
3. The other agent has only non-approval tools (market data lookup).
4. Both agents receive the same task and work concurrently.
5. When the financial agent tries to execute a trade, it triggers an approval request.
6. The sample simulates human approval and the workflow completes.
7. Results from both agents are aggregated and output.
2. Both agents have the same tools, including one requiring approval (execute_trade).
3. Both agents receive the same task and work concurrently on their respective stocks.
4. When either agent tries to execute a trade, it triggers an approval request.
5. The sample simulates human approval and the workflow completes.
6. Results from both agents are aggregated and output.
Purpose:
Show how tool call approvals work in parallel execution scenarios where only some
agents have sensitive tools.
Show how tool call approvals work in parallel execution scenarios where multiple
agents may independently trigger approval requests.
Demonstrate:
- Combining agents with and without approval-required tools in concurrent workflows.
- Handling multiple approval requests from different agents in concurrent workflows.
- Handling RequestInfoEvent during concurrent agent execution.
- Understanding that approval pauses only the agent that triggered it, not all agents.
@@ -47,7 +44,7 @@ Prerequisites:
"""
# 1. Define tools for the research agent (no approval required)
# 1. Define market data tools (no approval required)
@ai_function
def get_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
"""Get the current stock price for a given symbol."""
@@ -61,10 +58,16 @@ def get_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
def get_market_sentiment(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
"""Get market sentiment analysis for a stock."""
# Mock sentiment data
return f"Market sentiment for {symbol.upper()}: Bullish (72% positive mentions in last 24h)"
mock_data = {
"AAPL": "Market sentiment for AAPL: Bullish (68% positive mentions in last 24h)",
"GOOGL": "Market sentiment for GOOGL: Neutral (50% positive mentions in last 24h)",
"MSFT": "Market sentiment for MSFT: Bullish (72% positive mentions in last 24h)",
"AMZN": "Market sentiment for AMZN: Bearish (40% positive mentions in last 24h)",
}
return mock_data.get(symbol.upper(), f"Market sentiment for {symbol.upper()}: Unknown")
# 2. Define tools for the trading agent (approval required for trades)
# 2. Define trading tools (approval required)
@ai_function(approval_mode="always_require")
def execute_trade(
symbol: Annotated[str, "The stock ticker symbol"],
@@ -78,52 +81,68 @@ def execute_trade(
@ai_function
def get_portfolio_balance() -> str:
"""Get current portfolio balance and available funds."""
return "Portfolio: $50,000 invested, $10,000 cash available"
return "Portfolio: $50,000 invested, $10,000 cash available. Holdings: AAPL, GOOGL, MSFT."
def _print_output(event: WorkflowOutputEvent) -> None:
if not event.data:
raise ValueError("WorkflowOutputEvent has no data")
if not isinstance(event.data, list) and not all(isinstance(msg, ChatMessage) for msg in event.data):
raise ValueError("WorkflowOutputEvent data is not a list of ChatMessage")
messages: list[ChatMessage] = event.data # type: ignore
print("\n" + "-" * 60)
print("Workflow completed. Aggregated results from both agents:")
for msg in messages:
if msg.text:
print(f"- {msg.author_name or msg.role.value}: {msg.text}")
async def main() -> None:
# 3. Create two agents with different tool sets
# 3. Create two agents focused on different stocks but with the same tool sets
chat_client = OpenAIChatClient()
research_agent = chat_client.create_agent(
name="ResearchAgent",
microsoft_agent = chat_client.create_agent(
name="MicrosoftAgent",
instructions=(
"You are a market research analyst. Analyze stock data and provide "
"recommendations based on price and sentiment. Do not execute trades."
"You are a personal trading assistant focused on Microsoft (MSFT). "
"You manage my portfolio and take actions based on market data."
),
tools=[get_stock_price, get_market_sentiment],
tools=[get_stock_price, get_market_sentiment, get_portfolio_balance, execute_trade],
)
trading_agent = chat_client.create_agent(
name="TradingAgent",
google_agent = chat_client.create_agent(
name="GoogleAgent",
instructions=(
"You are a trading assistant. When asked to buy or sell shares, you MUST "
"call the execute_trade function to complete the transaction. Check portfolio "
"balance first, then execute the requested trade."
"You are a personal trading assistant focused on Google (GOOGL). "
"You manage my trades and portfolio based on market conditions."
),
tools=[get_portfolio_balance, execute_trade],
tools=[get_stock_price, get_market_sentiment, get_portfolio_balance, execute_trade],
)
# 4. Build a concurrent workflow with both agents
# ConcurrentBuilder requires at least 2 participants for fan-out
workflow = ConcurrentBuilder().participants([research_agent, trading_agent]).build()
workflow = ConcurrentBuilder().participants([microsoft_agent, google_agent]).build()
# 5. Start the workflow - both agents will process the same task in parallel
print("Starting concurrent workflow with tool approval...")
print("Two agents will analyze MSFT - one for research, one for trading.")
print("-" * 60)
# Phase 1: Run workflow and collect all events (stream ends at IDLE or IDLE_WITH_PENDING_REQUESTS)
# Phase 1: Run workflow and collect request info events
request_info_events: list[RequestInfoEvent] = []
workflow_completed_without_approvals = False
async for event in workflow.run_stream("Analyze MSFT stock and if sentiment is positive, buy 10 shares."):
async for event in workflow.run_stream(
"Manage my portfolio. Use a max of 5000 dollars to adjust my position using "
"your best judgment based on market sentiment. No need to confirm trades with me."
):
if isinstance(event, RequestInfoEvent):
request_info_events.append(event)
if isinstance(event.data, FunctionApprovalRequestContent):
print(f"\nApproval requested for tool: {event.data.function_call.name}")
print(f" Arguments: {event.data.function_call.arguments}")
elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
workflow_completed_without_approvals = True
elif isinstance(event, WorkflowOutputEvent):
_print_output(event)
# 6. Handle approval requests (if any)
if request_info_events:
@@ -136,46 +155,37 @@ async def main() -> None:
if responses:
# Phase 2: Send all approvals and continue workflow
output: list[ChatMessage] | None = None
async for event in workflow.send_responses_streaming(responses):
if isinstance(event, WorkflowOutputEvent):
output = event.data
if output:
print("\n" + "-" * 60)
print("Workflow completed. Aggregated results from both agents:")
for msg in output:
if hasattr(msg, "author_name") and msg.author_name:
print(f"\n[{msg.author_name}]:")
text = msg.text[:300] + "..." if len(msg.text) > 300 else msg.text
if text:
print(f" {text}")
elif workflow_completed_without_approvals:
_print_output(event)
else:
print("\nWorkflow completed without requiring approvals.")
print("(The trading agent may have only checked balance without executing a trade)")
print("(The agents may have only checked data without executing trades)")
"""
Sample Output:
Starting concurrent workflow with tool approval...
Two agents will analyze MSFT - one for research, one for trading.
------------------------------------------------------------
Approval requested for tool: execute_trade
Arguments: {"symbol": "MSFT", "action": "buy", "quantity": 10}
Arguments: {"symbol":"MSFT","action":"buy","quantity":13}
Approval requested for tool: execute_trade
Arguments: {"symbol":"GOOGL","action":"buy","quantity":35}
Simulating human approval for: execute_trade
Simulating human approval for: execute_trade
------------------------------------------------------------
Workflow completed. Aggregated results from both agents:
[ResearchAgent]:
MSFT is currently trading at $175.50 with bullish market sentiment
(72% positive mentions). Based on the positive sentiment, this could
be a good opportunity to consider buying.
[TradingAgent]:
I've checked your portfolio balance ($10,000 cash available) and
executed the trade: BUY 10 shares of MSFT at approximately $175.50
per share, totaling ~$1,755.
- user: Manage my portfolio. Use a max of 5000 dollars to adjust my position using your best judgment based on
market sentiment. No need to confirm trades with me.
- MicrosoftAgent: I have successfully executed the trade, purchasing 13 shares of Microsoft (MSFT). This action
was based on the positive market sentiment and available funds within the specified limit.
Your portfolio has been adjusted accordingly.
- GoogleAgent: I have successfully executed the trade, purchasing 35 shares of GOOGL. If you need further
assistance or any adjustments, feel free to ask!
"""
python/samples/getting_started/workflows/tool-approval/group_chat_builder_tool_approval.py
+47 -19
View File
@@ -4,9 +4,11 @@ import asyncio
from typing import Annotated
from agent_framework import (
AgentRunUpdateEvent,
FunctionApprovalRequestContent,
GroupChatBuilder,
GroupChatStateSnapshot,
GroupChatRequestSentEvent,
GroupChatState,
RequestInfoEvent,
ai_function,
)
@@ -73,7 +75,7 @@ def create_rollback_plan(version: Annotated[str, "The version being deployed"])
# 2. Define the speaker selector function
def select_next_speaker(state: GroupChatStateSnapshot) -> str | None:
def select_next_speaker(state: GroupChatState) -> str:
"""Select the next speaker based on the conversation flow.
This simple selector follows a predefined flow:
@@ -81,19 +83,13 @@ def select_next_speaker(state: GroupChatStateSnapshot) -> str | None:
2. DevOps Engineer checks staging and creates rollback plan
3. DevOps Engineer deploys to production (triggers approval)
"""
round_index: int = state["round_index"]
if not state.conversation:
raise RuntimeError("Conversation is empty; cannot select next speaker.")
# Define the conversation flow
speaker_order: list[str] = [
"QAEngineer", # Round 0: Run tests
"DevOpsEngineer", # Round 1: Check staging, create rollback
"DevOpsEngineer", # Round 2: Deploy to production (approval required)
]
if len(state.conversation) == 1:
return "QAEngineer" # First speaker
if round_index >= len(speaker_order):
return None # End the conversation
return speaker_order[round_index]
return "DevOpsEngineer" # Subsequent speakers
async def main() -> None:
@@ -123,28 +119,47 @@ async def main() -> None:
workflow = (
GroupChatBuilder()
# Optionally, use `.set_manager(...)` to customize the group chat manager
.set_select_speakers_func(select_next_speaker)
.with_select_speaker_func(select_next_speaker)
.participants([qa_engineer, devops_engineer])
.with_max_rounds(5)
# Set a hard limit to 4 rounds
# First round: QAEngineer speaks
# Second round: DevOpsEngineer speaks (check staging + create rollback)
# Third round: DevOpsEngineer speaks with an approval request (deploy to production)
# Fourth round: DevOpsEngineer speaks again after approval
.with_max_rounds(4)
.build()
)
# 5. Start the workflow
print("Starting group chat workflow for software deployment...")
print("Agents: QA Engineer, DevOps Engineer")
print(f"Agents: {[qa_engineer.name, devops_engineer.name]}")
print("-" * 60)
# Phase 1: Run workflow and collect all events (stream ends at IDLE or IDLE_WITH_PENDING_REQUESTS)
request_info_events: list[RequestInfoEvent] = []
# Keep track of the last response to format output nicely in streaming mode
last_response_id: str | None = None
async for event in workflow.run_stream(
"We need to deploy version 2.4.0 to production. Please coordinate the deployment."
):
if isinstance(event, RequestInfoEvent):
request_info_events.append(event)
if isinstance(event.data, FunctionApprovalRequestContent):
print("\n[APPROVAL REQUIRED]")
print("\n[APPROVAL REQUIRED] From agent:", event.source_executor_id)
print(f" Tool: {event.data.function_call.name}")
print(f" Arguments: {event.data.function_call.arguments}")
elif isinstance(event, AgentRunUpdateEvent):
if not event.data.text:
continue # Skip empty updates
response_id = event.data.response_id
if response_id != last_response_id:
if last_response_id is not None:
print("\n")
print(f"- {event.executor_id}:", end=" ", flush=True)
last_response_id = response_id
print(event.data, end="", flush=True)
elif isinstance(event, GroupChatRequestSentEvent):
print(f"\n[REQUEST SENT ({event.round_index})] to agent: {event.participant_name}")
# 6. Handle approval requests
if request_info_events:
@@ -160,8 +175,21 @@ async def main() -> None:
approval_response = request_event.data.create_response(approved=True)
# Phase 2: Send approval and continue workflow
async for _ in workflow.send_responses_streaming({request_event.request_id: approval_response}):
pass # Consume all events
# Keep track of the response to format output nicely in streaming mode
last_response_id: str | None = None
async for event in workflow.send_responses_streaming({request_event.request_id: approval_response}):
if isinstance(event, AgentRunUpdateEvent):
if not event.data.text:
continue # Skip empty updates
response_id = event.data.response_id
if response_id != last_response_id:
if last_response_id is not None:
print("\n")
print(f"- {event.executor_id}:", end=" ", flush=True)
last_response_id = response_id
print(event.data, end="", flush=True)
elif isinstance(event, GroupChatRequestSentEvent):
print(f"\n[REQUEST SENT ({event.round_index})] To agent: {event.participant_name}")
print("\n" + "-" * 60)
print("Deployment workflow completed successfully!")