> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superagentx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start building awesome documentation in under 5 minutes

## Introduction

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

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

<Note>
  Note: <br />
  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.
</Note>

## Create an Application

### For Linux / macOS

```shell theme={null}
$ mkdir <"folderName">
$ python -m venv .venv
$ Source .venv/bin/activate
$ pip install superagentx
```

### For Windows (PowerShell)

```shell theme={null}
$ mkdir <"folderName">
$ python -m venv .venv
$ .venv\Scripts\activate
$ pip install superagentx
```

## Simple Tutorial

<iframe width="100%" height="400" src="https://www.youtube.com/embed/BlbX0JewjCM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

```python theme={null}
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`.

```shell theme={null}
$ python3 -m pip install superagentx
```

```shell theme={null}
$ superagentx-cli create
```

### Follow the steps

```shell theme={null}
# 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.

```shell theme={null}
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:

```shell theme={null}
$ 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.

```python theme={null}

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 <a href="llm" target="_blank">here</a>.

```python theme={null}
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 <a href="memory" target="_blank">here</a>.

```python theme={null}
    # 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 <a href="handler" target="_blank">here</a>.

```python theme={null}
    # 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 <a href="prompt" target="_blank">here</a>.

```python theme={null}
    # 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 <a href="engine" target="_blank">here</a>.

```python theme={null}
    # 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 <a href="agent" target="_blank">here</a>.

```python theme={null}
    # 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 <a href="pipe" target="_blank">here</a>.

```python theme={null}

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

### All Together

```python theme={null}
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:

```shell theme={null}
# 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`

```shell theme={null}
# Console Pipe
$ VERBOSE=1 python3 Content Creator/iopipe.py

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

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

### Result

```shell theme={null}

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 ───────────────────────────────────────────────────────────────────────────
```