Exercise 5 — Build a Multi-Agent Workflow

Learning Objectives

By the end of this exercise you will be able to:

1. Create multiple specialist agents, each with different tools
2. Connect agents into a pipeline using WorkflowBuilder edges
3. Consume streaming events from the unified WorkflowEvent (use event.type to discriminate: "data", "executor_completed", "output") to monitor workflow progress
4. Understand event-driven orchestration — why ordering, state, and business-process control matter

Prerequisites

Background

Why Workflows?

In Exercises 1–4 you ran a single agent at a time. Real-world scenarios often require multiple specialists that hand off work in a defined order — this is a workflow.

Workflows give you:

• Business-process control — enforce the order in which agents run
• State passing — each agent receives the output of the previous one
• Observability — streaming events let you track progress in real time
• Reliability — the framework manages agent lifecycle and error propagation

The WorkflowBuilder API

The framework provides WorkflowBuilder to assemble a directed graph of agents:

WorkflowBuilder()           # create a builder
  # In Agent Framework 1.2.2, pass start_executor=a (and output_executors=[...]) to WorkflowBuilder()
  .add_edge(a, b)           # a → b (b runs after a completes)
  .add_edge(b, c)           # b → c
  .build()                  # returns a runnable Workflow

Call workflow.run_stream(prompt) to execute. It yields events as each agent progresses:

The Event Planning Scenario

In this exercise you will build a 5-agent pipeline that plans a corporate event:

Coordinator → Venue → Catering → Budget Analyst → Booking

Each agent specialises in one aspect and passes its work to the next:

Your Task

Open starter.py in this directory. You will see 8 TODO markers inside async def main(). The infrastructure code (imports, env loading, agent factory, helpers) is provided — your job is to wire up the agents, build the workflow, and handle the streaming events.

Step 1 — Create the Coordinator Agent (TODO 1)

Create an agent named "coordinator" with MCPStdioTool for sequential thinking:

• name: "coordinator"
• instructions: Describe the agent as an event coordinator who creates step-by-step plans
• tools: MCPStdioTool(name="sequential-thinking", command="npx", load_prompts=False, args=["-y", "@modelcontextprotocol/server-sequential-thinking"])

Step 2 — Create the Venue Agent (TODO 2)

Create an agent named "venue" with client.get_web_search_tool:

• name: "venue"
• instructions: Describe the agent as a venue specialist
• tools: client.get_web_search_tool(description="Search the web for current information using Bing", tool_properties=bing_props)

Step 3 — Create the Catering Agent (TODO 3)

Create an agent named "catering" with client.get_web_search_tool:

• name: "catering"
• instructions: Describe the agent as a catering coordinator
• tools: Same as venue (Bing search with bing_props)

Step 4 — Create the Budget Analyst Agent (TODO 4)

Create an agent named "budget_analyst" with client.get_code_interpreter_tool:

• name: "budget_analyst"
• instructions: Describe the agent as a budget analyst who uses code for calculations
• tools: client.get_code_interpreter_tool(description="Execute Python code for calculations: budget breakdowns, totals, per-person estimates, and simple what-if analysis.")

Step 5 — Create the Booking Agent (TODO 5)

Create an agent named "booking" with no tools — it synthesises all prior outputs:

• name: "booking"
• instructions: Describe the agent as an event booking specialist who creates a cohesive final plan

Step 6 — Build the Workflow (TODO 6)

Use WorkflowBuilder to chain the five agents:

coordinator → venue → catering → budget_analyst → booking

In Agent Framework 1.2.2, pass start_executor= and output_executors=[...] to WorkflowBuilder(...) constructor, then chain .add_edge() for each connection, then .build().

Step 7 — Run and Handle Streaming Events (TODO 7)

Call workflow.run_stream(prompt) and iterate over events with async for:

• event.type == "data": Print which executor is active (avoid spamming — only print when executor_id changes)
• event.type == "executor_completed": Save event.data into the completed dict keyed by event.executor_id
• event.type == "output": Save event.data as the final_output

Step 8 — Print Results (TODO 8)

Iterate over the chain list and print each completed executor’s result using _print_result_item(). Fall back to final_output if no per-executor completions were captured.

Hints

Work through the hints progressively — try on your own first!

Validate Your Work

1. Run the check script (offline — no Azure needed)

bash workshop/exercises/ex5_workflow/check.sh

This verifies syntax, required code patterns (WorkflowBuilder, edges, event handling), and that all TODOs are resolved.

2. Run against Azure

python3 -u workshop/exercises/ex5_workflow/starter.py

Expected behaviour:

• The script connects to your Foundry project and creates 5 agents.
• You see executor progress lines like -> coordinator, -> venue, etc.
• Each agent runs in sequence — the full workflow takes 2–5 minutes depending on model speed.
• After completion, you see per-executor results (venue recommendations, catering plans, budget breakdown, final event plan).
• If OpenTelemetry is available, [AGENT] and [TOOL] span lines appear.

Note: This exercise takes significantly longer than previous ones because 5 agents run sequentially. Be patient — the streaming events let you see progress in real time.

Bonus Challenges

1. Add a 6th agent — e.g., a “transportation” specialist that plans logistics between the venue and attendee locations. Insert it between venue and catering in the edge chain.
2. Change the edge order — What happens if you swap venue and catering? Does the output quality change?
3. Add error handling per executor — Wrap the event loop in more granular error handling. What if one agent fails — can you still show partial results?
4. Experiment with max_iterations — Pass max_iterations=10 to WorkflowBuilder() and observe how it affects workflow behaviour.

Troubleshooting

Solution Reference

See the complete working solution at: src/demo5_workflow_edges.py