9.8 KiB

Raw Blame History Unescape Escape

Contributing Tools and Plugins to the Swarms Ecosystem

Introduction

The Swarms ecosystem is a modular, intelligent framework built to support the seamless integration, execution, and orchestration of dynamic tools that perform specific functions. These tools form the foundation for how autonomous agents operate, enabling them to retrieve data, communicate with APIs, conduct computational tasks, and respond intelligently to real-world requests. By contributing to Swarms Tools, developers can empower agents with capabilities that drive practical, enterprise-ready applications.

This guide provides a comprehensive roadmap for contributing tools and plugins to the Swarms Tools repository. It is written for software engineers, data scientists, platform architects, and technologists who seek to develop modular, production-grade functionality within the Swarms agent framework.

Whether your expertise lies in finance, security, machine learning, or developer tooling, this documentation outlines the essential standards, workflows, and integration patterns to make your contributions impactful and interoperable.

Repository Architecture

The Swarms Tools GitHub repository is meticulously organized to maintain structure, scalability, and domain-specific clarity. Each folder within the repository represents a vertical where tools can be contributed and extended over time. These folders include:

finance/: Market analytics, stock price retrievers, blockchain APIs, etc.
social/: Sentiment analysis, engagement tracking, and media scraping utilities.
health/: Interfaces for EHR systems, wearable device APIs, or health informatics.
ai/: Model-serving utilities, embedding services, and prompt engineering functions.
security/: Encryption libraries, risk scoring tools, penetration test interfaces.
devtools/: Build tools, deployment utilities, code quality analyzers.
misc/: General-purpose helpers or utilities that serve multiple domains.

Each tool inside these directories is implemented as a single, self-contained function. These functions are expected to adhere to Swarms-wide standards for clarity, typing, documentation, and API key handling.

Tool Development Specifications

To ensure long-term maintainability and smooth agent-tool integration, each contribution must strictly follow the specifications below.

1. Function Structure and API Usage

import requests
import os

def fetch_data(symbol: str, date_range: str) -> str:
    """
    Fetch financial data for a given symbol and date range.

    Args:
        symbol (str): Ticker symbol of the asset.
        date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y').

    Returns:
        str: A string containing financial data or an error message.
    """
    api_key = os.getenv("FINANCE_API_KEY")
    url = f"https://api.financeprovider.com/data?symbol={symbol}&range={date_range}&apikey={api_key}"
    response = requests.get(url)
    if response.status_code == 200:
        return response.text
    return "Error fetching data."

All logic must be encapsulated inside a single callable function, written using pure Python. Where feasible, network requests should be stateless, side-effect-free, and gracefully handle errors or timeouts.

2. Type Hints and Input Validation

All function parameters must be typed using Python's type hinting system. Use built-in primitives where possible (e.g., str, int, float, bool) and make use of Optional or Union types when dealing with nullable parameters or multiple formats. This aids LLMs and type checkers in understanding expected input ranges.

3. Standardized Output Format

Regardless of internal logic or complexity, tools must return outputs in a consistent string format. This string can contain plain text or a serialized JSON object (as a string), but must not return raw objects, dictionaries, or binary blobs. This standardization ensures all downstream agents can interpret tool output predictably.

4. API Key Management Best Practices

Security and environment isolation are paramount. Never hardcode API keys or sensitive credentials inside source code. Always retrieve them dynamically using the os.getenv("ENV_VAR") approach. If a tool requires credentials, clearly document the required environment variable names in the function docstring.

5. Documentation Guidelines

Every tool must include a detailed docstring that describes:

The function's purpose and operational scope
All parameter types and formats
A clear return type
Usage examples or sample inputs/outputs

Example usage:

result = fetch_data("AAPL", "1m")
print(result)

Well-documented code accelerates adoption and improves LLM interpretability.

Contribution Workflow

To submit a tool, follow the workflow below. This ensures your code integrates cleanly and is easy for maintainers to review.

Step 1: Fork the Repository

Navigate to the Swarms Tools repository and fork it to your personal or organization’s GitHub account.

Step 2: Clone Your Fork

git clone https://github.com/YOUR_USERNAME/swarms-tools.git
cd swarms-tools

Step 3: Create a Feature Branch

git checkout -b feature/add-tool-<tool-name>

Use descriptive branch names. This is especially helpful when collaborating in teams or maintaining audit trails.

Step 4: Build Your Tool

Navigate into the appropriate category folder (e.g., finance/, ai/, etc.) and implement your tool according to the defined schema.

If your tool belongs in a new category, you may create a new folder with a clear, lowercase name.

Step 5: Run Local Tests (if applicable)

Ensure the function executes correctly and does not throw runtime errors. If feasible, test edge cases and verify consistent behavior across platforms.

Step 6: Commit Your Changes

git add .
git commit -m "Add <tool_name> under <folder_name>: API-based tool for X"

Step 7: Push to GitHub

git push origin feature/add-tool-<tool-name>

Step 8: Submit a Pull Request

On GitHub, open a pull request from your fork to the main Swarms Tools repository. Your PR description should:

Summarize the tool’s functionality
Reference any related issues or enhancements
Include usage notes or setup instructions (e.g., required API keys)

Integration with Swarms Agents

Once your tool has been merged into the official repository, it can be utilized by Swarms agents as part of their available capabilities.

The example below illustrates how to embed a newly added tool into an autonomous agent:

from swarms import Agent
from finance.stock_price import get_stock_price

agent = Agent(
    agent_name="Devin",
    system_prompt=(
        "Autonomous agent that can interact with humans and other agents."
        " Be helpful and kind. Use the tools provided to assist the user."
        " Return all code in markdown format."
    ),
    llm=llm,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    interactive=True,
    tools=[get_stock_price, terminal, browser, file_editor, create_file],
    metadata_output_type="json",
    function_calling_format_type="OpenAI",
    function_calling_type="json",
)

agent.run("Create a new file for a plan to take over the world.")

By registering tools in the tools parameter during agent creation, you enable dynamic function calling. The agent interprets natural language input, selects the appropriate tool, and invokes it with valid arguments.

This agent-tool paradigm enables highly flexible and responsive behavior across workflows involving research, automation, financial analysis, social listening, and more.

Tool Maintenance and Long-Term Ownership

Contributors are expected to uphold the quality of their tools post-merge. This includes:

Monitoring for issues or bugs reported by the community
Updating tools when APIs deprecate or modify their behavior
Improving efficiency, error handling, or documentation over time

If a tool becomes outdated or unsupported, maintainers may archive or revise it to maintain ecosystem integrity.

Contributors whose tools receive wide usage or demonstrate excellence in design may be offered elevated privileges or invited to maintain broader tool categories.

Best Practices for Enterprise-Grade Contributions

To ensure your tool is production-ready and enterprise-compliant, observe the following practices:

Run static type checking with mypy
Use formatters like black and linters such as flake8
Avoid unnecessary external dependencies
Keep functions modular and readable
Prefer named parameters over positional arguments for clarity
Handle API errors gracefully and return user-friendly messages
Document limitations or assumptions in the docstring

Optional but encouraged:

Add unit tests to validate function output
Benchmark performance if your tool operates on large datasets

Conclusion

The Swarms ecosystem is built on the principle of extensibility through community-driven contributions. By submitting modular, typed, and well-documented tools to the Swarms Tools repository, you directly enhance the problem-solving power of intelligent agents.

This documentation serves as your blueprint for contributing high-quality, reusable functionality. From idea to implementation to integration, your efforts help shape the future of collaborative, agent-powered software.

We encourage all developers, data scientists, and domain experts to contribute meaningfully. Review existing tools for inspiration, or create something entirely novel.

To begin, fork the Swarms Tools repository and start building impactful, reusable tools that can scale across agents and use cases.

9.8 KiB Raw Blame History Unescape Escape