Orquestração Handoff

2025-05-23

Importante

Os recursos de orquestração de agentes no Agent Framework estão em estágio experimental. Eles estão em desenvolvimento ativo e podem mudar significativamente antes de avançar para o estágio de prévia ou versão candidata.

A orquestração Handoff permite que os agentes transfiram o controle uns para os outros com base no contexto ou na solicitação do usuário. Cada agente pode "transferir" a conversa para outro agente com a experiência apropriada, garantindo que o agente certo trate de cada parte da tarefa. Isso é particularmente útil no suporte ao cliente, sistemas especializados ou qualquer cenário que exija delegação dinâmica.

Casos de uso comuns

Um agente de suporte ao cliente lida com uma consulta geral e, em seguida, entrega a um agente técnico especializado para solução de problemas ou a um agente de cobrança, se necessário:

diagrama

O que você vai aprender

Como definir os agentes e suas relações de transferência
Como configurar uma orquestração de entrega para distribuição dinâmica de agentes
Como envolver um ser humano no ciclo de conversação

Definir Agentes Especializados

Cada agente é responsável por uma área específica. Neste exemplo, definimos um agente de triagem, um agente de reembolso, um agente de status de pedido e um agente de devolução de pedidos. Alguns agentes usam plugins para lidar com tarefas específicas.

Sugestão

O ChatCompletionAgent é usado aqui, mas você pode usar qualquer tipo de agente.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.Agents.Orchestration;
using Microsoft.SemanticKernel.Agents.Orchestration.Handoff;
using Microsoft.SemanticKernel.Agents.Runtime.InProcess;
using Microsoft.SemanticKernel.ChatCompletion;

// Plugin implementations
public sealed class OrderStatusPlugin {
    [KernelFunction]
    public string CheckOrderStatus(string orderId) => $"Order {orderId} is shipped and will arrive in 2-3 days.";
}
public sealed class OrderReturnPlugin {
    [KernelFunction]
    public string ProcessReturn(string orderId, string reason) => $"Return for order {orderId} has been processed successfully.";
}
public sealed class OrderRefundPlugin {
    [KernelFunction]
    public string ProcessReturn(string orderId, string reason) => $"Refund for order {orderId} has been processed successfully.";
}

// Helper function to create a kernel with chat completion
public static Kernel CreateKernelWithChatCompletion(...)
{
    ...
}

ChatCompletionAgent triageAgent = new ChatCompletionAgent {
    Name = "TriageAgent",
    Description = "Handle customer requests.",
    Instructions = "A customer support agent that triages issues.",
    Kernel = CreateKernelWithChatCompletion(...),
};

ChatCompletionAgent statusAgent = new ChatCompletionAgent {
    Name = "OrderStatusAgent",
    Description = "A customer support agent that checks order status.",
    Instructions = "Handle order status requests.",
    Kernel = CreateKernelWithChatCompletion(...),
};
statusAgent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromObject(new OrderStatusPlugin()));

ChatCompletionAgent returnAgent = new ChatCompletionAgent {
    Name = "OrderReturnAgent",
    Description = "A customer support agent that handles order returns.",
    Instructions = "Handle order return requests.",
    Kernel = CreateKernelWithChatCompletion(...),
};
returnAgent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromObject(new OrderReturnPlugin()));

ChatCompletionAgent refundAgent = new ChatCompletionAgent {
    Name = "OrderRefundAgent",
    Description = "A customer support agent that handles order refund.",
    Instructions = "Handle order refund requests.",
    Kernel = CreateKernelWithChatCompletion(...),
};
refundAgent.Kernel.Plugins.Add(KernelPluginFactory.CreateFromObject(new OrderRefundPlugin()));

Configurar relações de Handoff

Use OrchestrationHandoffs para especificar que agente pode entregar a quem e em que circunstâncias.

var handoffs = OrchestrationHandoffs
    .StartWith(triageAgent)
    .Add(triageAgent, statusAgent, returnAgent, refundAgent)
    .Add(statusAgent, triageAgent, "Transfer to this agent if the issue is not status related")
    .Add(returnAgent, triageAgent, "Transfer to this agent if the issue is not return related")
    .Add(refundAgent, triageAgent, "Transfer to this agent if the issue is not refund related");

Observar as respostas do agente

Você pode criar um retorno de chamada para capturar as respostas do agente enquanto a conversa se desenrola através da propriedade ResponseCallback.

ChatHistory history = [];

ValueTask responseCallback(ChatMessageContent response)
{
    history.Add(response);
    return ValueTask.CompletedTask;
}

Intervenção Humana no Processo

Uma característica fundamental da orquestração de handoff é a capacidade de um ser humano participar na conversa. Isso é conseguido fornecendo um InteractiveCallback, que é chamado sempre que um agente precisa de entrada do usuário. Em um aplicativo real, isso solicitaria a entrada do usuário; Em um exemplo, você pode usar uma fila de respostas.

// Simulate user input with a queue
Queue<string> responses = new();
responses.Enqueue("I'd like to track the status of my order");
responses.Enqueue("My order ID is 123");
responses.Enqueue("I want to return another order of mine");
responses.Enqueue("Order ID 321");
responses.Enqueue("Broken item");
responses.Enqueue("No, bye");

ValueTask<ChatMessageContent> interactiveCallback()
{
    string input = responses.Dequeue();
    Console.WriteLine($"\n# INPUT: {input}\n");
    return ValueTask.FromResult(new ChatMessageContent(AuthorRole.User, input));
}

Configurar a Orquestração "Handoff"

Crie um objeto HandoffOrchestration, passando os agentes, as relações de transferência e os retornos de chamada.

HandoffOrchestration orchestration = new HandoffOrchestration(
    handoffs,
    triageAgent,
    statusAgent,
    returnAgent,
    refundAgent)
{
    InteractiveCallback = interactiveCallback,
    ResponseCallback = responseCallback,
};

Iniciar o tempo de execução

Um ambiente de execução é necessário para gerir a execução de agentes. Aqui, usamos InProcessRuntime e iniciamos o processo antes de invocar a orquestração.

InProcessRuntime runtime = new InProcessRuntime();
await runtime.StartAsync();

Invoque a orquestração

Invoque a orquestração com sua tarefa inicial (por exemplo, "Sou um cliente que precisa de ajuda com meus pedidos"). Os agentes encaminharão a conversa conforme necessário, envolvendo o ser humano quando necessário.

string task = "I am a customer that needs help with my orders";
var result = await orchestration.InvokeAsync(task, runtime);

Recolher Resultados

Aguarde a conclusão da orquestração e recupere a saída final.

string output = await result.GetValueAsync(TimeSpan.FromSeconds(300));
Console.WriteLine($"\n# RESULT: {output}");
Console.WriteLine("\n\nORCHESTRATION HISTORY");
foreach (ChatMessageContent message in history)
{
    // Print each message
    Console.WriteLine($"# {message.Role} - {message.AuthorName}: {message.Content}");
}

Opcional: Pare o tempo de execução

Após a conclusão do processamento, pare o tempo de execução para limpar recursos.

await runtime.RunUntilIdleAsync();

Saída de amostra

# RESULT: Handled order return for order ID 321 due to a broken item, and successfully processed the return.

ORCHESTRATION HISTORY

# Assistant - TriageAgent: Could you please specify what kind of help you need with your orders? Are you looking to check the order status, return an item, or request a refund?

# Assistant - OrderStatusAgent: Could you please tell me your order ID?

# Assistant - OrderStatusAgent: Your order with ID 123 has been shipped and will arrive in 2-3 days. Anything else I can assist you with?

# Assistant - OrderReturnAgent: I can help you with that. Could you please provide the order ID and the reason you'd like to return it?

# Assistant - OrderReturnAgent: Please provide the reason for returning the order with ID 321.

# Assistant - OrderReturnAgent: The return for your order with ID 321 has been successfully processed due to the broken item. Anything else I can assist you with?

Sugestão

O código de exemplo completo está disponível aqui

Definir Agentes Especializados

Cada agente é responsável por uma área específica. Por exemplo:

TriageAgent: lida com as solicitações iniciais dos clientes e decide qual especialista envolver.
RefundAgent: Lida com pedidos de reembolso.
OrderStatusAgent: Verifica o status do pedido.
OrderReturnAgent: lida com devoluções de pedidos.

Plug-ins

Primeiro precisamos definir os plugins que serão usados nos agentes. Esses plugins conterão a lógica para lidar com tarefas específicas.

from semantic_kernel.functions import kernel_function

class OrderStatusPlugin:
    @kernel_function
    def check_order_status(self, order_id: str) -> str:
        """Check the status of an order."""
        # Simulate checking the order status
        return f"Order {order_id} is shipped and will arrive in 2-3 days."


class OrderRefundPlugin:
    @kernel_function
    def process_refund(self, order_id: str, reason: str) -> str:
        """Process a refund for an order."""
        # Simulate processing a refund
        print(f"Processing refund for order {order_id} due to: {reason}")
        return f"Refund for order {order_id} has been processed successfully."


class OrderReturnPlugin:
    @kernel_function
    def process_return(self, order_id: str, reason: str) -> str:
        """Process a return for an order."""
        # Simulate processing a return
        print(f"Processing return for order {order_id} due to: {reason}")
        return f"Return for order {order_id} has been processed successfully."

Agentes

Em seguida, definimos os agentes que usarão esses plugins.

Sugestão

O ChatCompletionAgent é utilizado aqui com o Azure OpenAI, contudo, pode-se usar qualquer tipo de agente ou serviço de modelo.

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

support_agent = ChatCompletionAgent(
    name="TriageAgent",
    description="A customer support agent that triages issues.",
    instructions="Handle customer requests.",
    service=OpenAIChatCompletion(),
)

refund_agent = ChatCompletionAgent(
    name="RefundAgent",
    description="A customer support agent that handles refunds.",
    instructions="Handle refund requests.",
    service=OpenAIChatCompletion(),
    plugins=[OrderRefundPlugin()],
)

order_status_agent = ChatCompletionAgent(
    name="OrderStatusAgent",
    description="A customer support agent that checks order status.",
    instructions="Handle order status requests.",
    service=OpenAIChatCompletion(),
    plugins=[OrderStatusPlugin()],
)

order_return_agent = ChatCompletionAgent(
    name="OrderReturnAgent",
    description="A customer support agent that handles order returns.",
    instructions="Handle order return requests.",
    service=OpenAIChatCompletion(),
    plugins=[OrderReturnPlugin()],
)

Definir Relacionamentos de Transferência

Use OrchestrationHandoffs para especificar que agente pode entregar a quem e em que circunstâncias.

from semantic_kernel.agents import OrchestrationHandoffs

handoffs = (
    OrchestrationHandoffs()
    .add_many(    # Use add_many to add multiple handoffs to the same source agent at once
        source_agent=support_agent.name,
        target_agents={
            refund_agent.name: "Transfer to this agent if the issue is refund related",
            order_status_agent.name: "Transfer to this agent if the issue is order status related",
            order_return_agent.name: "Transfer to this agent if the issue is order return related",
        },
    )
    .add(    # Use add to add a single handoff
        source_agent=refund_agent.name,
        target_agent=support_agent.name,
        description="Transfer to this agent if the issue is not refund related",
    )
    .add(
        source_agent=order_status_agent.name,
        target_agent=support_agent.name,
        description="Transfer to this agent if the issue is not order status related",
    )
    .add(
        source_agent=order_return_agent.name,
        target_agent=support_agent.name,
        description="Transfer to this agent if the issue is not order return related",
    )
)

Observar as respostas do agente

Você pode definir um retorno de chamada para imprimir a mensagem de cada agente à medida que a conversa progride.

from semantic_kernel.contents import ChatMessageContent

def agent_response_callback(message: ChatMessageContent) -> None:
    print(f"{message.name}: {message.content}")

Intervenção Humana no Processo

Uma característica fundamental da orquestração de handoff é a capacidade de um ser humano participar na conversa. Isso é conseguido fornecendo um retorno de chamada human_response_function, que é chamado sempre que um agente precisa de input do utilizador.

from semantic_kernel.contents import AuthorRole, ChatMessageContent

def human_response_function() -> ChatMessageContent:
    user_input = input("User: ")
    return ChatMessageContent(role=AuthorRole.USER, content=user_input)

Configurar a Orquestração "Handoff"

Crie um objeto HandoffOrchestration, passando os agentes, as relações de transferência e os retornos de chamada.

from semantic_kernel.agents import HandoffOrchestration

handoff_orchestration = HandoffOrchestration(
    members=[
        support_agent,
        refund_agent,
        order_status_agent,
        order_return_agent,
    ],
    handoffs=handoffs,
    agent_response_callback=agent_response_callback,
    human_response_function=human_response_function,
)

Iniciar o tempo de execução

Inicie o ambiente de execução para gerenciar a execução do agente.

from semantic_kernel.agents.runtime import InProcessRuntime

runtime = InProcessRuntime()
runtime.start()

Invoque a orquestração

Invoque a orquestração com sua tarefa inicial (por exemplo, "Um cliente está na linha."). Os agentes encaminharão a conversa conforme necessário, envolvendo o ser humano quando necessário.

orchestration_result = await handoff_orchestration.invoke(
    task="A customer is on the line.",
    runtime=runtime,
)

Recolher Resultados

Aguarde até que a orquestração seja concluída.

value = await orchestration_result.get()
print(value)

Opcional: Pare o tempo de execução

Após a conclusão do processamento, pare o tempo de execução para limpar recursos.

await runtime.stop_when_idle()

Saída de amostra

TriageAgent: Hello! Thank you for reaching out. How can I assist you today?
User: I'd like to track the status of my order
OrderStatusAgent: Sure, I can help you with that. Could you please provide me with your order ID?
User: My order ID is 123
OrderStatusAgent: Your order with ID 123 has been shipped and is expected to arrive in 2-3 days. Is there anything else I can assist you with?
User: I want to return another order of mine
OrderReturnAgent: I can help you with returning your order. Could you please provide the order ID for the return and the reason you'd like to return it?
User: Order ID 321
OrderReturnAgent: Please provide the reason for returning the order with ID 321.
User: Broken item
OrderReturnAgent: The return for your order with ID 321 has been successfully processed due to the broken item. Is there anything else I can assist you with?
User: No, bye
Task is completed with summary: Handled order return for order ID 321 due to a broken item, and successfully processed the return.

Sugestão

O código de exemplo completo está disponível aqui.

Observação

A orquestração de agentes ainda não está disponível no Java SDK.

Próximos passos

Orquestração Magentica

Partilhar via

Orquestração Handoff

Casos de uso comuns

O que você vai aprender

Definir Agentes Especializados

Configurar relações de Handoff

Observar as respostas do agente

Intervenção Humana no Processo

Configurar a Orquestração "Handoff"

Iniciar o tempo de execução

Invoque a orquestração

Recolher Resultados

Opcional: Pare o tempo de execução

Saída de amostra

Definir Agentes Especializados

Plug-ins

Agentes

Definir Relacionamentos de Transferência

Observar as respostas do agente

Intervenção Humana no Processo

Configurar a Orquestração "Handoff"

Iniciar o tempo de execução

Invoque a orquestração

Recolher Resultados

Opcional: Pare o tempo de execução

Saída de amostra

Próximos passos

Recursos adicionais