agent/agent-framework
2
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/packages/core/agent_framework/_workflows/__init__.py
+37 -40
View File
@@ -6,6 +6,13 @@ from ._agent_executor import (
AgentExecutorRequest,
AgentExecutorResponse,
)
from ._agent_utils import resolve_agent_id
from ._base_group_chat_orchestrator import (
BaseGroupChatOrchestrator,
GroupChatRequestMessage,
GroupChatRequestSentEvent,
GroupChatResponseReceivedEvent,
)
from ._checkpoint import (
CheckpointStorage,
FileCheckpointStorage,
@@ -56,37 +63,30 @@ from ._executor import (
)
from ._function_executor import FunctionExecutor, executor
from ._group_chat import (
DEFAULT_MANAGER_INSTRUCTIONS,
DEFAULT_MANAGER_STRUCTURED_OUTPUT_PROMPT,
AgentBasedGroupChatOrchestrator,
GroupChatBuilder,
GroupChatDirective,
GroupChatStateSnapshot,
ManagerDirectiveModel,
ManagerSelectionRequest,
ManagerSelectionResponse,
GroupChatState,
)
from ._handoff import HandoffBuilder, HandoffUserInputRequest
from ._handoff import HandoffAgentUserRequest, HandoffBuilder, HandoffSentEvent
from ._magentic import (
MAGENTIC_EVENT_TYPE_AGENT_DELTA,
MAGENTIC_EVENT_TYPE_ORCHESTRATOR,
ORCH_MSG_KIND_INSTRUCTION,
ORCH_MSG_KIND_NOTICE,
ORCH_MSG_KIND_TASK_LEDGER,
ORCH_MSG_KIND_USER_TASK,
MagenticBuilder,
MagenticContext,
MagenticHumanInputRequest,
MagenticHumanInterventionDecision,
MagenticHumanInterventionKind,
MagenticHumanInterventionReply,
MagenticHumanInterventionRequest,
MagenticManagerBase,
MagenticStallInterventionDecision,
MagenticStallInterventionReply,
MagenticStallInterventionRequest,
MagenticOrchestrator,
MagenticOrchestratorEvent,
MagenticOrchestratorEventType,
MagenticPlanReviewRequest,
MagenticPlanReviewResponse,
MagenticProgressLedger,
MagenticProgressLedgerItem,
MagenticResetSignal,
StandardMagenticManager,
)
from ._orchestration_request_info import AgentInputRequest, AgentResponseReviewRequest, RequestInfoInterceptor
from ._orchestration_request_info import AgentRequestInfoResponse
from ._orchestration_state import OrchestrationState
from ._request_info_mixin import response_handler
from ._runner import Runner
@@ -112,22 +112,19 @@ from ._workflow_context import WorkflowContext
from ._workflow_executor import SubWorkflowRequestMessage, SubWorkflowResponseMessage, WorkflowExecutor
__all__ = [
"DEFAULT_MANAGER_INSTRUCTIONS",
"DEFAULT_MANAGER_STRUCTURED_OUTPUT_PROMPT",
"DEFAULT_MAX_ITERATIONS",
"MAGENTIC_EVENT_TYPE_AGENT_DELTA",
"MAGENTIC_EVENT_TYPE_ORCHESTRATOR",
"ORCH_MSG_KIND_INSTRUCTION",
"ORCH_MSG_KIND_NOTICE",
"ORCH_MSG_KIND_TASK_LEDGER",
"ORCH_MSG_KIND_USER_TASK",
"AgentBasedGroupChatOrchestrator",
"AgentExecutor",
"AgentExecutorRequest",
"AgentExecutorResponse",
"AgentInputRequest",
"AgentResponseReviewRequest",
"AgentRequestInfoResponse",
"AgentRunEvent",
"AgentRunUpdateEvent",
"BaseGroupChatOrchestrator",
"Case",
"CheckpointStorage",
"ConcurrentBuilder",
@@ -146,30 +143,29 @@ __all__ = [
"FunctionExecutor",
"GraphConnectivityError",
"GroupChatBuilder",
"GroupChatDirective",
"GroupChatStateSnapshot",
"GroupChatRequestMessage",
"GroupChatRequestSentEvent",
"GroupChatResponseReceivedEvent",
"GroupChatState",
"HandoffAgentUserRequest",
"HandoffBuilder",
"HandoffUserInputRequest",
"HandoffSentEvent",
"InMemoryCheckpointStorage",
"InProcRunnerContext",
"MagenticBuilder",
"MagenticContext",
"MagenticHumanInputRequest",
"MagenticHumanInterventionDecision",
"MagenticHumanInterventionKind",
"MagenticHumanInterventionReply",
"MagenticHumanInterventionRequest",
"MagenticManagerBase",
"MagenticStallInterventionDecision",
"MagenticStallInterventionReply",
"MagenticStallInterventionRequest",
"ManagerDirectiveModel",
"ManagerSelectionRequest",
"ManagerSelectionResponse",
"MagenticOrchestrator",
"MagenticOrchestratorEvent",
"MagenticOrchestratorEventType",
"MagenticPlanReviewRequest",
"MagenticPlanReviewResponse",
"MagenticProgressLedger",
"MagenticProgressLedgerItem",
"MagenticResetSignal",
"Message",
"OrchestrationState",
"RequestInfoEvent",
"RequestInfoInterceptor",
"Runner",
"RunnerContext",
"SequentialBuilder",
@@ -208,6 +204,7 @@ __all__ = [
"executor",
"get_checkpoint_summary",
"handler",
"resolve_agent_id",
"response_handler",
"validate_workflow_graph",
]
python/packages/core/agent_framework/_workflows/_agent_executor.py
+25 -8
View File
@@ -10,6 +10,7 @@ from agent_framework import FunctionApprovalRequestContent, FunctionApprovalResp
from .._agents import AgentProtocol, ChatAgent
from .._threads import AgentThread
from .._types import AgentRunResponse, AgentRunResponseUpdate, ChatMessage
from ._agent_utils import resolve_agent_id
from ._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
from ._const import WORKFLOW_RUN_KWARGS_KEY
from ._conversation_state import encode_chat_messages
@@ -88,16 +89,20 @@ class AgentExecutor(Executor):
id: A unique identifier for the executor. If None, the agent's name will be used if available.
"""
# Prefer provided id; else use agent.name if present; else generate deterministic prefix
exec_id = id or agent.name
exec_id = id or resolve_agent_id(agent)
if not exec_id:
raise ValueError("Agent must have a name or an explicit id must be provided.")
raise ValueError("Agent must have a non-empty name or id or an explicit id must be provided.")
super().__init__(exec_id)
self._agent = agent
self._agent_thread = agent_thread or self._agent.get_new_thread()
self._pending_agent_requests: dict[str, FunctionApprovalRequestContent] = {}
self._pending_responses_to_agent: list[FunctionApprovalResponseContent] = []
self._output_response = output_response
# AgentExecutor maintains an internal cache of messages in between runs
self._cache: list[ChatMessage] = []
# This tracks the full conversation after each run
self._full_conversation: list[ChatMessage] = []
@property
def output_response(self) -> bool:
@@ -227,6 +232,7 @@ class AgentExecutor(Executor):
return {
"cache": encode_chat_messages(self._cache),
"full_conversation": encode_chat_messages(self._full_conversation),
"agent_thread": serialized_thread,
"pending_agent_requests": encode_checkpoint_value(self._pending_agent_requests),
"pending_responses_to_agent": encode_checkpoint_value(self._pending_responses_to_agent),
@@ -251,6 +257,16 @@ class AgentExecutor(Executor):
else:
self._cache = []
full_conversation_payload = state.get("full_conversation")
if full_conversation_payload:
try:
self._full_conversation = decode_chat_messages(full_conversation_payload)
except Exception as exc:
logger.warning("Failed to restore full conversation: %s", exc)
self._full_conversation = []
else:
self._full_conversation = []
thread_payload = state.get("agent_thread")
if thread_payload:
try:
@@ -289,6 +305,12 @@ class AgentExecutor(Executor):
# Non-streaming mode: use run() and emit single event
response = await self._run_agent(cast(WorkflowContext, ctx))
# Always extend full conversation with cached messages plus agent outputs
# (agent_run_response.messages) after each run. This is to avoid losing context
# when agent did not complete and the cache is cleared when responses come back.
# Do not mutate response.messages so AgentRunEvent remains faithful to the raw output.
self._full_conversation.extend(list(self._cache) + (list(response.messages) if response else []))
if response is None:
# Agent did not complete (e.g., waiting for user input); do not emit response
logger.info("AgentExecutor %s: Agent did not complete, awaiting user input", self.id)
@@ -297,12 +319,7 @@ class AgentExecutor(Executor):
if self._output_response:
await ctx.yield_output(response)
# Always construct a full conversation snapshot from inputs (cache)
# plus agent outputs (agent_run_response.messages). Do not mutate
# response.messages so AgentRunEvent remains faithful to the raw output.
full_conversation: list[ChatMessage] = list(self._cache) + list(response.messages)
agent_response = AgentExecutorResponse(self.id, response, full_conversation=full_conversation)
agent_response = AgentExecutorResponse(self.id, response, full_conversation=self._full_conversation)
await ctx.send_message(agent_response)
self._cache.clear()
python/packages/core/agent_framework/_workflows/_agent_utils.py
+17
View File
@@ -0,0 +1,17 @@
# Copyright (c) Microsoft. All rights reserved.
from .._agents import AgentProtocol
def resolve_agent_id(agent: AgentProtocol) -> str:
"""Resolve the unique identifier for an agent.
Prefers the `.name` attribute if set; otherwise falls back to `.id`.
Args:
agent: The agent whose identifier is to be resolved.
Returns:
The resolved unique identifier for the agent.
"""
return agent.name if agent.name else agent.id
python/packages/core/agent_framework/_workflows/_base_group_chat_orchestrator.py
+394 -82
View File
@@ -2,16 +2,23 @@
"""Base class for group chat orchestrators that manages conversation flow and participant selection."""
import asyncio
import inspect
import logging
import sys
from abc import ABC, abstractmethod
from abc import ABC
from collections import OrderedDict
from collections.abc import Awaitable, Callable, Sequence
from typing import Any
from dataclasses import dataclass
from typing import Any, ClassVar, TypeAlias
from .._types import ChatMessage
from ._executor import Executor
from ._orchestrator_helpers import ParticipantRegistry
from typing_extensions import Never
from .._types import ChatMessage, Role
from ._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
from ._events import WorkflowEvent
from ._executor import Executor, handler
from ._orchestration_request_info import AgentApprovalExecutor
from ._workflow_context import WorkflowContext
if sys.version_info >= (3, 12):
@@ -23,6 +30,129 @@ else:
logger = logging.getLogger(__name__)
@dataclass
class GroupChatRequestMessage:
"""Request envelope sent from the orchestrator to a participant."""
additional_instruction: str | None = None
metadata: dict[str, Any] | None = None
@dataclass
class GroupChatParticipantMessage:
"""Message envelop containing messages generated by a participant.
This message envelope is used to broadcast messages from one participant
to other participants in the group chat to keep them synchronized.
"""
messages: list[ChatMessage]
@dataclass
class GroupChatResponseMessage:
"""Response envelope emitted by participants back to the orchestrator."""
message: ChatMessage
TerminationCondition: TypeAlias = Callable[[list[ChatMessage]], bool | Awaitable[bool]]
GroupChatWorkflowContext_T_Out: TypeAlias = AgentExecutorRequest | GroupChatRequestMessage | GroupChatParticipantMessage
# region Group chat events
class GroupChatEvent(WorkflowEvent):
"""Base class for group chat workflow events."""
def __init__(self, round_index: int, data: Any | None = None) -> None:
"""Initialize group chat event.
Args:
round_index: Current round index
data: Optional event-specific data
"""
super().__init__(data)
self.round_index = round_index
class GroupChatResponseReceivedEvent(GroupChatEvent):
"""Event emitted when a participant response is received."""
def __init__(self, round_index: int, participant_name: str, data: Any | None = None) -> None:
"""Initialize response received event.
Args:
round_index: Current round index
participant_name: Name of the participant who sent the response
data: Optional event-specific data
"""
super().__init__(round_index, data)
self.participant_name = participant_name
class GroupChatRequestSentEvent(GroupChatEvent):
"""Event emitted when a request is sent to a participant."""
def __init__(self, round_index: int, participant_name: str, data: Any | None = None) -> None:
"""Initialize request sent event.
Args:
round_index: Current round index
participant_name: Name of the participant to whom the request was sent
data: Optional event-specific data
"""
super().__init__(round_index, data)
self.participant_name = participant_name
# endregion
# region Participant registry
class ParticipantRegistry:
"""Simple registry for tracking group chat participants and their types and other properties."""
EMPTY_DESCRIPTION_PLACEHOLDER: ClassVar[str] = (
"<no description, use name to identify the purpose of this participant>"
)
def __init__(self, participants: Sequence[Executor]) -> None:
"""Initialize the registry and validate participant IDs.
Args:
participants: List of executors (agents or custom executors) to register
Raises:
ValueError: If there are duplicate or conflicting participant IDs
"""
self._agents: set[str] = set()
self._participants: OrderedDict[str, str] = OrderedDict()
self._resolve_participants(participants)
def _resolve_participants(self, participants: Sequence[Executor]) -> None:
"""Register participants and validate IDs."""
for participant in participants:
if participant.id in self._participants:
raise ValueError(f"Participant ID conflict: '{participant.id}' registered as both agent and executor.")
if isinstance(participant, AgentExecutor | AgentApprovalExecutor):
self._agents.add(participant.id)
self._participants[participant.id] = participant.description or self.EMPTY_DESCRIPTION_PLACEHOLDER
else:
self._participants[participant.id] = self.EMPTY_DESCRIPTION_PLACEHOLDER
def is_agent(self, name: str) -> bool:
"""Check if a participant is an agent (vs custom executor)."""
return name in self._agents
@property
def participants(self) -> OrderedDict[str, str]:
"""Get all registered participant names and descriptions in an ordered dictionary."""
return self._participants
# endregion
class BaseGroupChatOrchestrator(Executor, ABC):
"""Abstract base class for group chat orchestrators.
@@ -33,36 +163,159 @@ class BaseGroupChatOrchestrator(Executor, ABC):
inheriting the common participant management infrastructure.
"""
def __init__(self, executor_id: str) -> None:
TERMINATION_CONDITION_MET_MESSAGE: ClassVar[str] = "The group chat has reached its termination condition."
MAX_ROUNDS_MET_MESSAGE: ClassVar[str] = "The group chat has reached the maximum number of rounds."
def __init__(
self,
id: str,
participant_registry: ParticipantRegistry,
*,
name: str | None = None,
max_rounds: int | None = None,
termination_condition: TerminationCondition | None = None,
) -> None:
"""Initialize base orchestrator.
Args:
executor_id: Unique identifier for this orchestrator executor
id: Unique identifier for this orchestrator executor
participant_registry: Registry of group chat participants that tracks their types (agents
vs custom executors)
name: Optional display name for orchestrator messages
max_rounds: Optional maximum number of conversation rounds.
Must be equal to or greater than 1 if set. Number smaller than 1 will be coerced to 1.
termination_condition: Optional callable to determine conversation termination
"""
super().__init__(executor_id)
self._registry = ParticipantRegistry()
# Shared conversation state management
self._conversation: list[ChatMessage] = []
super().__init__(id)
self._name = name or id
self._max_rounds = max(1, max_rounds) if max_rounds is not None else None
self._termination_condition = termination_condition
self._round_index: int = 0
self._max_rounds: int | None = None
self._termination_condition: Callable[[list[ChatMessage]], bool | Awaitable[bool]] | None = None
self._participant_registry = participant_registry
# Shared conversation state management
self._full_conversation: list[ChatMessage] = []
def register_participant_entry(
self, name: str, *, entry_id: str, is_agent: bool, exit_id: str | None = None
# region Handlers
@handler
async def handle_str(
self,
task: str,
ctx: WorkflowContext[GroupChatWorkflowContext_T_Out, list[ChatMessage]],
) -> None:
"""Record routing details for a participant's entry executor.
"""Handler for string input as workflow entry point.
This method provides a unified interface for registering participants
across all orchestrator patterns, whether they are agents or custom executors.
Wraps the string in a USER role ChatMessage and delegates to _handle_task_message.
Args:
name: Participant name (used for selection and tracking)
entry_id: Executor ID for this participant's entry point
is_agent: Whether this is an AgentExecutor (True) or custom Executor (False)
exit_id: Executor ID for this participant's exit point (where responses come from).
If None, defaults to entry_id.
task: Plain text task description from user
ctx: Workflow context
Usage:
workflow.run("Write a blog post about AI agents")
"""
self._registry.register(name, entry_id=entry_id, is_agent=is_agent, exit_id=exit_id)
await self._handle_messages([ChatMessage(role=Role.USER, text=task)], ctx)
@handler
async def handle_message(
self,
task: ChatMessage,
ctx: WorkflowContext[GroupChatWorkflowContext_T_Out, list[ChatMessage]],
) -> None:
"""Handler for single ChatMessage input as workflow entry point.
Wraps the message in a list and delegates to _handle_task_message.
Args:
task: ChatMessage from user
ctx: Workflow context
Usage:
workflow.run(ChatMessage(role=Role.USER, text="Write a blog post about AI agents"))
"""
await self._handle_messages([task], ctx)
@handler
async def handle_messages(
self,
task: list[ChatMessage],
ctx: WorkflowContext[GroupChatWorkflowContext_T_Out, list[ChatMessage]],
) -> None:
"""Handler for list of ChatMessages as workflow entry point.
Delegates to _handle_task_message.
Args:
task: List of ChatMessages from user
ctx: Workflow context
Usage:
workflow.run([
ChatMessage(role=Role.USER, text="Write a blog post about AI agents"),
ChatMessage(role=Role.USER, text="Make it engaging and informative.")
])
"""
if not task:
raise ValueError("At least one ChatMessage is required to start the group chat workflow.")
await self._handle_messages(task, ctx)
@handler
async def handle_participant_response(
self,
response: AgentExecutorResponse | GroupChatResponseMessage,
ctx: WorkflowContext[GroupChatWorkflowContext_T_Out, list[ChatMessage]],
) -> None:
"""Handler for participant responses.
This method can be overridden by subclasses if specific response handling is needed.
Args:
response: Response from a participant
ctx: Workflow context
"""
await ctx.add_event(
GroupChatResponseReceivedEvent(
round_index=self._round_index,
participant_name=ctx.source_executor_ids[0] if ctx.source_executor_ids else "unknown",
data=response,
)
)
await self._handle_response(response, ctx)
# endregion
# region Handler methods subclasses must implement
async def _handle_messages(
self,
messages: list[ChatMessage],
ctx: WorkflowContext[GroupChatWorkflowContext_T_Out, list[ChatMessage]],
) -> None:
"""Handle task messages from users as workflow entry point.
Subclasses must implement this method to define pattern-specific orchestration logic.
Args:
messages: Task messages from user
ctx: Workflow context
"""
raise NotImplementedError("_handle_messages must be implemented by subclasses.")
async def _handle_response(
self,
response: AgentExecutorResponse | GroupChatResponseMessage,
ctx: WorkflowContext[GroupChatWorkflowContext_T_Out, list[ChatMessage]],
) -> None:
"""Handle a participant response.
Subclasses must implement this method to define pattern-specific response handling logic.
Args:
response: Response from a participant
ctx: Workflow context
"""
raise NotImplementedError("_handle_response must be implemented by subclasses.")
# endregion
# Conversation state management (shared across all patterns)
@@ -72,7 +325,7 @@ class BaseGroupChatOrchestrator(Executor, ABC):
Args:
messages: Messages to append
"""
self._conversation.extend(messages)
self._full_conversation.extend(messages)
def _get_conversation(self) -> list[ChatMessage]:
"""Get a copy of the current conversation.
@@ -80,11 +333,27 @@ class BaseGroupChatOrchestrator(Executor, ABC):
Returns:
Cloned conversation list
"""
return list(self._conversation)
return list(self._full_conversation)
def _process_participant_response(
self, response: AgentExecutorResponse | GroupChatResponseMessage
) -> list[ChatMessage]:
"""Extract ChatMessage from participant response.
Args:
response: Response from participant
Returns:
List of ChatMessages extracted from the response
"""
if isinstance(response, AgentExecutorResponse):
return response.agent_run_response.messages
if isinstance(response, GroupChatResponseMessage):
return [response.message]
raise TypeError(f"Unsupported response type: {type(response)}")
def _clear_conversation(self) -> None:
"""Clear the conversation history."""
self._conversation.clear()
self._full_conversation.clear()
def _increment_round(self) -> None:
"""Increment the round counter."""
@@ -102,97 +371,121 @@ class BaseGroupChatOrchestrator(Executor, ABC):
return False
result = self._termination_condition(self._get_conversation())
if inspect.iscoroutine(result) or inspect.isawaitable(result):
if inspect.isawaitable(result):
result = await result
return bool(result)
return result
@abstractmethod
def _get_author_name(self) -> str:
"""Get the author name for orchestrator-generated messages.
async def _check_terminate_and_yield(self, ctx: WorkflowContext[Never, list[ChatMessage]]) -> bool:
"""Check termination conditions and yield completion if met.
Subclasses must implement this to provide a stable author name
for completion messages and other orchestrator-generated content.
Args:
ctx: Workflow context for yielding output
Returns:
Author name to use for messages generated by this orchestrator
True if termination condition met and output yielded, False otherwise
"""
...
terminate = await self._check_termination()
if terminate:
self._append_messages([self._create_completion_message(self.TERMINATION_CONDITION_MET_MESSAGE)])
await ctx.yield_output(self._full_conversation)
return True
def _create_completion_message(
self,
text: str | None = None,
reason: str = "completed",
) -> ChatMessage:
return False
def _create_completion_message(self, message: str) -> ChatMessage:
"""Create a standardized completion message.
Args:
text: Optional message text (auto-generated if None)
reason: Completion reason for default text
message: Completion text
Returns:
ChatMessage with completion content
"""
from .._types import Role
message_text = text or f"Conversation {reason}."
return ChatMessage(
role=Role.ASSISTANT,
text=message_text,
author_name=self._get_author_name(),
)
return ChatMessage(role=Role.ASSISTANT, text=message, author_name=self._name)
# Participant routing (shared across all patterns)
async def _route_to_participant(
async def _broadcast_messages_to_participants(
self,
participant_name: str,
conversation: list[ChatMessage],
ctx: WorkflowContext[Any, Any],
messages: list[ChatMessage],
ctx: WorkflowContext[AgentExecutorRequest | GroupChatParticipantMessage],
participants: Sequence[str] | None = None,
) -> None:
"""Broadcast messages to participants.
This method sends the given messages to all registered participants
or a specified subset. This acts as a message broadcast mechanism for
participants in the group chat to stay synchronized.
Args:
messages: Messages to send
ctx: Workflow context for message broadcasting
participants: Optional list of participant names to route to.
If None, routes to all registered participants.
"""
target_participants = (
participants if participants is not None else list(self._participant_registry.participants)
)
async def _send_messages(target: str) -> None:
if self._participant_registry.is_agent(target):
# Send messages without requesting a response
await ctx.send_message(AgentExecutorRequest(messages=messages, should_respond=False), target_id=target)
else:
# Send messages wrapped in GroupChatParticipantMessage
await ctx.send_message(GroupChatParticipantMessage(messages=messages), target_id=target)
await asyncio.gather(*[_send_messages(p) for p in target_participants])
async def _send_request_to_participant(
self,
target: str,
ctx: WorkflowContext[AgentExecutorRequest | GroupChatRequestMessage],
*,
instruction: str | None = None,
task: ChatMessage | None = None,
additional_instruction: str | None = None,
metadata: dict[str, Any] | None = None,
) -> None:
"""Route a conversation to a participant.
"""Send a request to a participant.
This method handles the dual envelope pattern:
- AgentExecutors receive AgentExecutorRequest (messages only)
- Custom executors receive GroupChatRequestMessage (full context)
Args:
participant_name: Name of the participant to route to
conversation: Conversation history to send
target: Name of the participant to route to
ctx: Workflow context for message routing
instruction: Optional instruction from manager/orchestrator
task: Optional task context
additional_instruction: Optional additional instruction for the participant.
This can be used to provide guidance to steer the participant's response.
metadata: Optional metadata dict
Raises:
ValueError: If participant is not registered
"""
from ._agent_executor import AgentExecutorRequest
from ._orchestrator_helpers import prepare_participant_request
entry_id = self._registry.get_entry_id(participant_name)
if entry_id is None:
raise ValueError(f"No registered entry executor for participant '{participant_name}'.")
if self._registry.is_agent(participant_name):
if self._participant_registry.is_agent(target):
# AgentExecutors receive simple message list
await ctx.send_message(
AgentExecutorRequest(messages=conversation, should_respond=True),
target_id=entry_id,
messages: list[ChatMessage] = []
if additional_instruction:
messages.append(ChatMessage(role=Role.USER, text=additional_instruction))
request = AgentExecutorRequest(messages=messages, should_respond=True)
await ctx.send_message(request, target_id=target)
await ctx.add_event(
GroupChatRequestSentEvent(
round_index=self._round_index,
participant_name=target,
data=request,
)
)
else:
# Custom executors receive full context envelope
request = prepare_participant_request(
participant_name=participant_name,
conversation=conversation,
instruction=instruction or "",
task=task,
metadata=metadata,
request = GroupChatRequestMessage(additional_instruction=additional_instruction, metadata=metadata) # type: ignore[assignment]
await ctx.send_message(request, target_id=target)
await ctx.add_event(
GroupChatRequestSentEvent(
round_index=self._round_index,
participant_name=target,
data=request,
)
)
await ctx.send_message(request, target_id=entry_id)
# Round limit enforcement (shared across all patterns)
@@ -217,6 +510,23 @@ class BaseGroupChatOrchestrator(Executor, ABC):
return False
async def _check_round_limit_and_yield(self, ctx: WorkflowContext[Never, list[ChatMessage]]) -> bool:
"""Check round limit and yield completion if reached.
Args:
ctx: Workflow context for yielding output
Returns:
True if round limit reached and output yielded, False otherwise
"""
reach_max_rounds = self._check_round_limit()
if reach_max_rounds:
self._append_messages([self._create_completion_message(self.MAX_ROUNDS_MET_MESSAGE)])
await ctx.yield_output(self._full_conversation)
return True
return False
# State persistence (shared across all patterns)
# State persistence (shared across all patterns)
@@ -234,8 +544,9 @@ class BaseGroupChatOrchestrator(Executor, ABC):
from ._orchestration_state import OrchestrationState
state = OrchestrationState(
conversation=list(self._conversation),
conversation=list(self._full_conversation),
round_index=self._round_index,
orchestrator_name=self._name,
metadata=self._snapshot_pattern_metadata(),
)
return state.to_dict()
@@ -263,8 +574,9 @@ class BaseGroupChatOrchestrator(Executor, ABC):
from ._orchestration_state import OrchestrationState
orch_state = OrchestrationState.from_dict(state)
self._conversation = list(orch_state.conversation)
self._full_conversation = list(orch_state.conversation)
self._round_index = orch_state.round_index
self._name = orch_state.orchestrator_name
self._restore_pattern_metadata(orch_state.metadata)
def _restore_pattern_metadata(self, metadata: dict[str, Any]) -> None:
python/packages/core/agent_framework/_workflows/_concurrent.py
+63 -32
View File
@@ -10,11 +10,12 @@ from typing_extensions import Never
from agent_framework import AgentProtocol, ChatMessage, Role
from ._agent_executor import AgentExecutorRequest, AgentExecutorResponse
from ._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
from ._agent_utils import resolve_agent_id
from ._checkpoint import CheckpointStorage
from ._executor import Executor, handler
from ._message_utils import normalize_messages_input
from ._orchestration_request_info import RequestInfoInterceptor
from ._orchestration_request_info import AgentApprovalExecutor
from ._workflow import Workflow
from ._workflow_builder import WorkflowBuilder
from ._workflow_context import WorkflowContext
@@ -247,6 +248,7 @@ class ConcurrentBuilder:
self._aggregator_factory: Callable[[], Executor] | None = None
self._checkpoint_storage: CheckpointStorage | None = None
self._request_info_enabled: bool = False
self._request_info_filter: set[str] | None = None
def register_participants(
self,
@@ -461,25 +463,68 @@ class ConcurrentBuilder:
self._checkpoint_storage = checkpoint_storage
return self
def with_request_info(self) -> "ConcurrentBuilder":
"""Enable request info before aggregation in the workflow.
def with_request_info(
self,
*,
agents: Sequence[str | AgentProtocol] | None = None,
) -> "ConcurrentBuilder":
"""Enable request info after agent participant responses.
When enabled, the workflow pauses after all parallel agents complete,
emitting a RequestInfoEvent that allows the caller to review and optionally
modify the combined results before aggregation. The caller provides feedback
via the standard response_handler/request_info pattern.
This enables human-in-the-loop (HIL) scenarios for the sequential orchestration.
When enabled, the workflow pauses after each agent participant runs, emitting
a RequestInfoEvent that allows the caller to review the conversation and optionally
inject guidance for the agent participant to iterate. The caller provides input via
the standard response_handler/request_info pattern.
Note:
Unlike SequentialBuilder and GroupChatBuilder, ConcurrentBuilder does not
support per-agent filtering since all agents run in parallel and results
are collected together. The pause occurs once with all agent outputs received.
Simulated flow with HIL:
Input -> [Agent Participant <-> Request Info] -> [Agent Participant <-> Request Info] -> ...
Note: This is only available for agent participants. Executor participants can incorporate
request info handling in their own implementation if desired.
Args:
agents: Optional list of agents names or agent factories to enable request info for.
If None, enables HIL for all agent participants.
Returns:
self: The builder instance for fluent chaining.
Self for fluent chaining
"""
from ._orchestration_request_info import resolve_request_info_filter
self._request_info_enabled = True
self._request_info_filter = resolve_request_info_filter(list(agents) if agents else None)
return self
def _resolve_participants(self) -> list[Executor]:
"""Resolve participant instances into Executor objects."""
participants: list[Executor | AgentProtocol] = []
if self._participant_factories:
# Resolve the participant factories now. This doesn't break the factory pattern
# since the Sequential builder still creates new instances per workflow build.
for factory in self._participant_factories:
p = factory()
participants.append(p)
else:
participants = self._participants
executors: list[Executor] = []
for p in participants:
if isinstance(p, Executor):
executors.append(p)
elif isinstance(p, AgentProtocol):
if self._request_info_enabled and (
not self._request_info_filter or resolve_agent_id(p) in self._request_info_filter
):
# Handle request info enabled agents
executors.append(AgentApprovalExecutor(p))
else:
executors.append(AgentExecutor(p))
else:
raise TypeError(f"Participants must be AgentProtocol or Executor instances. Got {type(p).__name__}.")
return executors
def build(self) -> Workflow:
r"""Build and validate the concurrent workflow.
@@ -521,29 +566,15 @@ class ConcurrentBuilder:
)
)
participants: list[Executor | AgentProtocol] = []
if self._participant_factories:
# Resolve the participant factories now. This doesn't break the factory pattern
# since the Concurrent builder still creates new instances per workflow build.
for factory in self._participant_factories:
p = factory()
participants.append(p)
else:
participants = self._participants
# Resolve participants and participant factories to executors
participants: list[Executor] = self._resolve_participants()
builder = WorkflowBuilder()
builder.set_start_executor(dispatcher)
# Fan-out for parallel execution
builder.add_fan_out_edges(dispatcher, participants)
if self._request_info_enabled:
# Insert interceptor between fan-in and aggregator
# participants -> fan-in -> interceptor -> aggregator
request_info_interceptor = RequestInfoInterceptor(executor_id="request_info")
builder.add_fan_in_edges(participants, request_info_interceptor)
builder.add_edge(request_info_interceptor, aggregator)
else:
# Direct fan-in to aggregator
builder.add_fan_in_edges(participants, aggregator)
# Direct fan-in to aggregator
builder.add_fan_in_edges(participants, aggregator)
if self._checkpoint_storage is not None:
builder = builder.with_checkpointing(self._checkpoint_storage)
python/packages/core/agent_framework/_workflows/_events.py
+4 -4
View File
@@ -367,9 +367,9 @@ class ExecutorFailedEvent(ExecutorEvent):
class AgentRunUpdateEvent(ExecutorEvent):
"""Event triggered when an agent is streaming messages."""
data: AgentRunResponseUpdate | None
data: AgentRunResponseUpdate
def __init__(self, executor_id: str, data: AgentRunResponseUpdate | None = None):
def __init__(self, executor_id: str, data: AgentRunResponseUpdate):
"""Initialize the agent streaming event."""
super().__init__(executor_id, data)
@@ -381,9 +381,9 @@ class AgentRunUpdateEvent(ExecutorEvent):
class AgentRunEvent(ExecutorEvent):
"""Event triggered when an agent run is completed."""
data: AgentRunResponse | None
data: AgentRunResponse
def __init__(self, executor_id: str, data: AgentRunResponse | None = None):
def __init__(self, executor_id: str, data: AgentRunResponse):
"""Initialize the agent run event."""
super().__init__(executor_id, data)
python/packages/core/agent_framework/_workflows/_executor.py
+26 -4
View File
@@ -250,6 +250,8 @@ class Executor(RequestInfoMixin, DictConvertible):
):
# Find the handler and handler spec that matches the message type.
handler = self._find_handler(message)
original_message = message
if isinstance(message, Message):
# Unwrap raw data for handler call
message = message.data
@@ -261,6 +263,9 @@ class Executor(RequestInfoMixin, DictConvertible):
runner_context=runner_context,
trace_contexts=trace_contexts,
source_span_ids=source_span_ids,
request_id=original_message.original_request_info_event.request_id
if isinstance(original_message, Message) and original_message.original_request_info_event
else None,
)
# Invoke the handler with the message and context
@@ -291,6 +296,7 @@ class Executor(RequestInfoMixin, DictConvertible):
runner_context: RunnerContext,
trace_contexts: list[dict[str, str]] | None = None,
source_span_ids: list[str] | None = None,
request_id: str | None = None,
) -> WorkflowContext[Any]:
"""Create the appropriate WorkflowContext based on the handler's context annotation.
@@ -300,6 +306,7 @@ class Executor(RequestInfoMixin, DictConvertible):
runner_context: The runner context that provides methods to send messages and events.
trace_contexts: Optional trace contexts from multiple sources for OpenTelemetry propagation.
source_span_ids: Optional source span IDs from multiple sources for linking.
request_id: Optional request ID if this context is for a `handle_response` handler.
Returns:
WorkflowContext[Any] based on the handler's context annotation.
@@ -312,6 +319,7 @@ class Executor(RequestInfoMixin, DictConvertible):
runner_context=runner_context,
trace_contexts=trace_contexts,
source_span_ids=source_span_ids,
request_id=request_id,
)
def _discover_handlers(self) -> None:
@@ -356,7 +364,17 @@ class Executor(RequestInfoMixin, DictConvertible):
True if the executor can handle the message type, False otherwise.
"""
if message.type == MessageType.RESPONSE:
return any(is_instance_of(message.data, message_type) for message_type in self._response_handlers)
if message.original_request_info_event is None:
logger.warning(
f"Executor {self.__class__.__name__} received a response message without an original request event."
)
return False
return any(
is_instance_of(message.original_request_info_event.data, message_type[0])
and is_instance_of(message.data, message_type[1])
for message_type in self._response_handlers
)
return any(is_instance_of(message.data, message_type) for message_type in self._handlers)
@@ -427,7 +445,7 @@ class Executor(RequestInfoMixin, DictConvertible):
output_types: set[type[Any]] = set()
# Collect workflow output types from all handlers
for handler_spec in self._handler_specs:
for handler_spec in self._handler_specs + self._response_handler_specs:
handler_workflow_output_types = handler_spec.get("workflow_output_types", [])
output_types.update(handler_workflow_output_types)
@@ -457,11 +475,15 @@ class Executor(RequestInfoMixin, DictConvertible):
f"Executor {self.__class__.__name__} cannot handle message of type {type(message.data)}."
)
# Response message case - find response handler based on original request and response types
handler = self._find_response_handler(message.original_request, message.data)
if message.original_request_info_event is None:
raise RuntimeError(
f"Executor {self.__class__.__name__} received a response message without an original request event."
)
handler = self._find_response_handler(message.original_request_info_event.data, message.data)
if not handler:
raise RuntimeError(
f"Executor {self.__class__.__name__} cannot handle request of type "
f"{type(message.original_request)} and response of type {type(message.data)}."
f"{type(message.original_request_info_event.data)} and response of type {type(message.data)}."
)
return handler
python/packages/core/agent_framework/_workflows/_group_chat.py
+698 -1847
View File
File diff suppressed because it is too large Load Diff
python/packages/core/agent_framework/_workflows/_handoff.py
+715 -1530
View File
File diff suppressed because it is too large Load Diff
python/packages/core/agent_framework/_workflows/_magentic.py
+670 -1745
View File
File diff suppressed because it is too large Load Diff
python/packages/core/agent_framework/_workflows/_orchestration_request_info.py
+90 -273
View File
@@ -1,37 +1,20 @@
# Copyright (c) Microsoft. All rights reserved.
"""Request info support for high-level builder APIs.
This module provides a mechanism for pausing workflows to request external input
before agent turns in `SequentialBuilder`, `ConcurrentBuilder`, `GroupChatBuilder`,
and `HandoffBuilder`.
The design follows the standard `request_info` pattern used throughout the
workflow system, keeping the API consistent and predictable.
Key components:
- AgentInputRequest: Request type emitted via RequestInfoEvent for pre-agent steering
- RequestInfoInterceptor: Internal executor that pauses workflow before agent runs
"""
import logging
import uuid
from dataclasses import dataclass, field
from typing import Any
from dataclasses import dataclass
from .._agents import AgentProtocol
from .._types import ChatMessage, Role
from ._agent_executor import AgentExecutorRequest
from ._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
from ._agent_utils import resolve_agent_id
from ._executor import Executor, handler
from ._request_info_mixin import response_handler
from ._workflow import Workflow
from ._workflow_builder import WorkflowBuilder
from ._workflow_context import WorkflowContext
logger = logging.getLogger(__name__)
from ._workflow_executor import WorkflowExecutor
def resolve_request_info_filter(
agents: list[str | AgentProtocol | Executor] | None,
) -> set[str] | None:
def resolve_request_info_filter(agents: list[str | AgentProtocol] | None) -> set[str]:
"""Resolve a list of agent/executor references to a set of IDs for filtering.
Args:
@@ -42,288 +25,122 @@ def resolve_request_info_filter(
Set of executor/agent IDs to filter on, or None if no filtering.
"""
if agents is None:
return None
return set()
result: set[str] = set()
for agent in agents:
if isinstance(agent, str):
result.add(agent)
elif isinstance(agent, Executor):
result.add(agent.id)
elif isinstance(agent, AgentProtocol):
name = getattr(agent, "name", None)
if name:
result.add(name)
else:
logger.warning("AgentProtocol without name cannot be used for request_info filtering")
result.add(resolve_agent_id(agent))
else:
logger.warning(f"Unsupported type for request_info filter: {type(agent).__name__}")
raise TypeError(f"Unsupported type for request_info filter: {type(agent).__name__}")
return result if result else None
return result
@dataclass
class AgentInputRequest:
"""Request for human input before an agent runs in high-level builder workflows.
Emitted via RequestInfoEvent when a workflow pauses before an agent executes.
The response is injected into the conversation as a user message to steer
the agent's behavior.
This is the standard request type used by `.with_request_info()` on
SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, and HandoffBuilder.
class AgentRequestInfoResponse:
"""Response containing additional information requested from users for agents.
Attributes:
target_agent_id: ID of the agent that is about to run
conversation: Current conversation history the agent will receive
instruction: Optional instruction from the orchestrator (e.g., manager in GroupChat)
metadata: Builder-specific context (stores internal state for resume)
messages: list[ChatMessage]: Additional messages provided by users. If empty,
the agent response is approved as-is.
"""
target_agent_id: str | None
conversation: list[ChatMessage] = field(default_factory=lambda: [])
instruction: str | None = None
metadata: dict[str, Any] = field(default_factory=lambda: {})
messages: list[ChatMessage]
# Keep legacy name as alias for backward compatibility
AgentResponseReviewRequest = AgentInputRequest
DEFAULT_REQUEST_INFO_ID = "request_info_interceptor"
class RequestInfoInterceptor(Executor):
"""Internal executor that pauses workflow for human input before agent runs.
This executor is inserted into the workflow graph by builders when
`.with_request_info()` is called. It intercepts AgentExecutorRequest messages
BEFORE the agent runs and pauses the workflow via `ctx.request_info()` with
an AgentInputRequest.
When a response is received, the response handler injects the input
as a user message into the conversation and forwards the request to the agent.
The optional `agent_filter` parameter allows limiting which agents trigger the pause.
If the target agent's ID is not in the filter set, the request is forwarded
without pausing.
"""
def __init__(
self,
executor_id: str | None = None,
agent_filter: set[str] | None = None,
) -> None:
"""Initialize the request info interceptor executor.
@staticmethod
def from_messages(messages: list[ChatMessage]) -> "AgentRequestInfoResponse":
"""Create an AgentRequestInfoResponse from a list of ChatMessages.
Args:
executor_id: ID for this executor. If None, generates a unique ID
using the format "request_info_interceptor-<uuid4>".
agent_filter: Optional set of agent/executor IDs to filter on.
If provided, only requests to these agents trigger a pause.
If None (default), all requests trigger a pause.
messages: List of ChatMessage instances provided by users.
Returns:
AgentRequestInfoResponse instance.
"""
if executor_id is None:
executor_id = f"{DEFAULT_REQUEST_INFO_ID}-{uuid.uuid4().hex[:8]}"
super().__init__(executor_id)
self._agent_filter = agent_filter
return AgentRequestInfoResponse(messages=messages)
def _should_pause_for_agent(self, agent_id: str | None) -> bool:
"""Check if we should pause for the given agent ID."""
if self._agent_filter is None:
return True
if agent_id is None:
return False
# Check both the full ID and any name portion after a prefix
# e.g., "groupchat_agent:writer" should match filter "writer"
if agent_id in self._agent_filter:
return True
# Extract name from prefixed IDs like "groupchat_agent:writer" or "request_info:writer"
if ":" in agent_id:
name_part = agent_id.split(":", 1)[1]
if name_part in self._agent_filter:
return True
return False
@staticmethod
def from_strings(texts: list[str]) -> "AgentRequestInfoResponse":
"""Create an AgentRequestInfoResponse from a list of string messages.
def _extract_agent_name_from_executor_id(self) -> str | None:
"""Extract the agent name from this interceptor's executor ID.
Args:
texts: List of text messages provided by users.
The interceptor ID is typically "request_info:<agent_name>", so we
extract the agent name to determine which agent we're intercepting for.
Returns:
AgentRequestInfoResponse instance.
"""
if ":" in self.id:
return self.id.split(":", 1)[1]
return None
return AgentRequestInfoResponse(messages=[ChatMessage(role=Role.USER, text=text) for text in texts])
@staticmethod
def approve() -> "AgentRequestInfoResponse":
"""Create an AgentRequestInfoResponse that approves the original agent response.
Returns:
AgentRequestInfoResponse instance with no additional messages.
"""
return AgentRequestInfoResponse(messages=[])
class AgentRequestInfoExecutor(Executor):
"""Executor for gathering request info from users to assist agents."""
@handler
async def intercept_agent_request(
self,
request: AgentExecutorRequest,
ctx: WorkflowContext[AgentExecutorRequest, Any],
) -> None:
"""Intercept request before agent runs and pause for human input.
Pauses the workflow and emits a RequestInfoEvent with the current
conversation for steering. If an agent filter is configured and this
agent is not in the filter, the request is forwarded without pausing.
Args:
request: The request about to be sent to the agent
ctx: Workflow context for requesting info
"""
# Determine the target agent from our executor ID
target_agent = self._extract_agent_name_from_executor_id()
# Check if we should pause for this agent
if not self._should_pause_for_agent(target_agent):
logger.debug(f"Skipping request_info pause for agent {target_agent} (not in filter)")
await ctx.send_message(request)
return
conversation = list(request.messages or [])
input_request = AgentInputRequest(
target_agent_id=target_agent,
conversation=conversation,
instruction=None, # Could be extended to include manager instruction
metadata={"_original_request": request, "_input_type": "AgentExecutorRequest"},
)
await ctx.request_info(input_request, str)
@handler
async def intercept_conversation(
self,
messages: list[ChatMessage],
ctx: WorkflowContext[list[ChatMessage], Any],
) -> None:
"""Intercept conversation before agent runs (used by SequentialBuilder).
SequentialBuilder passes list[ChatMessage] directly to agents. This handler
intercepts that flow and pauses for human input.
Args:
messages: The conversation about to be sent to the agent
ctx: Workflow context for requesting info
"""
# Determine the target agent from our executor ID
target_agent = self._extract_agent_name_from_executor_id()
# Check if we should pause for this agent
if not self._should_pause_for_agent(target_agent):
logger.debug(f"Skipping request_info pause for agent {target_agent} (not in filter)")
await ctx.send_message(messages)
return
input_request = AgentInputRequest(
target_agent_id=target_agent,
conversation=list(messages),
instruction=None,
metadata={"_original_messages": messages, "_input_type": "list[ChatMessage]"},
)
await ctx.request_info(input_request, str)
@handler
async def intercept_concurrent_requests(
self,
requests: list[AgentExecutorRequest],
ctx: WorkflowContext[list[AgentExecutorRequest], Any],
) -> None:
"""Intercept requests before concurrent agents run.
This handler is used by ConcurrentBuilder to get human input before
all parallel agents execute.
Args:
requests: List of requests for all concurrent agents
ctx: Workflow context for requesting info
"""
# Combine conversations for display
combined_conversation: list[ChatMessage] = []
if requests:
combined_conversation = list(requests[0].messages or [])
input_request = AgentInputRequest(
target_agent_id=None, # Multiple agents
conversation=combined_conversation,
instruction=None,
metadata={"_original_requests": requests},
)
await ctx.request_info(input_request, str)
async def request_info(self, agent_response: AgentExecutorResponse, ctx: WorkflowContext) -> None:
"""Handle the agent's response and gather additional info from users."""
await ctx.request_info(agent_response, AgentRequestInfoResponse)
@response_handler
async def handle_input_response(
async def handle_request_info_response(
self,
original_request: AgentInputRequest,
# TODO(@moonbox3): Extend to support other content types
response: str,
ctx: WorkflowContext[AgentExecutorRequest | list[ChatMessage], Any],
original_request: AgentExecutorResponse,
response: AgentRequestInfoResponse,
ctx: WorkflowContext[AgentExecutorRequest, AgentExecutorResponse],
) -> None:
"""Handle the human input and forward the modified request to the agent.
"""Process the additional info provided by users."""
if response.messages:
# User provided additional messages, further iterate on agent response
await ctx.send_message(AgentExecutorRequest(messages=response.messages, should_respond=True))
else:
# No additional info, approve original agent response
await ctx.yield_output(original_request)
Injects the response as a user message into the conversation
and forwards the modified request to the agent.
class AgentApprovalExecutor(WorkflowExecutor):
"""Executor for enabling scenarios requiring agent approval in an orchestration.
This executor wraps a sub workflow that contains two executors: an agent executor
and an request info executor. The agent executor provides intelligence generation,
while the request info executor gathers input from users to further iterate on the
agent's output or send the final response to down stream executors in the orchestration.
"""
def __init__(self, agent: AgentProtocol) -> None:
"""Initialize the AgentApprovalExecutor.
Args:
original_request: The AgentInputRequest that triggered the pause
response: The human input text
ctx: Workflow context for continuing the workflow
TODO: Consider having each orchestration implement its own response handler
for more specialized behavior.
agent: The agent protocol to use for generating responses.
"""
human_message = ChatMessage(role=Role.USER, text=response)
super().__init__(workflow=self._build_workflow(agent), id=resolve_agent_id(agent), propagate_request=True)
self._description = agent.description
# Handle concurrent case (list of AgentExecutorRequest)
original_requests: list[AgentExecutorRequest] | None = original_request.metadata.get("_original_requests")
if original_requests is not None:
updated_requests: list[AgentExecutorRequest] = []
for orig_req in original_requests:
messages = list(orig_req.messages or [])
messages.append(human_message)
updated_requests.append(
AgentExecutorRequest(
messages=messages,
should_respond=orig_req.should_respond,
)
)
def _build_workflow(self, agent: AgentProtocol) -> Workflow:
"""Build the internal workflow for the AgentApprovalExecutor."""
agent_executor = AgentExecutor(agent)
request_info_executor = AgentRequestInfoExecutor(id="agent_request_info_executor")
logger.debug(
f"Human input received for concurrent workflow, "
f"continuing with {len(updated_requests)} updated requests"
)
await ctx.send_message(updated_requests) # type: ignore[arg-type]
return
return (
WorkflowBuilder()
# Create a loop between agent executor and request info executor
.add_edge(agent_executor, request_info_executor)
.add_edge(request_info_executor, agent_executor)
.set_start_executor(agent_executor)
.build()
)
# Handle list[ChatMessage] case (SequentialBuilder)
original_messages: list[ChatMessage] | None = original_request.metadata.get("_original_messages")
if original_messages is not None:
messages = list(original_messages)
messages.append(human_message)
logger.debug(
f"Human input received for agent {original_request.target_agent_id}, "
f"forwarding conversation with steering context"
)
await ctx.send_message(messages)
return
# Handle AgentExecutorRequest case (GroupChatBuilder)
orig_request: AgentExecutorRequest | None = original_request.metadata.get("_original_request")
if orig_request is not None:
messages = list(orig_request.messages or [])
messages.append(human_message)
updated_request = AgentExecutorRequest(
messages=messages,
should_respond=orig_request.should_respond,
)
logger.debug(
f"Human input received for agent {original_request.target_agent_id}, "
f"forwarding request with steering context"
)
await ctx.send_message(updated_request)
return
logger.error("Input response handler missing original request/messages in metadata")
raise RuntimeError("Missing original request or messages in AgentInputRequest metadata")
@property
def description(self) -> str | None:
"""Get a description of the underlying agent."""
return self._description
python/packages/core/agent_framework/_workflows/_orchestration_state.py
+1
View File
@@ -47,6 +47,7 @@ class OrchestrationState:
conversation: list[ChatMessage] = field(default_factory=_new_chat_message_list)
round_index: int = 0
orchestrator_name: str = ""
metadata: dict[str, Any] = field(default_factory=_new_metadata_dict)
task: ChatMessage | None = None
python/packages/core/agent_framework/_workflows/_orchestrator_helpers.py
-108
View File
@@ -7,13 +7,9 @@ No inheritance required - just import and call.
"""
import logging
from typing import TYPE_CHECKING, Any
from .._types import ChatMessage, Role
if TYPE_CHECKING:
from ._group_chat import _GroupChatRequestMessage # type: ignore[reportPrivateUsage]
logger = logging.getLogger(__name__)
@@ -99,107 +95,3 @@ def create_completion_message(
text=message_text,
author_name=author_name,
)
def prepare_participant_request(
*,
participant_name: str,
conversation: list[ChatMessage],
instruction: str | None = None,
task: ChatMessage | None = None,
metadata: dict[str, Any] | None = None,
) -> "_GroupChatRequestMessage":
"""Create a standardized participant request message.
Simple helper to avoid duplicating request construction.
Args:
participant_name: Name of the target participant
conversation: Conversation history to send
instruction: Optional instruction from manager/orchestrator
task: Optional task context
metadata: Optional metadata dict
Returns:
GroupChatRequestMessage ready to send
"""
# Import here to avoid circular dependency
from ._group_chat import _GroupChatRequestMessage # type: ignore[reportPrivateUsage]
return _GroupChatRequestMessage(
agent_name=participant_name,
conversation=list(conversation),
instruction=instruction or "",
task=task,
metadata=metadata,
)
class ParticipantRegistry:
"""Simple registry for tracking participant executor IDs and routing info.
Provides a clean interface for the common pattern of mapping participant names
to executor IDs and tracking which are agents vs custom executors.
Tracks both entry IDs (where to send requests) and exit IDs (where responses
come from) to support pipeline configurations where these differ.
"""
def __init__(self) -> None:
self._participant_entry_ids: dict[str, str] = {}
self._agent_executor_ids: dict[str, str] = {}
self._executor_id_to_participant: dict[str, str] = {}
self._non_agent_participants: set[str] = set()
def register(
self,
name: str,
*,
entry_id: str,
is_agent: bool,
exit_id: str | None = None,
) -> None:
"""Register a participant's routing information.
Args:
name: Participant name
entry_id: Executor ID for this participant's entry point (where to send)
is_agent: Whether this is an AgentExecutor (True) or custom Executor (False)
exit_id: Executor ID for this participant's exit point (where responses come from).
If None, defaults to entry_id (single-executor pipeline).
"""
self._participant_entry_ids[name] = entry_id
actual_exit_id = exit_id if exit_id is not None else entry_id
if is_agent:
self._agent_executor_ids[name] = entry_id
# Map both entry and exit IDs to participant name for response routing
self._executor_id_to_participant[entry_id] = name
if actual_exit_id != entry_id:
self._executor_id_to_participant[actual_exit_id] = name
else:
self._non_agent_participants.add(name)
def get_entry_id(self, name: str) -> str | None:
"""Get the entry executor ID for a participant name."""
return self._participant_entry_ids.get(name)
def get_participant_name(self, executor_id: str) -> str | None:
"""Get the participant name for an executor ID (agents only)."""
return self._executor_id_to_participant.get(executor_id)
def is_agent(self, name: str) -> bool:
"""Check if a participant is an agent (vs custom executor)."""
return name in self._agent_executor_ids
def is_registered(self, name: str) -> bool:
"""Check if a participant is registered."""
return name in self._participant_entry_ids
def is_participant_registered(self, name: str) -> bool:
"""Check if a participant is registered (alias for is_registered for compatibility)."""
return self.is_registered(name)
def all_participants(self) -> set[str]:
"""Get all registered participant names."""
return set(self._participant_entry_ids.keys())
python/packages/core/agent_framework/_workflows/_participant_utils.py
-134
View File
@@ -1,134 +0,0 @@
# Copyright (c) Microsoft. All rights reserved.
"""Shared participant helpers for orchestration builders."""
import re
from collections.abc import Callable, Iterable, Mapping
from dataclasses import dataclass
from typing import Any
from .._agents import AgentProtocol
from ._agent_executor import AgentExecutor
from ._executor import Executor
@dataclass
class GroupChatParticipantSpec:
"""Metadata describing a single participant in group chat orchestrations.
Used by multiple orchestration patterns (GroupChat, Handoff, Magentic) to describe
participants with consistent structure across different workflow types.
Attributes:
name: Unique identifier for the participant used by managers for selection
participant: AgentProtocol or Executor instance representing the participant
description: Human-readable description provided to managers for selection context
"""
name: str
participant: AgentProtocol | Executor
description: str
_SANITIZE_PATTERN = re.compile(r"[^0-9a-zA-Z]+")
def sanitize_identifier(value: str, *, default: str = "agent") -> str:
"""Return a deterministic, lowercase identifier derived from `value`."""
cleaned = _SANITIZE_PATTERN.sub("_", value).strip("_")
if not cleaned:
cleaned = default
if cleaned[0].isdigit():
cleaned = f"{default}_{cleaned}"
return cleaned.lower()
def wrap_participant(participant: AgentProtocol | Executor, *, executor_id: str | None = None) -> Executor:
"""Represent `participant` as an `Executor`."""
if isinstance(participant, Executor):
return participant
if not isinstance(participant, AgentProtocol):
raise TypeError(
f"Participants must implement AgentProtocol or be Executor instances. Got {type(participant).__name__}."
)
executor_id = executor_id or participant.name or participant.id
return AgentExecutor(participant, id=executor_id)
def participant_description(participant: AgentProtocol | Executor, fallback: str) -> str:
"""Produce a human-readable description for manager context."""
if isinstance(participant, Executor):
description = getattr(participant, "description", None)
if isinstance(description, str) and description.strip():
return description.strip()
return fallback
description = getattr(participant, "description", None)
if isinstance(description, str) and description.strip():
return description.strip()
return fallback
def build_alias_map(participant: AgentProtocol | Executor, executor: Executor) -> dict[str, str]:
"""Collect canonical and sanitised aliases that should resolve to `executor`."""
aliases: dict[str, str] = {}
def _register(values: Iterable[str | None]) -> None:
for value in values:
if not value:
continue
key = str(value)
if key not in aliases:
aliases[key] = executor.id
sanitized = sanitize_identifier(key)
if sanitized not in aliases:
aliases[sanitized] = executor.id
_register([executor.id])
if isinstance(participant, AgentProtocol):
name = getattr(participant, "name", None)
agent_id = getattr(participant, "id", None)
_register([name, agent_id])
else:
participant_id = getattr(participant, "id", None)
_register([participant_id])
return aliases
def merge_alias_maps(maps: Iterable[Mapping[str, str]]) -> dict[str, str]:
"""Merge alias mappings, preserving the first occurrence of each alias."""
merged: dict[str, str] = {}
for mapping in maps:
for key, value in mapping.items():
merged.setdefault(key, value)
return merged
def prepare_participant_metadata(
participants: Mapping[str, AgentProtocol | Executor],
*,
executor_id_factory: Callable[[str, AgentProtocol | Executor], str | None] | None = None,
description_factory: Callable[[str, AgentProtocol | Executor], str] | None = None,
) -> dict[str, dict[str, Any]]:
"""Return metadata dicts for participants keyed by participant name."""
executors: dict[str, Executor] = {}
descriptions: dict[str, str] = {}
alias_maps: list[Mapping[str, str]] = []
for name, participant in participants.items():
desired_id = executor_id_factory(name, participant) if executor_id_factory else None
executor = wrap_participant(participant, executor_id=desired_id)
fallback_description = description_factory(name, participant) if description_factory else executor.id
descriptions[name] = participant_description(participant, fallback_description)
executors[name] = executor
alias_maps.append(build_alias_map(participant, executor))
aliases = merge_alias_maps(alias_maps)
return {
"executors": executors,
"descriptions": descriptions,
"aliases": aliases,
}
python/packages/core/agent_framework/_workflows/_runner_context.py
+6 -5
View File
@@ -13,6 +13,7 @@ from ._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_val
from ._const import INTERNAL_SOURCE_ID
from ._events import RequestInfoEvent, WorkflowEvent
from ._shared_state import SharedState
from ._typing_utils import is_instance_of
logger = logging.getLogger(__name__)
@@ -44,7 +45,7 @@ class Message:
source_span_ids: list[str] | None = None # Publishing span IDs for linking from multiple sources
# For response messages, the original request data
original_request: Any = None
original_request_info_event: RequestInfoEvent | None = None
# Backward compatibility properties
@property
@@ -66,7 +67,7 @@ class Message:
"type": self.type.value,
"trace_contexts": self.trace_contexts,
"source_span_ids": self.source_span_ids,
"original_request": self.original_request,
"original_request_info_event": encode_checkpoint_value(self.original_request_info_event),
}
@staticmethod
@@ -86,7 +87,7 @@ class Message:
type=MessageType(data.get("type", "standard")),
trace_contexts=data.get("trace_contexts"),
source_span_ids=data.get("source_span_ids"),
original_request=data.get("original_request"),
original_request_info_event=decode_checkpoint_value(data.get("original_request_info_event")),
)
@@ -493,7 +494,7 @@ class InProcRunnerContext:
raise ValueError(f"No pending request found for request_id: {request_id}")
# Validate response type if specified
if event.response_type and not isinstance(response, event.response_type):
if event.response_type and not is_instance_of(response, event.response_type):
raise TypeError(
f"Response type mismatch for request_id {request_id}: "
f"expected {event.response_type.__name__}, got {type(response).__name__}"
@@ -505,7 +506,7 @@ class InProcRunnerContext:
source_id=INTERNAL_SOURCE_ID(event.source_executor_id),
target_id=event.source_executor_id,
type=MessageType.RESPONSE,
original_request=event.data,
original_request_info_event=event,
)
await self.send_message(response_msg)
python/packages/core/agent_framework/_workflows/_sequential.py
+74 -74
View File
@@ -47,13 +47,14 @@ from ._agent_executor import (
AgentExecutor,
AgentExecutorResponse,
)
from ._agent_utils import resolve_agent_id
from ._checkpoint import CheckpointStorage
from ._executor import (
Executor,
handler,
)
from ._message_utils import normalize_messages_input
from ._orchestration_request_info import RequestInfoInterceptor
from ._orchestration_request_info import AgentApprovalExecutor
from ._workflow import Workflow
from ._workflow_builder import WorkflowBuilder
from ._workflow_context import WorkflowContext
@@ -77,24 +78,33 @@ class _InputToConversation(Executor):
await ctx.send_message(normalize_messages_input(messages))
class _ResponseToConversation(Executor):
"""Converts AgentExecutorResponse to list[ChatMessage] conversation for chaining."""
@handler
async def convert(self, response: AgentExecutorResponse, ctx: WorkflowContext[list[ChatMessage]]) -> None:
# Always use full_conversation; AgentExecutor guarantees it is populated.
if response.full_conversation is None: # Defensive: indicates a contract violation
raise RuntimeError("AgentExecutorResponse.full_conversation missing. AgentExecutor must populate it.")
await ctx.send_message(list(response.full_conversation))
class _EndWithConversation(Executor):
"""Terminates the workflow by emitting the final conversation context."""
@handler
async def end(self, conversation: list[ChatMessage], ctx: WorkflowContext[Any, list[ChatMessage]]) -> None:
async def end_with_messages(
self,
conversation: list[ChatMessage],
ctx: WorkflowContext[Any, list[ChatMessage]],
) -> None:
"""Handler for ending with a list of ChatMessage.
This is used when the last participant is a custom executor.
"""
await ctx.yield_output(list(conversation))
@handler
async def end_with_agent_executor_response(
self,
response: AgentExecutorResponse,
ctx: WorkflowContext[Any, list[ChatMessage] | None],
) -> None:
"""Handle case where last participant is an agent.
The agent is wrapped by AgentExecutor and emits AgentExecutorResponse.
"""
await ctx.yield_output(response.full_conversation)
class SequentialBuilder:
r"""High-level builder for sequential agent/executor workflows with shared context.
@@ -206,44 +216,65 @@ class SequentialBuilder:
def with_request_info(
self,
*,
agents: Sequence[str | AgentProtocol | Executor] | None = None,
agents: Sequence[str | AgentProtocol] | None = None,
) -> "SequentialBuilder":
"""Enable request info before agents run in the workflow.
"""Enable request info after agent participant responses.
When enabled, the workflow pauses before each agent runs, emitting
a RequestInfoEvent that allows the caller to review the conversation and
optionally inject guidance before the agent responds. The caller provides
input via the standard response_handler/request_info pattern.
This enables human-in-the-loop (HIL) scenarios for the sequential orchestration.
When enabled, the workflow pauses after each agent participant runs, emitting
a RequestInfoEvent that allows the caller to review the conversation and optionally
inject guidance for the agent participant to iterate. The caller provides input via
the standard response_handler/request_info pattern.
Simulated flow with HIL:
Input -> [Agent Participant <-> Request Info] -> [Agent Participant <-> Request Info] -> ...
Note: This is only available for agent participants. Executor participants can incorporate
request info handling in their own implementation if desired.
Args:
agents: Optional filter - only pause before these specific agents/executors.
Accepts agent names (str), agent instances, or executor instances.
If None (default), pauses before every agent.
agents: Optional list of agents names or agent factories to enable request info for.
If None, enables HIL for all agent participants.
Returns:
self: The builder instance for fluent chaining.
Example:
.. code-block:: python
# Pause before all agents
workflow = SequentialBuilder().participants([a1, a2]).with_request_info().build()
# Pause only before specific agents
workflow = (
SequentialBuilder()
.participants([drafter, reviewer, finalizer])
.with_request_info(agents=[reviewer]) # Only pause before reviewer
.build()
)
Self for fluent chaining
"""
from ._orchestration_request_info import resolve_request_info_filter
self._request_info_enabled = True
self._request_info_filter = resolve_request_info_filter(list(agents) if agents else None)
return self
def _resolve_participants(self) -> list[Executor]:
"""Resolve participant instances into Executor objects."""
participants: list[Executor | AgentProtocol] = []
if self._participant_factories:
# Resolve the participant factories now. This doesn't break the factory pattern
# since the Sequential builder still creates new instances per workflow build.
for factory in self._participant_factories:
p = factory()
participants.append(p)
else:
participants = self._participants
executors: list[Executor] = []
for p in participants:
if isinstance(p, Executor):
executors.append(p)
elif isinstance(p, AgentProtocol):
if self._request_info_enabled and (
not self._request_info_filter or resolve_agent_id(p) in self._request_info_filter
):
# Handle request info enabled agents
executors.append(AgentApprovalExecutor(p))
else:
executors.append(AgentExecutor(p))
else:
raise TypeError(f"Participants must be AgentProtocol or Executor instances. Got {type(p).__name__}.")
return executors
def build(self) -> Workflow:
"""Build and validate the sequential workflow.
@@ -272,48 +303,17 @@ class SequentialBuilder:
input_conv = _InputToConversation(id="input-conversation")
end = _EndWithConversation(id="end")
# Resolve participants and participant factories to executors
participants: list[Executor] = self._resolve_participants()
builder = WorkflowBuilder()
builder.set_start_executor(input_conv)
# Start of the chain is the input normalizer
prior: Executor | AgentProtocol = input_conv
participants: list[Executor | AgentProtocol] = []
if self._participant_factories:
# Resolve the participant factories now. This doesn't break the factory pattern
# since the Sequential builder still creates new instances per workflow build.
for factory in self._participant_factories:
p = factory()
participants.append(p)
else:
participants = self._participants
for p in participants:
if isinstance(p, (AgentProtocol, AgentExecutor)):
label = p.id if isinstance(p, AgentExecutor) else p.name
if self._request_info_enabled:
# Insert request info interceptor BEFORE the agent
interceptor = RequestInfoInterceptor(
executor_id=f"request_info:{label}",
agent_filter=self._request_info_filter,
)
builder.add_edge(prior, interceptor)
builder.add_edge(interceptor, p)
else:
builder.add_edge(prior, p)
resp_to_conv = _ResponseToConversation(id=f"to-conversation:{label}")
builder.add_edge(p, resp_to_conv)
prior = resp_to_conv
elif isinstance(p, Executor):
# Custom executor operates on list[ChatMessage]
# If the executor doesn't handle list[ChatMessage] correctly, validation will fail
builder.add_edge(prior, p)
prior = p
else:
raise TypeError(f"Unsupported participant type: {type(p).__name__}")
builder.add_edge(prior, p)
prior = p
# Terminate with the final conversation
builder.add_edge(prior, end)
python/packages/core/agent_framework/_workflows/_workflow.py
+2 -8
View File
@@ -5,7 +5,6 @@ import functools
import hashlib
import json
import logging
import sys
import uuid
from collections.abc import AsyncIterable, Awaitable, Callable
from typing import Any
@@ -34,12 +33,7 @@ from ._model_utils import DictConvertible
from ._runner import Runner
from ._runner_context import RunnerContext
from ._shared_state import SharedState
if sys.version_info >= (3, 11):
pass # pragma: no cover
else:
pass # pragma: no cover
from ._typing_utils import is_instance_of
logger = logging.getLogger(__name__)
@@ -734,7 +728,7 @@ class Workflow(DictConvertible):
if request_id not in pending_requests:
raise ValueError(f"Response provided for unknown request ID: {request_id}")
pending_request = pending_requests[request_id]
if not isinstance(response, pending_request.response_type):
if not is_instance_of(response, pending_request.response_type):
raise ValueError(
f"Response type mismatch for request ID {request_id}: "
f"expected {pending_request.response_type}, got {type(response)}"
python/packages/core/agent_framework/_workflows/_workflow_context.py
+18 -2
View File
@@ -269,6 +269,7 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
runner_context: RunnerContext,
trace_contexts: list[dict[str, str]] | None = None,
source_span_ids: list[str] | None = None,
request_id: str | None = None,
):
"""Initialize the executor context with the given workflow context.
@@ -281,6 +282,7 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
runner_context: The runner context that provides methods to send messages and events.
trace_contexts: Optional trace contexts from multiple sources for OpenTelemetry propagation.
source_span_ids: Optional source span IDs from multiple sources for linking (not for nesting).
request_id: Optional request ID if this context is for a `handle_response` handler.
"""
self._executor = executor
self._executor_id = executor.id
@@ -298,9 +300,21 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
self._trace_contexts = trace_contexts or []
self._source_span_ids = source_span_ids or []
# request info related
self._request_id: str | None = request_id
if not self._source_executor_ids:
raise ValueError("source_executor_ids cannot be empty. At least one source executor ID is required.")
@property
def request_id(self) -> str | None:
"""Get the request ID if this context is for a `handle_response` handler.
Returns:
The request ID string or None if not applicable.
"""
return self._request_id
async def send_message(self, message: T_Out, target_id: str | None = None) -> None:
"""Send a message to the workflow context.
@@ -361,7 +375,7 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
return
await self._runner_context.add_event(event)
async def request_info(self, request_data: object, response_type: type) -> None:
async def request_info(self, request_data: object, response_type: type, *, request_id: str | None = None) -> None:
"""Request information from outside of the workflow.
Calling this method will cause the workflow to emit a RequestInfoEvent, carrying the
@@ -374,6 +388,8 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
Args:
request_data: The data associated with the information request.
response_type: The expected type of the response, used for validation.
request_id: Optional unique identifier for the request. If not provided,
a new UUID will be generated. This allows executors to track requests and responses.
"""
request_type: type = type(request_data)
if not self._executor.is_request_supported(request_type, response_type):
@@ -385,7 +401,7 @@ class WorkflowContext(Generic[T_Out, T_W_Out]):
)
request_info_event = RequestInfoEvent(
request_id=str(uuid.uuid4()),
request_id=request_id or str(uuid.uuid4()),
source_executor_id=self._executor_id,
request_data=request_data,
response_type=response_type,
python/packages/core/agent_framework/_workflows/_workflow_executor.py
+116 -60
View File
@@ -18,10 +18,8 @@ from ._events import (
WorkflowFailedEvent,
WorkflowRunState,
)
from ._executor import (
Executor,
handler,
)
from ._executor import Executor, handler
from ._request_info_mixin import response_handler
from ._runner_context import Message
from ._typing_utils import is_instance_of
from ._workflow import WorkflowRunResult
@@ -265,7 +263,14 @@ class WorkflowExecutor(Executor):
- Concurrent executions are fully isolated and do not interfere with each other
"""
def __init__(self, workflow: "Workflow", id: str, allow_direct_output: bool = False, **kwargs: Any):
def __init__(
self,
workflow: "Workflow",
id: str,
allow_direct_output: bool = False,
propagate_request: bool = False,
**kwargs: Any,
):
"""Initialize the WorkflowExecutor.
Args:
@@ -277,6 +282,11 @@ class WorkflowExecutor(Executor):
When this is set to true, the outputs are yielded
directly from the WorkflowExecutor to the parent
workflow's event stream.
propagate_request: Whether to propagate requests from the sub-workflow to the
parent workflow. If set to true, requests from the sub-workflow
will be propagated as the original RequestInfoEvent to the parent
workflow. Otherwise, they will be wrapped in a SubWorkflowRequestMessage,
which should be handled by an executor in the parent workflow.
Keyword Args:
**kwargs: Additional keyword arguments passed to the parent constructor.
@@ -289,6 +299,7 @@ class WorkflowExecutor(Executor):
self._execution_contexts: dict[str, ExecutionContext] = {} # execution_id -> ExecutionContext
# Map request_id to execution_id for response routing
self._request_to_execution: dict[str, str] = {} # request_id -> execution_id
self._propagate_request = propagate_request
@property
def input_types(self) -> list[type[Any]]:
@@ -336,8 +347,15 @@ class WorkflowExecutor(Executor):
This prevents the WorkflowExecutor from accepting messages that should go to other
executors because the handler `process_workflow` has no type restrictions.
"""
# Always handle SubWorkflowResponseMessage
if isinstance(message.data, SubWorkflowResponseMessage):
# Always handle SubWorkflowResponseMessage
return True
if (
message.original_request_info_event is not None
and message.original_request_info_event.request_id in self._request_to_execution
):
# Handle propagated responses for known requests
return True
# For other messages, only handle if the wrapped workflow can accept them as input
@@ -388,7 +406,11 @@ class WorkflowExecutor(Executor):
del self._execution_contexts[execution_id]
@handler
async def handle_response(self, response: SubWorkflowResponseMessage, ctx: WorkflowContext[Any]) -> None:
async def handle_message_wrapped_request_response(
self,
response: SubWorkflowResponseMessage,
ctx: WorkflowContext[Any],
) -> None:
"""Handle response from parent for a forwarded request.
This handler accumulates responses and only resumes the sub-workflow
@@ -398,55 +420,34 @@ class WorkflowExecutor(Executor):
response: The response to a previous request.
ctx: The workflow context.
"""
# Find the execution context for this request
original_request = response.source_event
execution_id = self._request_to_execution.get(original_request.request_id)
if not execution_id or execution_id not in self._execution_contexts:
logger.warning(
f"WorkflowExecutor {self.id} received response for unknown request_id: {original_request.request_id}. "
"This response will be ignored."
)
return
await self._handle_response(
request_id=response.source_event.request_id,
response=response.data,
ctx=ctx,
)
execution_context = self._execution_contexts[execution_id]
@response_handler
async def handle_propagated_request_response(
self,
original_request: Any,
response: object,
ctx: WorkflowContext[Any],
) -> None:
"""Handle response for a request that was propagated to the parent workflow.
# Check if we have this pending request in the execution context
if original_request.request_id not in execution_context.pending_requests:
logger.warning(
f"WorkflowExecutor {self.id} received response for unknown request_id: "
f"{original_request.request_id} in execution {execution_id}, ignoring"
)
return
Args:
original_request: The original RequestInfoEvent.
response: The response data.
ctx: The workflow context.
"""
if ctx.request_id is None:
raise RuntimeError("WorkflowExecutor received a propagated response without a request ID in the context.")
# Remove the request from pending list and request mapping
execution_context.pending_requests.pop(original_request.request_id, None)
self._request_to_execution.pop(original_request.request_id, None)
# Accumulate the response in this execution's context
execution_context.collected_responses[original_request.request_id] = response.data
# Check if we have all expected responses for this execution
if len(execution_context.collected_responses) < execution_context.expected_response_count:
logger.debug(
f"WorkflowExecutor {self.id} execution {execution_id} waiting for more responses: "
f"{len(execution_context.collected_responses)}/{execution_context.expected_response_count} received"
)
return # Wait for more responses
# Send all collected responses to the sub-workflow
responses_to_send = dict(execution_context.collected_responses)
execution_context.collected_responses.clear() # Clear for next batch
try:
# Resume the sub-workflow with all collected responses
result = await self.workflow.send_responses(responses_to_send)
# Process the workflow result using shared logic
await self._process_workflow_result(result, execution_context, ctx)
finally:
# Clean up execution context if it's completed (no pending requests)
if not execution_context.pending_requests:
del self._execution_contexts[execution_id]
await self._handle_response(
request_id=ctx.request_id,
response=response,
ctx=ctx,
)
@override
async def on_checkpoint_save(self) -> dict[str, Any]:
@@ -552,13 +553,15 @@ class WorkflowExecutor(Executor):
execution_context.pending_requests[event.request_id] = event
# Map request to execution for response routing
self._request_to_execution[event.request_id] = execution_context.execution_id
# TODO(@taochen): There should be two ways a sub-workflow can make a request:
# 1. In a workflow where the parent workflow has an executor that may intercept the
# request and handle it directly, a message should be sent.
# 2. In a workflow where the parent workflow does not handle the request, the request
# should be propagated via the `request_info` mechanism to an external source. And
# a @response_handler would be required in the WorkflowExecutor to handle the response.
await ctx.send_message(SubWorkflowRequestMessage(source_event=event, executor_id=self.id))
if self._propagate_request:
# In a workflow where the parent workflow does not handle the request, the request
# should be propagated via the `request_info` mechanism to an external source. And
# a @response_handler would be required in the WorkflowExecutor to handle the response.
await ctx.request_info(event.data, event.response_type, request_id=event.request_id)
else:
# In a workflow where the parent workflow has an executor that may intercept the
# request and handle it directly, a message should be sent.
await ctx.send_message(SubWorkflowRequestMessage(source_event=event, executor_id=self.id))
# Update expected response count for this execution
execution_context.expected_response_count = len(request_info_events)
@@ -602,3 +605,56 @@ class WorkflowExecutor(Executor):
)
else:
raise RuntimeError(f"Unexpected workflow run state: {workflow_run_state}")
async def _handle_response(
self,
request_id: str,
response: Any,
ctx: WorkflowContext[Any],
) -> None:
execution_id = self._request_to_execution.get(request_id)
if not execution_id or execution_id not in self._execution_contexts:
logger.warning(
f"WorkflowExecutor {self.id} received response for unknown request_id: {request_id}. "
"This response will be ignored."
)
return
execution_context = self._execution_contexts[execution_id]
# Check if we have this pending request in the execution context
if request_id not in execution_context.pending_requests:
logger.warning(
f"WorkflowExecutor {self.id} received response for unknown request_id: "
f"{request_id} in execution {execution_id}, ignoring"
)
return
# Remove the request from pending list and request mapping
execution_context.pending_requests.pop(request_id, None)
self._request_to_execution.pop(request_id, None)
# Accumulate the response in this execution's context
execution_context.collected_responses[request_id] = response
# Check if we have all expected responses for this execution
if len(execution_context.collected_responses) < execution_context.expected_response_count:
logger.debug(
f"WorkflowExecutor {self.id} execution {execution_id} waiting for more responses: "
f"{len(execution_context.collected_responses)}/{execution_context.expected_response_count} received"
)
return # Wait for more responses
# Send all collected responses to the sub-workflow
responses_to_send = dict(execution_context.collected_responses)
execution_context.collected_responses.clear() # Clear for next batch
try:
# Resume the sub-workflow with all collected responses
result = await self.workflow.send_responses(responses_to_send)
# Process the workflow result using shared logic
await self._process_workflow_result(result, execution_context, ctx)
finally:
# Clean up execution context if it's completed (no pending requests)
if not execution_context.pending_requests:
del self._execution_contexts[execution_id]
python/packages/core/tests/workflow/test_agent_run_event_typing.py
-16
View File
@@ -17,14 +17,6 @@ def test_agent_run_event_data_type() -> None:
assert data.text == "Hello"
def test_agent_run_event_data_none() -> None:
"""Verify AgentRunEvent.data can be None."""
event = AgentRunEvent(executor_id="test")
data: AgentRunResponse | None = event.data
assert data is None
def test_agent_run_update_event_data_type() -> None:
"""Verify AgentRunUpdateEvent.data is typed as AgentRunResponseUpdate | None."""
update = AgentRunResponseUpdate()
@@ -33,11 +25,3 @@ def test_agent_run_update_event_data_type() -> None:
# This assignment should pass type checking without a cast
data: AgentRunResponseUpdate | None = event.data
assert data is not None
def test_agent_run_update_event_data_none() -> None:
"""Verify AgentRunUpdateEvent.data can be None."""
event = AgentRunUpdateEvent(executor_id="test")
data: AgentRunResponseUpdate | None = event.data
assert data is None
python/packages/core/tests/workflow/test_agent_utils.py
+82
View File
@@ -0,0 +1,82 @@
# Copyright (c) Microsoft. All rights reserved.
from collections.abc import AsyncIterable
from typing import Any
from agent_framework import AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
from agent_framework._workflows._agent_utils import resolve_agent_id
class MockAgent:
"""Mock agent for testing agent utilities."""
def __init__(self, agent_id: str, name: str | None = None) -> None:
self._id = agent_id
self._name = name
@property
def id(self) -> str:
return self._id
@property
def name(self) -> str | None:
return self._name
@property
def display_name(self) -> str:
"""Returns the display name of the agent."""
...
@property
def description(self) -> str | None:
"""Returns the description of the agent."""
...
async def run(
self,
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
*,
thread: AgentThread | None = None,
**kwargs: Any,
) -> AgentRunResponse: ...
def run_stream(
self,
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
*,
thread: AgentThread | None = None,
**kwargs: Any,
) -> AsyncIterable[AgentRunResponseUpdate]: ...
def get_new_thread(self, **kwargs: Any) -> AgentThread:
"""Creates a new conversation thread for the agent."""
...
def test_resolve_agent_id_with_name() -> None:
"""Test that resolve_agent_id returns name when agent has a name."""
agent = MockAgent(agent_id="agent-123", name="MyAgent")
result = resolve_agent_id(agent)
assert result == "MyAgent"
def test_resolve_agent_id_without_name() -> None:
"""Test that resolve_agent_id returns id when agent has no name."""
agent = MockAgent(agent_id="agent-456", name=None)
result = resolve_agent_id(agent)
assert result == "agent-456"
def test_resolve_agent_id_with_empty_name() -> None:
"""Test that resolve_agent_id returns id when agent has empty string name."""
agent = MockAgent(agent_id="agent-789", name="")
result = resolve_agent_id(agent)
assert result == "agent-789"
def test_resolve_agent_id_prefers_name_over_id() -> None:
"""Test that resolve_agent_id prefers name over id when both are set."""
agent = MockAgent(agent_id="agent-abc", name="PreferredName")
result = resolve_agent_id(agent)
assert result == "PreferredName"
assert result != "agent-abc"
python/packages/core/tests/workflow/test_executor.py
+242
View File
@@ -12,6 +12,7 @@ from agent_framework import (
WorkflowContext,
executor,
handler,
response_handler,
)
@@ -266,6 +267,247 @@ async def test_executor_events_with_complex_message_types():
assert collector_invoked.data.results == ["HELLO", "HELLO", "HELLO"]
def test_executor_output_types_property():
"""Test that the output_types property correctly identifies message output types."""
# Test executor with no output types
class NoOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext) -> None:
pass
executor = NoOutputExecutor(id="no_output")
assert executor.output_types == []
# Test executor with single output type
class SingleOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int]) -> None:
pass
executor = SingleOutputExecutor(id="single_output")
assert int in executor.output_types
assert len(executor.output_types) == 1
# Test executor with union output types
class UnionOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int | str]) -> None:
pass
executor = UnionOutputExecutor(id="union_output")
assert int in executor.output_types
assert str in executor.output_types
assert len(executor.output_types) == 2
# Test executor with multiple handlers having different output types
class MultiHandlerExecutor(Executor):
@handler
async def handle_string(self, text: str, ctx: WorkflowContext[int]) -> None:
pass
@handler
async def handle_number(self, num: int, ctx: WorkflowContext[bool]) -> None:
pass
executor = MultiHandlerExecutor(id="multi_handler")
assert int in executor.output_types
assert bool in executor.output_types
assert len(executor.output_types) == 2
def test_executor_workflow_output_types_property():
"""Test that the workflow_output_types property correctly identifies workflow output types."""
from typing_extensions import Never
# Test executor with no workflow output types
class NoWorkflowOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int]) -> None:
pass
executor = NoWorkflowOutputExecutor(id="no_workflow_output")
assert executor.workflow_output_types == []
# Test executor with workflow output type (second type parameter)
class WorkflowOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int, str]) -> None:
pass
executor = WorkflowOutputExecutor(id="workflow_output")
assert str in executor.workflow_output_types
assert len(executor.workflow_output_types) == 1
# Test executor with union workflow output types
class UnionWorkflowOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int, str | bool]) -> None:
pass
executor = UnionWorkflowOutputExecutor(id="union_workflow_output")
assert str in executor.workflow_output_types
assert bool in executor.workflow_output_types
assert len(executor.workflow_output_types) == 2
# Test executor with multiple handlers having different workflow output types
class MultiHandlerWorkflowExecutor(Executor):
@handler
async def handle_string(self, text: str, ctx: WorkflowContext[int, str]) -> None:
pass
@handler
async def handle_number(self, num: int, ctx: WorkflowContext[bool, float]) -> None:
pass
executor = MultiHandlerWorkflowExecutor(id="multi_workflow")
assert str in executor.workflow_output_types
assert float in executor.workflow_output_types
assert len(executor.workflow_output_types) == 2
# Test executor with Never for message output (only workflow output)
class YieldOnlyExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
pass
executor = YieldOnlyExecutor(id="yield_only")
assert str in executor.workflow_output_types
assert len(executor.workflow_output_types) == 1
# Should have no message output types
assert executor.output_types == []
def test_executor_output_and_workflow_output_types_combined():
"""Test executor with both message and workflow output types."""
class DualOutputExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int, str]) -> None:
pass
executor = DualOutputExecutor(id="dual")
# Should have int as message output type
assert int in executor.output_types
assert len(executor.output_types) == 1
# Should have str as workflow output type
assert str in executor.workflow_output_types
assert len(executor.workflow_output_types) == 1
# They should be distinct
assert int not in executor.workflow_output_types
assert str not in executor.output_types
def test_executor_output_types_includes_response_handlers():
"""Test that output_types includes types from response handlers."""
from agent_framework import response_handler
class RequestResponseExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int]) -> None:
pass
@response_handler
async def handle_response(self, original_request: str, response: bool, ctx: WorkflowContext[float]) -> None:
pass
executor = RequestResponseExecutor(id="request_response")
# Should include output types from both handler and response_handler
assert int in executor.output_types
assert float in executor.output_types
assert len(executor.output_types) == 2
def test_executor_workflow_output_types_includes_response_handlers():
"""Test that workflow_output_types includes types from response handlers."""
from agent_framework import response_handler
class RequestResponseWorkflowExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int, str]) -> None:
pass
@response_handler
async def handle_response(
self, original_request: str, response: bool, ctx: WorkflowContext[float, bool]
) -> None:
pass
executor = RequestResponseWorkflowExecutor(id="request_response_workflow")
# Should include workflow output types from both handler and response_handler
assert str in executor.workflow_output_types
assert bool in executor.workflow_output_types
assert len(executor.workflow_output_types) == 2
# Verify message output types are separate
assert int in executor.output_types
assert float in executor.output_types
assert len(executor.output_types) == 2
def test_executor_multiple_response_handlers_output_types():
"""Test that multiple response handlers contribute their output types."""
class MultiResponseHandlerExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext[int]) -> None:
pass
@response_handler
async def handle_string_bool_response(
self, original_request: str, response: bool, ctx: WorkflowContext[float]
) -> None:
pass
@response_handler
async def handle_int_bool_response(
self, original_request: int, response: bool, ctx: WorkflowContext[bool]
) -> None:
pass
executor = MultiResponseHandlerExecutor(id="multi_response")
# Should include output types from all handlers and response handlers
assert int in executor.output_types
assert float in executor.output_types
assert bool in executor.output_types
assert len(executor.output_types) == 3
def test_executor_response_handler_union_output_types():
"""Test that response handlers with union output types contribute all types."""
from agent_framework import response_handler
class UnionResponseHandlerExecutor(Executor):
@handler
async def handle(self, text: str, ctx: WorkflowContext) -> None:
pass
@response_handler
async def handle_response(
self, original_request: str, response: bool, ctx: WorkflowContext[int | str | float, bool | int]
) -> None:
pass
executor = UnionResponseHandlerExecutor(id="union_response")
# Should include all output types from the union
assert int in executor.output_types
assert str in executor.output_types
assert float in executor.output_types
assert len(executor.output_types) == 3
# Should include all workflow output types from the union
assert bool in executor.workflow_output_types
assert int in executor.workflow_output_types
assert len(executor.workflow_output_types) == 2
async def test_executor_invoked_event_data_not_mutated_by_handler():
"""Test that ExecutorInvokedEvent.data captures original input, not mutated input."""
python/packages/core/tests/workflow/test_group_chat.py
+214 -537
View File
File diff suppressed because it is too large Load Diff
python/packages/core/tests/workflow/test_handoff.py
+212 -1174
View File
File diff suppressed because it is too large Load Diff
python/packages/core/tests/workflow/test_magentic.py
+242 -400
View File
File diff suppressed because it is too large Load Diff
python/packages/core/tests/workflow/test_orchestration_request_info.py
+206 -115
View File
@@ -1,59 +1,51 @@
# Copyright (c) Microsoft. All rights reserved.
"""Unit tests for request info support in high-level builders."""
"""Unit tests for orchestration request info support."""
from collections.abc import AsyncIterable
from typing import Any
from unittest.mock import MagicMock
from unittest.mock import AsyncMock, MagicMock
import pytest
from agent_framework import (
AgentInputRequest,
AgentProtocol,
AgentResponseReviewRequest,
AgentRunResponse,
AgentRunResponseUpdate,
AgentThread,
ChatMessage,
RequestInfoInterceptor,
Role,
)
from agent_framework._workflows._executor import Executor, handler
from agent_framework._workflows._orchestration_request_info import resolve_request_info_filter
from agent_framework._workflows._agent_executor import AgentExecutorRequest, AgentExecutorResponse
from agent_framework._workflows._orchestration_request_info import (
AgentApprovalExecutor,
AgentRequestInfoExecutor,
AgentRequestInfoResponse,
resolve_request_info_filter,
)
from agent_framework._workflows._workflow_context import WorkflowContext
class DummyExecutor(Executor):
"""Dummy executor with a handler for testing."""
@handler
async def handle(self, data: str, ctx: WorkflowContext[Any, Any]) -> None:
pass
class TestResolveRequestInfoFilter:
"""Tests for resolve_request_info_filter function."""
def test_returns_none_for_none_input(self):
"""Test that None input returns None (no filtering)."""
def test_returns_empty_set_for_none_input(self):
"""Test that None input returns empty set (no filtering)."""
result = resolve_request_info_filter(None)
assert result is None
assert result == set()
def test_returns_none_for_empty_list(self):
"""Test that empty list returns None."""
def test_returns_empty_set_for_empty_list(self):
"""Test that empty list returns empty set."""
result = resolve_request_info_filter([])
assert result is None
assert result == set()
def test_resolves_string_names(self):
"""Test resolving string agent names."""
result = resolve_request_info_filter(["agent1", "agent2"])
assert result == {"agent1", "agent2"}
def test_resolves_executor_ids(self):
"""Test resolving Executor instances by ID."""
exec1 = DummyExecutor(id="executor1")
exec2 = DummyExecutor(id="executor2")
result = resolve_request_info_filter([exec1, exec2])
assert result == {"executor1", "executor2"}
def test_resolves_agent_names(self):
"""Test resolving AgentProtocol-like objects by name attribute."""
def test_resolves_agent_display_names(self):
"""Test resolving AgentProtocol instances by name attribute."""
agent1 = MagicMock(spec=AgentProtocol)
agent1.name = "writer"
agent2 = MagicMock(spec=AgentProtocol)
@@ -63,106 +55,205 @@ class TestResolveRequestInfoFilter:
assert result == {"writer", "reviewer"}
def test_mixed_types(self):
"""Test resolving a mix of strings, agents, and executors."""
"""Test resolving a mix of strings and agents."""
agent = MagicMock(spec=AgentProtocol)
agent.name = "writer"
executor = DummyExecutor(id="custom_exec")
result = resolve_request_info_filter(["manual_name", agent, executor])
assert result == {"manual_name", "writer", "custom_exec"}
result = resolve_request_info_filter(["manual_name", agent])
assert result == {"manual_name", "writer"}
def test_skips_agent_without_name(self):
"""Test that agents without names are skipped."""
agent_with_name = MagicMock(spec=AgentProtocol)
agent_with_name.name = "valid"
agent_without_name = MagicMock(spec=AgentProtocol)
agent_without_name.name = None
result = resolve_request_info_filter([agent_with_name, agent_without_name])
assert result == {"valid"}
def test_raises_on_unsupported_type(self):
"""Test that unsupported types raise TypeError."""
with pytest.raises(TypeError, match="Unsupported type for request_info filter"):
resolve_request_info_filter([123]) # type: ignore
class TestAgentInputRequest:
"""Tests for AgentInputRequest dataclass (formerly AgentResponseReviewRequest)."""
class TestAgentRequestInfoResponse:
"""Tests for AgentRequestInfoResponse dataclass."""
def test_create_request(self):
"""Test creating an AgentInputRequest with all fields."""
conversation = [ChatMessage(role=Role.USER, text="Hello")]
request = AgentInputRequest(
target_agent_id="test_agent",
conversation=conversation,
instruction="Review this",
metadata={"key": "value"},
def test_create_response_with_messages(self):
"""Test creating an AgentRequestInfoResponse with messages."""
messages = [ChatMessage(role=Role.USER, text="Additional info")]
response = AgentRequestInfoResponse(messages=messages)
assert response.messages == messages
def test_from_messages_factory(self):
"""Test creating response from ChatMessage list."""
messages = [
ChatMessage(role=Role.USER, text="Message 1"),
ChatMessage(role=Role.USER, text="Message 2"),
]
response = AgentRequestInfoResponse.from_messages(messages)
assert response.messages == messages
def test_from_strings_factory(self):
"""Test creating response from string list."""
texts = ["First message", "Second message"]
response = AgentRequestInfoResponse.from_strings(texts)
assert len(response.messages) == 2
assert response.messages[0].role == Role.USER
assert response.messages[0].text == "First message"
assert response.messages[1].role == Role.USER
assert response.messages[1].text == "Second message"
def test_approve_factory(self):
"""Test creating an approval response (empty messages)."""
response = AgentRequestInfoResponse.approve()
assert response.messages == []
class TestAgentRequestInfoExecutor:
"""Tests for AgentRequestInfoExecutor."""
@pytest.mark.asyncio
async def test_request_info_handler(self):
"""Test that request_info handler calls ctx.request_info."""
executor = AgentRequestInfoExecutor(id="test_executor")
agent_run_response = AgentRunResponse(messages=[ChatMessage(role=Role.ASSISTANT, text="Agent response")])
agent_response = AgentExecutorResponse(
executor_id="test_agent",
agent_run_response=agent_run_response,
)
assert request.target_agent_id == "test_agent"
assert request.conversation == conversation
assert request.instruction == "Review this"
assert request.metadata == {"key": "value"}
ctx = MagicMock(spec=WorkflowContext)
ctx.request_info = AsyncMock()
def test_create_request_defaults(self):
"""Test creating an AgentInputRequest with default values."""
request = AgentInputRequest(target_agent_id="test_agent")
await executor.request_info(agent_response, ctx)
assert request.target_agent_id == "test_agent"
assert request.conversation == []
assert request.instruction is None
assert request.metadata == {}
ctx.request_info.assert_called_once_with(agent_response, AgentRequestInfoResponse)
def test_backward_compatibility_alias(self):
"""Test that AgentResponseReviewRequest is an alias for AgentInputRequest."""
assert AgentResponseReviewRequest is AgentInputRequest
@pytest.mark.asyncio
async def test_handle_request_info_response_with_messages(self):
"""Test response handler when user provides additional messages."""
executor = AgentRequestInfoExecutor(id="test_executor")
class TestRequestInfoInterceptor:
"""Tests for RequestInfoInterceptor executor."""
def test_interceptor_creation_generates_unique_id(self):
"""Test creating a RequestInfoInterceptor generates unique IDs."""
interceptor1 = RequestInfoInterceptor()
interceptor2 = RequestInfoInterceptor()
assert interceptor1.id.startswith("request_info_interceptor-")
assert interceptor2.id.startswith("request_info_interceptor-")
assert interceptor1.id != interceptor2.id
def test_interceptor_with_custom_id(self):
"""Test creating a RequestInfoInterceptor with custom ID."""
interceptor = RequestInfoInterceptor(executor_id="custom_review")
assert interceptor.id == "custom_review"
def test_interceptor_with_agent_filter(self):
"""Test creating a RequestInfoInterceptor with agent filter."""
agent_filter = {"agent1", "agent2"}
interceptor = RequestInfoInterceptor(
executor_id="filtered_review",
agent_filter=agent_filter,
agent_run_response = AgentRunResponse(messages=[ChatMessage(role=Role.ASSISTANT, text="Original")])
original_request = AgentExecutorResponse(
executor_id="test_agent",
agent_run_response=agent_run_response,
)
assert interceptor.id == "filtered_review"
assert interceptor._agent_filter == agent_filter
def test_should_pause_for_agent_no_filter(self):
"""Test that interceptor pauses for all agents when no filter is set."""
interceptor = RequestInfoInterceptor()
assert interceptor._should_pause_for_agent("any_agent") is True
assert interceptor._should_pause_for_agent("another_agent") is True
assert interceptor._should_pause_for_agent(None) is True
response = AgentRequestInfoResponse.from_strings(["Additional input"])
def test_should_pause_for_agent_with_filter(self):
"""Test that interceptor only pauses for agents in the filter."""
agent_filter = {"writer", "reviewer"}
interceptor = RequestInfoInterceptor(agent_filter=agent_filter)
ctx = MagicMock(spec=WorkflowContext)
ctx.send_message = AsyncMock()
assert interceptor._should_pause_for_agent("writer") is True
assert interceptor._should_pause_for_agent("reviewer") is True
assert interceptor._should_pause_for_agent("drafter") is False
assert interceptor._should_pause_for_agent(None) is False
await executor.handle_request_info_response(original_request, response, ctx)
def test_should_pause_for_agent_with_prefixed_id(self):
"""Test that filter matches agent names in prefixed executor IDs."""
agent_filter = {"writer"}
interceptor = RequestInfoInterceptor(agent_filter=agent_filter)
# Should send new request with additional messages
ctx.send_message.assert_called_once()
call_args = ctx.send_message.call_args[0][0]
assert isinstance(call_args, AgentExecutorRequest)
assert call_args.should_respond is True
assert len(call_args.messages) == 1
assert call_args.messages[0].text == "Additional input"
# Should match the name portion after the colon
assert interceptor._should_pause_for_agent("groupchat_agent:writer") is True
assert interceptor._should_pause_for_agent("request_info:writer") is True
assert interceptor._should_pause_for_agent("groupchat_agent:editor") is False
@pytest.mark.asyncio
async def test_handle_request_info_response_approval(self):
"""Test response handler when user approves (no additional messages)."""
executor = AgentRequestInfoExecutor(id="test_executor")
agent_run_response = AgentRunResponse(messages=[ChatMessage(role=Role.ASSISTANT, text="Original")])
original_request = AgentExecutorResponse(
executor_id="test_agent",
agent_run_response=agent_run_response,
)
response = AgentRequestInfoResponse.approve()
ctx = MagicMock(spec=WorkflowContext)
ctx.yield_output = AsyncMock()
await executor.handle_request_info_response(original_request, response, ctx)
# Should yield original response without modification
ctx.yield_output.assert_called_once_with(original_request)
class _TestAgent:
"""Simple test agent implementation."""
def __init__(self, id: str, name: str | None = None, description: str | None = None):
self._id = id
self._name = name
self._description = description
@property
def id(self) -> str:
return self._id
@property
def name(self) -> str | None:
return self._name
@property
def display_name(self) -> str:
return self._name or self._id
@property
def description(self) -> str | None:
return self._description
async def run(
self,
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
*,
thread: AgentThread | None = None,
**kwargs: Any,
) -> AgentRunResponse:
"""Dummy run method."""
return AgentRunResponse(messages=[ChatMessage(role=Role.ASSISTANT, text="Test response")])
def run_stream(
self,
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
*,
thread: AgentThread | None = None,
**kwargs: Any,
) -> AsyncIterable[AgentRunResponseUpdate]:
"""Dummy run_stream method."""
async def generator():
yield AgentRunResponseUpdate(messages=[ChatMessage(role=Role.ASSISTANT, text="Test response stream")])
return generator()
def get_new_thread(self, **kwargs: Any) -> AgentThread:
"""Creates a new conversation thread for the agent."""
return AgentThread(**kwargs)
class TestAgentApprovalExecutor:
"""Tests for AgentApprovalExecutor."""
def test_initialization(self):
"""Test that AgentApprovalExecutor initializes correctly."""
agent = _TestAgent(id="test_id", name="test_agent", description="Test agent description")
executor = AgentApprovalExecutor(agent)
assert executor.id == "test_agent"
assert executor.description == "Test agent description"
def test_builds_workflow_with_agent_and_request_info_executors(self):
"""Test that the internal workflow is created successfully."""
agent = _TestAgent(id="test_id", name="test_agent", description="Test description")
executor = AgentApprovalExecutor(agent)
# Verify the executor has a workflow
assert executor.workflow is not None
assert executor.id == "test_agent"
def test_propagate_request_enabled(self):
"""Test that AgentApprovalExecutor has propagate_request enabled."""
agent = _TestAgent(id="test_id", name="test_agent", description="Test description")
executor = AgentApprovalExecutor(agent)
assert executor._propagate_request is True # type: ignore
python/packages/core/tests/workflow/test_sequential.py
+3 -1
View File
@@ -6,6 +6,7 @@ from typing import Any
import pytest
from agent_framework import (
AgentExecutorResponse,
AgentRunResponse,
AgentRunResponseUpdate,
AgentThread,
@@ -52,7 +53,8 @@ class _SummarizerExec(Executor):
"""Custom executor that summarizes by appending a short assistant message."""
@handler
async def summarize(self, conversation: list[ChatMessage], ctx: WorkflowContext[list[ChatMessage]]) -> None:
async def summarize(self, agent_response: AgentExecutorResponse, ctx: WorkflowContext[list[ChatMessage]]) -> None:
conversation = agent_response.full_conversation or []
user_texts = [m.text for m in conversation if m.role == Role.USER]
agents = [m.author_name or m.role for m in conversation if m.role == Role.ASSISTANT]
summary = ChatMessage(role=Role.ASSISTANT, text=f"Summary of users:{len(user_texts)} agents:{len(agents)}")
python/packages/core/tests/workflow/test_workflow_kwargs.py
+42 -61
View File
@@ -3,6 +3,8 @@
from collections.abc import AsyncIterable
from typing import Annotated, Any
import pytest
from agent_framework import (
AgentRunResponse,
AgentRunResponseUpdate,
@@ -11,7 +13,7 @@ from agent_framework import (
ChatMessage,
ConcurrentBuilder,
GroupChatBuilder,
GroupChatStateSnapshot,
GroupChatState,
HandoffBuilder,
Role,
SequentialBuilder,
@@ -26,11 +28,6 @@ from agent_framework._workflows._const import WORKFLOW_RUN_KWARGS_KEY
_received_kwargs: list[dict[str, Any]] = []
def _reset_received_kwargs() -> None:
"""Reset the kwargs tracker before each test."""
_received_kwargs.clear()
@ai_function
def tool_with_kwargs(
action: Annotated[str, "The action to perform"],
@@ -73,28 +70,6 @@ class _KwargsCapturingAgent(BaseAgent):
yield AgentRunResponseUpdate(contents=[TextContent(text=f"{self.name} response")])
class _EchoAgent(BaseAgent):
"""Simple agent that echoes back for workflow completion."""
async def run(
self,
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
*,
thread: AgentThread | None = None,
**kwargs: Any,
) -> AgentRunResponse:
return AgentRunResponse(messages=[ChatMessage(role=Role.ASSISTANT, text=f"{self.name} reply")])
async def run_stream(
self,
messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
*,
thread: AgentThread | None = None,
**kwargs: Any,
) -> AsyncIterable[AgentRunResponseUpdate]:
yield AgentRunResponseUpdate(contents=[TextContent(text=f"{self.name} reply")])
# region Sequential Builder Tests
@@ -200,17 +175,21 @@ async def test_groupchat_kwargs_flow_to_agents() -> None:
# Simple selector that takes GroupChatStateSnapshot
turn_count = 0
def simple_selector(state: GroupChatStateSnapshot) -> str | None:
def simple_selector(state: GroupChatState) -> str:
nonlocal turn_count
turn_count += 1
if turn_count > 2: # Stop after 2 turns
return None
if turn_count > 2: # Loop after two turns for test
turn_count = 0
# state is a Mapping - access via dict syntax
names = list(state["participants"].keys())
names = list(state.participants.keys())
return names[(turn_count - 1) % len(names)]
workflow = (
GroupChatBuilder().participants(chat1=agent1, chat2=agent2).set_select_speakers_func(simple_selector).build()
GroupChatBuilder()
.participants([agent1, agent2])
.with_select_speaker_func(simple_selector)
.with_max_rounds(2) # Limit rounds to prevent infinite loop
.build()
)
custom_data = {"session_id": "group123"}
@@ -359,6 +338,7 @@ async def test_kwargs_preserved_across_workflow_reruns() -> None:
# region Handoff Builder Tests
@pytest.mark.xfail(reason="Handoff workflow does not yet propagate kwargs to agents")
async def test_handoff_kwargs_flow_to_agents() -> None:
"""Test that kwargs flow to agents in a handoff workflow."""
agent1 = _KwargsCapturingAgent(name="coordinator")
@@ -367,8 +347,9 @@ async def test_handoff_kwargs_flow_to_agents() -> None:
workflow = (
HandoffBuilder()
.participants([agent1, agent2])
.set_coordinator(agent1)
.with_interaction_mode("autonomous")
.with_start_agent(agent1)
.with_autonomous_mode()
.with_termination_condition(lambda conv: len(conv) >= 4)
.build()
)
@@ -395,8 +376,8 @@ async def test_magentic_kwargs_flow_to_agents() -> None:
from agent_framework._workflows._magentic import (
MagenticContext,
MagenticManagerBase,
_MagenticProgressLedger,
_MagenticProgressLedgerItem,
MagenticProgressLedger,
MagenticProgressLedgerItem,
)
# Create a mock manager that completes after one round
@@ -405,29 +386,29 @@ async def test_magentic_kwargs_flow_to_agents() -> None:
super().__init__(max_stall_count=3, max_reset_count=None, max_round_count=2)
self.task_ledger = None
async def plan(self, context: MagenticContext) -> ChatMessage:
async def plan(self, magentic_context: MagenticContext) -> ChatMessage:
return ChatMessage(role=Role.ASSISTANT, text="Plan: Test task", author_name="manager")
async def replan(self, context: MagenticContext) -> ChatMessage:
async def replan(self, magentic_context: MagenticContext) -> ChatMessage:
return ChatMessage(role=Role.ASSISTANT, text="Replan: Test task", author_name="manager")
async def create_progress_ledger(self, context: MagenticContext) -> _MagenticProgressLedger:
async def create_progress_ledger(self, magentic_context: MagenticContext) -> MagenticProgressLedger:
# Return completed on first call
return _MagenticProgressLedger(
is_request_satisfied=_MagenticProgressLedgerItem(answer=True, reason="Done"),
is_progress_being_made=_MagenticProgressLedgerItem(answer=True, reason="Progress"),
is_in_loop=_MagenticProgressLedgerItem(answer=False, reason="Not looping"),
instruction_or_question=_MagenticProgressLedgerItem(answer="Complete", reason="Done"),
next_speaker=_MagenticProgressLedgerItem(answer="agent1", reason="First"),
return MagenticProgressLedger(
is_request_satisfied=MagenticProgressLedgerItem(answer=True, reason="Done"),
is_progress_being_made=MagenticProgressLedgerItem(answer=True, reason="Progress"),
is_in_loop=MagenticProgressLedgerItem(answer=False, reason="Not looping"),
instruction_or_question=MagenticProgressLedgerItem(answer="Complete", reason="Done"),
next_speaker=MagenticProgressLedgerItem(answer="agent1", reason="First"),
)
async def prepare_final_answer(self, context: MagenticContext) -> ChatMessage:
async def prepare_final_answer(self, magentic_context: MagenticContext) -> ChatMessage:
return ChatMessage(role=Role.ASSISTANT, text="Final answer", author_name="manager")
agent = _KwargsCapturingAgent(name="agent1")
manager = _MockManager()
workflow = MagenticBuilder().participants(agent1=agent).with_standard_manager(manager=manager).build()
workflow = MagenticBuilder().participants([agent]).with_standard_manager(manager=manager).build()
custom_data = {"session_id": "magentic123"}
@@ -446,8 +427,8 @@ async def test_magentic_kwargs_stored_in_shared_state() -> None:
from agent_framework._workflows._magentic import (
MagenticContext,
MagenticManagerBase,
_MagenticProgressLedger,
_MagenticProgressLedgerItem,
MagenticProgressLedger,
MagenticProgressLedgerItem,
)
class _MockManager(MagenticManagerBase):
@@ -455,28 +436,28 @@ async def test_magentic_kwargs_stored_in_shared_state() -> None:
super().__init__(max_stall_count=3, max_reset_count=None, max_round_count=1)
self.task_ledger = None
async def plan(self, context: MagenticContext) -> ChatMessage:
async def plan(self, magentic_context: MagenticContext) -> ChatMessage:
return ChatMessage(role=Role.ASSISTANT, text="Plan", author_name="manager")
async def replan(self, context: MagenticContext) -> ChatMessage:
async def replan(self, magentic_context: MagenticContext) -> ChatMessage:
return ChatMessage(role=Role.ASSISTANT, text="Replan", author_name="manager")
async def create_progress_ledger(self, context: MagenticContext) -> _MagenticProgressLedger:
return _MagenticProgressLedger(
is_request_satisfied=_MagenticProgressLedgerItem(answer=True, reason="Done"),
is_progress_being_made=_MagenticProgressLedgerItem(answer=True, reason="Progress"),
is_in_loop=_MagenticProgressLedgerItem(answer=False, reason="Not looping"),
instruction_or_question=_MagenticProgressLedgerItem(answer="Done", reason="Done"),
next_speaker=_MagenticProgressLedgerItem(answer="agent1", reason="First"),
async def create_progress_ledger(self, magentic_context: MagenticContext) -> MagenticProgressLedger:
return MagenticProgressLedger(
is_request_satisfied=MagenticProgressLedgerItem(answer=True, reason="Done"),
is_progress_being_made=MagenticProgressLedgerItem(answer=True, reason="Progress"),
is_in_loop=MagenticProgressLedgerItem(answer=False, reason="Not looping"),
instruction_or_question=MagenticProgressLedgerItem(answer="Done", reason="Done"),
next_speaker=MagenticProgressLedgerItem(answer="agent1", reason="First"),
)
async def prepare_final_answer(self, context: MagenticContext) -> ChatMessage:
async def prepare_final_answer(self, magentic_context: MagenticContext) -> ChatMessage:
return ChatMessage(role=Role.ASSISTANT, text="Final", author_name="manager")
agent = _KwargsCapturingAgent(name="agent1")
manager = _MockManager()
magentic_workflow = MagenticBuilder().participants(agent1=agent).with_standard_manager(manager=manager).build()
magentic_workflow = MagenticBuilder().participants([agent]).with_standard_manager(manager=manager).build()
# Use MagenticWorkflow.run_stream() which goes through the kwargs attachment path
custom_data = {"magentic_key": "magentic_value"}
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!")