Skip to main content

​
Get Started in Minutes

This guide will walk you through creating your first autonomous agent and multi-agent swarm using Swarms. By the end of this tutorial, you’ll have a working agent and understand how to orchestrate multiple agents to work together.
Before you begin, make sure you’ve installed Swarms and configured your environment.

​
Your First Agent

An Agent is the fundamental building block of a swarm—an autonomous entity powered by an LLM + Tools + Memory.
1

Import the Agent class

Start by importing the Agent class from the swarms package:
from swarms import Agent
2

Initialize your agent

Create a new agent with basic configuration:
# Initialize a new agent
agent = Agent(
    model_name="gpt-4o-mini",  # Specify the LLM
    max_loops="auto",          # Set the number of interactions
    interactive=True,          # Enable interactive mode for real-time feedback
)
Key Parameters:
  • model_name: The language model to use (e.g., “gpt-4o-mini”, “claude-sonnet-4-5”)
  • max_loops: Number of reasoning iterations (“auto” for automatic determination)
  • interactive: Enable real-time feedback and conversation
3

Run your agent

Execute a task with your agent:
# Run the agent with a task
response = agent.run(
    "What are the key benefits of using a multi-agent system?"
)
print(response)

from swarms import Agent

# Initialize a new agent
agent = Agent(
    model_name="gpt-4o-mini",  # Specify the LLM
    max_loops="auto",          # Set the number of interactions
    interactive=True,          # Enable interactive mode for real-time feedback
)

# Run the agent with a task
response = agent.run(
    "What are the key benefits of using a multi-agent system?"
)
print(response)

​
Your First Swarm: Multi-Agent Collaboration

A Swarm consists of multiple agents working together. Let’s create a two-agent workflow for researching and writing a blog post.
1

Import required classes

Import both Agent and SequentialWorkflow:
from swarms import Agent, SequentialWorkflow
2

Create specialized agents

Define two agents with specific roles:
# Agent 1: The Researcher
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Your job is to research the provided topic and provide a detailed summary.",
    model_name="gpt-4o-mini",
)

# Agent 2: The Writer
writer = Agent(
    agent_name="Writer",
    system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.",
    model_name="gpt-4o-mini",
)
The system_prompt defines each agent’s role and responsibilities. Be specific about what you want each agent to do.
3

Create a sequential workflow

Connect the agents in a pipeline where the researcher’s output feeds into the writer’s input:
# Create a sequential workflow where the researcher's output feeds into the writer's input
workflow = SequentialWorkflow(agents=[researcher, writer])
4

Run the workflow

Execute the workflow with a task:
# Run the workflow on a task
final_post = workflow.run(
    "The history and future of artificial intelligence"
)
print(final_post)
The workflow will:
  1. Send the task to the Researcher agent
  2. The Researcher analyzes the topic and provides a summary
  3. The Writer receives the research and creates a blog post
  4. The final blog post is returned
from swarms import Agent, SequentialWorkflow

# Agent 1: The Researcher
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Your job is to research the provided topic and provide a detailed summary.",
    model_name="gpt-4o-mini",
)

# Agent 2: The Writer
writer = Agent(
    agent_name="Writer",
    system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.",
    model_name="gpt-4o-mini",
)

# Create a sequential workflow where the researcher's output feeds into the writer's input
workflow = SequentialWorkflow(agents=[researcher, writer])

# Run the workflow on a task
final_post = workflow.run(
    "The history and future of artificial intelligence"
)
print(final_post)

​
Understanding the Workflow

The SequentialWorkflow executes agents in order, creating a pipeline where each agent builds upon the work of the previous one. This is ideal for:
  • Research → Analysis → Writing workflows
  • Data Collection → Processing → Reporting pipelines
  • Planning → Execution → Review processes
  • Any task with clear sequential dependencies
Want to run agents in parallel instead? Check out ConcurrentWorkflow for simultaneous execution.

​
What You Can Do Next

Add Tools to Your Agent

Extend your agent’s capabilities with external tools and APIs

Explore Multi-Agent Architectures

Learn about HierarchicalSwarm, ConcurrentWorkflow, MixtureOfAgents, and more

Use Different Model Providers

Connect to OpenAI, Anthropic, Groq, Cohere, and other LLM providers

Build Production Applications

Deploy agents as distributed services with Agent Orchestration Protocol

​
Common Use Cases

​
Single Agent Examples

# Customer Support Agent
customer_support = Agent(
    agent_name="Customer-Support",
    system_prompt="You are a helpful customer support agent. Respond professionally and empathetically to customer inquiries.",
    model_name="gpt-4o-mini",
    max_loops=1,
)

response = customer_support.run(
    "I haven't received my order yet. What should I do?"
)

​
Multi-Agent Examples

# Financial Analysis Swarm
from swarms import Agent, ConcurrentWorkflow

market_analyst = Agent(
    agent_name="Market-Analyst",
    system_prompt="Analyze market trends and provide insights.",
    model_name="gpt-4o-mini",
)

financial_analyst = Agent(
    agent_name="Financial-Analyst",
    system_prompt="Provide financial analysis and recommendations.",
    model_name="gpt-4o-mini",
)

risk_analyst = Agent(
    agent_name="Risk-Analyst",
    system_prompt="Assess risks and provide risk management strategies.",
    model_name="gpt-4o-mini",
)

# Run all analysts concurrently
concurrent_workflow = ConcurrentWorkflow(
    agents=[market_analyst, financial_analyst, risk_analyst]
)

results = concurrent_workflow.run(
    "Analyze the potential impact of AI technology on the healthcare industry"
)

​
Troubleshooting

Make sure your API keys are properly configured in your .env file. Check the environment setup guide for details.
Verify that you’re using a valid model name. See the Model Providers documentation for supported models.
Consider using max_loops=1 to reduce API calls, or implement retry logic with exponential backoff.

​
Next Steps

Now that you’ve created your first agent and swarm, you’re ready to:
  1. Customize your agents with specific system prompts and configurations
  2. Add tools to extend agent capabilities
  3. Explore different workflows like HierarchicalSwarm and MixtureOfAgents
  4. Build production applications with advanced features
Join our Discord community to get help, share your projects, and connect with other Swarms developers!

Build docs developers (and LLMs) love

Get started for freeTalk to us