AgentMarketplaceHandler

Overview

AgentMarketplaceHandler owns both directions of Swarms Marketplace integration: resolving a prompt UUID into an agent’s system prompt, and publishing an agent’s prompt with its metadata. Every Agent builds one as agent.marketplace. The class also works with no agent at all — fetching and publishing are classmethods, so you can use it as a standalone marketplace client.

from swarms import Agent

# Load a prompt at construction
agent = Agent(marketplace_prompt_id="550e8400-e29b-41d4-a716-446655440000")

# Publish this agent's prompt
agent.handle_publish_to_marketplace()

Import

from swarms.agents.agent_marketplace_handler import AgentMarketplaceHandler

Authentication

Both directions require SWARMS_API_KEY. Get one at swarms.world/platform/api-keys.

export SWARMS_API_KEY="your-key"

check_api_key

@staticmethod
def check_api_key() -> str

Return the key from the environment, raising ValueError when it is unset, empty, or whitespace-only.

The key is read fresh on every call — not cached. A key exported after import, or rotated mid-process, is picked up immediately.

Fetching

fetch

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

GET https://swarms.world/api/get-prompts/<uuid-or-url-encoded-name>

str

The prompt’s UUID. Takes precedence over name when both are given.

str

The prompt’s name, URL-encoded automatically.

float

default:"30.0"

Request timeout in seconds.

bool

default:"true"

True returns a (name, description, prompt) tuple; False returns the full JSON response.

Returns None when the prompt does not exist (404). Raises ValueError when neither argument is given, and httpx.HTTPStatusError for any other error status.

name, description, prompt = AgentMarketplaceHandler.fetch(
    name="code-review-assistant"
)

fetch_prompt

@classmethod
def fetch_prompt(prompt_id: str) -> Tuple[str, str, str]

Like fetch, but requires the prompt to exist — raises ValueError with a helpful message on 404.

load_prompt

def load_prompt(prompt_id: Optional[str] = None) -> None

Fetch a prompt and fold it into the owning agent:

appends the prompt body to agent.system_prompt
sets agent_name / name only if agent.agent_name still equals the default sentinel "swarm-worker-01" (a value comparison, not a flag — an agent deliberately named "swarm-worker-01" is treated as unnamed and gets overwritten)
sets agent_description / description only if it is None

Defaults to the agent’s configured marketplace_prompt_id.

Agent.__init__ gives agent_description a generic default string rather than None, so the description back-fill only fires when you explicitly pass agent_description=None.

Publishing

publish

def publish(category: str = "research") -> Dict[str, Any]

Publish the owning agent’s prompt and metadata. Raises AgentInitializationError when use_cases was not provided.

agent = Agent(
    agent_name="Medical-Analyst",
    agent_description="Analyzes lab results",
    tags=["medical", "diagnostics"],
    capabilities=["lab-analysis"],
    use_cases=[{"title": "Blood panel review", "description": "..."}],
    publish_to_marketplace=True,     # publishes on construction
)

build_tags

def build_tags() -> str

Merge the agent’s tags and capabilities into one comma-separated string. Either list may be empty or unset; only what exists is included, and neither returns "".

add_prompt

@classmethod
def add_prompt(
    name=None, prompt=None, description=None, use_cases=None,
    tags=None, is_free=True, price_usd=0.0,
    category="research", timeout=30.0,
) -> Dict[str, Any]

POST https://swarms.world/api/add-prompt — the low-level publish, usable without an agent.

str

required

Prompt name.

str

required

The prompt text.

str

required

What the prompt does.

List[Dict[str, str]]

required

Dicts with title and description keys. Sent to the API as useCases.

str

Comma-separated tags. None becomes "".

bool

default:"true"

Whether the prompt is free.

float

default:"0.0"

Price, ignored when is_free.

str

default:"research"

Category of the prompt (e.g. "content", "coding"). Despite the default, it is validated like the other required fields — passing category=None explicitly raises ValueError.

float

default:"30.0"

Request timeout in seconds for the underlying HTTP call.

Each missing required field (including category, if explicitly passed as None) raises ValueError naming that field.

Agent integration

`Agent` member	Behavior
`agent.marketplace`	The `AgentMarketplaceHandler` instance
`Agent(marketplace_prompt_id=...)`	Loads the prompt during construction
`Agent(publish_to_marketplace=True, ...)`	Publishes during construction
`agent.handle_publish_to_marketplace()`	Delegates to `publish()`
`agent._load_prompt_from_marketplace()`	Delegates to `load_prompt()`

Standalone use

from swarms.agents.agent_marketplace_handler import AgentMarketplaceHandler

# No agent required
handler = AgentMarketplaceHandler()

AgentMarketplaceHandler.check_api_key()
AgentMarketplaceHandler.fetch(name="code-review-assistant")
AgentMarketplaceHandler.add_prompt(
    name="My Prompt",
    prompt="You are...",
    description="Does a thing",
    use_cases=[{"title": "Example", "description": "..."}],
)

Migration

This class absorbed two modules that have been removed:

Removed	Replacement
`swarms.utils.fetch_prompts_marketplace.fetch_prompts_from_marketplace`	`AgentMarketplaceHandler.fetch`
`swarms.utils.fetch_prompts_marketplace.return_params`	inlined into `fetch`
`swarms.utils.swarms_marketplace_utils.add_prompt_to_marketplace`	`AgentMarketplaceHandler.add_prompt`
`swarms.utils.swarms_marketplace_utils.check_swarms_api_key`	`AgentMarketplaceHandler.check_api_key`

Marketplace

Marketplace integration guide

Agent

The class that owns the handler

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

AgentMarketplaceHandler

Overview

Import

Authentication

check_api_key

Fetching

fetch

fetch_prompt

load_prompt

Publishing

publish

build_tags

add_prompt

Agent integration

Standalone use

Migration

Marketplace

Agent

​Overview

​Import

​Authentication

​check_api_key

​Fetching

​fetch

​fetch_prompt

​load_prompt

​Publishing

​publish

​build_tags

​add_prompt

​Agent integration

​Standalone use

​Migration

​Related

Marketplace

Agent

Overview

Import

Authentication

check_api_key

Fetching

fetch

fetch_prompt

load_prompt

Publishing

publish

build_tags

add_prompt

Agent integration

Standalone use

Migration

Related