Orquestração sequencial

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.

No padrão sequencial, os agentes são organizados em um pipeline. Cada agente processa a tarefa por sua vez, passando sua saída para o próximo agente na sequência. Isso é ideal para fluxos de trabalho em que cada etapa se baseia na anterior, como revisão de documentos, pipelines de processamento de dados ou raciocínio em vários estágios.

Casos de uso comuns

Um documento passa por um agente de sumarização, depois por um agente de tradução e, finalmente, por um agente de garantia de qualidade, cada um com base no resultado anterior:

diagrama

O que você vai aprender

Como definir uma sequência de agentes, cada um com uma função especializada
Como orquestrar esses agentes para que cada um processe a saída do anterior
Como observar saídas intermediárias e coletar o resultado final

Defina seus agentes

Os agentes são entidades especializadas que processam tarefas em sequência. Aqui, definimos três agentes: um analista, um redator e um editor.

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.Sequential;
using Microsoft.SemanticKernel.Agents.Runtime.InProcess;

// Create a kernel with an AI service
Kernel kernel = ...;

ChatCompletionAgent analystAgent = new ChatCompletionAgent {
    Name = "Analyst",
    Instructions = "You are a marketing analyst. Given a product description, identify:\n- Key features\n- Target audience\n- Unique selling points",
    Kernel = kernel,
};

ChatCompletionAgent writerAgent = new ChatCompletionAgent {
    Name = "Copywriter",
    Instructions = "You are a marketing copywriter. Given a block of text describing features, audience, and USPs, compose a compelling marketing copy (like a newsletter section) that highlights these points. Output should be short (around 150 words), output just the copy as a single text block.",
    Kernel = kernel,
};

ChatCompletionAgent editorAgent = new ChatCompletionAgent {
    Name = "Editor",
    Instructions = "You are an editor. Given the draft copy, correct grammar, improve clarity, ensure consistent tone, give format and make it polished. Output the final improved copy as a single text block.",
    Kernel = kernel,
};

Opcional: Observe as respostas do agente

Você pode criar um retorno de chamada para capturar as respostas do agente à medida que a sequência progride através da ResponseCallback propriedade.

ChatHistory history = [];

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

Configurar a orquestração sequencial

Crie um objeto SequentialOrchestration, passando os agentes e o callback de resposta opcional.

SequentialOrchestration orchestration = new(analystAgent, writerAgent, editorAgent)
{
    ResponseCallback = responseCallback,
};

Iniciar Runtime

É necessário um runtime para gerir a execução de agentes. Aqui, usamos InProcessRuntime e começamos a sua execução antes de invocar a orquestração.

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

Acione a orquestração

Invoque a orquestração com a sua tarefa inicial (por exemplo, uma descrição de produto). A saída fluirá através de cada agente em sequência.

var result = await orchestration.InvokeAsync(
    "An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours",
    runtime);

Recolher Resultados

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

string output = await result.GetValueAsync(TimeSpan.FromSeconds(20));
Console.WriteLine($"\n# RESULT: {text}");
Console.WriteLine("\n\nORCHESTRATION HISTORY");
foreach (ChatMessageContent message in history)
{
    this.WriteAgentChatMessage(message);
}

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: Introducing our Eco-Friendly Stainless Steel Water Bottles – the perfect companion for those who care about the planet while staying hydrated! Our bottles ...


ORCHESTRATION HISTORY

# Assistant - Analyst: **Key Features:**
- Made from eco-friendly stainless steel
- Insulation technology that maintains cold temperatures for up to 24 hours
- Reusable and sustainable design
- Various sizes and colors available (assumed based on typical offerings)
- Leak-proof cap
- BPA-free ...

# Assistant - copywriter: Introducing our Eco-Friendly Stainless ...

# Assistant - editor: Introducing our Eco-Friendly Stainless Steel Water Bottles – the perfect companion for those who care about the planet while staying hydrated! Our bottles ...

Sugestão

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

Defina seus agentes

Cada agente na sequência tem uma responsabilidade específica. Neste exemplo, temos:

ConceptExtractorAgent: extrai os principais recursos, público-alvo e pontos de venda exclusivos de uma descrição do produto.
WriterAgent: Cria um texto de marketing com base nas informações extraídas.
FormatProofAgent: Edita e poli a cópia de rascunho para maior clareza e consistência.

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 Agent, ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

def get_agents() -> list[Agent]:
    concept_extractor_agent = ChatCompletionAgent(
        name="ConceptExtractorAgent",
        instructions=(
            "You are a marketing analyst. Given a product description, identify:\n"
            "- Key features\n"
            "- Target audience\n"
            "- Unique selling points\n\n"
        ),
        service=AzureChatCompletion(),
    )
    writer_agent = ChatCompletionAgent(
        name="WriterAgent",
        instructions=(
            "You are a marketing copywriter. Given a block of text describing features, audience, and USPs, "
            "compose a compelling marketing copy (like a newsletter section) that highlights these points. "
            "Output should be short (around 150 words), output just the copy as a single text block."
        ),
        service=AzureChatCompletion(),
    )
    format_proof_agent = ChatCompletionAgent(
        name="FormatProofAgent",
        instructions=(
            "You are an editor. Given the draft copy, correct grammar, improve clarity, ensure consistent tone, "
            "give format and make it polished. Output the final improved copy as a single text block."
        ),
        service=AzureChatCompletion(),
    )
    return [concept_extractor_agent, writer_agent, format_proof_agent]

Opcional: Observe as respostas do agente

Você pode definir um retorno de chamada para observar e imprimir a saída de cada agente à medida que a sequência progride.

from semantic_kernel.contents import ChatMessageContent

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

Configurar a orquestração sequencial

Num objeto SequentialOrchestration, passa os agentes e um retorno de chamada de resposta opcional.

from semantic_kernel.agents import SequentialOrchestration

agents = get_agents()
sequential_orchestration = SequentialOrchestration(
    members=agents,
    agent_response_callback=agent_response_callback,
)

Iniciar Runtime

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

from semantic_kernel.agents.runtime import InProcessRuntime

runtime = InProcessRuntime()
runtime.start()

Acione a orquestração

Invoque a orquestração com a sua tarefa inicial (por exemplo, uma descrição de produto). A saída fluirá através de cada agente em sequência.

orchestration_result = await sequential_orchestration.invoke(
    task="An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours",
    runtime=runtime,
)

Recolher Resultados

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

value = await orchestration_result.get(timeout=20)
print(f"***** Final Result *****\n{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

# ConceptExtractorAgent
- Key Features:
- Made of eco-friendly stainless steel
- Keeps drinks cold for 24 hours
...
# WriterAgent
Keep your beverages refreshingly chilled all day long with our eco-friendly stainless steel bottles...
# FormatProofAgent
Keep your beverages refreshingly chilled all day long with our eco-friendly stainless steel bottles...
***** Final Result *****
Keep your beverages refreshingly chilled all day long with our eco-friendly stainless steel bottles...

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 do Chat de Grupo

Partilhar via

Orquestração sequencial

Casos de uso comuns

O que você vai aprender

Defina seus agentes

Opcional: Observe as respostas do agente

Configurar a orquestração sequencial

Iniciar Runtime

Acione a orquestração

Recolher Resultados

Opcional: Pare o tempo de execução

Saída de amostra

Defina seus agentes

Opcional: Observe as respostas do agente

Configurar a orquestração sequencial

Iniciar Runtime

Acione a orquestração

Recolher Resultados

Opcional: Pare o tempo de execução

Saída de amostra

Próximos passos

Recursos adicionais