docs/swarms/agents/third_party.md

# Swarms Framework: Integrating and Customizing Agent Libraries

Agent-based systems have emerged as a powerful paradigm for solving complex problems and automating tasks. 

The swarms framework offers a flexible and extensible approach to working with various agent libraries, allowing developers to create custom agents and integrate them seamlessly into their projects. 

In this comprehensive guide, we'll explore the swarms framework, discuss agent handling, and demonstrate how to build custom agents using swarms. We'll also cover the integration of popular agent libraries such as Langchain, Griptape, CrewAI, and Autogen.

## Table of Contents

1. [Introduction to the Swarms Framework](#introduction-to-the-swarms-framework)
2. [The Need for Wrappers](#the-need-for-wrappers)
3. [Building Custom Agents with Swarms](#building-custom-agents-with-swarms)
4. [Integrating Third-Party Agent Libraries](#integrating-third-party-agent-libraries)
   - [Griptape Integration](#griptape-integration)
   - [Langchain Integration](#langchain-integration)
   - [CrewAI Integration](#crewai-integration)
   - [Autogen Integration](#autogen-integration)
5. [Advanced Agent Handling Techniques](#advanced-agent-handling-techniques)
6. [Best Practices for Custom Agent Development](#best-practices-for-custom-agent-development)
7. [Future Directions and Challenges](#future-directions-and-challenges)
8. [Conclusion](#conclusion)

## 1. Introduction to the Swarms Framework

The swarms framework is a powerful and flexible system designed to facilitate the creation, management, and coordination of multiple AI agents. It provides a standardized interface for working with various agent types, allowing developers to leverage the strengths of different agent libraries while maintaining a consistent programming model.

At its core, the swarms framework is built around the concept of a parent `Agent` class, which serves as a foundation for creating custom agents and integrating third-party agent libraries. This approach offers several benefits:

1. **Consistency**: By wrapping different agent implementations with a common interface, developers can work with a unified API across various agent types.
2. **Extensibility**: The framework makes it easy to add new agent types or customize existing ones without affecting the overall system architecture.
3. **Interoperability**: Agents from different libraries can communicate and collaborate seamlessly within the swarms ecosystem.
4. **Scalability**: The standardized approach allows for easier scaling of agent-based systems, from simple single-agent applications to complex multi-agent swarms.

## 2. The Need for Wrappers

As the field of AI and agent-based systems continues to grow, numerous libraries and frameworks have emerged, each with its own strengths and specialized features. While this diversity offers developers a wide range of tools to choose from, it also presents challenges in terms of integration and interoperability.

This is where the concept of wrappers becomes crucial. By creating wrappers around different agent libraries, we can:

1. **Unify interfaces**: Standardize the way we interact with agents, regardless of their underlying implementation.
2. **Simplify integration**: Make it easier to incorporate new agent libraries into existing projects.
3. **Enable composition**: Allow for the creation of complex agent systems that leverage the strengths of multiple libraries.
4. **Facilitate maintenance**: Centralize the management of agent-related code and reduce the impact of library-specific changes.

In the context of the swarms framework, wrappers take the form of custom classes that inherit from the parent `Agent` class. These wrapper classes encapsulate the functionality of specific agent libraries while exposing a consistent interface that aligns with the swarms framework.

## 3. Building Custom Agents with Swarms

To illustrate the process of building custom agents using the swarms framework, let's start with a basic example of creating a custom agent class:

```python
from swarms import Agent

class MyCustomAgent(Agent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # Custom initialization logic

    def custom_method(self, *args, **kwargs):
        # Implement custom logic here
        pass

    def run(self, task, *args, **kwargs):
        # Customize the run method
        response = super().run(task, *args, **kwargs)
        # Additional custom logic
        return response
```

This example demonstrates the fundamental structure of a custom agent class within the swarms framework. Let's break down the key components:

1. **Inheritance**: The class inherits from the `Agent` parent class, ensuring it adheres to the swarms framework's interface.

2. **Initialization**: The `__init__` method calls the parent class's initializer and can include additional custom initialization logic.

3. **Custom methods**: You can add any number of custom methods to extend the agent's functionality.

4. **Run method**: The `run` method is a key component of the agent interface. By overriding this method, you can customize how the agent processes tasks while still leveraging the parent class's functionality.

To create more sophisticated custom agents, you can expand on this basic structure by adding features such as:

- **State management**: Implement methods to manage the agent's internal state.
- **Communication protocols**: Define how the agent interacts with other agents in the swarm.
- **Learning capabilities**: Incorporate machine learning models or adaptive behaviors.
- **Specialized task handling**: Create methods for dealing with specific types of tasks or domains.

By leveraging these custom agent classes, developers can create highly specialized and adaptive agents tailored to their specific use cases while still benefiting from the standardized interface provided by the swarms framework.

## 4. Integrating Third-Party Agent Libraries

One of the key strengths of the swarms framework is its ability to integrate with various third-party agent libraries. In this section, we'll explore how to create wrappers for popular agent libraries, including Griptape, Langchain, CrewAI, and Autogen.

### Griptape Integration

Griptape is a powerful library for building AI agents with a focus on composability and tool use. Let's create a wrapper for a Griptape agent:

```python
from typing import List, Optional

from griptape.structures import Agent as GriptapeAgent
from griptape.tools import FileManager, TaskMemoryClient, WebScraper

from swarms import Agent


class GriptapeAgentWrapper(Agent):
    """
    A wrapper class for the GriptapeAgent from the griptape library.
    """

    def __init__(self, name: str, tools: Optional[List] = None, *args, **kwargs):
        """
        Initialize the GriptapeAgentWrapper.

        Parameters:
        - name: The name of the agent.
        - tools: A list of tools to be used by the agent. If not provided, default tools will be used.
        - *args, **kwargs: Additional arguments to be passed to the parent class constructor.
        """
        super().__init__(*args, **kwargs)
        self.name = name
        self.tools = tools or [
            WebScraper(off_prompt=True),
            TaskMemoryClient(off_prompt=True),
            FileManager()
        ]
        self.griptape_agent = GriptapeAgent(
            input=f"I am {name}, an AI assistant. How can I help you?",
            tools=self.tools
        )

    def run(self, task: str, *args, **kwargs) -> str:
        """
        Run a task using the GriptapeAgent.

        Parameters:
        - task: The task to be performed by the agent.

        Returns:
        - The response from the GriptapeAgent as a string.
        """
        response = self.griptape_agent.run(task, *args, **kwargs)
        return str(response)

    def add_tool(self, tool) -> None:
        """
        Add a tool to the agent.

        Parameters:
        - tool: The tool to be added.
        """
        self.tools.append(tool)
        self.griptape_agent = GriptapeAgent(
            input=f"I am {self.name}, an AI assistant. How can I help you?",
            tools=self.tools
        )

# Usage example
griptape_wrapper = GriptapeAgentWrapper("GriptapeAssistant")
result = griptape_wrapper.run("Load https://example.com, summarize it, and store it in a file called example_summary.txt.")
print(result)

```

This wrapper encapsulates the functionality of a Griptape agent while exposing it through the swarms framework's interface. It allows for easy customization of tools and provides a simple way to execute tasks using the Griptape agent.

### Langchain Integration

Langchain is a popular framework for developing applications powered by language models. Here's an example of how we can create a wrapper for a Langchain agent:

```python
from typing import List, Optional

from langchain.agents import AgentExecutor, LLMSingleActionAgent, Tool
from langchain.chains import LLMChain
from langchain_community.llms import OpenAI
from langchain.prompts import StringPromptTemplate
from langchain.tools import DuckDuckGoSearchRun

from swarms import Agent


class LangchainAgentWrapper(Agent):
    """
    Initialize the LangchainAgentWrapper.

    Args:
        name (str): The name of the agent.
        tools (List[Tool]): The list of tools available to the agent.
        llm (Optional[OpenAI], optional): The OpenAI language model to use. Defaults to None.
    """
    def __init__(
        self,
        name: str,
        tools: List[Tool],
        llm: Optional[OpenAI] = None,
        *args,
        **kwargs,
    ):
        super().__init__(*args, **kwargs)
        self.name = name
        self.tools = tools
        self.llm = llm or OpenAI(temperature=0)

        prompt = StringPromptTemplate.from_template(
            "You are {name}, an AI assistant. Answer the following question: {question}"
        )

        llm_chain = LLMChain(llm=self.llm, prompt=prompt)
        tool_names = [tool.name for tool in self.tools]

        self.agent = LLMSingleActionAgent(
            llm_chain=llm_chain,
            output_parser=None,
            stop=["\nObservation:"],
            allowed_tools=tool_names,
        )

        self.agent_executor = AgentExecutor.from_agent_and_tools(
            agent=self.agent, tools=self.tools, verbose=True
        )

    def run(self, task: str, *args, **kwargs):
        """
        Run the agent with the given task.

        Args:
            task (str): The task to be performed by the agent.

        Returns:
            Any: The result of the agent's execution.
        """
        try:
            return self.agent_executor.run(task)
        except Exception as e:
            print(f"An error occurred: {e}")


# Usage example

search_tool = DuckDuckGoSearchRun()
tools = [
    Tool(
        name="Search",
        func=search_tool.run,
        description="Useful for searching the internet",
    )
]

langchain_wrapper = LangchainAgentWrapper("LangchainAssistant", tools)
result = langchain_wrapper.run("What is the capital of France?")
print(result)
```

This wrapper integrates a Langchain agent into the swarms framework, allowing for easy use of Langchain's powerful features such as tool use and multi-step reasoning.

### CrewAI Integration

CrewAI is a library focused on creating and managing teams of AI agents. Let's create a wrapper for a CrewAI agent:

```python
from swarms import Agent
from crewai import Agent as CrewAIAgent
from crewai import Task, Crew, Process

class CrewAIAgentWrapper(Agent):
    def __init__(self, name, role, goal, backstory, tools=None, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name
        self.crewai_agent = CrewAIAgent(
            role=role,
            goal=goal,
            backstory=backstory,
            verbose=True,
            allow_delegation=False,
            tools=tools or []
        )

    def run(self, task, *args, **kwargs):
        crew_task = Task(
            description=task,
            agent=self.crewai_agent
        )
        crew = Crew(
            agents=[self.crewai_agent],
            tasks=[crew_task],
            process=Process.sequential
        )
        result = crew.kickoff()
        return result

# Usage example
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

crewai_wrapper = CrewAIAgentWrapper(
    "ResearchAnalyst",
    role='Senior Research Analyst',
    goal='Uncover cutting-edge developments in AI and data science',
    backstory="""You work at a leading tech think tank.
    Your expertise lies in identifying emerging trends.
    You have a knack for dissecting complex data and presenting actionable insights.""",
    tools=[search_tool]
)

result = crewai_wrapper.run("Analyze the latest trends in quantum computing and summarize the key findings.")
print(result)
```

This wrapper allows us to use CrewAI agents within the swarms framework, leveraging CrewAI's focus on role-based agents and collaborative task execution.

### Autogen Integration

Autogen is a framework for building conversational AI agents. Here's how we can create a wrapper for an Autogen agent:

```python
from swarms import Agent
from autogen import ConversableAgent

class AutogenAgentWrapper(Agent):
    def __init__(self, name, llm_config, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name
        self.autogen_agent = ConversableAgent(
            name=name,
            llm_config=llm_config,
            code_execution_config=False,
            function_map=None,
            human_input_mode="NEVER"
        )

    def run(self, task, *args, **kwargs):
        messages = [{"content": task, "role": "user"}]
        response = self.autogen_agent.generate_reply(messages)
        return response

# Usage example
import os

llm_config = {
    "config_list": [{"model": "gpt-4", "api_key": os.environ.get("OPENAI_API_KEY")}]
}

autogen_wrapper = AutogenAgentWrapper("AutogenAssistant", llm_config)
result = autogen_wrapper.run("Tell me a joke about programming.")
print(result)
```

This wrapper integrates Autogen's ConversableAgent into the swarms framework, allowing for easy use of Autogen's conversational AI capabilities.

By creating these wrappers, we can seamlessly integrate agents from various libraries into the swarms framework, allowing for a unified approach to agent management and task execution.

## 5. Advanced Agent Handling Techniques

As you build more complex systems using the swarms framework and integrated agent libraries, you'll need to employ advanced techniques for agent handling. Here are some strategies to consider:

### 1. Dynamic Agent Creation

Implement a factory pattern to create agents dynamically based on task requirements:

```python
class AgentFactory:
    @staticmethod
    def create_agent(agent_type, *args, **kwargs):
        if agent_type == "griptape":
            return GriptapeAgentWrapper(*args, **kwargs)
        elif agent_type == "langchain":
            return LangchainAgentWrapper(*args, **kwargs)
        elif agent_type == "crewai":
            return CrewAIAgentWrapper(*args, **kwargs)
        elif agent_type == "autogen":
            return AutogenAgentWrapper(*args, **kwargs)
        else:
            raise ValueError(f"Unknown agent type: {agent_type}")

# Usage
agent = AgentFactory.create_agent("griptape", "DynamicGriptapeAgent")
```


### 2. Agent Pooling

Implement an agent pool to manage and reuse agents efficiently:

```python
from queue import Queue

class AgentPool:
    def __init__(self, pool_size=5):
        self.pool = Queue(maxsize=pool_size)
        self.pool_size = pool_size

    def get_agent(self, agent_type, *args, **kwargs):
        if not self.pool.empty():
            return self.pool.get()
        else:
            return AgentFactory.create_agent(agent_type, *args, **kwargs)

    def release_agent(self, agent):
        if self.pool.qsize() < self.pool_size:
            self.pool.put(agent)

# Usage
pool = AgentPool()
agent = pool.get_agent("langchain", "PooledLangchainAgent")
result = agent.run("Perform a task")
pool.release_agent(agent)
```

### 3. Agent Composition

Create composite agents that combine the capabilities of multiple agent types:

```python
class CompositeAgent(Agent):
    def __init__(self, name, agents):
        super().__init__()
        self.name = name
        self.agents = agents

    def run(self, task):
        results = []
        for agent in self.agents:
            results.append(agent.run(task))
        return self.aggregate_results(results)

    def aggregate_results(self, results):
        # Implement your own logic to combine results
        return "\n".join(results)

# Usage
griptape_agent = GriptapeAgentWrapper("GriptapeComponent")
langchain_agent = LangchainAgentWrapper("LangchainComponent", [])
composite_agent = CompositeAgent("CompositeAssistant", [griptape_agent, langchain_agent])
result = composite_agent.run("Analyze the pros and cons of quantum computing")
```

### 4. Agent Specialization

Create specialized agents for specific domains or tasks:

```python
class DataAnalysisAgent(Agent):
    def __init__(self, name, analysis_tools):
        super().__init__()
        self.name = name
        self.analysis_tools = analysis_tools

    def run(self, data):
        results = {}
        for tool in self.analysis_tools:
            results[tool.name] = tool.analyze(data)
        return results

# Usage
import pandas as pd
from sklearn.preprocessing import StandardScaler
from sklearn.decomposition import PCA

class AnalysisTool:
    def __init__(self, name, func):
        self.name = name
        self.func = func

    def analyze(self, data):
        return self.func(data)

tools = [
    AnalysisTool("Descriptive Stats", lambda data: data.describe()),
    AnalysisTool("Correlation", lambda data: data.corr()),
    AnalysisTool("PCA", lambda data: PCA().fit_transform(StandardScaler().fit_transform(data)))
]

data_agent = DataAnalysisAgent("DataAnalyst", tools)
df = pd.read_csv("sample_data.csv")
analysis_results = data_agent.run(df)
```

### 5. Agent Monitoring and Logging

Implement a monitoring system to track agent performance and log their activities:

```python
import logging
from functools import wraps

def log_agent_activity(func):
    @wraps(func)
    def wrapper(self, *args, **kwargs):
        logging.info(f"Agent {self.name} started task: {args[0]}")
        result = func(self, *args, **kwargs)
        logging.info(f"Agent {self.name} completed task. Result length: {len(str(result))}")
        return result
    return wrapper

class MonitoredAgent(Agent):
    def __init__(self, name, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name

    @log_agent_activity
    def run(self, task, *args, **kwargs):
        return super().run(task, *args, **kwargs)

# Usage
logging.basicConfig(level=logging.INFO)
monitored_agent = MonitoredAgent("MonitoredGriptapeAgent")
result = monitored_agent.run("Summarize the latest AI research papers")
```
Additionally the Agent class now includes built-in logging functionality and the ability to switch between JSON and string output. 

To switch between JSON and string output:
- Use `output_type="str"` for string output (default)
- Use `output_type="json"` for JSON output

The `output_type` parameter determines the format of the final result returned by the `run` method. When set to "str", it returns a string representation of the agent's response. When set to "json", it returns a JSON object containing detailed information about the agent's run, including all steps and metadata.

## 6. Best Practices for Custom Agent Development

When developing custom agents using the swarms framework, consider the following best practices:

1. **Modular Design**: Design your agents with modularity in mind. Break down complex functionality into smaller, reusable components.

2. **Consistent Interfaces**: Maintain consistent interfaces across your custom agents to ensure interoperability within the swarms framework.

3. **Error Handling**: Implement robust error handling and graceful degradation in your agents to ensure system stability.

4. **Performance Optimization**: Optimize your agents for performance, especially when dealing with resource-intensive tasks or large-scale deployments.

5. **Testing and Validation**: Develop comprehensive test suites for your custom agents to ensure their reliability and correctness.

6. **Documentation**: Provide clear and detailed documentation for your custom agents, including their capabilities, limitations, and usage examples.

7. **Versioning**: Implement proper versioning for your custom agents to manage updates and maintain backwards compatibility.

8. **Security Considerations**: Implement security best practices, especially when dealing with sensitive data or integrating with external services.

Here's an example that incorporates some of these best practices:

```python
import logging
from typing import Dict, Any
from swarms import Agent

class SecureCustomAgent(Agent):
    def __init__(self, name: str, api_key: str, version: str = "1.0.0", *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name
        self._api_key = api_key  # Store sensitive data securely
        self.version = version
        self.logger = logging.getLogger(f"{self.__class__.__name__}.{self.name}")

    def run(self, task: str, *args, **kwargs) -> Dict[str, Any]:
        try:
            self.logger.info(f"Agent {self.name} (v{self.version}) starting task: {task}")
            result = self._process_task(task)
            self.logger.info(f"Agent {self.name} completed task successfully")
            return {"status": "success", "result": result}
        except Exception as e:
            self.logger.error(f"Error in agent {self.name}: {str(e)}")
            return {"status": "error", "message": str(e)}

    def _process_task(self, task: str) -> str:
        # Implement the core logic of your agent here
        # This is a placeholder implementation
        return f"Processed task: {task}"

    @property
    def api_key(self) -> str:
        # Provide a secure way to access the API key
        return self._api_key

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} name='{self.name}' version='{self.version}'>"

# Usage
logging.basicConfig(level=logging.INFO)
secure_agent = SecureCustomAgent("SecureAgent", api_key="your-api-key-here")
result = secure_agent.run("Perform a secure operation")
print(result)
```

This example demonstrates several best practices:
- Modular design with separate methods for initialization and task processing
- Consistent interface adhering to the swarms framework
- Error handling and logging
- Secure storage of sensitive data (API key)
- Version tracking
- Type hinting for improved code readability and maintainability
- Informative string representation of the agent

## 7. Future Directions and Challenges

As the field of AI and agent-based systems continues to evolve, the swarms framework and its ecosystem of integrated agent libraries will face new opportunities and challenges. Some potential future directions and areas of focus include:

1. **Enhanced Interoperability**: Developing more sophisticated protocols for agent communication and collaboration across different libraries and frameworks.

2. **Scalability**: Improving the framework's ability to handle large-scale swarms of agents, potentially leveraging distributed computing techniques.

3. **Adaptive Learning**: Incorporating more advanced machine learning techniques to allow agents to adapt and improve their performance over time.

4. **Ethical AI**: Integrating ethical considerations and safeguards into the agent development process to ensure responsible AI deployment.

5. **Human-AI Collaboration**: Exploring new paradigms for human-AI interaction and collaboration within the swarms framework.

6. **Domain-Specific Optimizations**: Developing specialized agent types and tools for specific industries or problem domains.

7. **Explainability and Transparency**: Improving the ability to understand and explain agent decision-making processes.

8. **Security and Privacy**: Enhancing the framework's security features to protect against potential vulnerabilities and ensure data privacy.

As these areas develop, developers working with the swarms framework will need to stay informed about new advancements and be prepared to adapt their agent implementations accordingly.

## 8. Conclusion

The swarms framework provides a powerful and flexible foundation for building custom agents and integrating various agent libraries. By leveraging the techniques and best practices discussed in this guide, developers can create sophisticated, efficient, and scalable agent-based systems.

The ability to seamlessly integrate agents from libraries like Griptape, Langchain, CrewAI, and Autogen opens up a world of possibilities for creating diverse and specialized AI applications. Whether you're building a complex multi-agent system for data analysis, a conversational AI platform, or a collaborative problem-solving environment, the swarms framework offers the tools and flexibility to bring your vision to life.

As you embark on your journey with the swarms framework, remember that the field of AI and agent-based systems is rapidly evolving. Stay curious, keep experimenting, and don't hesitate to push the boundaries of what's possible with custom agents and integrated libraries.

By embracing the power of the swarms framework and the ecosystem of agent libraries it supports, you're well-positioned to create the next generation of intelligent, adaptive, and collaborative AI systems. Happy agent building!