Python: extend HITL support for all orchestration patterns (#2620)

* Support HITL for orchestration patterns * Cleanup around naming * Fix typing issues * Clean up * Naming clean up * Updates to HITL to make it cleaner * Rename human input hook to orchestration request info * Clean up per PR feedback
2026-06-16 21:04:09 +08:00 · 2025-12-11 00:59:29 +09:00
parent 0d9ae1920d
commit b378ca75d1
23 changed files with 2186 additions and 36 deletions
@@ -0,0 +1,198 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+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.
+
+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.
+
+Demonstrate:
+- Configuring request info with `.with_request_info()`
+- Reviewing outputs from multiple concurrent agents
+- Injecting human guidance after agents execute but before aggregation
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+from typing import Any
+
+from agent_framework import (
+    AgentInputRequest,
+    ChatMessage,
+    ConcurrentBuilder,
+    RequestInfoEvent,
+    Role,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework._workflows._agent_executor import AgentExecutorResponse
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+# Store chat client at module level for aggregator access
+_chat_client: AzureOpenAIChatClient | None = None
+
+
+async def aggregate_with_synthesis(results: list[AgentExecutorResponse]) -> Any:
+    """Custom aggregator that synthesizes concurrent agent outputs using an LLM.
+
+    This aggregator extracts the outputs from each parallel agent and uses the
+    chat client to create a unified summary, incorporating any human feedback
+    that was injected into the conversation.
+
+    Args:
+        results: List of responses from all concurrent agents
+
+    Returns:
+        The synthesized summary text
+    """
+    if not _chat_client:
+        return "Error: Chat client not initialized"
+
+    # Extract each agent's final output
+    expert_sections: list[str] = []
+    human_guidance = ""
+
+    for r in results:
+        try:
+            messages = getattr(r.agent_run_response, "messages", [])
+            final_text = messages[-1].text if messages and hasattr(messages[-1], "text") else "(no content)"
+            expert_sections.append(f"{getattr(r, 'executor_id', 'analyst')}:\n{final_text}")
+
+            # Check for human feedback in the conversation (will be last user message if present)
+            if r.full_conversation:
+                for msg in reversed(r.full_conversation):
+                    if msg.role == Role.USER and msg.text and "perspectives" not in msg.text.lower():
+                        human_guidance = msg.text
+                        break
+        except Exception:
+            expert_sections.append(f"{getattr(r, 'executor_id', 'analyst')}: (error extracting output)")
+
+    # Build prompt with human guidance if provided
+    guidance_text = f"\n\nHuman guidance: {human_guidance}" if human_guidance else ""
+
+    system_msg = ChatMessage(
+        Role.SYSTEM,
+        text=(
+            "You are a synthesis expert. Consolidate the following analyst perspectives "
+            "into one cohesive, balanced summary (3-4 sentences). If human guidance is provided, "
+            "prioritize aspects as directed."
+        ),
+    )
+    user_msg = ChatMessage(Role.USER, text="\n\n".join(expert_sections) + guidance_text)
+
+    response = await _chat_client.get_response([system_msg, user_msg])
+    return response.messages[-1].text if response.messages else ""
+
+
+async def main() -> None:
+    global _chat_client
+    _chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents that analyze from different perspectives
+    technical_analyst = _chat_client.create_agent(
+        name="technical_analyst",
+        instructions=(
+            "You are a technical analyst. When given a topic, provide a technical "
+            "perspective focusing on implementation details, performance, and architecture. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    business_analyst = _chat_client.create_agent(
+        name="business_analyst",
+        instructions=(
+            "You are a business analyst. When given a topic, provide a business "
+            "perspective focusing on ROI, market impact, and strategic value. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    user_experience_analyst = _chat_client.create_agent(
+        name="ux_analyst",
+        instructions=(
+            "You are a UX analyst. When given a topic, provide a user experience "
+            "perspective focusing on usability, accessibility, and user satisfaction. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    # Build workflow with request info enabled and custom aggregator
+    workflow = (
+        ConcurrentBuilder()
+        .participants([technical_analyst, business_analyst, user_experience_analyst])
+        .with_aggregator(aggregate_with_synthesis)
+        .with_request_info()
+        .build()
+    )
+
+    # Run the workflow with human-in-the-loop
+    pending_responses: dict[str, str] | None = None
+    workflow_complete = False
+
+    print("Starting multi-perspective analysis workflow...")
+    print("=" * 60)
+
+    while not workflow_complete:
+        # Run or continue the workflow
+        stream = (
+            workflow.send_responses_streaming(pending_responses)
+            if pending_responses
+            else workflow.run_stream("Analyze the impact of large language models on software development.")
+        )
+
+        pending_responses = 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
+                    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
+                    )
+                    for msg in recent:
+                        role = msg.role.value if msg.role else "unknown"
+                        text = (msg.text or "")[:150]
+                        print(f"  [{role}]: {text}...")
+                    print("-" * 40)
+
+                    # Get human input to steer all agents
+                    user_input = input("Your guidance for the analysts (or 'skip' to continue): ")  # noqa: ASYNC250
+                    if user_input.lower() == "skip":
+                        user_input = "Please analyze objectively from your unique perspective."
+
+                    pending_responses = {event.request_id: user_input}
+                    print("(Resuming workflow...)")
+
+            elif isinstance(event, WorkflowOutputEvent):
+                print("\n" + "=" * 60)
+                print("WORKFLOW COMPLETE")
+                print("=" * 60)
+                print("Aggregated output:")
+                # Custom aggregator returns a string
+                if event.data:
+                    print(event.data)
+                workflow_complete = True
+
+            elif isinstance(event, WorkflowStatusEvent):
+                if event.state == WorkflowRunState.IDLE:
+                    workflow_complete = True
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,175 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Request Info with GroupChatBuilder
+
+This sample demonstrates using the `.with_request_info()` method to pause a
+GroupChatBuilder workflow BEFORE specific participants speak. By using the
+`agents=` filter parameter, you can target only certain participants rather
+than pausing before every turn.
+
+Purpose:
+Show how to use the request info API with selective filtering to pause before
+specific participants speak, allowing human input to steer their response.
+
+Demonstrate:
+- Configuring request info with `.with_request_info(agents=[...])`
+- Using agent filtering to reduce interruptions
+- Steering agent behavior with pre-agent human input
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+
+from agent_framework import (
+    AgentInputRequest,
+    AgentRunUpdateEvent,
+    ChatMessage,
+    GroupChatBuilder,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+
+async def main() -> None:
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents for a group discussion
+    optimist = chat_client.create_agent(
+        name="optimist",
+        instructions=(
+            "You are an optimistic team member. You see opportunities and potential "
+            "in ideas. Engage constructively with the discussion, building on others' "
+            "points while maintaining a positive outlook. Keep responses to 2-3 sentences."
+        ),
+    )
+
+    pragmatist = chat_client.create_agent(
+        name="pragmatist",
+        instructions=(
+            "You are a pragmatic team member. You focus on practical implementation "
+            "and realistic timelines. Sometimes you disagree with overly optimistic views. "
+            "Keep responses to 2-3 sentences."
+        ),
+    )
+
+    creative = chat_client.create_agent(
+        name="creative",
+        instructions=(
+            "You are a creative team member. You propose innovative solutions and "
+            "think outside the box. You may suggest alternatives to conventional approaches. "
+            "Keep responses to 2-3 sentences."
+        ),
+    )
+
+    # Manager orchestrates the discussion
+    manager = chat_client.create_agent(
+        name="manager",
+        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"
+            "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"
+        ),
+    )
+
+    # Build workflow with request info enabled
+    # Using agents= filter to only pause before pragmatist speaks (not every turn)
+    workflow = (
+        GroupChatBuilder()
+        .set_manager(manager=manager, display_name="Discussion Manager")
+        .participants([optimist, pragmatist, creative])
+        .with_max_rounds(6)
+        .with_request_info(agents=[pragmatist])  # Only pause before pragmatist speaks
+        .build()
+    )
+
+    # Run the workflow with human-in-the-loop
+    pending_responses: dict[str, str] | None = None
+    workflow_complete = False
+    current_agent: str | None = None  # Track current streaming agent
+
+    print("Starting group discussion workflow...")
+    print("=" * 60)
+
+    while not workflow_complete:
+        # Run or continue the workflow
+        stream = (
+            workflow.send_responses_streaming(pending_responses)
+            if pending_responses
+            else workflow.run_stream(
+                "Discuss how our team should approach adopting AI tools for productivity. "
+                "Consider benefits, risks, and implementation strategies."
+            )
+        )
+
+        pending_responses = None
+
+        # Process events
+        async for event in stream:
+            if isinstance(event, AgentRunUpdateEvent):
+                # Show all agent responses as they stream
+                if event.data and event.data.text:
+                    agent_name = event.data.author_name or "unknown"
+                    # Print agent name header only when agent changes
+                    if agent_name != current_agent:
+                        current_agent = agent_name
+                        print(f"\n[{agent_name}]: ", end="", flush=True)
+                    print(event.data.text, end="", flush=True)
+
+            elif isinstance(event, RequestInfoEvent):
+                current_agent = None  # Reset for next agent
+                if isinstance(event.data, AgentInputRequest):
+                    # 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("-" * 40)
+                    print("Conversation context:")
+                    recent = (
+                        event.data.conversation[-3:] if len(event.data.conversation) > 3 else event.data.conversation
+                    )
+                    for msg in recent:
+                        role = msg.role.value if msg.role else "unknown"
+                        text = (msg.text or "")[:100]
+                        print(f"  [{role}]: {text}...")
+                    print("-" * 40)
+
+                    # Get human input to steer the agent
+                    user_input = input("Steer the discussion (or 'skip' to continue): ")  # noqa: ASYNC250
+                    if user_input.lower() == "skip":
+                        user_input = "Please continue the discussion naturally."
+
+                    pending_responses = {event.request_id: user_input}
+                    print("(Resuming discussion...)")
+
+            elif isinstance(event, WorkflowOutputEvent):
+                print("\n" + "=" * 60)
+                print("DISCUSSION COMPLETE")
+                print("=" * 60)
+                print("Final conversation:")
+                if event.data:
+                    messages: list[ChatMessage] = event.data[-4:]
+                    for msg in messages:
+                        role = msg.role.value if msg.role else "unknown"
+                        text = (msg.text or "")[:200]
+                        print(f"[{role}]: {text}...")
+                workflow_complete = True
+
+            elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
+                workflow_complete = True
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,128 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+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.
+
+Purpose:
+Show how to use the request info API that pauses before every agent response,
+using the standard request_info pattern for consistency.
+
+Demonstrate:
+- Configuring request info with `.with_request_info()`
+- Handling RequestInfoEvent with AgentInputRequest data
+- Injecting responses back into the workflow via send_responses_streaming
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+
+from agent_framework import (
+    AgentInputRequest,
+    ChatMessage,
+    RequestInfoEvent,
+    SequentialBuilder,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+
+async def main() -> None:
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents for a sequential document review workflow
+    drafter = chat_client.create_agent(
+        name="drafter",
+        instructions=("You are a document drafter. When given a topic, create a brief draft (2-3 sentences)."),
+    )
+
+    editor = chat_client.create_agent(
+        name="editor",
+        instructions=(
+            "You are an editor. Review the draft and suggest improvements. "
+            "Incorporate any human feedback that was provided."
+        ),
+    )
+
+    finalizer = chat_client.create_agent(
+        name="finalizer",
+        instructions=(
+            "You are a finalizer. Take the edited content and create a polished final version. "
+            "Incorporate any additional feedback provided."
+        ),
+    )
+
+    # Build workflow with request info enabled (pauses before each agent)
+    workflow = SequentialBuilder().participants([drafter, editor, finalizer]).with_request_info().build()
+
+    # Run the workflow with request info handling
+    pending_responses: dict[str, str] | None = None
+    workflow_complete = False
+
+    print("Starting document review workflow...")
+    print("=" * 60)
+
+    while not workflow_complete:
+        # Run or continue the workflow
+        stream = (
+            workflow.send_responses_streaming(pending_responses)
+            if pending_responses
+            else workflow.run_stream("Write a brief introduction to artificial intelligence.")
+        )
+
+        pending_responses = None
+
+        # Process events
+        async for event in stream:
+            if isinstance(event, RequestInfoEvent):
+                if isinstance(event.data, AgentInputRequest):
+                    # Display pre-agent context for steering
+                    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
+                    )
+                    for msg in recent:
+                        role = msg.role.value if msg.role else "unknown"
+                        text = (msg.text or "")[:150]
+                        print(f"  [{role}]: {text}...")
+                    print("-" * 40)
+
+                    # Get input to steer the agent
+                    user_input = input("Your guidance (or 'skip' to continue): ")  # noqa: ASYNC250
+                    if user_input.lower() == "skip":
+                        user_input = "Please continue naturally."
+
+                    pending_responses = {event.request_id: user_input}
+                    print("(Resuming workflow...)")
+
+            elif isinstance(event, WorkflowOutputEvent):
+                print("\n" + "=" * 60)
+                print("WORKFLOW COMPLETE")
+                print("=" * 60)
+                print("Final output:")
+                if event.data:
+                    messages: list[ChatMessage] = event.data[-3:]
+                    for msg in messages:
+                        role = msg.role.value if msg.role else "unknown"
+                        print(f"[{role}]: {msg.text}")
+                workflow_complete = True
+
+            elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
+                workflow_complete = True
+
+
+if __name__ == "__main__":
+    asyncio.run(main())