​
Introduction

This simple walkthrough will help you get started with building powerful applications using SuperAgentX in just a few steps.

1. Installation: How to install SuperAgentX on your system.
2. Create an Application: Set up a new SuperAgentX project with the basic structure.
3. Virtual Environment Setup: How to create and configure a Python virtual environment for your project.
4. Building a Use Case: Customizing the pipe.py file to fit your application’s needs.
5. Run the Application: Finally, how to execute your new project with a simple command.

Note:
After installation, the superagentx-cli will be available in the path ~/.local/bin on linux. You may need to add this to your environment’s path variable.

​
Create an Application

$ mkdir <"folderName">
$ python -m venv venv
$ Source venv/bin/activate
$ pip install superagentx

​
Simple Tutorial

import asyncio

from superagentx.agent import Agent
from superagentx.engine import Engine
from superagentx.handler.mcp import MCPHandler
from superagentx.llm import LLMClient
from superagentx.prompt import PromptTemplate


async def main():
    print("Welcome to SuperAgentX MCP Tutorial")

    # Step 1: Initialize LLM
    # Note: You need to setup your OpenAI API key before running this step.
    # export OPENAI_API_KEY=<your-api-key>
    llm_config = {"model": "gpt-4o", "llm_type": "openai"}
    llm_client = LLMClient(llm_config=llm_config)

    # Step 2: Setup MCP tool handler (Reddit trending analyzer) 
    # Note: You need to install the mcp-server-reddit package before running this step.
    # pip install mcp-server-reddit
    mcp_handler = MCPHandler(command="python", mcp_args=["-m", "mcp_server_reddit"])

    # Step 3: Create Prompt Template
    prompt_template = PromptTemplate()

    # Step 4: Create Engine for Reddit analysis using MCP
    reddit_engine = Engine(handler=mcp_handler, llm=llm_client,
                           prompt_template=prompt_template)

    # Step 5: Define Reddit Agent
    agent = Agent(goal="Summarize Reddit Messages",
                  role="You're Reddit Trend Analyzer",
                  llm=llm_client, prompt_template=prompt_template,
                  engines=[reddit_engine])

    result = await agent.execute(query_instruction="List top AI Trends")

    print(f"Reddit Agent Result : {result}")


if __name__ == "__main__":
    asyncio.run(main())

​
How to Create an Application Using Cli

To create a new superagentx project, run the following command in your terminal. This will prompt you to create project with the basic structure set up for your superagentx.

$ python3 -m pip install superagentx

$ superagentx-cli create

​
Follow the steps

# First you have to give an application name or folder name.
Enter application name: content creator

# Then you have to enter pipe name or it will take a default application name.
Enter pipe name. Default is application name []: content

# Next you have to give any one of option given below, or it be take a default value all.
Enter one of the option (all, console, websocket, rest) [all]: all

After your inputs the superagentx-cli create a application like a below structure.

App Name ✈️ content creator
Pacakge Name 📦 content_creator
Pipe Name 🎢 content
App Type 🛠️ all

Creating app at /home/ben/content creator
Creating toml file at /home/ben/content creator/pyproject.toml
Creating readme file at /home/ben/content creator/README.md
Creating pipe file at /home/ben/content creator/content_creator/pipe.py
Your app type selection contains `websocket`, `rest api` option(s).

Enter auth token for `websocket`, `rest api` [5499161e37cb46809791596c0ce49483]:
Creating config file at /home/ben/content creator/content_creator/config.py
Creating iopipe file at /home/ben/content creator/content_creator/iopipe.py
Creating wspipe file at /home/ben/content creator/content_creator/wspipe.py
Creating restpipe file at /home/ben/content creator/content_creator/restpipe.py

​
Virtual Environment Setup

Now, you’ll need to create a Python virtual environment for your project:

$ python3 -m pip install poetry
$ cd /home/ben/Content Creator
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ poetry install

​
Build Your Use Case

If you’re building a new use case, You need to modify the file at /home/ben/Content Creator/content_creator/pipe.py. The path in this file will be generated based on the input you provide through the SuperAgentX application. In that file you can do your changes.

​
Step-by-Step process:

​
1. Import Package

This method imports various components from the superagentx library.


from superagentx.agent import Agent
from superagentx.agentxpipe import AgentXPipe
from superagentx.engine import Engine
from superagentx.llm import LLMClient
from superagentx.memory import Memory
from superagentx.prompt import PromptTemplate

from superagentx.handler import AIHandler

​
2. Define Method

This method get_content_creator_pipe initializes a content creation pipeline by configuring an LLM (Large Language Model) client using OpenAI’s API, for more detail about LLMClient refer here.

async def get_content_creator_pipe() -> AgentXPipe:
    # LLM Configuration
    llm_config = {
        'llm_type': 'openai'
    }
    llm_client = LLMClient(llm_config=llm_config)

​
3. Memory

This line enables memory functionality in the pipeline by configuring a Memory object that created llm_client for storing and retrieving, for more detail about Memory refer here.

    # Enable Memory
    memory = Memory(memory_config={"llm_client": llm_client})

​
4. Handler

This block initializes AIHandler which is configured with the llm_client to handle AI-driven operations, for more details refer here.

    # Example
    ai_handler = AIHandler(
        llm=llm_client
    )

​
5. PromptTemplate

This line creates an instance of PromptTemplate, which is used to define and manage prompt structures for the language model, for more detail refer here.

    # Prompt Template
    prompt_template = PromptTemplate()

​
6. Engine

This line initializes an Engine object for the handlers, combining it with the llm_client and prompt_template to process tasks with the specified handler and prompt structure, for more details refer here.

    # Example - Engine(s)
    ai_engine = Engine(
        handler=ai_handler,
        llm=llm_client,
        prompt_template=prompt_template
    )

​
7. Agent

This line creates an Agent with the role and goal to generate a list of URLs, and configuring it with the llm_client, prompt_template, and engine to perform, for more details about engine refer here.

    # Create Agent with ai Engines execute
    ai_agent = Agent(
        name='AI Agent',
        goal="Summarize the given content",
        role="You are the summarization.",
        llm=llm_client,
        prompt_template=prompt_template,
        engines=[ai_engine]
    )

​
8. AgentXPipe

This line sets up an AgentXPipe, combining multiple agents (serper_agent, crawler_agent, and ai_agent) with shared memory to enable coordinated processing and communication between the agents, for more details refer here.


    # Pipe Interface to send it to public accessible interface (Cli Console / WebSocket / Restful API)
    pipe = AgentXPipe(
        agents=[ai_agent],
        memory=memory
    )

​
All Together

from superagentx.agent import Agent
from superagentx.agentxpipe import AgentXPipe
from superagentx.engine import Engine
from superagentx.llm import LLMClient
from superagentx.memory import Memory
from superagentx.prompt import PromptTemplate

from superagentx.handler import AIHandler


async def get_content_creator_pipe() -> AgentXPipe:
    # LLM Configuration
    llm_config = {
        'llm_type': 'openai'
    }
    llm_client = LLMClient(llm_config=llm_config)

    # Enable Memory
    memory = Memory(memory_config={"llm_client": llm_client})

    ai_handler = AIHandler(
        llm=llm_client
    )

    # Prompt Template
    prompt_template = PromptTemplate()

    # Example - Engine(s)
    ai_engine = Engine(
        handler=ai_handler,
        llm=llm_client,
        prompt_template=prompt_template
    )

    # Create Agent with ai Engines execute
    ai_agent = Agent(
        name='AI Agent',
        goal="Summarize the given content",
        role="You are the summarization.",
        llm=llm_client,
        prompt_template=prompt_template,
        engines=[ai_engine]
    )

    # Pipe Interface to send it to public accessible interface (Cli Console / WebSocket / Restful API)
    pipe = AgentXPipe(
        agents=[ai_agent],
        memory=memory
    )
    return pipe

​
Run the Application

Once everything is set up, you can run your application with this command:

# Console Pipe
$ python3 Content Creator/iopipe.py

or
# WebSocket Pipe
$ python3 Content Creator/wspipe.py

or
# RestAPI Pipe(FastAPI)
$ python3 Content Creator/restpipe.py

This will start your SuperAgentX application and execute the tasks you’ve configured.

​
Run the Application with Verbose

# Console Pipe
$ VERBOSE=1 python3 Content Creator/iopipe.py

or
# Console Pipe
$ DEBUGGING=1 python3 Content Creator/iopipe.py

This is applicable for wspipe.py and restpipe.py. Even with your custom implementation. Valid options are 1, True, true and TRUE

​
Result


Enter your search here: Give me summary about Hon Solo

Result:
"Han Solo is a fictional character in the 'Star Wars' franchise, known for his quick
wit and roguish charm as a smuggler. He becomes a key figure in the Rebel Alliance,
aiding in significant battles like Yavin and Endor. Portrayed by Harrison Ford,
Han transforms from a self-interested rogue to a dedicated ally, playing a
crucial role in the storyline with connections to Princess Leia and Luke Skywalker."

Reason:: The summary provides an accurate and concise overview of Han Solo's
character based on the given output context.


Goal Satisfied: True


────────────────────────────────────────────────────────────────────────── End ───────────────────────────────────────────────────────────────────────────