Your First Multi-Agent Workflow

Now that you've run a simple workflow, let's build something practical: a document analysis system where multiple AI agents collaborate to analyze and summarize documents.

⚡ Progress Tracker

Total Time: ~15 minutes

• Step 1: Understand the workflow design (2 min)
• Step 2: Create the workflow CSV (5 min)
• Step 3: Prepare sample data (3 min)
• Step 4: Run and test (3 min)
• Step 5: Understand what happened (2 min)

Step 1: Workflow Design

We'll build a Personal Goal Analyzer that:

1. Collects a personal goal from the user
2. Analyzes it using AI to provide insights and action steps
3. Saves the analysis to a CSV file for tracking
4. Thanks the user and shows next steps

This demonstrates:

• ✅ User interaction (input agent)
• ✅ AI processing (LLM agent)
• ✅ Data persistence (CSV writer agent)
• ✅ Error handling (error handler)
• ✅ Data flow between agents

Expected time: 2 minutes

Step 2: Create the Workflow

Create a file called personal_goals.csv:

graph_name,node_name,description,agent_type,next_node,error_node,input_fields,output_field,prompt,context
PersonalGoals,GetGoal,Collect user's personal goal,input,AnalyzeGoal,ErrorHandler,,goal,What personal goal would you like to work on this year? Please be specific:,
PersonalGoals,AnalyzeGoal,AI analysis of the goal,llm,SaveGoal,ErrorHandler,goal,analysis,"You are a personal development coach. Analyze this goal and provide: 1) Why this goal is valuable 2) Three specific action steps 3) One potential challenge and how to overcome it. Goal: {goal}","{""provider"": ""anthropic"", ""model"": ""claude-3-5-sonnet-20241022"", ""temperature"": 0.3}"
PersonalGoals,SaveGoal,Save goal and analysis to CSV,csv_writer,ThankUser,ErrorHandler,"goal,analysis",save_result,personal_goals.csv,"{""format"": ""records"", ""mode"": ""append""}"
PersonalGoals,ThankUser,Thank user and show summary,echo,End,,save_result,final_message,Thank you! Your goal and AI analysis have been saved. You can view your goals database at personal_goals.csv,
PersonalGoals,ErrorHandler,Handle any errors,echo,End,,error,error_message,Sorry there was an error: {error},
PersonalGoals,End,Workflow complete,echo,,,final_message,completion,Workflow completed successfully!,

🔍 Understanding the Workflow

Let's break down what each agent does:

Agent	Type	Purpose	Input	Output
GetGoal	input	Prompts user for their goal	-	goal
AnalyzeGoal	llm	AI analyzes the goal	goal	analysis
SaveGoal	csv_writer	Saves to CSV file	goal, analysis	save_result
ThankUser	echo	Shows completion message	save_result	final_message
ErrorHandler	echo	Handles any errors	error	error_message
End	echo	Workflow completion	final_message	completion

Data Flow: goal → analysis → save_result → final_message → completion

Expected time: 5 minutes

Step 3: Prepare Sample Data

No preparation needed! The CSV writer will automatically create the personal_goals.csv file when it runs.

Expected time: 3 minutes

Step 4: Run the Workflow

agentmap run --csv personal_goals.csv --graph PersonalGoals

Sample interaction:

What personal goal would you like to work on this year? Please be specific:
> Learn to play piano and perform one song for my family

[AI processes the goal...]

Thank you! Your goal and AI analysis have been saved. 
You can view your goals database at data/personal_goals.csv

Workflow completed successfully!

Expected time: 3 minutes

Step 5: Check the Results

Look at the generated file:

cat personal_goals.csv

You should see:

goal,analysis
"Learn to play piano and perform one song for my family","**Why this goal is valuable:**
Learning piano enhances cognitive function, provides emotional outlet, and creates meaningful family moments...

**Three specific action steps:**
1. Start with basic finger exercises and simple scales (15 mins daily)
2. Choose one meaningful song and break it into small sections
3. Schedule weekly practice sessions and monthly family mini-performances

**Potential challenge and solution:**
Challenge: Finding consistent practice time with busy schedule
Solution: Set same time daily (like morning coffee) and use apps for 5-minute micro-sessions when full practice isn't possible"

Expected time: 2 minutes

🎯 What You Just Built

Congratulations! You created a sophisticated multi-agent system that:

✅ Handles user interaction - Collects input with validation
✅ Uses AI reasoning - Leverages Claude for smart analysis
✅ Persists data - Saves results to structured CSV
✅ Provides feedback - Clear user experience
✅ Handles errors - Graceful failure management
✅ Scales easily - Can process multiple goals over time

🔍 Key Concepts Demonstrated

Agent Chaining

GetGoal → AnalyzeGoal → SaveGoal → ThankUser → End

Each agent passes its output to the next agent's input.

Error Handling

error_node,ErrorHandler

Any agent failure routes to the error handler.

Service Integration

agent_type,llm
context,"{""provider"": ""anthropic""}"

Agents automatically get the services they need.

Data Persistence

agent_type,csv_writer
prompt,data/personal_goals.csv

Workflows can save data for later use.

🚀 Next Steps

You now understand multi-agent workflows! Here are your next learning paths:

🎓 Structured Learning
Basic Agents Lesson →
Deep dive into agent types and capabilities

🔧 Custom Agents
Custom Agent Development →
Build your own specialized agents

⚙️ Production Setup
Installation Guide →
Multiple providers, monitoring, deployment

📚 Agent Library
Built-in Agents →
Discover all available agent types

💡 Pro Tips

• Start with templates: Use existing workflows as starting points
• Test incrementally: Build one agent at a time, then connect them
• Use descriptive names: AnalyzeGoal is better than Step2
• Add error handling: Always include error nodes for production workflows
• Think about data flow: Plan what data flows between agents

🛠️ Troubleshooting

Issue: "LLM agent failed"

Check your API key:

echo $ANTHROPIC_API_KEY
# or
echo $OPENAI_API_KEY

Update the context to use your available provider:

context,"{""provider"": ""openai"", ""model"": ""gpt-4""}"

Issue: "CSV writer failed"

Verify file path in your CSV:

prompt,personal_goals.csv

Issue: "Graph not found"

Check the graph_name matches exactly:

agentmap run --csv personal_goals.csv --graph PersonalGoals

All instances of graph_name in your CSV must be identical.

---

Great job! You've mastered the fundamentals of multi-agent workflows. You're ready to build sophisticated AI systems with AgentMap.

Need help? Join the GitHub discussions or check out more examples.