41 |
--------------------------------------------------------------------------------
/superagentx/vector_stores/base.py:
--------------------------------------------------------------------------------
1 | from abc import ABCMeta, abstractmethod
2 |
3 |
4 | class BaseVectorStore(metaclass=ABCMeta):
5 |
6 | @abstractmethod
7 | async def create(self, *args, **kwargs):
8 | """Creating a new collection or index"""
9 | raise NotImplementedError
10 |
11 | @abstractmethod
12 | async def insert(self, *args, **kwargs):
13 | """Insert Vectors into a collection"""
14 | raise NotImplementedError
15 |
16 | @abstractmethod
17 | async def search(self, *args, **kwargs):
18 | """Search for similar vectors"""
19 | raise NotImplementedError
20 |
21 | @abstractmethod
22 | async def update(self, *args, **kwargs):
23 | """Update a vector"""
24 | raise NotImplementedError
25 |
26 | @abstractmethod
27 | async def exists(self, *args, **kwargs):
28 | raise NotImplementedError
29 |
30 | @abstractmethod
31 | async def delete_collection(self, *args, **kwargs):
32 | """Delete a collection."""
33 | raise NotImplementedError
34 |
35 | @abstractmethod
36 | async def delete_by_conversation_id(self, **kwargs):
37 | """Delete by conversation id."""
38 | raise NotImplementedError
39 |
--------------------------------------------------------------------------------
/docs/examples/handlers/azure/load_balancer.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Load Balancer Handler'
3 | icon: 'network-wired'
4 | ---
5 |
6 | The **Azure Load Balancer Handler** is responsible for retrieving and managing **Azure Load Balancers** within a subscription.
7 | It uses the Azure SDK for Python (`azure-mgmt-network`) and authentication via `azure-identity` to collect server asset details for governance, compliance, and monitoring.
8 |
9 |
10 |
11 | ## Example
12 |
13 | To create the **AzureLoadBalancerHandler** object, initialize it with your **Azure Subscription ID, Tenant ID, Client ID, and Client Secret** (or load them from environment variables):
14 |
15 | ```python
16 | import os
17 | from superagentx_handlers.azure.loadbalancer import AzureLoadBalancerHandler
18 |
19 | lb_handler = AzureLoadBalancerHandler(
20 | subscription_id=os.getenv("AZURE_SUBSCRIPTION_ID"),
21 | tenant_id=os.getenv("AZURE_TENANT_ID"),
22 | client_id=os.getenv("AZURE_CLIENT_ID"),
23 | client_secret=os.getenv("AZURE_CLIENT_SECRET")
24 | )
25 | ```
26 |
27 | **Get All Load Balancers in Subscription:** 30 | Retrieves a list of all storage accounts within the subscription, 31 | along with their associated properties. 32 | ```python 33 | accounts = await storage_handler.list_storage_accounts() 34 | print(accounts) 35 | ``` -------------------------------------------------------------------------------- /docs/handler.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Handler' 3 | icon: 'bars-progress' 4 | --- 5 | 6 | We use the term "handler" interchangeably with "tool calling." While "tool calling" is sometimes used to refer 7 | to the invocation of a single function. It contains the logic for managing particular operations, playing a 8 | key role in organizing and carrying out tasks. 9 | 10 | With the `BaseHandler` from `superagentx.handler.base`, you can create your own custom 11 | handlers. 12 | 13 | Additionally, we also provide pre-built handlers for various other 14 | services and libraries. 15 | 16 | ### Tool: 17 | A tool is a method or function that performs a specific action within a larger system. In this context, 18 | tools are asynchronous functions that handle specific tasks, like fetching data from external APIs or 19 | performing calculations. The @tool decorator marks these methods as tools that can be invoked by the system. 20 | 21 | ```python 22 | from superagentx.handler.decorators import tool 23 | 24 | class ExaHandler(BaseHandler): 25 | 26 | @tool 27 | async def search_contents( 28 | self, 29 | *, 30 | query: str, 31 | use_autoprompt: bool, 32 | num_results: int = 10, 33 | search_type: str | None = None 34 | ): 35 | ``` 36 | 37 | -------------------------------------------------------------------------------- /docs/examples/handlers/aws/security_groups.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Security Groups Handler' 3 | icon: 'lock' 4 | --- 5 | 6 | Amazon EC2 **Security Groups** act as virtual firewalls to control inbound and outbound traffic for your AWS resources, such as EC2 instances and load balancers. They help secure your applications by defining rules that allow or deny specific traffic. Security Groups operate at the instance level and are an essential part of AWS networking and security best practices. 7 | 8 | This handler enables you to interact with **AWS Security Groups** using boto3, making it easier to retrieve details such as rules, attached instances, and associated VPCs. It provides an abstraction for developers to collect security group data seamlessly. 9 | 10 | 11 | 12 | ## Example 13 | 14 | To create the AWS Security Groups Handler object with AWS credentials: 15 | 16 | ```python 17 | import os 18 | from superagentx_handlers.aws.security_groups import AWSSecurityGroupsHandler 19 | 20 | sg_handler = AWSSecurityGroupsHandler( 21 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 22 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 23 | region_name="us-east-1" 24 | ) 25 | ``` 26 | 27 | **List Security Groups:**
28 | Retrieves details of all security groups in your AWS account for the given region, including rules, VPCs, and attached resources. 29 | ```python 30 | security_groups = await sg_handler.get_ec2_security_groups() 31 | print(security_groups) 32 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/azure/vm.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'VM Handler' 3 | icon: 'server' 4 | --- 5 | 6 | Azure Virtual Machines (VMs) are scalable computing resources in Microsoft Azure. 7 | They allow you to run Windows or Linux servers in the cloud without needing to maintain physical hardware. 8 | With Azure VMs, you can host applications, databases, and workloads with built-in high availability, security, and scalability. 9 | 10 | This handler provides seamless interaction with Azure VMs to collect information about virtual machines within a subscription. 11 | It uses service principal authentication (`tenant_id`, `client_id`, `client_secret`) and requires appropriate Azure RBAC permissions (e.g., **Reader** role). 12 | 13 | 14 | 15 | ## Example 16 | 17 | To create the `AzureVMHandler` object with your Azure credentials: 18 | 19 | ```python 20 | import os 21 | from superagentx_handlers.azure.vm import AzureVMHandler 22 | 23 | azure_vm_handler = AzureVMHandler( 24 | subscription_id=os.getenv("AZURE_SUBSCRIPTION_ID"), 25 | tenant_id=os.getenv("AZURE_TENANT_ID"), 26 | client_id=os.getenv("AZURE_CLIENT_ID"), 27 | client_secret=os.getenv("AZURE_CLIENT_SECRET") 28 | ) 29 | ``` 30 | **List Virtual Machines (get_vms):**
31 | Retrieves a list of all accessible Azure VM instances within the configured subscription. 32 | Each VM’s details (name, ID, region, size, OS, and network/storage profile) are returned in dictionary format. 33 | ```python 34 | vms = await azure_vm_handler.get_vms() 35 | print(vms) 36 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/servicenow.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'ServiceNow Handler' 3 | icon: 'server' 4 | --- 5 | 6 | ServiceNow is a cloud-based platform that provides IT service management (ITSM), helping organizations manage incidents, assets, changes, and workflows. The `ServiceNowHandler` allows seamless integration with ServiceNow to fetch users, assets, and related tickets programmatically. 7 | 8 | ## Example 9 | 10 | To create the `ServiceNowHandler` object, initialize it with your ServiceNow instance URL and credentials. If not provided, the values will be picked up from environment variables. 11 | 12 | ```python 13 | import os 14 | from superagentx_handlers.servicenow import ServiceNowHandler 15 | 16 | servicenow_handler = ServiceNowHandler( 17 | instance_url=os.getenv("SERVICENOW_INSTANCE_URL"), 18 | username=os.getenv("SERVICENOW_USERNAME"), 19 | password=os.getenv("SERVICENOW_PASSWORD"), 20 | ) 21 | ``` 22 | 23 | **Get User Name:**
24 | Fetches the user’s display name from ServiceNow using their sys_id. 25 | ```python 26 | user_name = await servicenow_handler.get_user_name("46d44a2d1b2123009b5f3d92cc4bcb65") 27 | print(user_name) # e.g., "John Doe" 28 | ``` 29 | 30 | **Get Assets with Details and Tickets:**
31 | Retrieves a list of assets along with details like owner, model, warranty, and their associated incident tickets. 32 | ```python 33 | assets_report = await servicenow_handler.get_assets_with_details_and_tickets() 34 | for asset in assets_report: 35 | print(asset["Asset Name"], asset["Tickets"]) 36 | ``` -------------------------------------------------------------------------------- /tests/handlers/test_financial_data.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | import pytest 4 | 5 | from superagentx.handler.financial_data import FinancialHandler 6 | 7 | ''' 8 | Run Pytest: 9 | 10 | 1.pytest --log-cli-level=INFO tests/handlers/test_financial_data.py::TestFinancial::test_get_stock_price 11 | 2.pytest --log-cli-level=INFO tests/handlers/test_financial_data.py::TestFinancial::test_get_company_financials 12 | 3.pytest --log-cli-level=INFO tests/handlers/test_financial_data.py::TestFinancial::test_get_income_statement 13 | 14 | ''' 15 | 16 | @pytest.fixture 17 | def financial_client_init() -> FinancialHandler: 18 | financial_handler = FinancialHandler( 19 | api_key=os.getenv("FINANCIAL_MODELING_PREP_API_KEY"), 20 | symbol='AA' 21 | ) 22 | return financial_handler 23 | 24 | class TestFinancial: 25 | 26 | async def test_get_stock_price(self, financial_client_init: FinancialHandler): 27 | res = await financial_client_init.get_stock_price() 28 | assert isinstance(res, list) 29 | assert len(res) > 0 30 | 31 | async def test_get_company_financials(self, financial_client_init: FinancialHandler): 32 | res = await financial_client_init.get_company_financials() 33 | assert isinstance(res, list) 34 | assert len(res) > 0 35 | 36 | async def test_get_income_statement(self, financial_client_init: FinancialHandler ): 37 | res = await financial_client_init.get_income_statement() 38 | assert isinstance(res, list) 39 | assert len(res) > 0 40 | -------------------------------------------------------------------------------- /superagentx/computer_use/browser/state.py: -------------------------------------------------------------------------------- 1 | from dataclasses import dataclass, field 2 | from typing import Any 3 | 4 | from pydantic import BaseModel 5 | 6 | from superagentx.computer_use.browser.dom.history_tree_processor.tree_processor_service import DOMHistoryElement 7 | from superagentx.computer_use.browser.dom.views import DOMState 8 | 9 | 10 | class TabInfo(BaseModel): 11 | page_id: int 12 | url: str 13 | title: str 14 | 15 | 16 | @dataclass 17 | class BrowserState(DOMState): 18 | url: str 19 | title: str 20 | tabs: list[TabInfo] 21 | screenshot: str | None = None 22 | pixels_above: int = 0 23 | pixels_below: int = 0 24 | browser_errors: list[str] = field(default_factory=list) 25 | 26 | 27 | @dataclass 28 | class BrowserStateHistory: 29 | url: str 30 | title: str 31 | tabs: list[TabInfo] 32 | interacted_element: list[DOMHistoryElement | None] 33 | screenshot: str | None = None 34 | 35 | def to_dict(self) -> dict[str, Any]: 36 | return { 37 | "tabs": [tab.model_dump() for tab in self.tabs], 38 | "screenshot": self.screenshot, 39 | "interacted_element": [ 40 | el.to_dict() if el else None for el in self.interacted_element 41 | ], 42 | "url": self.url, 43 | "title": self.title, 44 | } 45 | 46 | 47 | class BrowserError(Exception): 48 | """Base class for all browser errors""" 49 | 50 | 51 | class URLNotAllowedError(BrowserError): 52 | """Error raised when a URL is not allowed""" -------------------------------------------------------------------------------- /docs/examples/handlers/datadog/incidents.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Datadog Incidents' 3 | icon: 'shield-dog' 4 | --- 5 | 6 | Datadog Incidents is a service that helps engineering and operations teams track, manage, and resolve incidents efficiently. 7 | It provides powerful integrations, collaborative workflows, and monitoring visibility to ensure quick resolution of critical issues. 8 | 9 | This handler allows seamless interaction with **Datadog Incidents API**, enabling you to **list** and **search** incidents programmatically. 10 | It uses API and Application keys for authentication (`DD_API_KEY`, `DD_APP_KEY`) and requires the `DD_SITE` configuration (e.g., `us5.datadoghq.com`). 11 | 12 | 13 | 14 | ## Example 15 | 16 | To create the `DDIncidentsHandler` object with Datadog credentials: 17 | 18 | ```python 19 | import os 20 | from superagentx_handlers.datadog.incidents import DDIncidentsHandler 21 | 22 | dd_handler = DDIncidentsHandler( 23 | host=os.getenv("DD_SITE"), # e.g., "us5.datadoghq.com" 24 | api_key=os.getenv("DD_API_KEY"), 25 | app_key=os.getenv("DD_APP_KEY") 26 | ) 27 | ``` 28 | **List Incidents (list_incidents):**
29 | Retrieves a list of all incidents in your Datadog account. 30 | ```python 31 | incidents = await dd_handler.list_incidents() 32 | print(incidents) 33 | ``` 34 | 35 | **Search Incidents (search_incidents):**
36 | Search for incidents that match a specific query (by title, status, severity, etc.). 37 | ```python 38 | results = await dd_handler.search_incidents(query="status:active severity:SEV-1") 39 | print(results) 40 | ``` 41 | -------------------------------------------------------------------------------- /docs/examples/handlers/slack.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Slack Handler' 3 | icon: 'slack' 4 | --- 5 | 6 | Slack is a messaging platform widely used for team communication and collaboration. It provides channels for organizing conversations, direct messaging, file sharing, and integrates with external tools via its API. Using the Slack API, you can send messages, fetch messages, and manage channels programmatically. 7 | 8 | ## Example 9 | 10 | To create the `SlackHandler` object, initialize it with your Slack **bot token**. 11 | The handler uses the Slack Web API to interact with channels and messages. 12 | 13 | ```python 14 | import os 15 | from superagentx_handlers.slack import SlackHandler 16 | 17 | slack_handler = SlackHandler( 18 | bot_token=os.getenv("SLACK_BOT_TOKEN") 19 | ) 20 | ``` 21 | 22 | **Send Slack Message:**
23 | Sends a plain text message to a specific Slack channel. 24 | ```python 25 | response = await slack_handler.send_slack_message( 26 | text="Hello team! :wave:", 27 | channel_id="C1234567890" 28 | ) 29 | print(response) 30 | ``` 31 | 32 | **Get Messages from a Channel:**
33 | Retrieves the most recent messages from a given Slack channel. 34 | ```python 35 | messages = await slack_handler.get_messages_from_channel( 36 | channel_id="C1234567890", 37 | limit=5 38 | ) 39 | for msg in messages: 40 | print(msg["text"]) 41 | ``` 42 | 43 | **Get Channel ID by Name:**
44 | Looks up the channel ID using its name. 45 | ```python 46 | channel_id = await slack_handler.get_channel_id("general") 47 | print("Channel ID:", channel_id) 48 | ``` -------------------------------------------------------------------------------- /tests/handlers/test_bedrock_ai_handler.py: -------------------------------------------------------------------------------- 1 | import logging 2 | 3 | import pytest 4 | 5 | from superagentx.handler.ai import AIHandler 6 | from superagentx.llm import LLMClient 7 | 8 | logger = logging.getLogger(__name__) 9 | 10 | ''' 11 | Run Pytest: 12 | 13 | 1. pytest --log-cli-level=INFO tests/handlers/test_bedrock_ai_handler.py::TestBedrockAIHandler::test_ai_bedrock_message 14 | ''' 15 | 16 | 17 | 18 | @pytest.fixture 19 | def ai_bedrock_client_init() -> dict: 20 | llm_config = {'model': 'anthropic.claude-3-5-sonnet-20240620-v1:0', 'llm_type': 'bedrock', 'async_mode': True} 21 | 22 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 23 | response = {'llm': llm_client} 24 | return response 25 | 26 | 27 | class TestBedrockAIHandler: 28 | 29 | async def test_ai_bedrock_message(self, ai_bedrock_client_init: dict): 30 | llm_client: LLMClient = ai_bedrock_client_init.get('llm') 31 | 32 | content_handler = AIHandler(llm=llm_client) 33 | response = await content_handler.text_creation(system_message="You are an app that creates playlists for a " 34 | "radio station that plays rock and pop music. " 35 | "Only return song names and the artist.", 36 | instruction="Make sure the songs are by artists from the " 37 | "United Kingdom.") 38 | logger.info(f"Response ==> {response}") 39 | -------------------------------------------------------------------------------- /superagentx/utils/helper.py: -------------------------------------------------------------------------------- 1 | from typing import Any 2 | import re 3 | import asyncio 4 | 5 | from typing import Callable, Awaitable, Any, Optional, Union 6 | 7 | StatusCallback = Callable[..., Awaitable[Any]] 8 | 9 | 10 | async def sync_to_async(func, *args, **kwargs) -> Any: 11 | return await asyncio.to_thread(func, *args, **kwargs) 12 | 13 | 14 | async def _maybe_await(coro): 15 | if asyncio.iscoroutine(coro): 16 | await coro 17 | 18 | 19 | async def iter_to_aiter(iterable): 20 | for item in iterable: 21 | yield item 22 | 23 | 24 | async def get_fstring_variables(s: str): 25 | # This regular expression looks for variables in curly braces 26 | return re.findall(r'\{(.*?)}', s) 27 | 28 | 29 | async def ptype_to_json_scheme(ptype: str) -> str: 30 | match ptype: 31 | case 'int': 32 | return "integer" 33 | case 'str': 34 | return "string" 35 | case 'bool': 36 | return "boolean" 37 | case 'list': 38 | return "array" 39 | case 'dict' | _: 40 | return "object" 41 | 42 | 43 | async def rm_trailing_spaces(data): 44 | """Recursively remove trailing whitespace from all string values in a JSON-like structure.""" 45 | if isinstance(data, dict): 46 | return {k: await rm_trailing_spaces(v) for k, v in data.items()} 47 | elif isinstance(data, list): 48 | return [await rm_trailing_spaces(v) for v in data] 49 | elif isinstance(data, str): 50 | return data.rstrip() # Remove trailing whitespace 51 | else: 52 | return data 53 | -------------------------------------------------------------------------------- /tests/io/test_console_io_stream.py: -------------------------------------------------------------------------------- 1 | import logging 2 | 3 | import pytest 4 | 5 | from superagentx.io.console import IOConsole 6 | from superagentx.utils.console_color import ConsoleColorType 7 | 8 | logger = logging.getLogger(__name__) 9 | 10 | '''PyTest 11 | 1. pytest -s --log-cli-level=INFO tests/io/test_console_io_stream.py::TestIOConsole::test_console_io_input_print 12 | 2. pytest -s --log-cli-level=INFO tests/io/test_console_io_stream.py::TestIOConsole::test_console_io_input_password 13 | ''' 14 | 15 | 16 | @pytest.fixture 17 | def console_io() -> IOConsole: 18 | return IOConsole() 19 | 20 | 21 | class TestIOConsole: 22 | 23 | async def test_console_io_input_print(self, console_io: IOConsole): 24 | logging.info(f"IO Console Print & Input Test.") 25 | 26 | await console_io.write(ConsoleColorType.CYELLOW2.value, end="") 27 | await console_io.write("Hello, Super AgentX World!", flush=True) 28 | 29 | # Getting input from the console 30 | data = await console_io.read("Enter something: ") 31 | await console_io.write(f"You entered: {data}", flush=True) 32 | 33 | async def test_console_io_input_password(self, console_io: IOConsole): 34 | logging.info(f"IO Console Print & Input Password Test.") 35 | 36 | await console_io.write(ConsoleColorType.CGREEN.value, end="") 37 | await console_io.write("Hello, Super AgentX World!", flush=True) 38 | 39 | # Getting password input from the console 40 | data = await console_io.read("Enter something: ", password=True) 41 | await console_io.write(f"You entered: {data}", flush=True) 42 | -------------------------------------------------------------------------------- /docs/examples/handlers/Google/gmail.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Gmail Handler' 3 | icon: 'square-m' 4 | --- 5 | 6 | The Gmail Handler is a specialized tool designed to interact with the Gmail API, enabling users to manage their 7 | email accounts programmatically. This handler simplifies the process of accessing user profiles, sending emails, 8 | and creating draft emails. It uses OAuth 2.0 for authentication and provides a user-friendly interface to perform 9 | various email-related tasks asynchronously. 10 | 11 | ## Example 12 | Set up a GmailHandler using the provided credentials, allowing the application to send, receive, and manage emails 13 | through Gmail programmatically. 14 | 15 | To setup and get a credentials refer here. 16 | 17 | After creating and enabling the Google Cloud API, you need to provide the path to the credentials in the _credentials_ parameters. 18 | 19 | ```python Gmail_handler.py 20 | import asyncio 21 | 22 | from superagentx_handlers.google.gmail import GmailHandler 23 | 24 | 25 | async def get_user_profile(): 26 | gmail_handler = GmailHandler( 27 | credentials="" 28 | ) 29 | return await gmail_handler.get_user_profile() 30 | 31 | 32 | async def main(): 33 | res = await get_user_profile() 34 | print(res) 35 | 36 | if __name__ == '__main__': 37 | asyncio.run(main()) 38 | ``` 39 | 40 | ## Result 41 | ```python Gmail user profile 42 | { 43 | 'emailAddress': 'bala234@gmail.com', 44 | 'messagesTotal': 3678, 45 | 'threadsTotal': 4352, 46 | 'historyId': '985428' 47 | } 48 | ``` 49 | -------------------------------------------------------------------------------- /superagentx_cli/templates/wspipe.py.jinja2: -------------------------------------------------------------------------------- 1 | {# templates/wspipe.py.jinja2 #} 2 | import asyncio 3 | import urllib.parse 4 | 5 | from rich import print as rprint 6 | from superagentx.pipeimpl.wspipe import WSPipe # https://websockets.readthedocs.io/en/stable/ 7 | from websockets import CloseCode, ServerConnection 8 | 9 | from {{ package_name }}.config import AUTH_TOKEN 10 | from {{ package_name }}.pipe import get_{{ pipe_name }}_pipe 11 | 12 | 13 | async def auth_handler(ws: ServerConnection) -> bool: 14 | """Authenticate user from token in query parameter.""" 15 | query = urllib.parse.urlparse(ws.request.path).query 16 | params = urllib.parse.parse_qs(query) 17 | values = params.get('token', []) 18 | if values: 19 | token = values[0] 20 | if token is None or token != AUTH_TOKEN: 21 | await ws.close( 22 | code=CloseCode.INTERNAL_ERROR, 23 | reason='Authentication failed!' 24 | ) 25 | return False 26 | return True 27 | 28 | 29 | async def main(): 30 | """ 31 | Launches the {{ app_name }} pipeline websocket server for processing requests and handling data. 32 | """ 33 | pipe = await get_{{ pipe_name }}_pipe() 34 | ws_pipe = WSPipe( 35 | search_name='SuperAgentX {{ app_name }} Websocket Server', 36 | agentx_pipe=pipe, 37 | auth_handler=auth_handler, 38 | ) 39 | await ws_pipe.start() 40 | 41 | 42 | if __name__ == '__main__': 43 | try: 44 | asyncio.run(main()) 45 | except (KeyboardInterrupt, asyncio.CancelledError): 46 | rprint("\nUser canceled the [bold yellow][i]pipe[/i]!"){{'\n'}} 47 | -------------------------------------------------------------------------------- /tests/handlers/test_elastic_search.py: -------------------------------------------------------------------------------- 1 | import pytest 2 | 3 | from superagentx.handler.elastic_search import ElasticsearchHandler 4 | 5 | ''' 6 | Run Pytest: 7 | 8 | 1.pytest --log-cli-level=INFO tests/handlers/test_elastic_search.py::TestElasticsearch::test_elasticsearch_search 9 | 2.pytest --log-cli-level=INFO tests/handlers/test_elastic_search.py::TestElasticsearch::test_elasticsearch_create 10 | 11 | ''' 12 | 13 | 14 | @pytest.fixture 15 | def elasticsearch_client_init() -> ElasticsearchHandler: 16 | elasticsearch_handler = ElasticsearchHandler( 17 | hosts="http://localhost:9200", 18 | username="elastic", 19 | password="password" 20 | ) 21 | return elasticsearch_handler 22 | 23 | 24 | class TestElasticsearch: 25 | 26 | # Test async elasticsearch handler - search method 27 | async def test_elasticsearch_search(self, elasticsearch_client_init: ElasticsearchHandler): 28 | elasticsearch = await elasticsearch_client_init.search( 29 | index_name="index_name", 30 | query={"match_all": {}} 31 | ) 32 | assert isinstance(elasticsearch, object) 33 | 34 | # Test async elasticsearch handler - create method 35 | async def test_elasticsearch_create(self, elasticsearch_client_init: ElasticsearchHandler): 36 | elasticsearch = await elasticsearch_client_init.create( 37 | index_name="index_name", 38 | document_id="index_name", 39 | document={ 40 | "@timestamp": "2099-11-15T13:12:00", 41 | "message": "GET /search HTTP/1.1 200 1070000", 42 | }, 43 | 44 | ) 45 | assert isinstance(elasticsearch, object) 46 | -------------------------------------------------------------------------------- /tests/llm/test_tool.py: -------------------------------------------------------------------------------- 1 | import inspect 2 | from typing import get_type_hints 3 | 4 | 5 | def get_delivery_date(order_id: str, id: int) -> str: 6 | """Get the delivery date for a customer's order. Call this whenever you need to know 7 | the delivery date, for example when a customer asks 'Where is my package""" 8 | return "test" 9 | 10 | 11 | def generate_function_json(func) -> dict: 12 | # Get function name 13 | func_name = func.__name__ 14 | 15 | # Get function docstring 16 | docstring = inspect.getdoc(func) 17 | 18 | # Get function annotations (parameter types and return llm_type) 19 | type_hints = get_type_hints(func) 20 | 21 | # Generate the 'properties' field based on function parameters 22 | properties = {} 23 | for param, param_type in type_hints.items(): 24 | if param != 'return': 25 | properties[param] = { 26 | "llm_type": param_type.__name__, 27 | "description": f"The {param.replace('_', ' ')}." 28 | } 29 | 30 | # Create the final JSON structure 31 | function_json = { 32 | "function": { 33 | "name": func_name, 34 | "description": docstring, 35 | "parameters": { 36 | "llm_type": "object", 37 | "properties": properties, 38 | "required": list(properties.keys()), 39 | "additionalProperties": False 40 | } 41 | } 42 | } 43 | # return json.dumps(function_json, indent=4) 44 | return function_json 45 | 46 | 47 | # Generate JSON for the function 48 | function_json = generate_function_json(get_delivery_date) 49 | tool = [function_json] 50 | -------------------------------------------------------------------------------- /examples/agents/ai_agent.py: -------------------------------------------------------------------------------- 1 | import asyncio 2 | 3 | from superagentx.agent import Agent 4 | from superagentx.engine import Engine 5 | from superagentx.handler.ai import AIHandler 6 | from superagentx.llm import LLMClient 7 | from superagentx.prompt import PromptTemplate 8 | 9 | 10 | async def main(): 11 | print("Welcome to SuperAgentX AI Content Generator Tutorial") 12 | 13 | # Step 1: Initialize LLM 14 | # Note: You need to setup your OpenAI API key before running this step. 15 | # export OPENAI_API_KEY=
23 | Retrieves the list of all employees in the Zoho People organization. 24 | ```python 25 | employees = await zoho_handler.list_employees() 26 | for emp in employees: 27 | print(emp["Name"], emp["Email"]) 28 | ``` 29 | 30 | **List Onboarding Workflows:**
31 | Fetches onboarding workflows configured in Zoho People. 32 | ```python 33 | onboarding_flows = await zoho_handler.list_onboarding_workflows() 34 | print(onboarding_flows) 35 | ``` 36 | 37 | **List Offboarding Workflows:**
38 | Fetches offboarding workflows configured in Zoho People. 39 | ```python 40 | offboarding_flows = await zoho_handler.list_offboarding_workflows() 41 | print(offboarding_flows) 42 | ``` 43 | 44 | **List Role Change Workflows:**
45 | Retrieves role change (transfer) workflows configured in Zoho People. 46 | ```python 47 | role_change_flows = await zoho_handler.list_role_change_workflows() 48 | print(role_change_flows) 49 | ``` -------------------------------------------------------------------------------- /tests/browser/sensitive_data.py: -------------------------------------------------------------------------------- 1 | import asyncio 2 | import logging 3 | import warnings 4 | 5 | from rich import print as rprint 6 | 7 | from superagentx.agent import Agent 8 | from superagentx.browser_engine import BrowserEngine 9 | from superagentx.llm import LLMClient 10 | from superagentx.prompt import PromptTemplate 11 | 12 | warnings.filterwarnings('ignore') 13 | 14 | sh = logging.StreamHandler() 15 | logging.basicConfig( 16 | level="INFO", 17 | format='%(asctime)s -%(levelname)s - %(name)s - %(funcName)s: %(message)s', 18 | datefmt='%Y-%m-%d %H:%M:%S', 19 | handlers=[sh] 20 | ) 21 | 22 | 23 | async def main(): 24 | llm_config = {'model': 'gpt-4o', 'llm_type': 'openai', 'async_mode': True} 25 | 26 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 27 | 28 | prompt_template = PromptTemplate() 29 | sensitive_data = {'x_name': '
31 | Reads a file from the given path and returns its Base64-encoded content. 32 | ```python 33 | file_data = await extract_handler.get_file_base64_data("invoice.pdf") 34 | print(file_data[:100]) # preview first 100 chars 35 | ``` 36 | 37 | **Extract API:**
38 | Initiates a file extraction request and polls until results are available. 39 | ```python 40 | result = await extract_handler.extract_api( 41 | file_path="invoice.pdf", 42 | file_data=file_data, 43 | poll_interval=5, 44 | retry=10 45 | ) 46 | print(result) 47 | ``` 48 | 49 | **Get Invoice JSON Data:**
50 | Fetches the extracted JSON data using the reference ID of a completed job. 51 | ```python 52 | invoice_data = await extract_handler.get_invoice_json_data("ref12345") 53 | print(invoice_data) 54 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/aws/serverless.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Serverless Handler' 3 | icon: 'lambda' 4 | --- 5 | 6 | AWS Lambda is a **serverless compute service** that lets you run code without provisioning or managing servers. You just upload your code (as a ZIP package or container image), and Lambda automatically scales and runs it in response to events such as API Gateway requests, S3 object uploads, DynamoDB streams, or scheduled CloudWatch events. 7 | 8 | Lambda integrates seamlessly with **VPC, IAM, Security Groups, and other AWS services**, making it a core component of modern serverless applications. 9 | 10 | 11 | 12 | ## Example 13 | 14 | To create the AWSLambdaHandler with AWS credentials: 15 | 16 | ```python 17 | import os 18 | from superagentx_handlers.aws.serverless import AWSLambdaHandler 19 | 20 | lambda_handler = AWSLambdaHandler( 21 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 22 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 23 | region_name="eu-central-1" 24 | ) 25 | ``` 26 | 27 | **List Lambda Functions:**
28 | Retrieves all Lambda functions in the account, including runtime, handler, role, security groups, IAM policies, and environment configurations. 29 | ```python 30 | functions = await lambda_handler.get_lambda_functions() 31 | print(functions) 32 | ``` 33 | 34 | **Get IAM Role Policies for a Lambda Role:**
35 | Fetches all attached and inline IAM policies for the IAM role associated with a Lambda. 36 | ```python 37 | policies = await lambda_handler.get_role_policies("MyLambdaRole") 38 | print(policies) 39 | ``` 40 | 41 | **Get Security Group Details:**
42 | Fetches inbound/outbound rules for security groups attached to a Lambda function’s VPC. 43 | ```python 44 | sg_details = await lambda_handler.get_security_group_details(["sg-12345678"]) 45 | print(sg_details) 46 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/aws/cloudwatch.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'CloudWatch Handler' 3 | icon: 'chart-bar' 4 | --- 5 | 6 | Amazon CloudWatch is a monitoring and observability service that provides data and actionable insights for AWS, hybrid, 7 | and on-premises applications and infrastructure resources. It allows you to collect metrics, logs, and events, helping 8 | you monitor system health, detect anomalies, and keep applications running smoothly. 9 | 10 | ## Example 11 | To create the AWSCloudWatchHandler object with AWS credentials. 12 | The AWSCloudWatchHandler connects to Amazon CloudWatch using access credentials 13 | (access key, secret key) and specifies a region. It enables seamless interaction 14 | with CloudWatch for tasks like fetching metrics and monitoring resources. 15 | 16 | ```python cloudwatch_handler_test.py 17 | import os 18 | from superagentx_handlers.aws.cloudwatch import AWSCloudWatchHandler 19 | 20 | cloudwatch_handler = AWSCloudWatchHandler( 21 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 22 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 23 | region_name="us-east-1" 24 | ) 25 | ``` 26 | **Get Metric Data:**
27 | The get_metric_data method retrieves metrics for a specific namespace, metric, and dimensions within a given time range. 28 | from datetime import datetime, timedelta 29 | ```python 30 | end_time = datetime.utcnow() 31 | start_time = end_time - timedelta(hours=1) 32 | 33 | response = await cloudwatch_handler.get_metric_data( 34 | namespace="AWS/EC2", 35 | metric_name="CPUUtilization", 36 | start_time=start_time, 37 | end_time=end_time, 38 | period=300, # granularity in seconds 39 | statistics=["Average"], # can also use Sum, Minimum, Maximum, etc. 40 | dimensions=[{"Name": "InstanceId", "Value": "i-1234567890abcdef0"}] 41 | ) 42 | print(response) 43 | ``` -------------------------------------------------------------------------------- /tests/agent/test_serper_agent.py: -------------------------------------------------------------------------------- 1 | import logging 2 | 3 | import pytest 4 | 5 | from superagentx.agent import Agent 6 | from superagentx.engine import Engine 7 | from superagentx.handler.serper_dev import SerperDevToolHandler 8 | from superagentx.llm import LLMClient 9 | from superagentx.prompt import PromptTemplate 10 | 11 | logger = logging.getLogger(__name__) 12 | 13 | ''' 14 | Run Pytest: 15 | 16 | 1. pytest --log-cli-level=DEBUG tests/agent/test_serper_agent.py::TestSerperDevAgent::test_search_agent 17 | ''' 18 | 19 | 20 | @pytest.fixture 21 | def agent_client_init() -> dict: 22 | llm_config = {'model': 'gpt-4-turbo-2024-04-09', 'llm_type': 'openai'} 23 | 24 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 25 | response = {'llm': llm_client, 'llm_type': 'openai'} 26 | return response 27 | 28 | 29 | class TestSerperDevAgent: 30 | 31 | @pytest.mark.asyncio 32 | async def test_search_agent(self, agent_client_init: dict): 33 | llm_client: LLMClient = agent_client_init.get('llm') 34 | serper_dev_handler = SerperDevToolHandler() 35 | 36 | prompt_template = PromptTemplate() 37 | serper_search_engine = Engine( 38 | handler=serper_dev_handler, 39 | llm=llm_client, 40 | prompt_template=prompt_template 41 | ) 42 | 43 | goal = """ 44 | List five AI companies started 2024.""" 45 | search_agent = Agent( 46 | goal=goal, 47 | role="You are the analyst", 48 | llm=llm_client, 49 | prompt_template=prompt_template 50 | ) 51 | 52 | await search_agent.add( 53 | serper_search_engine 54 | ) 55 | 56 | result = await search_agent.execute(query_instruction='') 57 | logger.info(f'Result ==> {result}') 58 | assert result 59 | -------------------------------------------------------------------------------- /superagentx_cli/templates/restpipe.py.jinja2: -------------------------------------------------------------------------------- 1 | {# templates/restpipe.py.jinja2 #} 2 | from contextlib import asynccontextmanager 3 | 4 | from fastapi import Depends, FastAPI, HTTPException # https://fastapi.tiangolo.com/ 5 | from fastapi.security import APIKeyHeader 6 | from superagentx.agentxpipe import AgentXPipe 7 | from superagentx.result import GoalResult 8 | 9 | from {{ package_name }}.config import AUTH_TOKEN 10 | from {{ package_name }}.pipe import get_{{ pipe_name }}_pipe 11 | 12 | pipes = {} 13 | 14 | 15 | @asynccontextmanager 16 | async def lifespan(app: FastAPI): 17 | pipes['{{ pipe_name }}_pipe'] = await get_{{ pipe_name }}_pipe() 18 | yield 19 | pipes.clear() 20 | 21 | 22 | {{ package_name }}_app = FastAPI( 23 | title='{{ app_name }} Search', 24 | lifespan=lifespan, 25 | docs_url='/app/rest/docs', 26 | openapi_url='/app/rest/openapi.json' 27 | ) 28 | 29 | 30 | async def verify_api_token( 31 | api_token: str = Depends(APIKeyHeader(name='api-token', auto_error=False)) 32 | ): 33 | if api_token != AUTH_TOKEN: 34 | raise HTTPException(status_code=401, detail='Invalid API Token!') 35 | 36 | 37 | @{{ package_name }}_app.get('/app/rest/health') 38 | async def index(): 39 | return {"name": '{{ app_name }} Search SuperagentX App'} 40 | 41 | 42 | @{{ package_name }}_app.get('/app/rest/search', dependencies=[Depends(verify_api_token)]) 43 | async def search(query: str) -> list[GoalResult]: 44 | {{ pipe_name }}_pipe: AgentXPipe = pipes.get('{{ pipe_name }}_pipe') 45 | return await {{ pipe_name }}_pipe.flow(query_instruction=query) 46 | 47 | 48 | """ 49 | # To Run this, `pip install 'fastapi[standard]'` 50 | 51 | # Development Mode 52 | fastapi dev {{ app_name }}/{{ package_name }}/rest_pipe.py 53 | 54 | # Server Mode 55 | fastapi run {{ app_name }}/{{ package_name }}/rest_pipe.py 56 | """{{'\n'}} -------------------------------------------------------------------------------- /docs/examples/handlers/Gcp/gmail.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Gmail Handler' 3 | icon: 'inbox' 4 | --- 5 | 6 | The Gmail Handler enables seamless interaction with the Gmail API for sending, reading, and managing emails. It handles authentication using OAuth 2.0, and provides methods to fetch user profiles, read emails with attachments, send new emails, and create drafts. It is designed to integrate Gmail into automation workflows securely and efficiently. 7 | 8 | ## Example 9 | 10 | To create the GmailHandler, initialize it with credentials JSON for OAuth: 11 | 12 | ```python 13 | from superagentx_handlers.gcp.gmail import GmailHandler 14 | 15 | gmail_handler = GmailHandler( 16 | credentials="credentials.json" # path to your OAuth 2.0 credentials file 17 | ) 18 | ``` 19 | 20 | **Get User Profile:**
21 | Retrieve Gmail profile information for the authenticated user. 22 | ```python 23 | profile = await gmail_handler.get_user_profile() 24 | print(profile) 25 | ``` 26 | 27 | **Read Emails:**
28 | Fetches the latest emails, including sender, receiver, subject, body, and attachments. 29 | ```python 30 | emails = await gmail_handler.read_mail(max_results=10) 31 | for mail in emails: 32 | print(mail["subject"], mail["sender"]) 33 | ``` 34 | 35 | **Send Email:**
36 | Send an email via Gmail. 37 | ```python 38 | await gmail_handler.send_email( 39 | from_address="you@example.com", 40 | to="friend@example.com", 41 | subject="Hello from GmailHandler", 42 | content="This is a test email!" 43 | ) 44 | ``` 45 | 46 | **Create Draft Email:**
47 | Create a draft email that can be sent later. 48 | ```python 49 | draft = await gmail_handler.create_draft_email( 50 | from_address="you@example.com", 51 | to="friend@example.com", 52 | subject="Draft subject", 53 | content="This is a saved draft message." 54 | ) 55 | print(draft) 56 | ``` 57 | -------------------------------------------------------------------------------- /tests/handlers/test_mcp_handler.py: -------------------------------------------------------------------------------- 1 | import inspect 2 | import logging 3 | 4 | import pytest 5 | from pydantic import typing 6 | 7 | from superagentx.handler.mcp import MCPHandler 8 | 9 | logger = logging.getLogger(__name__) 10 | 11 | ''' 12 | Run Pytest: 13 | 14 | 1. pytest --log-cli-level=INFO tests/handlers/test_mcp_handler.py::TestMCPHandler::test_get_mcp_tools 15 | 16 | ''' 17 | 18 | 19 | @pytest.fixture 20 | def mcp_handler_init() -> MCPHandler: 21 | mcp_handler = MCPHandler(command="npx", 22 | mcp_args=["-y", "@modelcontextprotocol/server-memory"]) 23 | 24 | # mcp_handler = MCPHandler(sse_url="http://0.0.0.0:8080/sse") 25 | 26 | logger.info(mcp_handler) 27 | return mcp_handler 28 | 29 | 30 | class TestMCPHandler: 31 | 32 | @pytest.mark.asyncio 33 | async def test_get_mcp_tools(self, mcp_handler_init: MCPHandler): 34 | tools = await mcp_handler_init.get_mcp_tools() 35 | logger.info(f"MCP Tools {tools}") 36 | 37 | @pytest.mark.asyncio 38 | async def test_load_and_run_if_mcp(self, mcp_handler_init: MCPHandler): 39 | """ 40 | Dynamically loads and runs `get_mcp_tools()` if handler has __type__ = "MCP". 41 | """ 42 | if getattr(mcp_handler_init, "__type__", None) == "MCP": 43 | func = getattr(mcp_handler_init, "get_mcp_tools", None) 44 | if callable(func): 45 | tools = await func() 46 | logger.info(f"Dynamic MCP Tools Loader .. {tools}") 47 | 48 | if isinstance(func, typing.Callable): 49 | _func_name = func.__name__ 50 | _doc_str = inspect.getdoc(func) 51 | _properties = {} 52 | _type_hints = typing.get_type_hints(func) 53 | logger.info(f"Function Name - {list(_type_hints)}") 54 | -------------------------------------------------------------------------------- /tests/agent/task/weather.py: -------------------------------------------------------------------------------- 1 | import logging 2 | 3 | import pytest 4 | import json 5 | from superagentx.agent import Agent 6 | 7 | from superagentx.handler.task.general.api_handler import APIHandler 8 | from superagentx.llm import LLMClient 9 | from superagentx.task_engine import TaskEngine 10 | 11 | logger = logging.getLogger(__name__) 12 | 13 | ''' 14 | Run Pytest: 15 | 16 | 1. pytest --log-cli-level=DEBUG tests/agent/task/weather.py::TestWeatherTaskAgent::test_weather_agent 17 | ''' 18 | 19 | 20 | @pytest.fixture 21 | def agent_client_init() -> dict: 22 | llm_config = {'model': 'gpt-4-turbo-2024-04-09', 'llm_type': 'openai'} 23 | 24 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 25 | response = {'llm': llm_client, 'llm_type': 'openai'} 26 | return response 27 | 28 | 29 | class TestWeatherTaskAgent: 30 | 31 | @pytest.mark.asyncio 32 | async def test_weather_agent(self, agent_client_init: dict): 33 | 34 | engine = TaskEngine( 35 | handler=APIHandler(), 36 | instructions=[ 37 | 38 | # PARALLEL (weather OK, stock FAILS, news OK) 39 | [ 40 | {"fetch_weather": {"city": "San Francisco"}}, 41 | {"fetch_news": {"topic": "AI"}} 42 | ], 43 | 44 | # Combine using $prev.
17 | 18 | ```python 19 | export ATLASSIAN_EMAIL = "**********" 20 | export ATLASSIAN_TOKEN = "*************" 21 | export ATLASSIAN_ORGANIZATION = "***************" 22 | ``` 23 | 24 | ```python jira_handler.py 25 | import os 26 | import asyncio 27 | 28 | from superagentx_handlers.atlassian.jira import JiraHandler 29 | 30 | 31 | async def get_active_sprint(): 32 | jira_handler = JiraHandler( 33 | email="
22 | Retrieves all events scheduled for today. 23 | ```python 24 | events_today = await calendar_handler.get_today_events() 25 | print(events_today) 26 | ``` 27 | 28 | **Get Week Events:**
29 | Retrieves all events scheduled for the next 7 days. 30 | ```python 31 | events_week = await calendar_handler.get_week_events() 32 | print(events_week) 33 | ``` 34 | 35 | **Get Month Events:**
36 | Retrieves all events scheduled for the next 30 days. 37 | ```python 38 | events_month = await calendar_handler.get_month_events() 39 | print(events_month) 40 | ``` 41 | 42 | **Get Events by Custom Days:**
43 | Fetches events for a custom range between 1 and 30 days. 44 | ```python 45 | events_5days = await calendar_handler.get_events_by_days(days=5) 46 | print(events_5days) 47 | ``` 48 | 49 | **Get Events by Type:**
50 | Fetches events of a specific type such as "birthday", "focusTime", or "workingLocation". 51 | ```python 52 | birthday_events = await calendar_handler.get_events_by_type(event_type="birthday") 53 | print(birthday_events) 54 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/aws/ecs.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'ECS Handler' 3 | icon: 'container-storage' 4 | --- 5 | 6 | Amazon ECS (Elastic Container Service) is a fully managed container orchestration service. 7 | It allows you to run Docker containers at scale, with integration to EC2 and Fargate. 8 | The ECS Handler helps fetch **clusters, services, tasks, and container instances**. 9 | 10 | 11 | ## Example 12 | 13 | To create the **ECS Handler**, pass AWS credentials (`access_key`, `secret_key`, and `region`). 14 | 15 | ```python 16 | import os 17 | from superagentx_handlers.aws.ecs import AWSECSHandler 18 | 19 | ecs_handler = AWSECSHandler( 20 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 21 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 22 | region_name="eu-central-1" 23 | ) 24 | ``` 25 | **List Clusters:**
26 | Fetches all ECS clusters. 27 | ```python 28 | clusters = await ecs_handler.list_clusters() 29 | print(clusters) 30 | ``` 31 | 32 | **List Services:**
33 | Lists ECS services running inside a cluster. 34 | ```python 35 | services = await ecs_handler.list_services(cluster="my-cluster") 36 | print(services) 37 | ``` 38 | **List Tasks:**
39 | Lists running tasks inside a service. 40 | ```python 41 | tasks = await ecs_handler.list_tasks(cluster="my-cluster") 42 | print(tasks) 43 | ``` 44 | 45 | **Describe Cluster:**
46 | Fetches detailed information about a cluster. 47 | ```python 48 | cluster_info = await ecs_handler.describe_cluster(cluster="my-cluster") 49 | print(cluster_info) 50 | ``` 51 | **Describe Service:**
52 | Fetches detailed info of a service inside a cluster. 53 | ```python 54 | service_info = await ecs_handler.describe_service( 55 | cluster="my-cluster", 56 | service="my-service" 57 | ) 58 | print(service_info) 59 | ``` 60 | 61 | **Describe Task:**
62 | Fetches details about a specific task. 63 | ```python 64 | task_info = await ecs_handler.describe_task( 65 | cluster="my-cluster", 66 | task="0123456789abcdef0" 67 | ) 68 | print(task_info) 69 | ``` 70 | -------------------------------------------------------------------------------- /docs/examples/handlers/email.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'E-mail Handler' 3 | icon: 'envelope-open-text' 4 | --- 5 | 6 | The EmailHandler is a simple and effective tool for managing email communication in your applications. 7 | It allows you to send emails easily, handle multiple recipients, and include attachments, making it 8 | perfect for both personal and professional use. 9 | 10 | >**From:** The email address of the sender.
11 | **To:** The primary recipient(s) of the email.
12 | **Cc:** Additional recipients who will receive a copy of the email, visible to all.
13 | **Bcc:** Recipients who receive a copy of the email without other recipients knowing their addresses.
14 | **Subject:** A brief summary or title of the email's content.
15 | **Body:** The main content or message of the email, where the sender communicates their thoughts or information. 16 | 17 | ### Setup 18 | Install Postfix locally by running it on your machine. For more detail refer here.
19 | >**Note:** Postfix can run on UNIX-like systems including AIX, BSD, HP-UX, Linux, MacOS X, Solaris, and more. 20 | 21 | ## Example 22 | This code initializes an EmailHandler to connect to an email server using the specified host and port number. 23 | This setup enables sending, receiving, or managing emails programmatically. 24 | ```python email_handler.py 25 | import asyncio 26 | 27 | from superagentx.handler.send_email import EmailHandler 28 | 29 | 30 | async def send_email(): 31 | email_handler = EmailHandler( 32 | host="mail.example.com", 33 | port=0 34 | ) 35 | body = { 36 | "sender": "sample123@abcd.io", 37 | "to": ["test231@abcdf.io"], 38 | "subject": "test", 39 | "body": "Hi" 40 | } 41 | return await email_handler.send_email(**body) 42 | 43 | 44 | async def main(): 45 | res = await send_email() 46 | print(res) 47 | 48 | if __name__ == '__main__': 49 | asyncio.run(main()) 50 | ``` 51 | -------------------------------------------------------------------------------- /tests/browser/test_gdocs.py: -------------------------------------------------------------------------------- 1 | import warnings 2 | with warnings.catch_warnings(): 3 | warnings.simplefilter("ignore", category=UserWarning) 4 | 5 | import logging 6 | import pytest 7 | from superagentx.agent import Agent 8 | from superagentx.browser_engine import BrowserEngine 9 | from superagentx.llm import LLMClient 10 | from superagentx.prompt import PromptTemplate 11 | 12 | logger = logging.getLogger(__name__) 13 | 14 | ''' 15 | Run Pytest: 16 | 17 | 1. pytest -s --log-cli-level=INFO tests/agent/test_gdocs.py::TestDocWriterAgent::test_generation_agent 18 | ''' 19 | 20 | 21 | @pytest.fixture 22 | def agent_client_init() -> dict: 23 | llm_config = {'model': 'gpt-4o', 'llm_type': 'openai'} 24 | 25 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 26 | response = {'llm': llm_client, 'llm_type': 'openai'} 27 | return response 28 | 29 | 30 | class TestDocWriterAgent: 31 | 32 | @pytest.mark.filterwarnings("ignore::UserWarning") 33 | async def test_generation_agent(self, agent_client_init: dict): 34 | llm_client: LLMClient = agent_client_init.get('llm') 35 | 36 | prompt_template = PromptTemplate() 37 | 38 | browser_engine = BrowserEngine( 39 | llm=llm_client, 40 | prompt_template=prompt_template, 41 | # browser_instance_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' 42 | ) 43 | 44 | goal = """Complete the user's input.""" 45 | 46 | marketing_agent = Agent( 47 | goal=goal, 48 | role="You are the AI Assistant", 49 | llm=llm_client, 50 | prompt_template=prompt_template, 51 | max_retry=1, 52 | engines=[browser_engine] 53 | ) 54 | 55 | task = 'In docs.google.com write about SuperAgentX' 56 | 57 | query_instruction = task 58 | 59 | result = await marketing_agent.execute( 60 | query_instruction=query_instruction 61 | ) 62 | logger.info(f'Result ==> {result}') 63 | assert result -------------------------------------------------------------------------------- /docs/examples/handlers/aws/elb.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'ELB Handler' 3 | icon: 'server' 4 | --- 5 | 6 | Amazon Elastic Load Balancing (ELBv2) automatically distributes incoming application traffic across multiple targets, such as Amazon EC2 instances, containers, and IP addresses. 7 | It provides high availability, automatic scaling, and robust security features, and supports multiple load balancer types (Application, Network, and Gateway). 8 | This handler focuses on **Application Load Balancers (ALBs)** and retrieves details about load balancers, listeners, listener rules, target groups, and target health. 9 | 10 | 11 | ## Example 12 | 13 | To create the 'AWSElasticLoadBalancerHandler' object, you must provide AWS credentials: 14 | 15 | ```python elb_handler_test.py 16 | import os 17 | from superagentx_handlers.aws.elb import AWSElasticLoadBalancerHandler 18 | 19 | elb_handler = AWSElasticLoadBalancerHandler( 20 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 21 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 22 | region_name="us-east-1" 23 | ) 24 | ``` 25 | **Get ELB Details:**
26 | Fetches all Application Load Balancer (ALB) details, including listeners, rules, target groups, and target health. 27 | ```python 28 | elb_details = await elb_handler.get_elb_details() 29 | print(elb_details) 30 | ``` 31 | **Collect Target Groups from Default Actions and Rules:**
32 | Collects all target groups referenced in listeners’ default actions and custom rules. 33 | ```python 34 | target_groups = await elb_handler.collect_target_groups_from_listeners("arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/my-alb/abc123") 35 | print(target_groups) 36 | ``` 37 | 38 | **Fetch Detailed Target Group Info:**
39 | Fetches complete target group configuration and health status, including protocol, port, health check config, and registered targets. 40 | ```python 41 | tg_info = await elb_handler.get_target_group_info("arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/my-tg/ghi789") 42 | print(tg_info) 43 | ``` 44 | -------------------------------------------------------------------------------- /tests/conversation/test_conversation_pipe.py: -------------------------------------------------------------------------------- 1 | import asyncio 2 | import uuid 3 | 4 | from rich import print as rprint 5 | 6 | from superagentx.agent import Agent 7 | from superagentx.agentxpipe import AgentXPipe 8 | from superagentx.engine import Engine 9 | from superagentx.handler.ai import AIHandler 10 | from superagentx.llm import LLMClient 11 | from superagentx.memory import Memory 12 | from superagentx.prompt import PromptTemplate 13 | 14 | 15 | async def get_test_ai_handler_pipe() -> AgentXPipe: 16 | # LLM Configuration 17 | llm_config = { 18 | 'llm_type': 'openai' 19 | } 20 | llm_client = LLMClient(llm_config=llm_config) 21 | 22 | # Enable Memory 23 | memory = Memory(memory_config={"llm_client": llm_client}) 24 | 25 | ai_handler = AIHandler( 26 | llm=llm_client 27 | ) 28 | 29 | # Prompt Template 30 | prompt_template = PromptTemplate() 31 | 32 | # Create Engine 33 | ai_engine = Engine( 34 | handler=ai_handler, 35 | llm=llm_client, 36 | prompt_template=prompt_template 37 | ) 38 | 39 | # Create Agents 40 | ai_agent = Agent( 41 | name='AI agent', 42 | goal="Get me the best results", 43 | role="You are the best at answering", 44 | llm=llm_client, 45 | prompt_template=prompt_template, 46 | engines=[ai_engine] 47 | ) 48 | 49 | # Expose via pipe for interaction 50 | pipe = AgentXPipe( 51 | agents=[ai_agent], 52 | memory=memory 53 | ) 54 | 55 | return pipe 56 | 57 | 58 | conversation_id = uuid.uuid4().hex # Unique ID for tracking this conversation 59 | 60 | async def main(): 61 | 62 | conversation_pipe = await get_test_ai_handler_pipe() 63 | 64 | while True: 65 | user_input = input(f"Enter Your Query Here: ") 66 | result = await conversation_pipe.flow( 67 | query_instruction=user_input, 68 | conversation_id=conversation_id # Context maintained here 69 | ) 70 | print(result) 71 | 72 | 73 | if __name__ == "__main__": 74 | asyncio.run(main()) -------------------------------------------------------------------------------- /docs/examples/handlers/aws/cloudfront.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'CloudFront Handler' 3 | icon: 'globe' 4 | --- 5 | 6 | Amazon CloudFront is a fast Content Delivery Network (CDN) service that securely delivers data, videos, applications, 7 | and APIs to customers globally with low latency and high transfer speeds. CloudFront works seamlessly with services 8 | like S3, API Gateway, and ACM for SSL/TLS certificates. 9 | 10 | ## Example 11 | To create the AWSCloudFrontHandler object with AWS credentials. 12 | The AWSCloudFrontHandler enables you to interact with CloudFront for tasks such as 13 | listing distributions, cache behaviors, access control settings, and certificates. 14 | 15 | ```python cloudfront_handler_test.py 16 | import os 17 | 18 | from superagentx_handlers.aws.cloudfront import AWSCloudFrontHandler 19 | 20 | 21 | cloudfront_handler = AWSCloudFrontHandler( 22 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 23 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 24 | region_name="us-east-1" 25 | ) 26 | ``` 27 | 28 | **List Distributions:**
29 | The list_distributions method retrieves all CloudFront distributions. 30 | ```python 31 | distributions = await cloudfront_handler.list_distributions() 32 | print(distributions) 33 | ``` 34 | 35 | **List Certificates:**
36 | The list_certificates method retrieves all ACM-managed certificates in us-east-1, 37 | typically used with CloudFront. 38 | ```python 39 | certificates = await cloudfront_handler.list_certificates() 40 | print(certificates) 41 | ``` 42 | 43 | **List Cache Behaviors:**
44 | The list_cache_behaviors method shows default and ordered cache behaviors for all distributions. 45 | ```python 46 | cache_behaviors = await cloudfront_handler.list_cache_behaviors() 47 | print(cache_behaviors) 48 | ``` 49 | 50 | **List Access Control Configurations:**
51 | The list_access_control_configs method retrieves access control settings like geo-restrictions and WAF associations. 52 | ```python 53 | access_controls = await cloudfront_handler.list_access_control_configs() 54 | print(access_controls) 55 | ``` -------------------------------------------------------------------------------- /tests/agent/test_mcp_reddit_agent.py: -------------------------------------------------------------------------------- 1 | import json 2 | import logging 3 | 4 | import pytest 5 | 6 | from superagentx.agent import Agent 7 | from superagentx.engine import Engine 8 | from superagentx.handler.mcp import MCPHandler 9 | from superagentx.llm import LLMClient 10 | from superagentx.prompt import PromptTemplate 11 | 12 | logger = logging.getLogger(__name__) 13 | 14 | 15 | @pytest.fixture 16 | def agent_client_init() -> dict: 17 | llm_config = {'model': 'openai/gpt-5-mini'} 18 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 19 | return {'llm': llm_client, 'llm_type': 'openai'} 20 | 21 | 22 | async def status_callback(event: str, **kwargs): 23 | logger.info(f"[Callback] Event: {event}") 24 | logger.info(f"[Callback] Event: {event}, Data: {kwargs}") 25 | 26 | 27 | class TestMCPRedditAgent: 28 | 29 | @pytest.mark.asyncio 30 | async def test_reddit_search_agent(self, agent_client_init: dict): 31 | llm_client: LLMClient = agent_client_init.get('llm') 32 | 33 | # MCP Tool - pip install mcp-server-reddit 34 | mcp_handler = MCPHandler(command="uvx", mcp_args=["mcp-server-reddit"]) 35 | prompt_template = PromptTemplate() 36 | 37 | # ✅ Enable engine to execute MCP Tools 38 | mcp_engine = Engine(handler=mcp_handler, llm=llm_client, prompt_template=prompt_template) 39 | 40 | goal = "Review and perform user's input" 41 | 42 | # ✅ SuperAgentX Agent 43 | reddit_search_agent = Agent( 44 | goal=goal, 45 | role="You're an Analyst", 46 | llm=llm_client, 47 | prompt_template=prompt_template, 48 | max_retry=1 49 | ) 50 | await reddit_search_agent.add(mcp_engine) 51 | 52 | # ✅ Ask question with live callback 53 | result = await reddit_search_agent.execute( 54 | query_instruction="What are the current hot posts on Reddit's frontpage and summarize?", 55 | status_callback=status_callback # <-- callback passed here 56 | ) 57 | 58 | # logger.info(f'Result ==> {result}') 59 | assert result 60 | -------------------------------------------------------------------------------- /tests/browser/test_check_appointment.py: -------------------------------------------------------------------------------- 1 | import warnings 2 | 3 | from superagentx.agentxpipe import AgentXPipe 4 | 5 | with warnings.catch_warnings(): 6 | warnings.simplefilter("ignore", category=UserWarning) 7 | 8 | import logging 9 | import pytest 10 | from superagentx.agent import Agent 11 | from superagentx.browser_engine import BrowserEngine 12 | from superagentx.llm import LLMClient 13 | from superagentx.prompt import PromptTemplate 14 | 15 | logger = logging.getLogger(__name__) 16 | 17 | ''' 18 | Run Pytest: 19 | 20 | 1. pytest --log-cli-level=INFO tests/browser/test_check_appointment.py::test_check_appointment 21 | ''' 22 | 23 | 24 | @pytest.fixture 25 | def agent_client_init() -> dict: 26 | llm_config = {'model': 'gpt-4o', 'llm_type': 'openai'} 27 | 28 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 29 | response = {'llm': llm_client, 'llm_type': 'openai'} 30 | return response 31 | 32 | 33 | @pytest.mark.filterwarnings("ignore::UserWarning") 34 | async def test_check_appointment(agent_client_init: dict): 35 | llm_client: LLMClient = agent_client_init.get('llm') 36 | prompt_template = PromptTemplate() 37 | browser_engine = BrowserEngine( 38 | llm=llm_client, 39 | prompt_template=prompt_template, 40 | # browser_instance_path="/usr/bin/google-chrome-stable" 41 | ) 42 | goal = """Complete the user's input.""" 43 | browser_agent = Agent( 44 | goal=goal, 45 | role="You are the AI Assistant", 46 | llm=llm_client, 47 | prompt_template=prompt_template, 48 | max_retry=1, 49 | engines=[browser_engine] 50 | ) 51 | 52 | pipe = AgentXPipe( 53 | agents=[browser_agent], 54 | # memory=memory 55 | ) 56 | 57 | task = ( 58 | 'Go to the Greece MFA webpage via the link I provided you.https://appointment.mfa.gr/en/reservations/aero/ireland-grcon-dub/' 59 | 'Check the visa appointment dates. If there is no available date in this month, check the next month.' 60 | 'If there is no available date in both months, tell me there is no available date.' 61 | ) 62 | 63 | await pipe.flow( 64 | query_instruction=task 65 | ) -------------------------------------------------------------------------------- /docs/examples/handlers/Gcp/api_gateway.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'API Gateway Handler' 3 | icon: 'server' 4 | --- 5 | 6 | Google Cloud API Gateway is a fully managed service that allows developers to create, secure, and monitor APIs for their applications. It enables seamless management of APIs at scale, integrates with IAM for authentication, and provides features like quota management, monitoring, and logging. 7 | 8 | The `GCPAPIGatewayHandler` helps interact with Google Cloud’s API Gateway service to fetch gateway details programmatically. 9 | 10 | ## Example 11 | 12 | To create the `GCPAPIGatewayHandler` object, initialize it with your Google service account credentials (JSON file path or dictionary). 13 | 14 | ```python 15 | from superagentx_handlers.gcp.api_gateway import GCPAPIGatewayHandler 16 | 17 | gateway_handler = GCPAPIGatewayHandler( 18 | creds="service-account.json" # or dict with service account info 19 | ) 20 | ``` 21 | 22 | **List API Gateways:**
23 | Lists all API Gateways available in your GCP project across supported regions. 24 | ```python 25 | gateways = await gateway_handler.list_gateways(page_size=50) 26 | for g in gateways: 27 | print(g["name"], g["state"], g["default_hostname"]) 28 | ``` 29 | 30 | **Convert Gateway to Dictionary (_gateway_to_dict):**
31 | Converts a Gateway object into a structured dictionary with useful metadata. 32 | ```python 33 | gateway_obj = (await gateway_handler.client.list_gateways( 34 | request={"parent": "projects/my-project/locations/us-central1"} 35 | )).pages[0][0] 36 | 37 | gateway_dict = await gateway_handler._gateway_to_dict(gateway_obj, location="us-central1") 38 | print(gateway_dict) 39 | ``` 40 | 41 | **Get Gateway State (_get_gateway_state):**
42 | Converts a raw state value (string, int, or enum) into a Gateway.State enum. 43 | ```python 44 | from google.cloud import apigateway_v1 45 | 46 | # Using string 47 | print(_get_gateway_state("CREATING").name) # Output: CREATING 48 | 49 | # Using integer (matches enum value) 50 | print(_get_gateway_state(1).name) # Output: ACTIVE 51 | 52 | # Using enum directly 53 | print(_get_gateway_state(apigateway_v1.Gateway.State.FAILED).name) # Output: FAILED 54 | ``` 55 | -------------------------------------------------------------------------------- /superagentx/llm/types/response.py: -------------------------------------------------------------------------------- 1 | from datetime import datetime 2 | from typing import Any 3 | 4 | from pydantic import BaseModel, Field 5 | 6 | 7 | class Tool(BaseModel): 8 | name: str = Field( 9 | ..., 10 | description="The name of the function to call." 11 | ) 12 | 13 | arguments: dict[str, Any] | None = Field( 14 | default=None, 15 | description="The arguments to call the function with, as generated by the model in JSON format" 16 | ) 17 | 18 | tool_type: str | None = Field( 19 | default=None, 20 | description="The type of the tool" 21 | ) 22 | 23 | 24 | class Message(BaseModel): 25 | role: str = Field( 26 | ..., 27 | description="Role of the message sender, e.g., 'assistant', 'user', or 'system'" 28 | ) 29 | 30 | model: str = Field( 31 | ..., 32 | description="The model used for the chat completion." 33 | ) 34 | 35 | content: str | None = Field( 36 | default=None, 37 | description="Content of the message" 38 | ) 39 | 40 | tool_calls: list[Tool] | None = Field( 41 | default=None, 42 | description="The name and arguments of a function that should be called, as generated by the model." 43 | ) 44 | 45 | system_fingerprint: str | None = Field( 46 | default=None, 47 | description="This fingerprint represents the backend configuration that the model runs with" 48 | ) 49 | 50 | completion_tokens: int = Field( 51 | default=0, 52 | description="Number of tokens in the generated completion." 53 | ) 54 | 55 | prompt_tokens: int = Field( 56 | default=0, 57 | description="Number of tokens in the prompt." 58 | ) 59 | 60 | total_tokens: int = Field( 61 | default=0, 62 | description="Total number of tokens used in the request (prompt + completion)." 63 | ) 64 | 65 | reasoning_tokens: int = Field( 66 | default=0, 67 | description="Tokens generated by the model for reasoning." 68 | ) 69 | 70 | created: datetime = Field( 71 | description="The timestamp when the message was created, in datetime format." 72 | ) # Updated created field as datetime 73 | -------------------------------------------------------------------------------- /docs/examples/handlers/elastic.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Elastic Search Handler' 3 | icon: 'circle-e' 4 | --- 5 | 6 | Elasticsearch is a powerful, open-source search and analytics engine based on Apache Lucene. It quickly stores, 7 | searches, and analyzes large amounts of data by creating indexes, rather than searching the text directly. With 8 | a document-based structure and easy-to-use REST APIs, it processes and returns data in JSON format, offering 9 | fast and scalable performance. 10 | 11 | ### Setup 12 | Install Elasticsearch locally by running it on your machine. The simplest method is to use the official 13 | Elasticsearch Docker image. For more details, check the Elasticsearch Docker documentation. 14 | 15 | ## Example 16 | This code initializes an ElasticsearchHandler to connect to an Elasticsearch server running on localhost with specified 17 | username and password. This setup allows for searching and managing data stored in Elasticsearch efficiently. 18 | 19 | ```python elastic_handler.py 20 | import asyncio 21 | 22 | from superagentx.handler.elastic_search import ElasticsearchHandler 23 | 24 | 25 | async def create_index(): 26 | elasticsearch_handler = ElasticsearchHandler( 27 | hosts="http://localhost:9200", 28 | username="
29 | Retrieves all function apps across the given subscription. 30 | ```python 31 | function_apps = await azure_handler.get_all_function_apps_in_subscription() 32 | print(function_apps) 33 | ``` 34 | 35 | **List Function Apps by Resource Group:**
36 | Get all function apps inside a specific resource group. 37 | ```python 38 | apps_in_rg = await azure_handler.get_function_apps_by_resource_group("my-resource-group") 39 | print(apps_in_rg) 40 | ``` 41 | 42 | **Get a Specific Function App by Name:**
43 | Retrieve metadata and configuration of a specific function app. 44 | ```python 45 | function_app = await azure_handler.get_function_app_by_name( 46 | resource_group_name="my-resource-group", 47 | function_app_name="my-function-app" 48 | ) 49 | print(function_app) 50 | ``` 51 | 52 | **Get Function App Configuration:**
53 | Fetches site configuration, app settings, and connection strings. 54 | ```python 55 | config = await azure_handler.get_function_app_configuration( 56 | resource_group_name="my-resource-group", 57 | function_app_name="my-function-app" 58 | ) 59 | print(config) 60 | ``` -------------------------------------------------------------------------------- /superagentx/handler/serper_dev.py: -------------------------------------------------------------------------------- 1 | import os 2 | import json 3 | import aiohttp 4 | 5 | from superagentx.handler.base import BaseHandler 6 | from superagentx.handler.decorators import tool 7 | 8 | 9 | class SerperDevToolHandler(BaseHandler): 10 | 11 | def __init__(self): 12 | super().__init__() 13 | self.search_url: str = "https://google.serper.dev/search" 14 | 15 | @tool 16 | async def search( 17 | self, 18 | *, 19 | query: str, 20 | total_results: int = 5 21 | ): 22 | """ 23 | A tool for performing real-time web searches and retrieving structured results based on the provided query. 24 | 25 | Parameters: 26 | query(str): The search text or query to find relevant information. 27 | total_results(int): Number of total results 28 | 29 | Return: 30 | List of Dict 31 | """ 32 | 33 | payload = json.dumps({ 34 | "q": query 35 | }) 36 | 37 | headers = { 38 | "X-API-KEY": os.environ["SERPER_API_KEY"], 39 | "content-type": "application/json", 40 | } 41 | results = [] 42 | async with aiohttp.ClientSession() as session: 43 | async with session.post( 44 | self.search_url, 45 | headers=headers, 46 | data=payload, 47 | ) as response: 48 | search_results = await response.json() 49 | 50 | if "organic" in search_results: 51 | results = search_results["organic"][: total_results] 52 | string = [] 53 | for result in results: 54 | try: 55 | string.append( 56 | "\n".join( 57 | [ 58 | f"Title: {result['title']}", 59 | f"Link: {result['link']}", 60 | f"Snippet: {result['snippet']}", 61 | "---", 62 | ] 63 | ) 64 | ) 65 | except KeyError: 66 | continue 67 | return results 68 | -------------------------------------------------------------------------------- /superagentx/utils/parsers/list.py: -------------------------------------------------------------------------------- 1 | import re 2 | 3 | from superagentx.utils.helper import iter_to_aiter 4 | from superagentx.utils.parsers.base import BaseParser 5 | 6 | 7 | class CommaSeparatedListOutputParser(BaseParser): 8 | 9 | async def parse(self, text: str) -> list[str]: 10 | """Parse the output of an LLM call. 11 | 12 | Args: 13 | text: The output of an LLM call. 14 | 15 | Returns: 16 | A list of strings. 17 | """ 18 | return [part.strip() async for part in iter_to_aiter(text.split(","))] 19 | 20 | async def get_format_instructions(self) -> str: 21 | """Return the format instructions for the comma-separated list output.""" 22 | return ( 23 | "Your response should be a list of comma separated values, " 24 | "eg: `foo, bar, baz` or `foo,bar,baz`" 25 | ) 26 | 27 | 28 | class NumberedListOutputParser(BaseParser): 29 | """Parse a numbered list.""" 30 | 31 | pattern: str = r"\d+\.\s([^\n]+)" 32 | """The pattern to match a numbered list item.""" 33 | 34 | async def get_format_instructions(self) -> str: 35 | return ( 36 | "Your response should be a numbered list with each item on a new line. " 37 | "For example: \n\n1. foo\n\n2. bar\n\n3. baz" 38 | ) 39 | 40 | async def parse(self, text: str) -> list[str]: 41 | """Parse the output of an LLM call. 42 | 43 | Args: 44 | text: The output of an LLM call. 45 | 46 | Returns: 47 | A list of strings. 48 | """ 49 | return re.findall(self.pattern, text) 50 | 51 | 52 | class MarkdownListOutputParser(BaseParser): 53 | """Parse a Markdown list.""" 54 | 55 | pattern: str = r"^\s*[-*]\s([^\n]+)$" 56 | """The pattern to match a Markdown list item.""" 57 | 58 | async def get_format_instructions(self) -> str: 59 | """Return the format instructions for the Markdown list output.""" 60 | return "Your response should be a markdown list, " "eg: `- foo\n- bar\n- baz`" 61 | 62 | async def parse(self, text: str) -> list[str]: 63 | """Parse the output of an LLM call. 64 | 65 | Args: 66 | text: The output of an LLM call. 67 | 68 | Returns: 69 | A list of strings. 70 | """ 71 | return re.findall(self.pattern, text, re.MULTILINE) 72 | -------------------------------------------------------------------------------- /superagentx/handler/exa_search.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | from exa_py import Exa 4 | 5 | from superagentx.handler.base import BaseHandler 6 | from superagentx.handler.decorators import tool 7 | from superagentx.utils.helper import sync_to_async 8 | 9 | 10 | class ExaHandler(BaseHandler): 11 | """ 12 | A handler class for managing interactions with an Exa database. 13 | This class extends BaseHandler and provides methods to perform various database operations, 14 | such as executing queries, managing tables, and handling data transactions in an Exa environment. 15 | """ 16 | 17 | def __init__( 18 | self, 19 | api_key: str | None = None 20 | ): 21 | super().__init__() 22 | api_key = api_key or os.getenv("EXA_API_KEY") 23 | self.exa = Exa(api_key=api_key) 24 | 25 | @tool 26 | async def search_contents( 27 | self, 28 | *, 29 | query: str, 30 | use_autoprompt: bool, 31 | num_results: int = 10, 32 | search_type: str | None = None 33 | ): 34 | """ 35 | Asynchronously searches content based on the query, with options to use autoprompt, limit the number of results, 36 | and filter by search type. Customizes the search experience according to the provided parameters. 37 | 38 | Parameters: 39 | query (str): The search query string used to find relevant content. 40 | use_autoprompt (bool): If True, the method will leverage autoprompt suggestions to enhance the search 41 | results. 42 | num_results (int | None, optional): The maximum number of search results to return. Defaults to 10. 43 | If set to None, all available results may be returned. 44 | search_type (str | None, optional): Specifies the type of search to perform. Defaults to None, 45 | in which case a general search is performed. 46 | 47 | Returns: 48 | Any: The search results, which may vary depending on the search type and query. 49 | 50 | """ 51 | if not search_type: 52 | search_type = "auto" 53 | 54 | return await sync_to_async( 55 | self.exa.search_and_contents, 56 | query=query, 57 | type=search_type, 58 | use_autoprompt=use_autoprompt, 59 | num_results=num_results, 60 | ) 61 | -------------------------------------------------------------------------------- /superagentx/io/base.py: -------------------------------------------------------------------------------- 1 | 2 | import logging 3 | from contextlib import contextmanager 4 | from contextvars import ContextVar 5 | from typing import Any, Iterator, Optional, Protocol, runtime_checkable, Self 6 | 7 | logger = logging.getLogger(__name__) 8 | 9 | 10 | @runtime_checkable 11 | class OutputStream(Protocol): 12 | async def write( 13 | self, 14 | *objects: Any, 15 | sep: str | None = None, 16 | end: str | None = None, 17 | flush: bool = False 18 | ) -> None: 19 | """Print data to the output stream.""" 20 | 21 | 22 | @runtime_checkable 23 | class InputStream(Protocol): 24 | async def read( 25 | self, 26 | prompt: str | None = None, 27 | *, 28 | password: bool = False 29 | ) -> str: 30 | """Read a line from the input stream.""" 31 | 32 | 33 | @runtime_checkable 34 | class IOStream(InputStream, OutputStream, Protocol): 35 | """A protocol for input/output streams.""" 36 | 37 | _default_io_stream: ContextVar[Self | None] = ContextVar("default_iostream", default=None) 38 | _global_default: Self | None = None 39 | 40 | @staticmethod 41 | def set_global_io_stream(stream: "IOStream") -> None: 42 | """Set the global default IO stream.""" 43 | IOStream._global_default = stream 44 | 45 | @staticmethod 46 | def get_global_io_stream() -> "IOStream": 47 | """Get the global default IO stream.""" 48 | if IOStream._global_default is None: 49 | raise RuntimeError("No global default IOStream has been set.") 50 | return IOStream._global_default 51 | 52 | @staticmethod 53 | def get_current_io_stream() -> "IOStream": 54 | """Get the current context's default IO stream.""" 55 | iostream = IOStream._default_io_stream.get() 56 | if iostream is None: 57 | iostream = IOStream.get_global_io_stream() 58 | IOStream.override_default_io_stream(iostream) 59 | return iostream 60 | 61 | @staticmethod 62 | @contextmanager 63 | async def override_default_io_stream(stream: Optional["IOStream"]) -> Iterator[None]: 64 | """Temporarily override the default IO stream for the current context.""" 65 | token = IOStream._default_io_stream.set(stream) 66 | try: 67 | yield 68 | finally: 69 | IOStream._default_io_stream.reset(token) 70 | -------------------------------------------------------------------------------- /superagentx/llm/constants.py: -------------------------------------------------------------------------------- 1 | OPENAI_PRICE1K = { 2 | "gpt-4.1": (0.005, 0.015), 3 | "gpt-4o": (0.005, 0.015), 4 | "gpt-4o-2024-05-13": (0.005, 0.015), 5 | "gpt-4o-2024-08-06": (0.0025, 0.01), 6 | # gpt-4-turbo 7 | "gpt-4-turbo-2024-04-09": (0.01, 0.03), 8 | # gpt-4 9 | "gpt-4": (0.03, 0.06), 10 | "gpt-4-32k": (0.06, 0.12), 11 | # gpt-4o-mini 12 | "gpt-4o-mini": (0.000150, 0.000600), 13 | "gpt-4o-mini-2024-07-18": (0.000150, 0.000600), 14 | # gpt-3.5 turbo 15 | "gpt-3.5-turbo": (0.0005, 0.0015), # default is 0125 16 | "gpt-3.5-turbo-0125": (0.0005, 0.0015), # 16k 17 | "gpt-3.5-turbo-instruct": (0.0015, 0.002), 18 | # base model 19 | "davinci-002": 0.002, 20 | "babbage-002": 0.0004, 21 | # old model 22 | "gpt-4-0125-preview": (0.01, 0.03), 23 | "gpt-4-1106-preview": (0.01, 0.03), 24 | "gpt-4-1106-vision-preview": (0.01, 0.03), 25 | "gpt-3.5-turbo-1106": (0.001, 0.002), 26 | "gpt-3.5-turbo-0613": (0.0015, 0.002), 27 | # "gpt-3.5-turbo-16k": (0.003, 0.004), 28 | "gpt-3.5-turbo-16k-0613": (0.003, 0.004), 29 | "gpt-3.5-turbo-0301": (0.0015, 0.002), 30 | "text-ada-001": 0.0004, 31 | "text-babbage-001": 0.0005, 32 | "text-curie-001": 0.002, 33 | "code-cushman-001": 0.024, 34 | "code-davinci-002": 0.1, 35 | "text-davinci-002": 0.02, 36 | "text-davinci-003": 0.02, 37 | "gpt-4-0314": (0.03, 0.06), # deprecate in Sep 38 | "gpt-4-32k-0314": (0.06, 0.12), # deprecate in Sep 39 | "gpt-4-0613": (0.03, 0.06), 40 | "gpt-4-32k-0613": (0.06, 0.12), 41 | "gpt-4-turbo-preview": (0.01, 0.03), 42 | # https://azure.microsoft.com/en-us/pricing/details/cognitive-services/openai-service/#pricing 43 | "gpt-35-turbo": (0.0005, 0.0015), # what's the default? using 0125 here. 44 | "gpt-35-turbo-0125": (0.0005, 0.0015), 45 | "gpt-35-turbo-instruct": (0.0015, 0.002), 46 | "gpt-35-turbo-1106": (0.001, 0.002), 47 | "gpt-35-turbo-0613": (0.0015, 0.002), 48 | "gpt-35-turbo-0301": (0.0015, 0.002), 49 | "gpt-35-turbo-16k": (0.003, 0.004), 50 | "gpt-35-turbo-16k-0613": (0.003, 0.004), 51 | } 52 | 53 | DEFAULT_OPENAI_EMBED = "text-embedding-ada-002" 54 | DEFAULT_BEDROCK_EMBED = "amazon.titan-embed-g1-text-02" 55 | DEFAULT_ANTHROPIC_EMBED = 'sentence-transformers/all-MiniLM-L6-v2' 56 | DEFAULT_OLLAMA_EMBED = "mxbai-embed-large" 57 | DEFAULT_EMBED = 'sentence-transformers/all-MiniLM-L6-v2' 58 | DEFAULT_GEMINI_EMBED = "gemini-embedding-exp-03-07" 59 | -------------------------------------------------------------------------------- /superagentx/utils/llm_config.py: -------------------------------------------------------------------------------- 1 | from enum import Enum 2 | 3 | 4 | class LLMType(str, Enum): 5 | OPENAI_CLIENT = 'openai' 6 | AZURE_OPENAI_CLIENT = 'azure-openai' 7 | DEEPSEEK = 'deepseek' 8 | LLAMA_CLIENT = 'llama' 9 | GEMINI_CLIENT = 'gemini' 10 | MISTRAL_CLIENT = 'mistral' 11 | BEDROCK_CLIENT = 'bedrock' 12 | TOGETHER_CLIENT = 'together' 13 | GROQ_CLIENT = 'groq' 14 | ANTHROPIC_CLIENT = 'anthropic' 15 | OLLAMA = 'ollama' 16 | LITELLM = 'litellm' 17 | 18 | @classmethod 19 | def has_member_key(cls, key): 20 | return key in cls.__members__ 21 | 22 | @classmethod 23 | def has_member_value(cls, value) -> bool: 24 | try: 25 | if cls(value): 26 | return True 27 | except ValueError: 28 | return False 29 | 30 | 31 | OPENAI_MODELS = [ 32 | "gpt-4.1-mini", 33 | "gpt-4.1", 34 | "gpt-4o", 35 | "gpt-4o-2024-05-13", 36 | "gpt-4o-2024-08-06", 37 | "gpt-4-turbo-2024-04-09", 38 | "gpt-4", 39 | "gpt-4o-mini-2024-07-18", 40 | "gpt-4o-mini", 41 | "text-embedding-ada-002", 42 | "text-embedding-3-small", 43 | "text-embedding-3-large" 44 | ] 45 | 46 | BEDROCK_MODELS = [ 47 | 'anthropic.claude-3-5-sonnet-20241022-v2:0', 48 | 'anthropic.claude-3-5-haiku-20241022-v1:0', 49 | 'anthropic.claude-instant-v1:2:100k', 50 | 'anthropic.claude-3-sonnet-20240229-v1:0', 51 | 'anthropic.claude-3-haiku-20240307-v1:0', 52 | 'anthropic.claude-3-opus-20240229-v1:0', 53 | 'anthropic.claude-3-5-sonnet-20240620-v1:0', 54 | 'cohere.command-r-v1:0', 55 | 'cohere.command-r-plus-v1:0', 56 | 'meta.llama3-1-8b-instruct-v1:0', 57 | 'meta.llama3-1-70b-instruct-v1:0', 58 | 'meta.llama3-1-405b-instruct-v1:0', 59 | 'meta.llama3-2-11b-instruct-v1:0', 60 | 'meta.llama3-2-90b-instruct-v1:0', 61 | 'meta.llama3-2-1b-instruct-v1:0', 62 | 'meta.llama3-2-3b-instruct-v1:0', 63 | 'mistral.mistral-large-2402-v1:0', 64 | 'mistral.mistral-large-2407-v1:0' 65 | ] 66 | 67 | ANTHROPIC_MODELS = [ 68 | 'claude-3-5-sonnet-20241022', 69 | 'claude-3-5-haiku-20241022', 70 | 'claude-3-opus-20240229', 71 | 'claude-3-sonnet-20240229', 72 | 'claude-3-haiku-20240307' 73 | ] 74 | 75 | DEEPSEEK_MODELS = [ 76 | "deepseek-chat", 77 | ] 78 | 79 | OLLAMA_MODELS = [ 80 | "mistral:latest", 81 | "llama3.3:latest", 82 | ] 83 | 84 | # Azure Open AI Version - Default 85 | DEFAULT_AZURE_API_VERSION = "2024-02-01" 86 | -------------------------------------------------------------------------------- /tests/browser/cricket_tweet.py: -------------------------------------------------------------------------------- 1 | import asyncio 2 | import logging 3 | import warnings 4 | 5 | from rich import print as rprint 6 | 7 | from superagentx.agent import Agent 8 | from superagentx.browser_engine import BrowserEngine 9 | from superagentx.llm import LLMClient 10 | from superagentx.prompt import PromptTemplate 11 | 12 | warnings.filterwarnings('ignore') 13 | 14 | sh = logging.StreamHandler() 15 | logging.basicConfig( 16 | level="INFO", 17 | format='%(asctime)s -%(levelname)s - %(name)s - %(funcName)s: %(message)s', 18 | datefmt='%Y-%m-%d %H:%M:%S', 19 | handlers=[sh] 20 | ) 21 | 22 | 23 | async def main(): 24 | llm_config = {'model': 'gpt-4o', 'llm_type': 'openai', 'async_mode': True} 25 | llm_config = {'llm_type': 'gemini', 'model': 'gemini-2.0-flash'} 26 | # llm_config = {"model": 'anthropic.claude-3-5-haiku-20241022-v1:0', "llm_type": 'bedrock'} 27 | 28 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 29 | 30 | prompt_template = PromptTemplate() 31 | 32 | browser_engine = BrowserEngine( 33 | llm=llm_client, 34 | prompt_template=prompt_template, 35 | # browser_instance_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' 36 | ) 37 | query_instruction = "Which team have 5 trophies in IPL" 38 | 39 | task = f""" 40 | 1. Analyse and find the result for the given {query_instruction}. 41 | 2. Goto https://x.com/compose/post and click and set focus. Wait until user manual login. 42 | 3. Write the a detail result. 43 | 3. Review the tweet before post it for submit. 44 | 4. Submit the button to tweet the result! 45 | 46 | Important: 47 | 1. DO NOT write the post as reply 48 | 2. DO NOT post more than one. 49 | 3. Strictly Follow the instructions 50 | 51 | """ 52 | 53 | cricket_analyse_agent = Agent( 54 | goal="Complete user's task.", 55 | role="You are a Cricket Expert Reviewer", 56 | llm=llm_client, 57 | prompt_template=prompt_template, 58 | max_retry=1, 59 | engines=[browser_engine] 60 | ) 61 | 62 | result = await cricket_analyse_agent.execute( 63 | query_instruction=task 64 | ) 65 | rprint(result) 66 | 67 | 68 | if __name__ == '__main__': 69 | try: 70 | asyncio.run(main()) 71 | except (KeyboardInterrupt, asyncio.CancelledError): 72 | rprint("\nUser canceled the [bold yellow][i]pipe[/i]!") -------------------------------------------------------------------------------- /docs/examples/handlers/aws/s3.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'S3 Handler' 3 | icon: 'bucket' 4 | --- 5 | 6 | Amazon S3 is a cloud storage service on AWS that lets you store different types of files, like photos, audio, and 7 | videos, as objects. It offers high scalability and security, making it easy to store and access any amount of data 8 | from anywhere, anytime. S3 also provides features like high availability, strong security, and smooth integration with 9 | other AWS services. 10 | 11 | ## Example 12 | To create the AWSHandler object creation with the aws credentials. 13 | The AWSS3Handler connects to an Amazon S3 bucket using access credentials 14 | (access key, secret key) and specifies a region and bucket name. It enables 15 | seamless interaction with S3 for tasks like uploading, downloading, and 16 | managing files. 17 | 18 | ```python s3_handler_test.py 19 | from superagentx_handlers.aws.s3 import AWSS3Handler 20 | 21 | s3_handler = AWSS3Handler( 22 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 23 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 24 | bucket_name="test", 25 | region_name="eu-central-1" 26 | ) 27 | ``` 28 | **File Upload:**
29 | The upload_file method accepts a file name and an object name. 30 | ```python 31 | await s3_handler.upload_file( 32 | file_name="test.txt", 33 | object_name="test.txt" 34 | ) 35 | ``` 36 | **List Buckets:**
37 | Returns a list of all buckets owned by the authenticated sender of the request. 38 | ```python 39 | buckets = await s3_handler.list_bucket() 40 | print(buckets) 41 | ``` 42 | 43 | **Download File:**
44 | The Download_file method accepts a file download in the buckets 45 | ```python 46 | 47 | await s3_handler.download_file( 48 | file_name="test.txt", 49 | object_name="test.txt" 50 | ) 51 | ``` 52 | **List Objects in a Bucket:**
60 | The Delete object can delete the object in the bucket 61 | ```python 62 | await s3_handler.delete_object( 63 | object_name="test.txt" 64 | ) 65 | ``` 66 | **Generate a Pre-Signed URL:**
67 | The method will generate_presigned_url for the account 68 | ```python 69 | await s3_handler.generate_presigned_url( 70 | object_name="test.txt", 71 | expiration=3600 # URL valid for 1 hour 72 | ) 73 | print("Presigned URL:", url) 74 | ``` 75 | -------------------------------------------------------------------------------- /superagentx/memory/base.py: -------------------------------------------------------------------------------- 1 | from abc import ABC, abstractmethod 2 | from typing import Optional, Dict, Any 3 | 4 | from pydantic import BaseModel, Field 5 | 6 | 7 | class MemoryItem(BaseModel): 8 | id: str = Field(..., description="The unique identifier for the text data") 9 | memory: str = Field( 10 | ..., description="The memory deduced from the text data" 11 | ) 12 | reason: str = Field( 13 | ..., description="The memory deduced from the text data" 14 | ) 15 | role: str = Field( 16 | ..., description="The memory of role" 17 | ) 18 | # The metadata value can be anything and not just string. Fix it 19 | metadata: Dict[str, Any] | None = Field(None, description="Additional metadata for the text data") 20 | score: float | None = Field(None, description="The score associated with the text data") 21 | created_at: Any | None = Field(None, description="The timestamp when the memory was created") 22 | updated_at: Any | None = Field(None, description="The timestamp when the memory was updated") 23 | 24 | 25 | class MemoryBase(ABC): 26 | 27 | @abstractmethod 28 | async def add(self, *args, **kwargs): 29 | """ 30 | Add the data. 31 | """ 32 | raise NotImplementedError 33 | 34 | @abstractmethod 35 | async def get(self, memory_id): 36 | """ 37 | Retrieve a memory by ID. 38 | 39 | Args: 40 | memory_id (str): ID of the memory to retrieve. 41 | 42 | Returns: 43 | dict: Retrieved memory. 44 | """ 45 | raise NotImplementedError 46 | 47 | @abstractmethod 48 | async def update(self, memory_id, data): 49 | """ 50 | Update a memory by ID. 51 | 52 | Args: 53 | memory_id (str): ID of the memory to update. 54 | data (dict): Data to update the memory with. 55 | 56 | Returns: 57 | dict: Updated memory. 58 | """ 59 | raise NotImplementedError 60 | 61 | @abstractmethod 62 | async def delete(self, memory_id): 63 | """ 64 | Delete a memory by ID. 65 | 66 | Args: 67 | memory_id (str): ID of the memory to delete. 68 | """ 69 | raise NotImplementedError 70 | 71 | @abstractmethod 72 | async def delete_by_conversation_id(self, conversation_id: str): 73 | """ 74 | Delete a conversation by ID. 75 | 76 | Args: 77 | conversation_id (str): ID of the memory to delete. 78 | """ 79 | raise NotImplementedError 80 | -------------------------------------------------------------------------------- /tests/agent/test_mcp_sse_weather_agent.py: -------------------------------------------------------------------------------- 1 | import logging 2 | 3 | import pytest 4 | 5 | from superagentx.agent import Agent 6 | from superagentx.engine import Engine 7 | from superagentx.handler.mcp import MCPHandler 8 | from superagentx.llm import LLMClient 9 | from superagentx.prompt import PromptTemplate 10 | 11 | logger = logging.getLogger(__name__) 12 | 13 | ''' 14 | Run Pytest: 15 | 16 | 1. pytest --log-cli-level=INFO tests/agent/test_mcp_sse_weather_agent.py::TestMCPWeatherAgent::test_weather_search_agent 17 | ''' 18 | 19 | 20 | @pytest.fixture 21 | def agent_client_init() -> dict: 22 | llm_config = {'model': 'gpt-4o', 'llm_type': 'openai'} 23 | # llm_config = {'model': 'anthropic.claude-3-5-sonnet-20240620-v1:0', 'llm_type': 'anthropic'} 24 | 25 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 26 | response = {'llm': llm_client, 'llm_type': 'openai'} 27 | return response 28 | 29 | 30 | class TestMCPWeatherAgent: 31 | 32 | @pytest.mark.asyncio 33 | async def test_weather_search_agent(self, agent_client_init: dict): 34 | llm_client: LLMClient = agent_client_init.get('llm') 35 | 36 | # MCP Tool - SSE 37 | mcp_handler = MCPHandler(sse_url="http://0.0.0.0:8080/sse") 38 | 39 | weather_analyst_prompt = """You're a Weather Analyst. 40 | 1. Identify Latitude & Longitude for the given State / City from the user's input query 41 | 2. For Forecast, you get accurate latitude & longitude for the given State or City. 42 | 3. For Weather alerts, convert city / state into TWO letter US code. Example CA, NY. Weather alerts, ONLY two letter 43 | US code should be passed!. 44 | """ 45 | prompt_template = PromptTemplate(system_message=weather_analyst_prompt) 46 | 47 | # Enable Engine to execute MCP Tools 48 | mcp_engine = Engine(handler=mcp_handler, llm=llm_client, 49 | prompt_template=prompt_template) 50 | 51 | goal = """ Answer the weather alert or forcast report""" 52 | 53 | # SuperAgentX's Agent to run based on the goal 54 | weather_search_agent = Agent(goal=goal, role="You're a Weather Analyst", max_retry=1, 55 | llm=llm_client, prompt_template=prompt_template) 56 | await weather_search_agent.add(mcp_engine) 57 | 58 | # Ask Question and get results 59 | result = await weather_search_agent.execute(query_instruction="Get weather forecast for California!") 60 | logger.info(f'Result ==> {result}') 61 | assert result 62 | -------------------------------------------------------------------------------- /docs/examples/handlers/aws/rds.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'RDS Handler' 3 | icon: 'database' 4 | --- 5 | 6 | Amazon RDS (Relational Database Service) is a managed service that makes it easy to set up, operate, and scale relational databases in the cloud. 7 | It supports multiple engines like MySQL, PostgreSQL, MariaDB, Oracle, and SQL Server, and provides features such as automated backups, scaling, monitoring, and high availability. 8 | 9 | 10 | ## Example 11 | 12 | To create the **RDS Handler**, you must pass AWS credentials (`access_key`, `secret_key`, and `region`). 13 | This enables you to interact with RDS resources, clusters, proxies, and their associations with EC2. 14 | 15 | ```python 16 | import os 17 | from superagentx_handlers.aws.rds import AWSRDSHandler 18 | 19 | rds_handler = AWSRDSHandler( 20 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 21 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 22 | region_name="eu-central-1" 23 | ) 24 | ``` 25 | **Get RDS Association Details:**
26 | Provides a comprehensive inventory of RDS resources and their associations. 27 | ```python 28 | details = await rds_handler.get_rds_association_details() 29 | print(details) 30 | ``` 31 | 32 | **List RDS Instances:**
33 | Fetches all RDS database instances in the account. 34 | ```python 35 | instances = await rds_handler.get_rds_instances() 36 | print(instances) 37 | ``` 38 | 39 | **List RDS Clusters:**
40 | Fetches all Aurora RDS clusters. 41 | ```python 42 | clusters = await rds_handler.get_rds_clusters() 43 | print(clusters) 44 | ``` 45 | 46 | **List RDS Proxies:**
47 | Fetches all RDS database proxies. 48 | ```python 49 | proxies = await rds_handler.get_rds_proxies() 50 | print(proxies) 51 | ``` 52 | 53 | **Get Proxy Targets:**
54 | Retrieves targets associated with a specific RDS proxy. 55 | ```python 56 | targets = await rds_handler.get_proxy_targets( 57 | proxy_name="my-rds-proxy" 58 | ) 59 | print(targets) 60 | ``` 61 | 62 | **Get EC2 Associations:**
63 | Finds EC2 instances that are associated with RDS security groups. 64 | ```python 65 | associations = await rds_handler.get_ec2_associations( 66 | rds_instances=instances 67 | ) 68 | print(associations) 69 | ``` 70 | 71 | **Get Backup Configuration:**
72 | Fetches backup details such as retention period, backup window, and maintenance window for an RDS instance or cluster. 73 | ```python 74 | backup = await rds_handler.get_backup_config( 75 | db_identifier="my-db-instance", 76 | is_cluster=False # set True for clusters 77 | ) 78 | print(backup) 79 | ``` -------------------------------------------------------------------------------- /superagentx_cli/templates/pipe.py.jinja2: -------------------------------------------------------------------------------- 1 | {# templates/pipe.py.jinja2 #} 2 | from superagentx.agent import Agent 3 | from superagentx.agentxpipe import AgentXPipe 4 | from superagentx.engine import Engine 5 | from superagentx.llm import LLMClient 6 | from superagentx.memory import Memory 7 | from superagentx.prompt import PromptTemplate 8 | 9 | # Import handlers 10 | 11 | # Example 12 | # ------- 13 | ################################################# 14 | # Uncomment below lines to enable ecom handlers # 15 | ################################################# 16 | # from superagentx_handlers import AmazonHandler 17 | # from superagentx_handlers.ecommerce.walmart import WalmartHandler 18 | 19 | 20 | async def get_{{ pipe_name }}_pipe() -> AgentXPipe: 21 | # LLM Configuration 22 | llm_config = { 23 | 'llm_type': 'openai' 24 | } 25 | llm_client = LLMClient(llm_config=llm_config) 26 | 27 | # Enable Memory 28 | memory = Memory(memory_config={"llm_client": llm_client}) 29 | 30 | # Example 31 | # ------- 32 | # amazon_ecom_handler = AmazonHandler() 33 | # walmart_ecom_handler = WalmartHandler() 34 | 35 | # Prompt Template 36 | prompt_template = PromptTemplate() 37 | 38 | # Example - Engine(s) 39 | # ------------------- 40 | # amazon_engine = Engine( 41 | # handler=amazon_ecom_handler, 42 | # llm=llm_client, 43 | # prompt_template=prompt_template 44 | # ) 45 | # walmart_engine = Engine( 46 | # handler=walmart_ecom_handler, 47 | # llm=llm_client, 48 | # prompt_template=prompt_template 49 | # ) 50 | 51 | # Create Agents 52 | 53 | # Example - Agent(s) 54 | # ------------------ 55 | # Create Agent with Amazon, Walmart Engines execute in Parallel - Search Products from user prompts 56 | # ecom_agent = Agent( 57 | # name='Ecom Agent', 58 | # goal="Get me the best search results", 59 | # role="You are the best product searcher", 60 | # llm=llm_client, 61 | # prompt_template=prompt_template, 62 | # engines=[[amazon_engine, walmart_engine]] 63 | # ) 64 | 65 | # Create Pipe - Interface 66 | 67 | # Pipe Interface to send it to public accessible interface (Cli Console / WebSocket / Restful API) 68 | pipe = AgentXPipe( 69 | ############################################### 70 | # Uncomment below lines to enable ecom agents # 71 | ############################################### 72 | # agents=[ecom_agent], 73 | memory=memory 74 | ) 75 | return pipe{{'\n'}} -------------------------------------------------------------------------------- /docs/examples/handlers/aws/ec2.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'EC2 Handler' 3 | icon: 'server' 4 | --- 5 | 6 | Amazon EC2 (Elastic Compute Cloud) is a service that provides secure, resizable compute capacity in the cloud. 7 | It allows you to launch virtual servers (instances), manage storage volumes, security groups, and networking configurations. 8 | With the EC2 handler, you can programmatically retrieve and manage EC2 resources such as instances, volumes, AMIs, snapshots, and more. 9 | 10 | ## Example 11 | To create the AWSEC2Handler object with AWS credentials. 12 | The AWSEC2Handler connects to AWS EC2 using access credentials (access key, secret key) and a region name. 13 | It enables seamless interaction with EC2 for retrieving and managing compute resources. 14 | 15 | ```python ec2_handler_test.py 16 | import os 17 | from superagentx_handlers.aws.ec2 import AWSEC2Handler 18 | 19 | ec2_handler = AWSEC2Handler( 20 | aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), 21 | aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), 22 | region_name="eu-central-1" 23 | ) 24 | ``` 25 | **Get Instances:**
26 | The get_instances method fetches all EC2 instances. 27 | ```python 28 | await ec2_handler.get_instances() 29 | print(instances) 30 | ``` 31 | 32 | **Get Security Groups:**
33 | The get_security_groups method fetches all security groups. 34 | ```python 35 | await ec2_handler.get_security_groups() 36 | print(security_groups) 37 | ``` 38 | 39 | **Get Volumes:**
40 | The get_volumes method fetches all EBS volumes. 41 | ```python 42 | await ec2_handler.get_volumes() 43 | print(volumes) 44 | ``` 45 | 46 | **Get AMIs:**
47 | The get_amis method fetches all AMIs owned by the account. 48 | ```python 49 | await ec2_handler.get_amis() 50 | print(amis) 51 | ``` 52 | 53 | **Get Snapshots:**
54 | The get_snapshots method fetches all snapshots owned by the account. 55 | ```python 56 | await ec2_handler.get_snapshots() 57 | print(snapshots) 58 | ``` 59 | 60 | **Get Key Pairs:**
61 | The get_key_pairs method fetches all key pairs. 62 | ```python 63 | key_pairs = await ec2_handler.get_key_pairs() 64 | print(key_pairs) 65 | ``` 66 | 67 | **Get Network Interfaces:**
68 | The get_network_interfaces method fetches all network interfaces. 69 | ```python 70 | network_interfaces = await ec2_handler.get_network_interfaces() 71 | print(network_interfaces) 72 | ``` 73 | 74 | **Collect All EC2 Resources:**
75 | The collect_all_ec2 method fetches all EC2 resources in parallel. 76 | ```python 77 | await ec2_handler.collect_all_ec2() 78 | print(all_ec2_data) 79 | ``` -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "superagentx" 3 | version = "1.0.2b1" 4 | description = "The Ultimate Modular Autonomous Multi AI Agent Framework." 5 | license = { text = "MIT" } 6 | authors = [ 7 | { name = "SuperAgentX AI", email = "
27 | Retrieves IAM policies for all accessible organizations. 28 | ```python 29 | org_policies = await gcp_handler.collect_organization_iam() 30 | print(org_policies) 31 | ``` 32 | 33 | **Collect Folder IAM Policies:**
34 | Fetches IAM policies for all folders under an organization or another folder. 35 | ```python 36 | folder_policies = await gcp_handler.collect_folder_iam(organization_id="1234567890") 37 | print(folder_policies) 38 | ``` 39 | 40 | **Collect Project IAM Policies:**
41 | Retrieves IAM policies for specific projects or all accessible projects. 42 | ```python 43 | project_policies = await gcp_handler.collect_project_iam(project_id="my-gcp-project") 44 | print(project_policies) 45 | ``` 46 | 47 | **Collect Service Accounts:**
48 | Lists service accounts in a given project. 49 | ```python 50 | service_accounts = await gcp_handler.collect_service_accounts(project_id="my-gcp-project") 51 | print(service_accounts) 52 | ``` 53 | 54 | **Collect Custom Roles:**
55 | Fetches custom IAM roles at the project or organization level. 56 | ```python 57 | custom_roles = await gcp_handler.collect_custom_roles(project_id="my-gcp-project") 58 | print(custom_roles) 59 | ``` 60 | 61 | **Collect All Security Information:**
62 | Performs a comprehensive security collection across IAM policies, service accounts, and custom roles for an organization or project. 63 | ```python 64 | security_info = await gcp_handler.collect_all_security_info(organization_id="1234567890") 65 | print(security_info.keys()) 66 | ``` -------------------------------------------------------------------------------- /docs/introduction.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Introduction 3 | icon: house 4 | --- 5 | 6 | **SuperAgentX**: A Lightweight Open Source AI Framework Built for Autonomous Multi-Agent Applications with Artificial General Intelligence (AGI) Capabilities. 7 | 8 | ## Why SuperAgentX? 9 | 10 | **Super** : Advanced AI systems with extraordinary capabilities, pioneering the path to AGI (Artificial General Intelligence) and ASI (Artificial Super Intelligence). 11 | 12 | **Agent** : Autonomous Multi AI agent framework designed to make decisions, act independently, and handle complex tasks. 13 | 14 | **X** : The unknown, the limitless, the extra factor that makes SuperAgentX revolutionary, futuristic, and transformative. 15 | 16 | 17 |
18 |
19 |
20 | ***SuperAgentX Features***
21 |
22 | 🚀 **Open-Source Framework**: A lightweight, open-source AI framework built for multi-agent applications with Artificial General Intelligence (AGI) capabilities.
23 |
24 | 🏖️ **Easy Deployment**: Offers WebSocket, RESTful API, IO console and Voice interfaces for rapid setup of agent-based AI solutions.
25 |
26 | ♨️ **Streamlined Architecture**: No major dependencies; built independently.
27 |
28 | 📚 **Contextual Memory**: Uses SQL + Vector databases to store and retrieve user-specific context effectively.
29 |
30 | 🧠 **Flexible LLM Configuration**: Supports simple configuration options of various Gen AI models.
31 |
32 | 🤝🏻 **Extendable Handlers**: Allows integration with diverse APIs, databases, data warehouses, data lakes, IoT streams, and more, making them accessible for function-calling features.
33 |
34 | 🎯 **Goal-Oriented Agents**: Enables the creation of agents with retry mechanisms to achieve set goals.
35 |
36 | It provides a powerful, modular, and flexible platform for building autonomous AI agents capable of executing complex tasks with minimal human intervention.
37 | By integrating cutting-edge AI technologies and promoting efficient, scalable agent behavior, SuperAgentX embodies a critical step forward in the path towards superintelligence and AGI.
38 | Whether for research, development, or deployment, SuperAgentX is built to push the boundaries of what is possible with autonomous AI systems.
39 |
40 |
41 | **Content Extraction:** Access clean, parsed HTML from search results, with the option to focus on 10 | relevant sections using the highlights feature.
**Similar Page Discovery:** Input a link to identify and retrieve 11 | pages with related content or meaning. 12 | 13 | ## Example 14 | This code sets up an ExaHandler to perform a search using an API key. It retrieves content based on the provided query, 15 | automatically determining the search type and returning up to five results, making it easy to find relevant information 16 | quickly. 17 | 18 | To access ExaSearch services, you'll need to create an ExaSearch account, obtain an API key, and subscribe to the 19 | required API for your application. For more details, refer to the 20 | ExaSearch documentation. 21 | 22 | >Set up a Exa API key as an environmental variable and run the following code. 23 | 24 | ```python 25 | export EXA_API_KEY = "**************************" 26 | ``` 27 | 28 | ```python exa_handler.py 29 | import os 30 | import asyncio 31 | 32 | from superagentx.handler.exa_search import ExaHandler 33 | 34 | 35 | async def search_contents(query): 36 | exa_handler = ExaHandler() 37 | return await exa_handler.search_contents( 38 | query=query, 39 | search_type="auto", 40 | use_autoprompt=True, 41 | num_results=5, 42 | ) 43 | 44 | 45 | async def main(query): 46 | res = await search_contents(query) 47 | print(res) 48 | 49 | if __name__ == '__main__': 50 | query = "What is Agentic AI Framework?" 51 | asyncio.run(main(query)) 52 | ``` 53 | 54 | ## Result 55 | 56 | ```log exa search 57 | URL: https://aima.eecs.berkeley.edu/2nd-ed/ai.html 58 | ID: http://aima.eecs.berkeley.edu/2nd-ed/ai.html 59 | Score: 0.19881151616573334 60 | Published Date: 2006-09-12T00:00:00.000Z 61 | Author: 62 | Image: None 63 | Text: This page links to 849 pages around the web with 64 | information on Artificial Intelligence. Links in Bold* followed by a star are especially useful 65 | and interesting sites. Links with a + sign at the end have "tooltip" 66 | information that will pop up if you put your mouse over the link for a 67 | second or two. If you have new links to add, mail them to peter@norvig.com. 68 | ``` 69 | -------------------------------------------------------------------------------- /docs/examples/handlers/scrape.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Scrape Handler' 3 | icon: 'spider' 4 | --- 5 | 6 | A scrape handler is a tool or part of a program that helps you "scrape" data from websites. When you want to collect 7 | information from a webpage, like product prices, weather data, or news headlines, a scrape handler is the part of the 8 | system that goes to the website, gets the data, and then processes it for you. 9 | 10 | ```python scrape_handler.py 11 | import asyncio 12 | 13 | from superagentx_handlers.scrape import ScrapeHandler 14 | 15 | 16 | async def scrap_content() -> ScrapeHandler: 17 | scrap_handler = ScrapeHandler() 18 | return await scrap_handler.scrap_content(domain_urls=["https://www.booking.com/"]) 19 | 20 | 21 | async def main(): 22 | res = await scrap_content() 23 | print(res) 24 | 25 | if __name__ == '__main__': 26 | asyncio.run(main()) 27 | ``` 28 | 29 | ### Result 30 | ```shell 31 | 32 | Synchronous WebCrawler is not available. Install crawl4ai[sync] for synchronous support. However, 33 | please note that the synchronous version will be deprecated soon. 34 | [LOG] 🌤️ Warming up the AsyncWebCrawler 35 | [LOG] 🌞 AsyncWebCrawler is ready to crawl 36 | [LOG] 🕸️ Crawling https://www.booking.com/ using AsyncPlaywrightCrawlerStrategy... 37 | [LOG] ✅ Crawled https://www.booking.com/ successfully! 38 | [LOG] 🚀 Crawling done for https://www.booking.com/, success: True, time taken: 5.25 seconds 39 | [LOG] 🚀 Content extracted for https://www.booking.com/, success: True, time taken: 0.78 seconds 40 | [LOG] 🔥 Extracting semantic blocks for https://www.booking.com/, Strategy: AsyncWebCrawler 41 | [LOG] 🚀 Extraction done for https://www.booking.com/, time taken: 0.78 seconds. 42 | ['[ Skip to main content ](#indexsearch)\n\n[](https://www.booking.com/index.en-gb.html?label=gen173nr- 43 | 1BCAEoggI46AdIM1gEaGyIAQGYAQm4ARfIAQzYAQHoAQGIAgGoAgO4At7Q67kGwAIB0gIkMjhlOTViMzAtOWI3Yy00NTM4LWEwNmEtOD 44 | I5NWJjMWFjOWJi2AIF4AIB&sid=e80cd7587c79910cad64ebb4460be87c&aid=304142)\n\nINR\n\n\n\n[](https://secure.booking.com/help.en-gb.html 46 | ?label=gen173nr-1BCAEoggI46AdIM1gEaGyIAQGYAQm4ARfIAQzYAQHoAQGIAgGoAgO4At7Q67kGwAIB0gIkMjhlOTViMzAtOWI3Yy00NT 47 | M4LWEwNmEtODI5NWJjMWFjOWJi2AIF4AIB&sid=e80cd7587c79910cad64ebb4460be87c&aid=304142&source=header&src=profile_ 48 | contact_cs)[List your property](https://join.booking.com/?label=gen173nr-1BCAEoggI46AdIM1gEaGyIAQGYAQm4ARfIAQz 49 | YAQHoAQGIAgGoAgO4At7Q67kGwAIB0gIkMjhlOTViMzAtOWI3Yy00NTM4LWEwNmEtODI5NWJjMWFjOWJi2AIF4AIB&sid=e80cd7587c79910ca 50 | d64ebb4460be87c&aid=304142&lang=en-gb&utm_medium=frontend&utm_source=topbar) 51 | 52 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/financial_data.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Financial Data Handler' 3 | icon: 'chart-mixed-up-circle-dollar' 4 | --- 5 | 6 | The Financial Data Handler is a tool that helps get important financial information from online sources. 7 | It allows businesses or individuals to easily access real-time data like stock prices, company financial 8 | details, and income statements. This information can be used for tracking market trends, analyzing a 9 | company’s performance, or making better investment decisions. 10 | 11 | Refer the link to know more details about symbol from the document 12 | here. 13 | 14 | ## Example 15 | This code sets up a FinancialHandler to access financial data using an API key and specifies the stock symbol for Amazon 16 | (AMZN). This allows for retrieving stock market information and other financial data programmatically. 17 | 18 | To use Financial Modeling, you'll need to create an Financial Modeling account and get an API key. For more details refer here. 19 | 20 | >Set up a FINANCIAL_DATA_API_KEY key as an environmental variable and run the following code. 21 | ```python 22 | export FINANCIAL_DATA_API_KEY = "**************************" 23 | ``` 24 | 25 | ```python financial_handler.py 26 | import os 27 | import asyncio 28 | 29 | from superagentx.handler.financial_data import FinancialHandler 30 | 31 | 32 | async def get_stock_price(): 33 | financial_handler = FinancialHandler( 34 | symbol='AMZN' 35 | ) 36 | return await financial_handler.get_stock_price() 37 | 38 | 39 | async def main(): 40 | res = await get_stock_price() 41 | print(res) 42 | 43 | if __name__ == '__main__': 44 | asyncio.run(main()) 45 | ``` 46 | ## Result 47 | ```inline Stock price Output: 48 | { 49 | "data": [ 50 | { 51 | "symbol": "AA", 52 | "name": "Alcoa Corporation", 53 | "price": 41.71, 54 | "changesPercentage": 3.3705, 55 | "change": 1.36, 56 | "dayLow": 40.86, 57 | "dayHigh": 42.1659, 58 | "yearHigh": 45.48, 59 | "yearLow": 23.07, 60 | "marketCap": 10775361358, 61 | "priceAvg50": 34.709, 62 | "priceAvg200": 34.4335, 63 | "exchange": "NYSE", 64 | "volume": 4489893, 65 | "avgVolume": 6216657, 66 | "open": 41.77, 67 | "previousClose": 40.35, 68 | "eps": -1.56, 69 | "pe": -26.74, 70 | "earningsAnnouncement": "2025-01-15T05:00:00.000+0000", 71 | "sharesOutstanding": 258339999, 72 | "timestamp": 1729281602 73 | } 74 | ] 75 | } 76 | 77 | ``` 78 | -------------------------------------------------------------------------------- /docs/examples/handlers/Gcp/iam.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'IAM Handler' 3 | icon: 'shield' 4 | --- 5 | 6 | Google Cloud IAM (Identity and Access Management) allows you to securely manage access to your GCP resources. 7 | It provides fine-grained controls for organizations, folders, and projects, ensuring that only authorized users and services can access resources. 8 | 9 | With the **GCPIAMHandler**, you can fetch IAM policy details across organizations, folders, and projects, and also collect MFA-related evidence to strengthen compliance and security posture. 10 | 11 | It helps with: 12 | - Discovering IAM policies for GCP organizations, folders, and projects. 13 | - Checking roles, bindings, and enforced conditions like MFA. 14 | - Building a full compliance picture of your GCP environment. 15 | 16 | 17 | ## Example 18 | ### Initialization 19 | 20 | To create a handler with your service account credentials: 21 | 22 | ```python 23 | from superagentx_handlers.gcp.iam import GCPIAMHandler 24 | 25 | iam_handler = GCPIAMHandler( 26 | creds="service_account.json", # path to service account json 27 | scope=["https://www.googleapis.com/auth/cloud-platform"] 28 | ) 29 | ``` 30 | 31 | **Collect Organization IAM Evidence:**
32 | Fetch IAM policy evidence for all accessible GCP organizations. 33 | ```python 34 | org_evidence = await iam_handler.collect_organization_iam_evidence() 35 | print(org_evidence) 36 | ``` 37 | 38 | **Collect Folder IAM Evidence:**
39 | Fetch IAM policy evidence for folders under a specific organization or folder. 40 | ```python 41 | folder_evidence = await iam_handler.collect_folder_iam_evidence( 42 | parent_resource="organizations/123456789" 43 | ) 44 | print(folder_evidence) 45 | ``` 46 | 47 | **Collect Project IAM Evidence:**
48 | Fetch IAM policies for projects under an organization or folder. 49 | ```python 50 | project_evidence = await iam_handler.collect_project_iam_evidence( 51 | parent_resource="folders/987654321" 52 | ) 53 | print(project_evidence) 54 | ``` 55 | 56 | **Collect All IAM Evidence:**
57 | Collects IAM evidence across organizations, folders, and projects in one run. 58 | ```python 59 | all_evidence = await iam_handler.collect_all_iam_evidence() 60 | print(all_evidence) 61 | ``` 62 | 63 | **_get_resource_iam_policy(resource_name: str, resource_type: str):**
64 | Internal method that retrieves IAM policy details for a specific resource (organization, folder, or project). 65 | It returns information about roles, members, bindings, conditions, and MFA enforcement. 66 | ```python 67 | policy = await iam_handler._get_resource_iam_policy( 68 | resource_name="projects/my-project-123", 69 | resource_type="project" 70 | ) 71 | print(policy) 72 | ``` 73 | -------------------------------------------------------------------------------- /tests/llm/test_gemini_client.py: -------------------------------------------------------------------------------- 1 | import logging 2 | 3 | import pytest 4 | 5 | from superagentx.llm import LLMClient 6 | from superagentx.llm.gemini import GeminiClient 7 | from superagentx.llm.models import ChatCompletionParams 8 | 9 | logger = logging.getLogger(__name__) 10 | 11 | ''' 12 | Run Pytest: 13 | 14 | 1. pytest --log-cli-level=INFO tests/llm/test_gemini_client.py::TestGeminiClient::test_gemini_chat_completion 15 | 2. pytest --log-cli-level=INFO tests/llm/test_gemini_client.py::TestGeminiClient::test_gemini_achat_completion 16 | ''' 17 | 18 | # Define the function declaration for the model 19 | weather_function = [{ 20 | "name": "get_current_temperature", 21 | "description": "Gets the current temperature for a given location.", 22 | "parameters": { 23 | "type": "object", 24 | "properties": { 25 | "location": { 26 | "type": "string", 27 | "description": "The city name, e.g. San Francisco", 28 | }, 29 | }, 30 | "required": ["location"], 31 | }, 32 | }] 33 | 34 | # Start a conversation with the user message. 35 | user_message = "What's the temperature in London?" 36 | 37 | content = [ 38 | { 39 | "role": "user", 40 | "content": user_message 41 | } 42 | ] 43 | 44 | 45 | @pytest.fixture 46 | def gemini_client_init() -> dict: 47 | llm_config = {'llm_type': 'gemini', 'model': 'gemini-2.0-flash'} 48 | llm_client: LLMClient = LLMClient(llm_config=llm_config) 49 | response = {'llm': llm_client} 50 | return response 51 | 52 | 53 | class TestGeminiClient: 54 | 55 | async def test_gemini_client(self, gemini_client_init: dict): 56 | llm_client: LLMClient = gemini_client_init.get('llm').client 57 | assert isinstance(llm_client, GeminiClient) 58 | 59 | @pytest.mark.asyncio 60 | async def test_gemini_chat_completion(self, gemini_client_init: dict): 61 | llm_client: LLMClient = gemini_client_init.get('llm') 62 | 63 | chat_completion_params = ChatCompletionParams( 64 | messages=content, 65 | tools=weather_function 66 | ) 67 | 68 | response = llm_client.chat_completion(chat_completion_params=chat_completion_params) 69 | logger.info(response) 70 | 71 | @pytest.mark.asyncio 72 | async def test_gemini_achat_completion(self, gemini_client_init: dict): 73 | llm_client: LLMClient = gemini_client_init.get('llm') 74 | 75 | chat_completion_params = ChatCompletionParams( 76 | messages=content, 77 | tools=weather_function 78 | ) 79 | 80 | response = await llm_client.achat_completion(chat_completion_params=chat_completion_params) 81 | logger.info(response) 82 | 83 | -------------------------------------------------------------------------------- /superagentx/io/console.py: -------------------------------------------------------------------------------- 1 | from typing import Any 2 | 3 | from rich import print as rprint 4 | from rich.console import Console 5 | from rich.prompt import Prompt 6 | 7 | from superagentx.io.base import IOStream 8 | 9 | 10 | class IOConsole(IOStream): 11 | """A console input/output stream.""" 12 | 13 | def __init__( 14 | self, 15 | read_phrase: str | None = None, 16 | write_phrase: str | None = None 17 | ): 18 | self.read_phrase = read_phrase or '' 19 | self.write_phrase = write_phrase or '' 20 | self._console = Console() 21 | 22 | def __repr__(self): 23 | return self.__str__() 24 | 25 | def __str__(self): 26 | return "
26 | Fetches all users and their IAM-related details (display name, UPN, email, type, assigned roles). 27 | Requires User.Read.All and optionally RoleManagement.Read.All. 28 | ```python 29 | users = await entra_handler.collect_users_iam_evidence() 30 | print(users) 31 | ``` 32 | 33 | **Collect Groups IAM Evidence:**
34 | Fetches all groups and their members (users, devices, service principals). 35 | Requires Group.Read.All. 36 | ```python 37 | groups = await entra_handler.collect_groups_iam_evidence() 38 | print(groups) 39 | ``` 40 | 41 | **Collect Applications IAM Evidence (Service Principals):**
42 | Retrieves all applications (service principals) and their owners. 43 | Requires Application.Read.All. 44 | ```python 45 | apps = await entra_handler.collect_applications_iam_evidence() 46 | print(apps) 47 | ``` 48 | 49 | **Collect Role Definitions:**
50 | Retrieves all built-in and custom role definitions available in Microsoft Entra ID. 51 | Requires RoleManagement.Read.Directory. 52 | ```python 53 | roles = await entra_handler.collect_roles_definitions() 54 | print(roles) 55 | ``` 56 | 57 | **Collect MFA Status Evidence:**
58 | Collects MFA registration status and recent MFA usage from sign-in logs for users. 59 | Requires Reports.Read.All, UserAuthenticationMethod.Read.All, and AuditLog.Read.All. 60 | ```python 61 | mfa = await entra_handler.collect_mfa_status_evidence(days_ago=30) 62 | print(mfa) 63 | ``` 64 | 65 | **Collect All entra IAM Evidence (Summary):**
66 | Fetches users, groups, applications, roles, and MFA evidence in a single call. 67 | ```python 68 | all_evidence = await entra_handler.collect_all_entra_iam_evidence() 69 | print(all_evidence) 70 | ``` -------------------------------------------------------------------------------- /docs/examples/handlers/openapi.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: 'Openapi Handler' 3 | icon: 'webhook' 4 | --- 5 | 6 | The OpenAPIHandler class provides a simple way to interact with APIs that follow the OpenAPI specification. 7 | It allows you to load the OpenAPI specification from either a URL or a local file in JSON or YAML format. 8 | You can easily retrieve all available API endpoints, get the supported HTTP methods for each endpoint, 9 | and view detailed information about specific operations. The class also includes a call_endpoint method 10 | that makes it easy to send API requests with customizable parameters, request bodies, and headers. This 11 | makes the OpenAPIHandler class a powerful tool for automating interactions with APIs in a Python-based workflow. 12 | 13 | ```python openapi_handler.py 14 | import asyncio 15 | 16 | from superagentx.handler.openapi import OpenAPIHandler 17 | 18 | async def openapi_handler(): 19 | openapi_handler = OpenAPIHandler( 20 | base_url='https://petstore.swagger.io/v2/', 21 | spec_url_path='swagger.json' 22 | ) 23 | 24 | return await openapi_handler.call_endpoint( 25 | endpoint="/pet/findByStatus", 26 | method="GET", 27 | params={'status': 'sold'}) 28 | 29 | async def main(): 30 | res = await create_contact() 31 | print(res) 32 | 33 | if __name__ == '__main__': 34 | asyncio.run(main()) 35 | 36 | ``` 37 | 38 | ## Result 39 | ```shell 40 | 41 | platform linux -- Python 3.12.3, pytest-8.3.3, pluggy-1.5.0 42 | rootdir: /home/ram/Projects/superagentX 43 | configfile: pyproject.toml 44 | plugins: asyncio-0.24.0, anyio-4.6.2.post1 45 | asyncio: mode=Mode.AUTO, default_loop_scope=None 46 | collected 1 item 47 | 48 | tests/handlers/test_openapi_spec_handler.py::TestOpenAPIHandler::test_openapi_handler 49 | INFO tests.handlers.test_openapi_spec_handler:test_openapi_spec_handler.py:30 Response 50 | [{'id': 360274, 'category': {'id': 126898, 'name': 'tbhBBPKt'}, 'name': 'doggie', 'photoUrls': ['AcPwDp'], 51 | 'tags': [{'id': 530594, 'name': 'cgAhLGLz'}], 'status': 'sold'}, {'id': 7, 'category': {'id': 51, 'name': 'cat'}, 52 | 'name': 'Milo', 'photoUrls': ['string'], 'tags': [{'id': 871, 'name': 'siamese'}], 'status': 'sold'}, {'id': 13, 53 | 'category': {'id': 0, 'name': 'cats'}, 'photoUrls': ['string'], 'tags': [{'id': 0, 'name': 'string'}], 'status': 'sold'}, 54 | {'id': 102, 'category': {'id': 102, 'name': 'Qwerty'}, 'name': 'Mufasa', 'photoUrls': ['string'], 'tags': [{'id': 102, 55 | 'name': 'Mufasa'}], 'status': 'sold'}, {'id': 1346780, 'name': '見響见响仮仏!$%&()*+,-ƄƅƆḞḟṀʶʷʸ㥹', 'photoUrls': 56 | ['https://petstore3.swagger.io/resources/photos/623389095.jpg'], 'tags': [], 'status': 'sold'}] 57 | PASSED [100%] 58 | 59 | ``` -------------------------------------------------------------------------------- /tests/pipe/create_pipe.py: -------------------------------------------------------------------------------- 1 | 2 | from superagentx.agent import Agent 3 | from superagentx.agentxpipe import AgentXPipe 4 | from superagentx.engine import Engine 5 | from superagentx.llm import LLMClient 6 | from superagentx.memory import Memory 7 | from superagentx.prompt import PromptTemplate 8 | 9 | # Import handlers 10 | from superagentx_handlers.google.gmail import GmailHandler 11 | from superagentx_handlers.crm.hubspot_crm import HubSpotHandler 12 | 13 | 14 | async def get_superagentx_voice_to_text_pipe() -> AgentXPipe: 15 | # LLM Configuration 16 | llm_config = { 17 | 'llm_type': 'openai' 18 | } 19 | llm_client = LLMClient(llm_config=llm_config) 20 | 21 | # Enable Memory 22 | memory = Memory(memory_config={"llm_client": llm_client}) 23 | 24 | # Enable Handler 25 | gmail_handler = GmailHandler( 26 | credentials="//path to json credentials." 27 | ) 28 | hubspot_handler = HubSpotHandler() 29 | 30 | system_prompt = """ 31 | 1. Get last email which is which is subject contains insurance or policy or claim 32 | """ 33 | 34 | hubspot_system_prompt = """ 35 | 1. Create only one ticket at a time in hubspot crm 36 | """ 37 | 38 | # Prompt Template 39 | 40 | gmail_prompt_template = PromptTemplate( 41 | system_message=system_prompt 42 | ) 43 | 44 | hubspot_prompt_template = PromptTemplate( 45 | system_message=hubspot_system_prompt 46 | ) 47 | 48 | # Read last email to create a new ticket in HubSpot. 49 | # Example - Engine(s) 50 | # ------------------- 51 | gmail_engine = Engine( 52 | handler=gmail_handler, 53 | llm=llm_client, 54 | prompt_template=gmail_prompt_template 55 | ) 56 | hubspot_engine = Engine( 57 | handler=hubspot_handler, 58 | llm=llm_client, 59 | prompt_template=hubspot_prompt_template 60 | ) 61 | 62 | # Create Agents 63 | # Create Agent with Gmail, Hubspot Engines execute in sequential 64 | gmail_agent = Agent( 65 | goal="Get me the best search results", 66 | role="You are the best gmail reader", 67 | llm=llm_client, 68 | prompt_template=gmail_prompt_template, 69 | engines=[[gmail_engine]] 70 | ) 71 | 72 | hubspot_agent = Agent( 73 | name='CRM Agent', 74 | goal="Create new Ticket in Hubspot", 75 | role="You are the Hubspot admin", 76 | llm=llm_client, 77 | prompt_template=hubspot_prompt_template, 78 | engines=[[hubspot_engine]] 79 | ) 80 | 81 | # Create Pipe - Interface 82 | # Pipe Interface to send it to public accessible interface (Cli Console / WebSocket / Restful API) 83 | pipe = AgentXPipe( 84 | agents=[gmail_agent, hubspot_agent], 85 | memory=memory 86 | ) 87 | return pipe 88 | 89 | --------------------------------------------------------------------------------