Оркестрация рабочих процессов Microsoft Agent Framework — передача управления

Оркестрация передачи позволяет агентам передавать управление друг другу в зависимости от контекста или запроса пользователя. Каждый агент может "передать" беседу другому агенту с соответствующим опытом, гарантируя, что правильный агент обрабатывает каждую часть задачи. Это особенно полезно для поддержки клиентов, экспертных систем или любого сценария, требующего динамического делегирования.

Внутри оркестрация передачи задач реализуется с помощью топологии сетки, в которой агенты подключены напрямую без оркестратора. Каждый агент может решить, когда следует передавать беседу на основе предопределенных правил или содержимого сообщений.

Замечание

Оркестрация передачи поддерживает только Agent, и агенты должны поддерживать выполнение локальных инструментов.

Различия между передачей управления и агентами как инструментами

Хотя агенты в роли инструментов обычно рассматриваются как многоагентный шаблон и на первый взгляд могут показаться схожими с передачей, между ними существуют фундаментальные различия:

• Поток управления: В оркестрации передачи управление явно передается между агентами на основе определенных правил. Каждый агент может решить передать всю задачу другому агенту. Централизованное управление рабочим процессом отсутствует. В отличие от этого, агент как инструмент включает основного агента, который делегирует подзадачи другим агентам, и после завершения подзадачи управление возвращается к основному агенту.
• Принятие на себя задач: при передаче агент, получивший задачу, полностью берет на себя ответственность за её выполнение. В концепции "агенты как инструменты" главный агент сохраняет общую ответственность за задачу, в то время как другие агенты рассматриваются как инструменты для помощи в выполнении конкретных подзадач.
• Управление контекстом: в оркестрации передачи разговор полностью передается другому агенту. Принимающий агент владеет полным контекстом того, что было сделано до сих пор. ** В агент-в-качестве-инструмента основной агент управляет общим контекстом и может предоставлять только соответствующую информацию агентам-инструментам по мере необходимости.

Цели обучения

• Создание специализированных агентов для разных доменов
• Как настроить правила передачи между агентами
• Создание интерактивных рабочих процессов с помощью динамической маршрутизации агентов
• Как обрабатывать многоходовые диалоги с переключением агентов
• Внедрение утверждения инструмента для чувствительных операций (HITL)
• Использование контрольных точек для устойчивых рабочих процессов передачи

В автоматической оркестрации передачи агенты могут передавать управление друг другу на основе контекста, что позволяет выполнять динамическую маршрутизацию и обработку запросов с использованием специализированной экспертизы.

Настройка клиента Azure OpenAI

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;

// 1) Set up the Azure OpenAI client
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ??
    throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
var client = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

Предупреждение

DefaultAzureCredential удобно для разработки, но требует тщательного рассмотрения в рабочей среде. В рабочей среде рекомендуется использовать определенные учетные данные (например, ManagedIdentityCredential), чтобы избежать проблем с задержкой, непреднамеренной проверки данных аутентификации и потенциальных рисков безопасности из-за резервных механизмов.

Определите своих специализированных агентов

Создайте специфичных для домена агентов и агента сортировки для маршрутизации.

// 2) Create specialized agents
ChatClientAgent historyTutor = new(client,
    "You provide assistance with historical queries. Explain important events and context clearly. Only respond about history.",
    "history_tutor",
    "Specialist agent for historical questions");

ChatClientAgent mathTutor = new(client,
    "You provide help with math problems. Explain your reasoning at each step and include examples. Only respond about math.",
    "math_tutor",
    "Specialist agent for math questions");

ChatClientAgent triageAgent = new(client,
    "You determine which agent to use based on the user's homework question. ALWAYS handoff to another agent.",
    "triage_agent",
    "Routes messages to the appropriate specialist agent");

Настройка правил передачи

Определите, какие агенты могут передавать задачи другим агентам.

// 3) Build handoff workflow with routing rules
var workflow = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
    .WithHandoffs(triageAgent, [mathTutor, historyTutor]) // Triage can route to either specialist
    .WithHandoff(mathTutor, triageAgent)                  // Math tutor can return to triage
    .WithHandoff(historyTutor, triageAgent)               // History tutor can return to triage
    .Build();

Запуск интерактивного процесса передачи управления

Динамическое переключение агента для обработки многократных диалогов:

// 4) Process multi-turn conversations
List<ChatMessage> messages = new();

while (true)
{
    Console.Write("Q: ");
    string userInput = Console.ReadLine()!;
    messages.Add(new(ChatRole.User, userInput));

    // Execute workflow and process events
    StreamingRun run = await InProcessExecution.StreamAsync(workflow, messages);
    await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

    List<ChatMessage> newMessages = new();
    await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
    {
        if (evt is AgentResponseUpdateEvent e)
        {
            Console.WriteLine($"{e.ExecutorId}: {e.Data}");
        }
        else if (evt is WorkflowOutputEvent outputEvt)
        {
            newMessages = (List<ChatMessage>)outputEvt.Data!;
            break;
        }
    }

    // Add new messages to conversation history
    messages.AddRange(newMessages.Skip(messages.Count));
}

Пример взаимодействия

Q: What is the derivative of x^2?
triage_agent: This is a math question. I'll hand this off to the math tutor.
math_tutor: The derivative of x^2 is 2x. Using the power rule, we bring down the exponent (2) and multiply it by the coefficient (1), then reduce the exponent by 1: d/dx(x^2) = 2x^(2-1) = 2x.

Q: Tell me about World War 2
triage_agent: This is a history question. I'll hand this off to the history tutor.
history_tutor: World War 2 was a global conflict from 1939 to 1945. It began when Germany invaded Poland and involved most of the world's nations. Key events included the Holocaust, Pearl Harbor attack, D-Day invasion, and ended with atomic bombs on Japan.

Q: Can you help me with calculus integration?
triage_agent: This is another math question. I'll route this to the math tutor.
math_tutor: I'd be happy to help with calculus integration! Integration is the reverse of differentiation. The basic power rule for integration is: ∫x^n dx = x^(n+1)/(n+1) + C, where C is the constant of integration.

Определение нескольких инструментов для демонстрации

@tool
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}."

@tool
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."

@tool
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."

Настройка клиента чата

from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

# Initialize the Azure OpenAI chat client
chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())

Определите своих специализированных агентов

Создайте агенты, относящиеся к домену, с координатором для маршрутизации:

# Create triage/coordinator agent
triage_agent = chat_client.as_agent(
    instructions=(
        "You are frontline support triage. Route customer issues to the appropriate specialist agents "
        "based on the problem described."
    ),
    description="Triage agent that handles general inquiries.",
    name="triage_agent",
)

# Refund specialist: Handles refund requests
refund_agent = chat_client.as_agent(
    instructions="You process refund requests.",
    description="Agent that handles refund requests.",
    name="refund_agent",
    # In a real application, an agent can have multiple tools; here we keep it simple
    tools=[process_refund],
)

# Order/shipping specialist: Resolves delivery issues
order_agent = chat_client.as_agent(
    instructions="You handle order and shipping inquiries.",
    description="Agent that handles order tracking and shipping issues.",
    name="order_agent",
    # In a real application, an agent can have multiple tools; here we keep it simple
    tools=[check_order_status],
)

# Return specialist: Handles return requests
return_agent = chat_client.as_agent(
    instructions="You manage product return requests.",
    description="Agent that handles return processing.",
    name="return_agent",
    # In a real application, an agent can have multiple tools; here we keep it simple
    tools=[process_return],
)

Настройка правил передачи

Создание рабочего процесса передачи с помощью HandoffBuilder:

from agent_framework.orchestrations import HandoffBuilder

# Build the handoff workflow
workflow = (
    HandoffBuilder(
        name="customer_support_handoff",
        participants=[triage_agent, refund_agent, order_agent, return_agent],
        termination_condition=lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower(),
    )
    .with_start_agent(triage_agent) # Triage receives initial user input
    .build()
)

По умолчанию все агенты могут передавать управление друг другу. Для более расширенной маршрутизации можно настроить раздатки:

workflow = (
    HandoffBuilder(
        name="customer_support_handoff",
        participants=[triage_agent, refund_agent, order_agent, return_agent],
        termination_condition=lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower(),
    )
    .with_start_agent(triage_agent) # Triage receives initial user input
    # Triage cannot route directly to refund agent
    .add_handoff(triage_agent, [order_agent, return_agent])
    # Only the return agent can handoff to refund agent - users wanting refunds after returns
    .add_handoff(return_agent, [refund_agent])
    # All specialists can handoff back to triage for further routing
    .add_handoff(order_agent, [triage_agent])
    .add_handoff(return_agent, [triage_agent])
    .add_handoff(refund_agent, [triage_agent])
    .build()
)

Замечание

Даже с пользовательскими правилами передачи все агенты по-прежнему подключены в топологии сетки. Это связано с тем, что агенты должны совместно использовать контекст друг с другом для поддержания журнала бесед (дополнительные сведения см. в разделе "Синхронизация контекста "). Правила передачи управляют только тем, какие агенты могут продолжить беседу в дальнейшем.

Запуск взаимодействия агента передачи

В отличие от других оркестраций, передача управления является интерактивной, так как агент может не решить передать управление после каждого хода. Если агент не передает управление, для продолжения диалога необходима помощь человека. Сведения об обходе этого требования см. в автономном режиме . В других оркестрациях после ответа агента управление переходит к оркестратору или следующему агенту.

Когда агент в рабочем процессе передачи решает не передавать (передача активируется специальным вызовом средства), рабочий процесс генерирует WorkflowEvent с type="request_info" и HandoffAgentUserRequest, содержащие самые последние сообщения агента. Пользователь должен ответить на этот запрос, чтобы продолжить рабочий процесс.

from agent_framework import WorkflowEvent
from agent_framework.orchestrations import HandoffAgentUserRequest

# Start workflow with initial user message
events = [event async for event in workflow.run_stream("I need help with my order")]

# Process events and collect pending input requests
pending_requests = []
for event in events:
    if event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest):
        pending_requests.append(event)
        request_data = event.data
        print(f"Agent {event.executor_id} is awaiting your input")
        # The request contains the most recent messages generated by the
        # agent requesting input
        for msg in request_data.agent_response.messages[-3:]:
            print(f"{msg.author_name}: {msg.text}")

# Interactive loop: respond to requests
while pending_requests:
    user_input = input("You: ")

    # Send responses to all pending requests
    responses = {req.request_id: HandoffAgentUserRequest.create_response(user_input) for req in pending_requests}
    # You can also send a `HandoffAgentUserRequest.terminate()` to end the workflow early
    events = [event async for event in workflow.run(responses=responses)]

    # Process new events
    pending_requests = []
    for event in events:
        # Check for new input requests

Автономный режим

Оркестрация Handoff предназначена для интерактивных сценариев, где требуется участие человека в случае, если агент принимает решение не передавать управление. Однако в качестве экспериментальной функции можно включить "автономный режим", чтобы рабочий процесс продолжался без вмешательства человека. В этом режиме, когда агент решает не передавать управление, рабочий процесс автоматически отправляет агенту ответ по умолчанию (например, User did not respond. Continue assisting autonomously.), что позволяет ему продолжить беседу.

Подсказка

Почему оркестрация Handoff по сути является интерактивной? В отличие от других оркестраций, где существует только один путь выполнения после отклика агента (например, обратно в оркестратор или следующему агенту), в оркестрации типа Handoff агент имеет возможность либо передать другому агенту, либо самостоятельно продолжить помощь пользователю. И поскольку передача достигается с помощью вызовов инструментов, если агент не вызывает средство передачи, а генерирует ответ, рабочий процесс не будет знать, что делать дальше, кроме как передать обратно пользователю для дальнейшего ввода. Кроме того, невозможно принудительно заставить агента всегда передавать задачу, требуя, чтобы он воспользовался инструментом передачи, так как агент иначе не сможет создавать значимые ответы.

Автономныйwith_autonomous_mode()режим включен путем вызоваHandoffBuilder. Это настраивает рабочий процесс для автоматического реагирования на входные запросы с сообщением по умолчанию, что позволяет агенту продолжать работу, не ожидая ввода человека.

workflow = (
    HandoffBuilder(
        name="autonomous_customer_support",
        participants=[triage_agent, refund_agent, order_agent, return_agent],
    )
    .with_start_agent(triage_agent)
    .with_autonomous_mode()
    .build()
)

Вы также можете включить автономный режим только в подмножестве агентов, передав список экземпляров агента с помощью with_autonomous_mode().

workflow = (
    HandoffBuilder(
        name="partially_autonomous_support",
        participants=[triage_agent, refund_agent, order_agent, return_agent],
    )
    .with_start_agent(triage_agent)
    .with_autonomous_mode(agents=[triage_agent])  # Only triage_agent runs autonomously
    .build()
)

Вы можете настроить ответное сообщение по умолчанию.

workflow = (
    HandoffBuilder(
        name="custom_autonomous_support",
        participants=[triage_agent, refund_agent, order_agent, return_agent],
    )
    .with_start_agent(triage_agent)
    .with_autonomous_mode(
        agents=[triage_agent],
        prompts={triage_agent.name: "Continue with your best judgment as the user is unavailable."},
    )
    .build()
)

Вы можете настроить количество циклов, которые агент может выполнять автономно, прежде чем потребуется вмешательство человека. Это может предотвратить выполнение рабочего процесса на неопределенный срок без участия пользователя.

workflow = (
    HandoffBuilder(
        name="limited_autonomous_support",
        participants=[triage_agent, refund_agent, order_agent, return_agent],
    )
    .with_start_agent(triage_agent)
    .with_autonomous_mode(
        agents=[triage_agent],
        turn_limits={triage_agent.name: 3},  # Max 3 autonomous turns
    )
    .build()
)

Дополнительно: утверждение инструментов в рабочих процессах передачи

В рабочие процессы передачи могут входить агенты с инструментами, для работы которых требуется одобрение человека перед выполнением. Это полезно для конфиденциальных операций, таких как возврат средств, покупка или выполнение необратимых действий.

Определение инструментов с обязательным утверждением

from typing import Annotated
from agent_framework import tool

@tool(approval_mode="always_require")
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}."

Создание агентов с использованием инструментов, требующих одобрения

from agent_framework import Agent
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity import AzureCliCredential

client = AzureOpenAIChatClient(credential=AzureCliCredential())

triage_agent = chat_client.as_agent(
    instructions=(
        "You are frontline support triage. Route customer issues to the appropriate specialist agents "
        "based on the problem described."
    ),
    description="Triage agent that handles general inquiries.",
    name="triage_agent",
)

refund_agent = chat_client.as_agent(
    instructions="You process refund requests.",
    description="Agent that handles refund requests.",
    name="refund_agent",
    tools=[process_refund],
)

order_agent = chat_client.as_agent(
    instructions="You handle order and shipping inquiries.",
    description="Agent that handles order tracking and shipping issues.",
    name="order_agent",
    tools=[check_order_status],
)

Обработка пользовательского ввода и запросов на утверждение инструментов

from agent_framework import (
    FunctionApprovalRequestContent,
    WorkflowEvent,
)
from agent_framework.orchestrations import HandoffBuilder, HandoffAgentUserRequest

workflow = (
    HandoffBuilder(
        name="support_with_approvals",
        participants=[triage_agent, refund_agent, order_agent],
    )
    .with_start_agent(triage_agent)
    .build()
)

pending_requests: list[WorkflowEvent] = []

# Start workflow
async for event in workflow.run_stream("My order 12345 arrived damaged. I need a refund."):
    if event.type == "request_info":
        pending_requests.append(event)

# Process pending requests - could be user input OR tool approval
while pending_requests:
    responses: dict[str, object] = {}

    for request in pending_requests:
        if isinstance(request.data, HandoffAgentUserRequest):
            # Agent needs user input
            print(f"Agent {request.executor_id} asks:")
            for msg in request.data.agent_response.messages[-2:]:
                print(f"  {msg.author_name}: {msg.text}")

            user_input = input("You: ")
            responses[request.request_id] = HandoffAgentUserRequest.create_response(user_input)

        elif isinstance(request.data, FunctionApprovalRequestContent):
            # Agent wants to call a tool that requires approval
            func_call = request.data.function_call
            args = func_call.parse_arguments() or {}

            print(f"\nTool approval requested: {func_call.name}")
            print(f"Arguments: {args}")

            approval = input("Approve? (y/n): ").strip().lower() == "y"
            responses[request.request_id] = request.data.create_response(approved=approval)

    # Send all responses and collect new requests
    pending_requests = []
    async for event in workflow.run(responses=responses):
        if event.type == "request_info":
            pending_requests.append(event)
        elif event.type == "output":
            print("\nWorkflow completed!")

Использование контрольных точек для долговечных рабочих процессов

Для длительных рабочих процессов, в которых утверждения инструментов могут произойти часы или дни спустя, используйте контрольные точки:

from agent_framework import FileCheckpointStorage

storage = FileCheckpointStorage(storage_path="./checkpoints")

workflow = (
    HandoffBuilder(
        name="durable_support",
        participants=[triage_agent, refund_agent, order_agent],
        checkpoint_storage=storage,
    )
    .with_start_agent(triage_agent)
    .build()
)

# Initial run - workflow pauses when approval is needed
pending_requests = []
async for event in workflow.run_stream("I need a refund for order 12345"):
    if event.type == "request_info":
        pending_requests.append(event)

# Process can exit here - checkpoint is saved automatically

# Later: Resume from checkpoint and provide approval
checkpoints = await storage.list_checkpoints()
latest = sorted(checkpoints, key=lambda c: c.timestamp, reverse=True)[0]

# Step 1: Restore checkpoint to reload pending requests
restored_requests = []
async for event in workflow.run_stream(checkpoint_id=latest.checkpoint_id):
    if event.type == "request_info":
        restored_requests.append(event)

# Step 2: Send responses
responses = {}
for req in restored_requests:
    if isinstance(req.data, FunctionApprovalRequestContent):
        responses[req.request_id] = req.data.create_response(approved=True)
    elif isinstance(req.data, HandoffAgentUserRequest):
        responses[req.request_id] = HandoffAgentUserRequest.create_response("Yes, please process the refund.")

async for event in workflow.run(responses=responses):
    if event.type == "output":
        print("Refund workflow completed!")

Пример взаимодействия

User: I need help with my order

triage_agent: I'd be happy to help you with your order. Could you please provide more details about the issue?

User: My order 1234 arrived damaged

triage_agent: I'm sorry to hear that your order arrived damaged. I will connect you with a specialist.

support_agent: I'm sorry about the damaged order. To assist you better, could you please:
- Describe the damage
- Would you prefer a replacement or refund?

User: I'd like a refund

triage_agent: I'll connect you with the refund specialist.

refund_agent: I'll process your refund for order 1234. Here's what will happen next:
1. Verification of the damaged items
2. Refund request submission
3. Return instructions if needed
4. Refund processing within 5-10 business days

Could you provide photos of the damage to expedite the process?

Синхронизация контекста

Агенты в Agent Framework используют сеансы агента (AgentSession) для управления контекстом. В сценарии оркестрации передачи агенты не используют один и тот же экземпляр сеанса; участники несут ответственность за обеспечение согласованности контекста. Для этого участники транслируют свои ответы или полученные входные данные пользователей всем участникам рабочего процесса при создании ответа, обеспечивая актуальность контекста для всех участников к их следующему шагу.

Замечание

Связанное с инструментами содержимое, включая вызовы для передачи с помощью инструмента, не передается другим агентам. Для всех участников синхронизируются только сообщения пользователей и агентов.

Подсказка

Агенты не используют один экземпляр сеанса, так как разные типы агентовAgentSession могут иметь разные реализации абстракции. Совместное использование одного экземпляра сеанса может привести к непоследовательностям в том, как каждый агент обрабатывает и поддерживает контекст.

После трансляции ответа участник затем проверяет, нужно ли передать беседу другому агенту. Если да, он отправляет запрос выбранному агенту, чтобы взять на себя беседу. В противном случае он запрашивает входные данные пользователя или продолжает автономно на основе конфигурации рабочего процесса.

Основные понятия

• Динамическая маршрутизация: агенты могут решить, какой агент должен обрабатывать следующее взаимодействие на основе контекста
• AgentWorkflowBuilder.StartHandoffWith(): определяет начальный агент, который запускает рабочий процесс.
• WithHandoff() и WithHandoffs(): настраивает правила передачи между определенными агентами
• Сохранение контекста: полная история беседы сохраняется во всех переходах.
• Поддержка с несколькими шагами: поддерживает текущие беседы с простым переключением агента
• Специализированный опыт: каждый агент фокусируется на своем домене в процессе совместной работы и передачи полномочий

• Динамическая маршрутизация: агенты могут решить, какой агент должен обрабатывать следующее взаимодействие на основе контекста
• HandoffBuilder: создание рабочих процессов с автоматической регистрацией средства передачи
• with_start_agent(): определяет, какой агент получает входные данные пользователя в первую очередь
• add_handoff(): конфигурирует конкретные связи передачи между агентами
• Сохранение контекста: полная история беседы сохраняется во всех переходах.
• Цикл запроса и ответа: рабочий процесс запрашивает входные данные пользователя, обрабатывает ответы и продолжается до тех пор, пока не будет выполнено условие завершения.
• Утверждение инструмента: использование @tool(approval_mode="always_require") для конфиденциальных операций, которым требуется утверждение человека
• FunctionApprovalRequestContent: создается, когда агент вызывает инструмент, в котором требуется утверждение; используется create_response(approved=...) для реагирования
• Чекпоинт: используется with_checkpointing() для надёжных рабочих процессов, которые могут быть приостановлены и возобновлены после перезапуска процесса
• Специализированный опыт: каждый агент фокусируется на своем домене в процессе совместной работы и передачи полномочий

Дальнейшие шаги

Оркестрация группового чата