Swarms Marketplace

The Swarms Marketplace is a platform for discovering and sharing production-ready prompts, agent configurations, and tools. Load prompts in a single line of code or publish your own creations to the community.

What is the Swarms Marketplace?

The Swarms Marketplace provides:

One-Line Prompt Loading: Load prompts instantly using a UUID
Community Sharing: Discover prompts created by other developers
Monetization: Publish paid prompts and earn from your expertise
Version Control: Track and manage prompt versions
Rich Metadata: Comprehensive descriptions, use cases, and tags
Direct Integration: Seamless integration with Swarms agents

Quick Start

Loading a Marketplace Prompt

Load a prompt from the marketplace in one line:

from swarms import Agent

# Create agent with marketplace prompt
agent = Agent(
    agent_name="Marketplace-Agent",
    model_name="claude-sonnet-4-6",
    marketplace_prompt_id="550e8400-e29b-41d4-a716-446655440000",
    max_loops=1,
)

# The marketplace prompt is appended to the system prompt
result = agent.run("Execute the task")

When you provide a marketplace_prompt_id, the agent fetches the prompt from the marketplace at construction and appends it to its system_prompt. If agent_name or agent_description were left at their defaults, they are filled in from the marketplace prompt. If no prompt with that ID exists, construction raises ValueError.

Fetching Prompts Programmatically

Fetch by Prompt ID

Fetch a prompt using its unique UUID:

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

# Fetch prompt details
name, description, prompt = AgentMarketplaceHandler.fetch(
    prompt_id="550e8400-e29b-41d4-a716-446655440000",
)

print(f"Prompt Name: {name}")
print(f"Description: {description}")
print(f"Prompt Content: {prompt}")

Fetch by Prompt Name

Fetch a prompt using its name:

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

# Fetch by name (automatically URL-encoded)
name, description, prompt = AgentMarketplaceHandler.fetch(
    name="financial-analysis-agent",
)

print(f"Loaded: {name}")

Get Full Response

Retrieve the complete prompt data:

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

# Get full JSON response
response = AgentMarketplaceHandler.fetch(
    prompt_id="550e8400-e29b-41d4-a716-446655440000",
    return_params_on=False,
)

print(response)
# {
#     "id": "550e8400-e29b-41d4-a716-446655440000",
#     "name": "Financial Analyst",
#     "description": "Expert financial analysis agent",
#     "prompt": "You are a financial analyst...",
#     "use_cases": [...],
#     "tags": "finance,analysis,trading",
#     "created_at": "2024-01-15T10:30:00Z",
#     "updated_at": "2024-01-15T10:30:00Z"
# }

Publishing to the Marketplace

Publishing a Prompt

Share your prompts with the community:

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

# Define use cases
use_cases = [
    {
        "title": "Financial Report Analysis",
        "description": "Analyze quarterly financial reports and extract key metrics"
    },
    {
        "title": "Investment Research",
        "description": "Research investment opportunities and provide recommendations"
    },
    {
        "title": "Risk Assessment",
        "description": "Evaluate financial risks in portfolio holdings"
    },
]

# Add prompt to marketplace
response = AgentMarketplaceHandler.add_prompt(
    name="financial-analyst-pro",
    prompt="""You are an expert financial analyst with deep expertise in:
    - Financial statement analysis
    - Investment research and valuation
    - Risk assessment and portfolio management
    - Market trend analysis
    - Regulatory compliance
    
    Provide detailed, data-driven analysis with clear reasoning.
    Always cite sources and explain your methodology.
    """,
    description="Professional-grade financial analysis agent for investment research and risk assessment",
    use_cases=use_cases,
    tags="finance,investing,analysis,research,risk-management",
    is_free=True,
    category="finance",
)

print(f"Prompt published: {response}")

Publishing from an Agent

Automatically publish an agent’s configuration:

from swarms import Agent

# Create agent with auto-publish enabled
agent = Agent(
    agent_name="Medical-Diagnosis-Agent",
    model_name="claude-sonnet-4-6",
    system_prompt="""You are an expert medical diagnostician specializing in:
    - Differential diagnosis
    - Medical imaging interpretation
    - Treatment planning
    - Patient case analysis
    
    Provide evidence-based recommendations following medical best practices.
    """,
    agent_description="Expert medical diagnosis and treatment planning agent",
    use_cases=[
        {
            "title": "Differential Diagnosis",
            "description": "Analyze symptoms to generate differential diagnoses"
        },
        {
            "title": "Medical Imaging",
            "description": "Interpret X-rays, CT scans, and MRI results"
        },
    ],
    tags=["medical", "healthcare", "diagnosis", "treatment"],
    capabilities=["diagnosis", "medical-imaging"],
    publish_to_marketplace=True,  # Auto-publish on initialization
)

# Agent is automatically published to marketplace

Make sure to set the SWARMS_API_KEY environment variable before publishing. Get your API key at swarms.world/platform/api-keys

When publishing via publish_to_marketplace=True, use the Agent’s real constructor parameters: agent_description (not description) and tags as a List[str]. There is currently no category parameter on Agent — auto-published agents are always filed under the "research" category server-side, regardless of the agent’s actual domain. tags and capabilities are merged into a single comma-separated string when publishing; either may be set on its own, or neither. use_cases is required: publishing without it raises AgentInitializationError. The prompt that gets published is short_memory.get_str(), the agent’s conversation history as one string, not the raw system_prompt you passed in. To control the category or publish exactly the prompt text you wrote, call AgentMarketplaceHandler.add_prompt directly instead.

API Configuration

Setting Up Your API Key

# Set environment variable
export SWARMS_API_KEY="your-api-key-here"

# Or add to .env file
echo "SWARMS_API_KEY=your-api-key-here" >> .env

API Key Validation

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

try:
    api_key = AgentMarketplaceHandler.check_api_key()
    print(f"API key configured (length: {len(api_key)})")
except ValueError as e:
    print(f"API key not set: {e}")

Advanced Usage

Custom Timeout Configuration

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

# Fetch with custom timeout
name, description, prompt = AgentMarketplaceHandler.fetch(
    prompt_id="550e8400-e29b-41d4-a716-446655440000",
    timeout=60.0,  # 60 second timeout
)

Error Handling

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)
import httpx

try:
    result = AgentMarketplaceHandler.fetch(
        name="non-existent-prompt",
    )
    
    if result is None:
        print("Prompt not found")
    else:
        name, description, prompt = result
        print(f"Loaded: {name}")
        
except httpx.HTTPStatusError as e:
    print(f"HTTP error: {e}")
except Exception as e:
    print(f"Error: {e}")

Publishing Paid Prompts

Monetize your expertise with paid prompts:

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

response = AgentMarketplaceHandler.add_prompt(
    name="premium-trading-agent",
    prompt="""Advanced trading strategy agent...""",
    description="Premium algorithmic trading agent with proprietary strategies",
    use_cases=[
        {
            "title": "Algorithmic Trading",
            "description": "Execute complex trading strategies"
        },
    ],
    tags="trading,finance,algorithms,premium",
    is_free=False,
    price_usd=49.99,  # Price in USD
    category="finance",
)

Real-World Examples

Example 1: Quantitative Trading Agent

Load a sophisticated trading agent from the marketplace:

from swarms import Agent

# Real marketplace prompt for quantitative trading
trading_agent = Agent(
    agent_name="Quant-Trader",
    model_name="claude-sonnet-4-6",
    marketplace_prompt_id="6d165e47-1827-4abe-9a84-b25005d8e3b4",
    max_loops=1,
    verbose=True,
)

result = trading_agent.run(
    "Analyze the current market conditions for tech stocks and suggest a trading strategy"
)

print(result)

Example 2: Medical AI Assistant

from swarms import Agent

# Medical AI agent from marketplace
medical_agent = Agent(
    agent_name="Medical-Assistant",
    model_name="claude-sonnet-4-6",
    marketplace_prompt_id="75fc0d28-b0d0-4372-bc04-824aa388b7d2",
    max_loops=1,
)

result = medical_agent.run(
    "Provide a differential diagnosis for a patient with fever and chest pain"
)

Example 3: Publishing a Research Agent

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

research_prompt = """
You are an expert research assistant specializing in:
- Academic paper analysis
- Literature review synthesis
- Research methodology design
- Data interpretation
- Citation management

Provide comprehensive, well-cited research support.
Always verify sources and maintain academic integrity.
"""

use_cases = [
    {
        "title": "Literature Review",
        "description": "Synthesize findings from multiple research papers"
    },
    {
        "title": "Research Design",
        "description": "Design robust research methodologies"
    },
    {
        "title": "Data Analysis",
        "description": "Interpret research data and statistics"
    },
]

response = AgentMarketplaceHandler.add_prompt(
    name="academic-research-assistant",
    prompt=research_prompt,
    description="Comprehensive research assistant for academic and scientific work",
    use_cases=use_cases,
    tags="research,academic,science,literature-review,methodology",
    is_free=True,
    category="research",
)

print(f"Research agent published: {response}")

Marketplace Categories

Organize your prompts by category. The SDK only defines the default, research, and sends whatever string you pass; the accepted set is decided by the marketplace server, so treat this list as examples:

research - Research and analysis
content - Content creation and writing
coding - Software development and programming
finance - Financial analysis and trading
healthcare - Medical and health applications
marketing - Marketing and advertising
education - Educational and training
legal - Legal analysis and documentation
customer-service - Customer support
data-science - Data analysis and ML

Best Practices

Clear Descriptions

Write comprehensive descriptions explaining what your prompt does

Detailed Use Cases

Provide specific use cases with clear titles and descriptions

Relevant Tags

Use descriptive tags to make your prompt discoverable

Test Thoroughly

Test prompts extensively before publishing to ensure quality

Troubleshooting

API Key Issues

# Check if API key is set
import os

api_key = os.getenv("SWARMS_API_KEY")
if not api_key:
    print("Set your API key: export SWARMS_API_KEY='your-key'")
    print("Get your key at: https://swarms.world/platform/api-keys")

Prompt Not Found

from swarms.agents.agent_marketplace_handler import (
    AgentMarketplaceHandler
)

result = AgentMarketplaceHandler.fetch(
    prompt_id="invalid-id",
)

if result is None:
    print("Prompt not found. Check the prompt ID or name.")
else:
    print("Prompt loaded successfully")

Authentication Errors

try:
    AgentMarketplaceHandler.add_prompt(
        name="test-prompt",
        prompt="Test",
        description="Test",
        use_cases=[{"title": "Test", "description": "Test"}],
    )
except Exception as e:
    if "401" in str(e) or "authentication" in str(e).lower():
        print("Authentication failed. Check your API key at:")
        print("https://swarms.world/platform/api-keys")
    else:
        print(f"Error: {e}")

API Reference

AgentMarketplaceHandler.fetch

AgentMarketplaceHandler.fetch(
    prompt_id: Optional[str] = None,
    name: Optional[str] = None,
    timeout: float = 30.0,
    return_params_on: bool = True,
) -> Optional[Union[Dict, Tuple[str, str, str]]]

Parameters:

prompt_id: UUID of the prompt to fetch. Takes precedence over name
name: Name of the prompt (alternative to prompt_id). One of the two is required, or ValueError is raised
timeout: Request timeout in seconds
return_params_on: If True, returns (name, description, prompt) tuple; if False, returns full dict. Returns None when the prompt does not exist (404)

AgentMarketplaceHandler.add_prompt

AgentMarketplaceHandler.add_prompt(
    name: str,
    prompt: str,
    description: str,
    use_cases: List[Dict[str, str]],
    tags: str = None,
    is_free: bool = True,
    price_usd: float = 0.0,
    category: str = "research",
    timeout: float = 30.0,
) -> Dict[str, Any]

Parameters:

name: Unique name for the prompt
prompt: The prompt content/template
description: Description of what the prompt does
use_cases: List of dicts with ‘title’ and ‘description’ keys
tags: Comma-separated tags
is_free: Whether the prompt is free or paid
price_usd: Price in USD (ignored when is_free is True)
category: Category for organization (defaults to "research")
timeout: Request timeout in seconds

Next Steps

Browse Marketplace

Explore available prompts on the marketplace

Get API Key

Get your API key to publish prompts

Model Providers

Configure LLM providers for your agents

Tools

Add custom tools to enhance agents

​What is the Swarms Marketplace?

​Quick Start

​Loading a Marketplace Prompt

​Fetching Prompts Programmatically

​Fetch by Prompt ID

​Fetch by Prompt Name

​Get Full Response

​Publishing to the Marketplace

​Publishing a Prompt

​Publishing from an Agent

​API Configuration

​Setting Up Your API Key

​API Key Validation

​Advanced Usage

​Custom Timeout Configuration

​Error Handling

​Publishing Paid Prompts

​Real-World Examples

​Example 1: Quantitative Trading Agent

​Example 2: Medical AI Assistant

​Example 3: Publishing a Research Agent

​Marketplace Categories

​Best Practices

Clear Descriptions

Detailed Use Cases

Relevant Tags

Test Thoroughly

​Troubleshooting

​API Key Issues

​Prompt Not Found

​Authentication Errors

​API Reference

​AgentMarketplaceHandler.fetch

​AgentMarketplaceHandler.add_prompt

​Next Steps

Browse Marketplace

Get API Key

Model Providers

Tools

What is the Swarms Marketplace?

Quick Start

Loading a Marketplace Prompt

Fetching Prompts Programmatically

Fetch by Prompt ID

Fetch by Prompt Name

Get Full Response

Publishing to the Marketplace

Publishing a Prompt

Publishing from an Agent

API Configuration

Setting Up Your API Key

API Key Validation

Advanced Usage

Custom Timeout Configuration

Error Handling

Publishing Paid Prompts

Real-World Examples

Example 1: Quantitative Trading Agent

Example 2: Medical AI Assistant

Example 3: Publishing a Research Agent

Marketplace Categories

Best Practices

Troubleshooting

API Key Issues

Prompt Not Found

Authentication Errors

API Reference

AgentMarketplaceHandler.fetch

AgentMarketplaceHandler.add_prompt

Next Steps