{
"cells": [
{
"cell_type": "markdown",
"id": "795c70a9",
"metadata": {},
"source": [
"# β‘ Concurrent Agent Workflows with GitHub Models (Python)\n",
"\n",
"## π Advanced Parallel Processing Tutorial\n",
"\n",
"This notebook demonstrates **concurrent workflow patterns** using the Microsoft Agent Framework. You'll learn how to build high-performance, parallel processing workflows where multiple AI agents execute simultaneously, dramatically improving throughput and enabling sophisticated multi-threaded business processes.\n",
"\n",
"## π― Learning Objectives\n",
"\n",
"### π **Concurrent Processing Fundamentals**\n",
"- **Parallel Agent Execution**: Run multiple agents simultaneously for maximum efficiency\n",
"- **Workflow Orchestration**: Coordinate concurrent operations while maintaining data consistency\n",
"- **Performance Optimization**: Achieve significant speedup through parallel processing\n",
"- **Resource Management**: Efficiently utilize AI model resources across concurrent operations\n",
"\n",
"### ποΈ **Advanced Concurrency Patterns**\n",
"- **Fork-Join Processing**: Split work across multiple agents and merge results\n",
"- **Pipeline Parallelism**: Overlapping execution stages for continuous throughput\n",
"- **Load Balancing**: Distribute work evenly across available agent resources\n",
"- **Synchronization Points**: Coordinate concurrent agents at critical workflow stages\n",
"\n",
"### π’ **Enterprise Concurrent Applications**\n",
"- **High-Volume Document Processing**: Process multiple documents simultaneously\n",
"- **Real-Time Content Analysis**: Concurrent analysis of incoming data streams\n",
"- **Batch Processing Optimization**: Maximize throughput for large-scale operations\n",
"- **Multi-Modal Analysis**: Parallel processing of different content types (text, images, data)\n",
"\n",
"## βοΈ Prerequisites & Setup\n",
"\n",
"### π¦ **Required Dependencies**\n",
"\n",
"Install Agent Framework with concurrent workflow capabilities:\n",
"\n",
"```bash\n",
"pip install agent-framework-core -U\n",
"```\n",
"\n",
"### π **GitHub Models Configuration**\n",
"\n",
"**Environment Setup (.env file):**\n",
"```env\n",
"GITHUB_TOKEN=your_github_personal_access_token\n",
"GITHUB_ENDPOINT=https://models.inference.ai.azure.com\n",
"GITHUB_MODEL_ID=gpt-4o-mini\n",
"```\n",
"\n",
"**Concurrent Processing Considerations:**\n",
"- **Rate Limits**: Monitor GitHub Models API rate limits for concurrent requests\n",
"- **Resource Usage**: Consider memory and CPU usage with multiple concurrent agents\n",
"- **Error Handling**: Implement robust error recovery for parallel operations\n",
"\n",
"### ποΈ **Concurrent Workflow Architecture**\n",
"\n",
"```mermaid\n",
"graph TD\n",
" A[Workflow Start] --> B[Concurrent Execution]\n",
" B --> C[Agent Pool 1]\n",
" B --> D[Agent Pool 2]\n",
" B --> E[Agent Pool 3]\n",
" C --> F[Result Aggregation]\n",
" D --> F\n",
" E --> F\n",
" F --> G[Final Output]\n",
" \n",
" H[GitHub Models API] --> C\n",
" H --> D\n",
" H --> E\n",
"```\n",
"\n",
"**Key Benefits:**\n",
"- **β‘ Performance**: Significant speedup through parallel execution\n",
"- **π Scalability**: Handle increased workloads without proportional time increase\n",
"- **π Efficiency**: Better utilization of available computational resources\n",
"- **π― Throughput**: Process more work in the same amount of time\n",
"\n",
"## π¨ **Concurrent Workflow Design Patterns**\n",
"\n",
"### π **Research & Analysis Pipeline**\n",
"```\n",
"Research Task β Parallel Research Agents β Content Synthesis β Quality Review\n",
"```\n",
"\n",
"### π **Data Processing Workflow**\n",
"```\n",
"Input Data β Concurrent Processing Agents β Result Aggregation β Final Report\n",
"```\n",
"\n",
"### π **Content Creation Pipeline**\n",
"```\n",
"Content Brief β Parallel Content Generators β Review & Merge β Final Content\n",
"```\n",
"\n",
"### π **Multi-Stage Processing**\n",
"```\n",
"Input β Stage 1 (Concurrent) β Stage 2 (Concurrent) β Stage 3 (Sequential) β Output\n",
"```\n",
"\n",
"## π’ **Enterprise Performance Benefits**\n",
"\n",
"### β‘ **Throughput Optimization**\n",
"- **Parallel Execution**: Multiple agents working simultaneously\n",
"- **Resource Utilization**: Maximum efficiency of available AI model capacity\n",
"- **Time Reduction**: Significant decrease in total processing time\n",
"- **Scalable Architecture**: Easily add more concurrent agents as needed\n",
"\n",
"### π‘οΈ **Reliability & Resilience**\n",
"- **Fault Tolerance**: Individual agent failures don't stop the entire workflow\n",
"- **Error Isolation**: Problems in one concurrent branch don't affect others\n",
"- **Graceful Degradation**: System continues operating even with reduced agent capacity\n",
"- **Recovery Mechanisms**: Automatic retry and error handling for failed operations\n",
"\n",
"### π **Monitoring & Observability**\n",
"- **Concurrent Execution Tracking**: Monitor progress of all parallel operations\n",
"- **Performance Metrics**: Measure speedup and efficiency gains\n",
"- **Resource Usage Analytics**: Optimize concurrent agent allocation\n",
"- **Bottleneck Identification**: Find and resolve performance constraints\n",
"\n",
"Let's build high-performance concurrent AI workflows! π"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "bd0b077f",
"metadata": {},
"outputs": [],
"source": [
"####### Linux / MacOS Setup Instructions #######\n",
"\n",
"####### Linux Instructions #######\n",
"# ! sudo apt update \n",
"# ! sudo apt install graphviz -y\n",
"\n",
"####### macOS Instructions #######\n",
"# ! brew install graphviz"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "81f035d2",
"metadata": {},
"outputs": [],
"source": [
"# ! pip install -r ../../../Installation/requirements.txt -U\n",
"# "
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "c171c539",
"metadata": {},
"outputs": [],
"source": [
"import os\n",
"from typing import Any\n",
"\n",
"from agent_framework import Message, WorkflowViz\n",
"from agent_framework.orchestrations import ConcurrentBuilder\n",
"from agent_framework.openai import OpenAIChatCompletionClient"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "6ce4663e",
"metadata": {},
"outputs": [],
"source": [
"chat_client = OpenAIChatCompletionClient(base_url=os.environ.get(\"GITHUB_ENDPOINT\"), api_key=os.environ.get(\"GITHUB_TOKEN\"), model=os.environ.get(\"GITHUB_MODEL_ID\") )"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "ae0b1744",
"metadata": {},
"outputs": [],
"source": [
"ResearcherAgentName = \"Researcher-Agent\"\n",
"ResearcherAgentInstructions = \"You are my travel researcher, working with me to analyze the destination, list relevant attractions, and make detailed plans for each attraction.\""
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "339ca225",
"metadata": {},
"outputs": [],
"source": [
"PlanAgentName = \"Plan-Agent\"\n",
"PlanAgentInstructions = \"You are my travel planner, working with me to create a detailed travel plan based on the researcher's findings.\""
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "36381824",
"metadata": {},
"outputs": [],
"source": [
"research_agent = chat_client.as_agent(\n",
" instructions=(\n",
" ResearcherAgentInstructions\n",
" ),\n",
" name=ResearcherAgentName,\n",
" )\n",
"\n",
"plan_agent = chat_client.as_agent(\n",
" instructions=(\n",
" PlanAgentInstructions\n",
" ),\n",
" name=PlanAgentName,\n",
" )"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "cc9f8593",
"metadata": {},
"outputs": [],
"source": [
"workflow = ConcurrentBuilder(participants=[research_agent, plan_agent]).build()"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "5c7ede3e",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Generating workflow visualization...\n",
"Mermaid string: \n",
"=======\n",
"flowchart TD\n",
" dispatcher[\"dispatcher (Start)\"];\n",
" Researcher_Agent[\"Researcher-Agent\"];\n",
" Plan_Agent[\"Plan-Agent\"];\n",
" aggregator[\"aggregator\"];\n",
" fan_in__aggregator__69d73de8((fan-in))\n",
" Plan_Agent --> fan_in__aggregator__69d73de8;\n",
" Researcher_Agent --> fan_in__aggregator__69d73de8;\n",
" fan_in__aggregator__69d73de8 --> aggregator;\n",
" dispatcher --> Researcher_Agent;\n",
" dispatcher --> Plan_Agent;\n",
"=======\n",
"DiGraph string: \n",
"=======\n",
"digraph Workflow {\n",
" rankdir=TD;\n",
" node [shape=box, style=filled, fillcolor=lightblue];\n",
" edge [color=black, arrowhead=vee];\n",
"\n",
" \"dispatcher\" [fillcolor=lightgreen, label=\"dispatcher\\n(Start)\"];\n",
" \"Researcher-Agent\" [label=\"Researcher-Agent\"];\n",
" \"Plan-Agent\" [label=\"Plan-Agent\"];\n",
" \"aggregator\" [label=\"aggregator\"];\n",
"\n",
" \"fan_in::aggregator::69d73de8\" [shape=ellipse, fillcolor=lightgoldenrod, label=\"fan-in\"];\n",
" \"Plan-Agent\" -> \"fan_in::aggregator::69d73de8\";\n",
" \"Researcher-Agent\" -> \"fan_in::aggregator::69d73de8\";\n",
" \"fan_in::aggregator::69d73de8\" -> \"aggregator\";\n",
" \"dispatcher\" -> \"Researcher-Agent\";\n",
" \"dispatcher\" -> \"Plan-Agent\";\n",
"}\n",
"=======\n",
"SVG file saved to: /var/folders/h1/d_gywhr90l1g98mqlt6wwrkh0000gn/T/tmpggoa6kkp.svg\n"
]
}
],
"source": [
"print(\"Generating workflow visualization...\")\n",
"viz = WorkflowViz(workflow)\n",
"# Print out the mermaid string.\n",
"print(\"Mermaid string: \\n=======\")\n",
"print(viz.to_mermaid())\n",
"print(\"=======\")\n",
"# Print out the DiGraph string.\n",
"print(\"DiGraph string: \\n=======\")\n",
"print(viz.to_digraph())\n",
"print(\"=======\")\n",
"svg_file = viz.export(format=\"svg\")\n",
"print(f\"SVG file saved to: {svg_file}\")"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "c329766a",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Attempting to display SVG file at: /var/folders/h1/d_gywhr90l1g98mqlt6wwrkh0000gn/T/tmpggoa6kkp.svg\n"
]
},
{
"data": {
"image/svg+xml": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from IPython.display import SVG, display, HTML\n",
"import os\n",
"\n",
"print(f\"Attempting to display SVG file at: {svg_file}\")\n",
"\n",
"if svg_file and os.path.exists(svg_file):\n",
" try:\n",
" # Preferred: direct SVG rendering\n",
" display(SVG(filename=svg_file))\n",
" except Exception as e:\n",
" print(f\"β οΈ Direct SVG render failed: {e}. Falling back to raw HTML.\")\n",
" try:\n",
" with open(svg_file, \"r\", encoding=\"utf-8\") as f:\n",
" svg_text = f.read()\n",
" display(HTML(svg_text))\n",
" except Exception as inner:\n",
" print(f\"β Fallback HTML render also failed: {inner}\")\n",
"else:\n",
" print(\"β SVG file not found. Ensure viz.export(format='svg') ran successfully.\")"
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "ccf93181",
"metadata": {},
"outputs": [],
"source": [
"events = await workflow.run(\"Plan a trip to Seattle in December\")\n",
"outputs = events.get_outputs()"
]
},
{
"cell_type": "code",
"execution_count": 12,
"id": "3b71d9c7",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"===== Final Aggregated Conversation (messages) =====\n",
"------------------------------------------------------------\n",
"\n",
"01 [user]:\n",
"Plan a trip to Seattle in December\n",
"------------------------------------------------------------\n",
"\n",
"02 [Researcher-Agent]:\n",
"Great choice! Seattle in December offers a mix of holiday festivities, cozy indoor activities, and some beautiful winter scenery. Letβs start by outlining the key aspects of your trip:\n",
"\n",
"### Step 1: Trip Overview\n",
"- **Destination:** Seattle, Washington\n",
"- **Month:** December\n",
"- **Weather:** Typically cold and rainy, average highs around 45Β°F (7Β°C), lows near 35Β°F (2Β°C). Snow is rare but possible.\n",
"- **General vibe:** Cozy, festive holiday atmosphere, indoor attractions popular, occasional outdoor brisk walks.\n",
"\n",
"### Step 2: Top Attractions in Seattle in December\n",
"1. **Pike Place Market** β Iconic marketplace with fresh produce, artisan goods, and holiday decor.\n",
"2. **Seattle Center & Space Needle** β Experience the landmark tower plus winter events at Seattle Center.\n",
"3. **Chihuly Garden and Glass** β Stunning glass art installations, magical with evening lighting.\n",
"4. **Museum of Pop Culture (MoPOP)** β Indoor museum featuring music, sci-fi, and pop culture exhibits.\n",
"5. **Seattle Aquarium** β Family-friendly and warm spot on the waterfront.\n",
"6. **Woodland Park Zoo** β Winter light displays (WildLights event) usually run in December.\n",
"7. **Holiday Festivities** β Such as the Pacific Science Center Winterfest, Gingerbread Village, and festive light displays.\n",
"8. **Coffee Shops** β Seattle is famous for its coffee culture (visit Starbucks Reserve Roastery, local favorites).\n",
"9. **Outdoor Walks** β Waterfront, Kerry Park for skyline views (bring warm clothes).\n",
"10. **Day Trips** β Mt. Rainier National Park for snowy landscapes if weather permits.\n",
"\n",
"### Step 3: Sample Itinerary (4 days)\n",
"\n",
"#### Day 1: Arrival & Pike Place Market\n",
"- Morning: Arrive, check into hotel.\n",
"- Afternoon: Explore Pike Place Market. Watch the fish toss, explore local shops, try fresh seafood or mulled cider.\n",
"- Evening: Dinner nearby, perhaps seafood at Elliottβs Oyster House.\n",
"\n",
"#### Day 2: Space Needle & Seattle Center\n",
"- Morning: Visit Seattle Center, Space Needle observation deck.\n",
"- Early afternoon: Chihuly Garden and Glass (next to Space Needle).\n",
"- Late afternoon: Explore MoPOP.\n",
"- Evening: Attend Winterfest (Pacific Science Center), enjoy holiday lights, ice skating.\n",
"\n",
"#### Day 3: Wildlife & Lights\n",
"- Morning: Seattle Aquarium visit.\n",
"- Afternoon: Woodland Park Zoo for WildLights.\n",
"- Evening: Wander along the waterfront for evening views and possibly local live music.\n",
"\n",
"#### Day 4: Views & Coffee Culture\n",
"- Morning: Visit Kerry Park for skyline photos.\n",
"- Midday: Coffee tour β start at Starbucks Reserve Roastery, then try local cafes like Storyville, Caffe Vita.\n",
"- Afternoon: Optional day trip or museum revisit.\n",
"- Evening: Final dinner, possibly a cozy restaurant with fireplace.\n",
"\n",
"---\n",
"\n",
"Would you like detailed plans, including addresses, opening hours, ticket prices, and dining recommendations for each attraction? Also, please share your interests (e.g., art, food, outdoor activities) and any other preferences!\n",
"------------------------------------------------------------\n",
"\n",
"03 [Plan-Agent]:\n",
"Sure! Hereβs a detailed travel plan for your trip to Seattle in December:\n",
"\n",
"### Trip Overview:\n",
"- **Destination:** Seattle, Washington\n",
"- **Duration:** 5 days / 4 nights (flexible)\n",
"- **Travel Month:** December\n",
"- **Focus:** Winter activities, indoor and outdoor attractions, holiday events\n",
"\n",
"---\n",
"\n",
"### Day 1: Arrival and Downtown Exploration\n",
"- **Morning:**\n",
" - Arrive at Seattle-Tacoma International Airport (SEA)\n",
" - Check-in at your hotel downtown (recommendations: Hotel Theodore, The Westin Seattle, or Kimpton Hotel Monaco)\n",
"- **Afternoon:**\n",
" - Explore Pike Place Market: see the famous fish toss, local crafts, and festive holiday decorations\n",
" - Visit the original Starbucks store\n",
"- **Evening:**\n",
" - Dinner at The Pink Door or a seafood restaurant by the waterfront\n",
" - Stroll along the waterfront and watch the sunset over Elliott Bay\n",
"\n",
"---\n",
"\n",
"### Day 2: Iconic Seattle Landmarks & Museums\n",
"- **Morning:**\n",
" - Visit the Space Needle - enjoy panoramic views, possibly with a cafΓ© breakfast at the rotating SkyCity restaurant (check if open/reopened)\n",
" - Explore Chihuly Garden and Glass, just beside the Space Needle\n",
"- **Afternoon:**\n",
" - Explore the Museum of Pop Culture (MoPOP) for interactive exhibits on music and sci-fi\n",
"- **Evening:**\n",
" - Attend a holiday concert or show (check local listings for Seattle Symphony or Pacific Northwest Ballet performances)\n",
"\n",
"---\n",
"\n",
"### Day 3: Outdoor Adventure & Christmas Festivities\n",
"- **Morning:**\n",
" - Take a quick trip to Discovery Park for a winter forest walk and views of Puget Sound\n",
"- **Afternoon:**\n",
" - Visit Woodland Park Zoo - they usually have a \"WildLights\" holiday event with festive lights and activities\n",
"- **Evening:**\n",
" - Head to the Seattle Center Winterfest (if running) for ice skating, holiday markets, and seasonal treats\n",
"\n",
"---\n",
"\n",
"### Day 4: Day Trip Option or Food & Neighborhoods\n",
"- **Option 1:**\n",
" - Take a day trip to Mount Rainier National Park for beautiful snowy wilderness views and winter hiking, or to Snoqualmie Falls\n",
"- **Option 2:**\n",
" - Explore Seattle neighborhoods like Capitol Hill for coffee shops and boutique shopping\n",
" - Afternoon at the Seattle Aquarium\n",
"- **Dinner:**\n",
" - Enjoy dining at a cozy Capitol Hill restaurant or try a trendy spot in Ballard\n",
"\n",
"---\n",
"\n",
"### Day 5: Shopping and Departure\n",
"- **Morning:**\n",
" - Browse local shops and holiday markets (check for local artisan fairs)\n",
" - Grab brunch at Tilikum Place CafΓ© or CafΓ© Besalu (great pastries)\n",
"- **Afternoon:**\n",
" - Last-minute souvenir shopping or a relaxing visit to a cafΓ© before heading to the airport\n",
"\n",
"---\n",
"\n",
"### Travel Tips for December Seattle:\n",
"- Weather: Typically cold and rainy, average highs around 45Β°F (7Β°C). Pack waterproof clothing and warm layers.\n",
"- Daylight: Short days, sunset around 4:15 PM, plan outdoor activities accordingly.\n",
"- Holiday Events: Check dates for Tree Lighting ceremonies, Winterfest, and local theater shows.\n",
"- Transportation: Use the Link light rail for airport transfers and easy downtown travel. Ride-sharing and buses are also good options.\n",
"\n",
"Would you like me to help with hotel bookings, restaurant reservations, or activity tickets?\n"
]
}
],
"source": [
"if outputs:\n",
" print(\"===== Final Aggregated Conversation (messages) =====\")\n",
" for output in outputs:\n",
" messages: list[Message] | Any = output\n",
" for i, msg in enumerate(messages, start=1):\n",
" name = msg.author_name if msg.author_name else \"user\"\n",
" print(f\"{'-' * 60}\\n\\n{i:02d} [{name}]:\\n{msg.text}\")"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "agentdev",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.12.10"
}
},
"nbformat": 4,
"nbformat_minor": 5
}