Pattern 1: Prompt Chaining

Learning Objectives

By the end of this tutorial, you will be able to:

• Understand the Prompt Chaining pattern and when to use it
• Create multiple specialized agents using ChatClientAgent
• Build sequential workflows with AgentWorkflowBuilder.BuildSequential()
• Handle streaming output with workflow events
• Implement proper error handling in chained workflows

Prerequisites

Before starting this tutorial, ensure you have:

• .NET 8.0 SDK or later installed
• An Azure OpenAI resource or OpenAI API key
• Azure CLI installed (for authentication)
• Basic familiarity with C# async/await patterns

Pattern Overview

What is Prompt Chaining?

Prompt Chaining is a foundational agentic pattern where multiple LLM calls execute sequentially, with each call’s output becoming the input for the next. Think of it as an assembly line where each station performs a specific task and passes the result forward.

[User Input] → [Agent 1] → [Agent 2] → [Agent 3] → [Final Output]
                   ↓           ↓           ↓
               Research    Outline      Write

Each agent specializes in one task, making the overall system more reliable and maintainable than a single monolithic prompt.

When to Use Prompt Chaining

Use this pattern when you need to:

• Break down complex tasks into simpler, focused steps
• Apply different expertise at each stage
• Create reproducible, auditable processing pipelines
• Maintain quality through specialization

Real-world examples:

Use Case	Pipeline Steps
Content Creation	Research → Outline → Write → Edit
Code Review	Parse → Analyze → Suggest → Report
Customer Support	Classify → Research → Draft → Review
Data Processing	Extract → Transform → Validate → Load

Step-by-Step Implementation

Step 1: Create the Project

First, create a new console project and add the required packages:

dotnet new console -n PromptChaining
cd PromptChaining
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package Microsoft.Agents.AI.Workflows --prerelease
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity

Step 2: Set Up the Azure OpenAI Client

Configure the connection to Azure OpenAI:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.AI;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT not set");
string deployment = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
    ?? "gpt-4o-mini";

IChatClient chatClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
    .GetChatClient(deployment)
    .AsIChatClient();

Step 3: Create Specialized Agents

Each agent has a single responsibility with focused instructions. Here’s how to create the three agents for our content pipeline:

Researcher Agent - Gathers key points about the topic:

using Microsoft.Agents.AI;

ChatClientAgent researcher = new(chatClient, new ChatClientAgentOptions
{
    Name = "Researcher",
    Instructions = """
        You are a research assistant specializing in gathering information.

        When given a topic:
        1. Identify the main concepts and subtopics
        2. List 3-5 key points that should be covered
        3. Note any important facts or examples
        4. Identify the target audience

        Output format: Structured research notes with clear sections.
        """
});

Outliner Agent - Creates a structured outline:

ChatClientAgent outliner = new(chatClient, new ChatClientAgentOptions
{
    Name = "Outliner",
    Instructions = """
        You are a content strategist who creates clear, logical outlines.

        Based on the research notes provided:
        1. Create a hierarchical outline with sections and subsections
        2. Include brief descriptions for each section
        3. Suggest an introduction hook and conclusion

        Output format: Numbered outline with clear hierarchy.
        """
});

Writer Agent - Produces the final content:

ChatClientAgent writer = new(chatClient, new ChatClientAgentOptions
{
    Name = "Writer",
    Instructions = """
        You are a professional content writer.

        Based on the outline provided:
        1. Write polished content following the outline structure
        2. Use clear, engaging language
        3. Include transitions between sections
        4. Add a compelling introduction and conclusion

        Output format: Complete article with headers and paragraphs.
        """
});

Step 4: Build the Sequential Workflow

Chain the agents together using AgentWorkflowBuilder.BuildSequential():

using Microsoft.Agents.AI.Workflows;

// Build the sequential workflow
Workflow pipeline = AgentWorkflowBuilder.BuildSequential(
    researcher,
    outliner,
    writer
);

This single line creates a workflow where:

• The user’s input goes to the Researcher
• The Researcher’s output goes to the Outliner
• The Outliner’s output goes to the Writer
• The Writer produces the final result

Step 5: Execute with Streaming

Run the pipeline with streaming to see each agent’s contribution:

var messages = new List<ChatMessage>
{
    new(ChatRole.User, "Create content about: async programming in C#")
};

StreamingRun run = await InProcessExecution.StreamAsync(pipeline, messages);
await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

await foreach (WorkflowEvent evt in run.WatchStreamAsync())
{
    if (evt is AgentRunUpdateEvent update)
    {
        Console.Write(update.Data);
    }
    else if (evt is WorkflowOutputEvent)
    {
        break; // Pipeline complete
    }
}

Code Walkthrough

Understanding Agent Instructions

The quality of your prompt chain depends heavily on the instructions you give each agent. Key principles:

1. Be specific: Tell the agent exactly what to do and what format to use
2. Define the output: Specify the structure of the expected response
3. Set context: Each agent receives the previous agent’s output as context

The AgentWorkflowBuilder Pattern

AgentWorkflowBuilder.BuildSequential() is a convenience method that:

• Creates a workflow with sequential edges between agents
• Automatically passes output from one agent to the next
• Maintains conversation history across the chain

For more complex routing, you can use WorkflowBuilder directly.

Event-Driven Execution

The streaming execution model uses events:

• AgentRunUpdateEvent: Text being generated by an agent
• WorkflowOutputEvent: Final output from the pipeline

This enables real-time UI updates as content is generated.

Common Pitfalls

1. Instructions Too Vague

Problem: Agent produces inconsistent or unexpected output.

❌ “Process this input”

✅ “Analyze the input, identify 3-5 key themes, and list supporting evidence for each”

2. Token Limits

Problem: Long chains accumulate tokens, hitting context limits.

Solution: For very long pipelines, consider summarizing between steps or using smaller intermediate outputs.

3. Missing Error Handling

Problem: API failures crash the entire pipeline.

Solution: Wrap streaming in try-catch:

try
{
    await foreach (string update in pipeline.GenerateContentStreamingAsync(topic))
    {
        Console.Write(update);
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Pipeline error: {ex.Message}");
}

Try It Yourself

Exercise 1: Add an Editor Agent

Extend the pipeline with a fourth agent that reviews and improves the Writer’s output. The Editor should:

• Check for grammar and clarity
• Ensure consistent tone
• Suggest improvements

Exercise 2: Implement Logging

Add structured logging to track:

• When each agent starts and finishes
• Processing time per agent
• Total pipeline duration

Exercise 3: Add Retry Logic

Implement exponential backoff for transient API failures:

• Retry up to 3 times
• Double the wait time between retries
• Log retry attempts

Summary

You have learned how to:

• Create specialized agents with ChatClientAgent
• Chain agents using AgentWorkflowBuilder.BuildSequential()
• Handle streaming output with workflow events
• Avoid common pitfalls in prompt chains

The Prompt Chaining pattern is the foundation for more complex agentic workflows. Mastering it enables you to break down any complex task into manageable, specialized steps.

Next Steps

Continue your learning with these related patterns:

• Pattern 2: Tool Use - Learn how agents can call external functions and APIs
• Pattern 3: Routing - Implement conditional paths based on input
• Pattern 4: Parallelization - Run multiple agents concurrently

Resources

• Complete code on GitHub
• Microsoft Agent Framework Documentation
• Sequential Workflow Guide

---

This pattern is inspired by concepts from “Agentic Design Patterns” by Antonio Gulli (O’Reilly Media). Implementation and explanations are original content using Microsoft Agent Framework.