Creating Agents

Agents are the fundamental building blocks of the Swarms framework. An agent is an autonomous entity powered by an LLM with tools, memory, and the ability to execute complex tasks.

Basic Agent Creation

The simplest way to create an agent is to instantiate the Agent class with minimal configuration:

from swarms import Agent

# Create a basic agent
agent = Agent(
    agent_name="my-agent",
    model_name="gpt-5.4",
    max_loops=1,
)

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

Agent Initialization Patterns

Pattern 1: Simple Agent

For quick prototyping and simple tasks:

from swarms import Agent

agent = Agent(
    model_name="gpt-5.4",
    max_loops=1,
)

response = agent.run("Generate a report on the financials.")
print(response)

Pattern 2: Named Agent with Description

For better organization and clarity:

agent = Agent(
    agent_name="Financial-Analyst",
    agent_description="An expert financial analyst specializing in market analysis and reporting",
    model_name="claude-sonnet-4-6",
    max_loops=1,
    verbose=True,
)

Pattern 3: Agent with System Prompt

For specialized behavior and domain expertise:

SYSTEM_PROMPT = """
You are a senior financial analyst with expertise in:
- Financial statement analysis
- Market research and competitor analysis
- Investment recommendations
- Risk assessment

Provide detailed, data-driven insights with proper citations.
"""

agent = Agent(
    agent_name="Financial-Expert",
    system_prompt=SYSTEM_PROMPT,
    model_name="claude-sonnet-4-6",
    max_loops=1,
)

Pattern 4: Interactive Agent

For conversational interfaces:

agent = Agent(
    agent_name="Assistant",
    model_name="gpt-5.4",
    max_loops=5,
    interactive=True,  # Enable interactive mode
    user_name="User",
    custom_exit_command="exit",
)

# Agent will prompt for user input in a loop
agent.run("Hello! How can I help you today?")

Pattern 5: Autonomous Agent

For complex, multi-step reasoning:

agent = Agent(
    agent_name="Research-Agent",
    model_name="claude-sonnet-4-6",
    max_loops="auto",  # Autonomous loop mode
    reasoning_prompt_on=True,
    dynamic_temperature_enabled=True,
    verbose=True,
)

response = agent.run(
    "Research the latest trends in AI and create a comprehensive report"
)

See Autonomous mode for the plan, execute and summarize loop and its iteration budgets.

Pattern 6: Agent with Fallback Models

For reliability and cost optimization:

agent = Agent(
    agent_name="Reliable-Agent",
    fallback_models=[
        "claude-sonnet-4-6",  # Primary model
        "gpt-5.4",            # First fallback
        "gpt-5.4-mini",       # Final fallback
    ],
    max_loops=1,
)

# If a model fails after retry_attempts, the agent moves to the next one
response = agent.run("Generate a report")

When fallback_models is set, its first entry is the primary model and model_name is not used.

Pattern 7: Agent from Marketplace Prompt

Load prompts from the Swarms Marketplace:

import os

# Set your Swarms API key
os.environ["SWARMS_API_KEY"] = "your-api-key"

agent = Agent(
    model_name="claude-sonnet-4-6",
    marketplace_prompt_id="550e8400-e29b-41d4-a716-446655440000",  # UUID from marketplace
    max_loops=1,
)

# The marketplace prompt is appended to the agent's system prompt at construction
response = agent.run("Execute the marketplace prompt task")

Pattern 8: Continue an Existing Conversation

Pass earlier turns as messages. On the constructor they seed the conversation and are sent with every run. On run() they apply to that call and are added to the conversation.

from swarms import Agent

history = [
    {"role": "user", "content": "My project is called Helios."},
    {"role": "assistant", "content": "Got it, your project is Helios."},
]

agent = Agent(
    agent_name="Project-Assistant",
    model_name="gpt-5.4",
    max_loops=1,
    messages=history,
)
print(agent.run("What is my project called?"))

# Or per call
other = Agent(agent_name="One-Off", model_name="gpt-5.4", max_loops=1)
print(other.run("What is my project called?", messages=history))

Pattern 9: Several Answers to One Task

run(task, n=3) runs the task three times and returns a list with one output per run. Every run gets the same img, imgs, messages and streaming_callback. The runs share the agent’s conversation, so later runs see the earlier answers. Use output_type="final" so each entry holds only that run’s answer. With max_loops="auto", n is ignored and you get one output.

from swarms import Agent

agent = Agent(
    agent_name="Brainstormer",
    model_name="gpt-5.4",
    max_loops=1,
    output_type="final",
)

ideas = agent.run("Suggest a name for a note-taking app.", n=3)
for idea in ideas:
    print(idea)

Best Practices

1. Always Name Your Agents

# Good
agent = Agent(
    agent_name="Financial-Analyst",
    agent_description="Expert in financial analysis",
    model_name="claude-sonnet-4-6",
)

# Avoid
agent = Agent(model_name="claude-sonnet-4-6")  # Uses default name

2. Use Descriptive System Prompts

# Good - Specific and detailed
system_prompt = """
You are a healthcare data analyst specializing in:
1. Patient data analysis
2. Medical coding (ICD-10, CPT)
3. HIPAA compliance
4. Clinical research metrics

Always maintain patient privacy and follow HIPAA guidelines.
"""

# Avoid - Too vague
system_prompt = "You are a helpful assistant."

3. Set Appropriate Max Loops

# For simple tasks
agent = Agent(max_loops=1)  # Single response

# For multi-step reasoning
agent = Agent(max_loops=5)  # Fixed iterations

# For autonomous tasks
agent = Agent(max_loops="auto")  # Dynamic execution

4. Enable Verbose Mode During Development

agent = Agent(
    model_name="gpt-5.4",
    verbose=True,  # See detailed logs
    print_on=True,  # Print agent responses
)

5. Use Autosave for Important Work

agent = Agent(
    agent_name="Research-Agent",
    model_name="claude-sonnet-4-6",
    autosave=True,  # Automatically save state
    saved_state_path="./agent_states/research_agent.json",
)

6. Set Environment Variables

import os

# Set API keys
os.environ["OPENAI_API_KEY"] = "your-api-key"
os.environ["WORKSPACE_DIR"] = "agent_workspace"

# Create agent
agent = Agent(
    model_name="claude-sonnet-4-6",
    max_loops=1,
)

Common Patterns

temperature defaults to None, which sends no temperature and uses the provider’s default. Set it only when you want to steer randomness, and leave it unset for models that reject a temperature value.

Research Agent

research_agent = Agent(
    agent_name="Researcher",
    system_prompt="You are an expert researcher. Provide detailed, cited information.",
    model_name="claude-sonnet-4-6",
    max_loops=3,
    temperature=0.5,
    verbose=True,
)

Writing Agent

writer_agent = Agent(
    agent_name="Writer",
    system_prompt="You are a professional writer. Create engaging, well-structured content.",
    model_name="claude-sonnet-4-6",
    max_loops=1,
    temperature=0.7,
)

Code Generation Agent

code_agent = Agent(
    agent_name="Code-Generator",
    system_prompt="You are an expert software engineer. Write clean, documented code.",
    model_name="claude-sonnet-4-6",
    max_loops=2,
    temperature=0.3,  # Lower temperature for more deterministic output
)

Next Steps

Agent Configuration

Learn about all configuration parameters

Agent Memory

Configure memory and conversation history

Agent Tools

Add tools to extend agent capabilities

Structured Outputs

Get structured responses from agents

Token Usage

See what each run cost in tokens

Reference

For the complete API reference, see the Agent class documentation. Location in source: swarms/structs/agent.py:130 (class Agent); the constructor (__init__) starts at line 306.

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Creating Agents

Basic Agent Creation

Agent Initialization Patterns

Pattern 1: Simple Agent

Pattern 2: Named Agent with Description

Pattern 3: Agent with System Prompt

Pattern 4: Interactive Agent

Pattern 5: Autonomous Agent

Pattern 6: Agent with Fallback Models

Pattern 7: Agent from Marketplace Prompt

Pattern 8: Continue an Existing Conversation

Pattern 9: Several Answers to One Task

Best Practices

1. Always Name Your Agents

2. Use Descriptive System Prompts

3. Set Appropriate Max Loops

4. Enable Verbose Mode During Development

5. Use Autosave for Important Work

6. Set Environment Variables

Common Patterns

Research Agent

Writing Agent

Code Generation Agent

Next Steps

Agent Configuration

Agent Memory

Agent Tools

Structured Outputs

Token Usage

Reference

​Basic Agent Creation

​Agent Initialization Patterns

​Pattern 1: Simple Agent

​Pattern 2: Named Agent with Description

​Pattern 3: Agent with System Prompt

​Pattern 4: Interactive Agent

​Pattern 5: Autonomous Agent

​Pattern 6: Agent with Fallback Models

​Pattern 7: Agent from Marketplace Prompt

​Pattern 8: Continue an Existing Conversation

​Pattern 9: Several Answers to One Task

​Best Practices

​1. Always Name Your Agents

​2. Use Descriptive System Prompts

​3. Set Appropriate Max Loops

​4. Enable Verbose Mode During Development

​5. Use Autosave for Important Work

​6. Set Environment Variables

​Common Patterns

​Research Agent

​Writing Agent

​Code Generation Agent

​Next Steps

Agent Configuration

Agent Memory

Agent Tools

Structured Outputs

Token Usage

​Reference

Basic Agent Creation

Agent Initialization Patterns

Pattern 1: Simple Agent

Pattern 2: Named Agent with Description

Pattern 3: Agent with System Prompt

Pattern 4: Interactive Agent

Pattern 5: Autonomous Agent

Pattern 6: Agent with Fallback Models

Pattern 7: Agent from Marketplace Prompt

Pattern 8: Continue an Existing Conversation

Pattern 9: Several Answers to One Task

Best Practices

1. Always Name Your Agents

2. Use Descriptive System Prompts

3. Set Appropriate Max Loops

4. Enable Verbose Mode During Development

5. Use Autosave for Important Work

6. Set Environment Variables

Common Patterns

Research Agent

Writing Agent

Code Generation Agent

Next Steps

Reference