- Notifications
You must be signed in to change notification settings - Fork36
SwarmZero's SDK for building AI agents, swarms of agents and much more.
License
swarmzero/swarmzero
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This library provides you with an easy way to create and run AI Agents and Swarms of Agents.
Supported LLM Providers:
- Python >= 3.11
You can either directly install with pip:
pip install swarmzero
Or can either directly install with poetry:
poetry add swarmzero
Or add it to yourrequirements.txt file:
...swarmzero==x.y.z...
You need to specify anOPENAI_API_KEY in a.env file in this directory.
Make a copy of the.env.example file and rename it to.env.
To use a configuration file with yourAgent, follow these steps:
Create a Configuration File:
- Create a TOML file (e.g.,
swarmzero_config.toml) in your project directory. (Seeswarmzero_config_example.toml).
- Create a TOML file (e.g.,
Create an SDK Context:
- Create an instance of SDKContext with the path to your configuration file.
- The SDKContext allows you to manage configurations, resources, and utilities across your SwarmZero Agents more efficiently.
fromswarmzero.sdk_contextimportSDKContextsdk_context=SDKContext(config_path="./swarmzero_config.toml")
Specify the Configuration Path:
- When creating a
Agentinstance, provide the relative or absolute path to your configuration file. - Agent will use the configuration from the SDK Context. If you have one agent you can directly pass the config_path it will create the sdk_context for you.
fromswarmzeroimportAgentsimple_agent=Agent(name="Simple Agent",functions=[],instruction="your instructions for this agent's goal",# sdk_context=sdk_contextconfig_path="./swarmzero_config.toml" )
- When creating a
More detailed examples can be found athttps://github.com/swarmzero/examples
First import theAgent class:
fromswarmzeroimportAgent
Load your environment variables:
fromdotenvimportload_dotenvload_dotenv()
Then create a Agent instance:
my_agent=Agent(name="my_agent",functions=[],instruction="your instructions for this agent's goal",)
Then, run your agent:
my_agent.run()
Finally, call the API endpoint,/api/v1/chat, to see the result:
curl --request POST \ --url http://localhost:8000/api/v1/chat \ --header'Content-Type: multipart/form-data' \ --form'user_id="test"' \ --form'session_id="test"' \ --form'chat_data={ "messages": [ { "role": "user", "content": "Who is Satoshi Nakamoto?" } ] }'
You can create tools that help your agent handle more complex tasks. Here's an example:
importosfromtypingimportOptional,Dictfromweb3importWeb3fromswarmzeroimportAgentfromdotenvimportload_dotenvload_dotenv()rpc_url=os.getenv("RPC_URL")# add an ETH Mainnet HTTP RPC URL to your `.env` filedefget_transaction_receipt(transaction_hash:str)->Optional[Dict]:""" Fetches the receipt of a specified transaction on the Ethereum blockchain and returns it as a dictionary. :param transaction_hash: The hash of the transaction to fetch the receipt for. :return: A dictionary containing the transaction receipt details, or None if the transaction cannot be found. """web3=Web3(Web3.HTTPProvider(rpc_url))ifnotweb3.is_connected():print("unable to connect to Ethereum")returnNonetry:transaction_receipt=web3.eth.get_transaction_receipt(transaction_hash)returndict(transaction_receipt)exceptExceptionase:print(f"an error occurred:{e}")returnNoneif__name__=="__main__":my_agent=Agent(name="my_agent",functions=[get_transaction_receipt] )my_agent.run()""" [1] send a request: ``` curl --request POST\ --url http://localhost:8000/api/v1/chat\ --header 'Content-Type: multipart/form-data'\ --form 'user_id="test"'\ --form 'session_id="test"'\ --form 'chat_data={ "messages": [ { "role": "user", "content": "Who is the sender of this transaction - 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060" } ] }' ``` [2] result: The address that initiated the transaction with hash 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 is 0xA1E4380A3B1f749673E270229993eE55F35663b4. """
You can create a swarm of agents to collaborate on complex tasks. Here's an example of how to set up and use a swarm:
fromswarmzero.swarmimportSwarmfromswarmzero.agentimportAgentfromswarmzero.sdk_contextimportSDKContextimportasyncio# Create SDK Contextsdk_context=SDKContext(config_path="./swarmzero_config_example.toml")defsave_report():return"save_item_to_csv"defsearch_on_web():return"search_on_web"# Create individual agentsagent1=Agent(name="Research Agent",instruction="Conduct research on given topics",sdk_context=sdk_context,functions=[search_on_web])agent2=Agent(name="Analysis Agent",instruction="Analyze data and provide insights",sdk_context=sdk_context,functions=[save_report])agent3=Agent(name="Report Agent",instruction="Compile findings into a report",sdk_context=sdk_context,functions=[])# Create swarmswarm=Swarm(name="Research Team",description="A swarm of agents that collaborate on research tasks",instruction="Be helpful and collaborative",functions=[],agents=[agent1,agent2,agent3])asyncdefchat_with_swarm():returnawaitswarm.chat("Can you analyze the following data: [1, 2, 3, 4, 5]")if__name__=="__main__":asyncio.run(chat_with_swarm())
You can add retriever tools to create vector embeddings and retrieve semantic information. It will create vector index for every pdf documents under 'swarmzero-data/files/user' folder and can filter files with required_exts parameter.
- SwarmZero agent supports ".md", '.mdx' ,".txt", '.csv', '.docx', '.pdf' file types.
- SwarmZero agent supports 4 type of retriever (basic, chroma, pinecone-serverless, pinecone-pod) and controlled with retrieval_tool parameter.
fromswarmzeroimportAgentfromdotenvimportload_dotenvload_dotenv()if__name__=="__main__":my_agent=Agent(name="retrieve-test",functions=[],retrieve=True,required_exts= ['.md'],retrieval_tool='chroma' )my_agent.run()""" [1] send a request: ``` curl --request POST\ --url http://localhost:8000/api/v1/chat\ --header 'Content-Type: multipart/form-data'\ --form 'user_id="test"'\ --form 'session_id="test"'\ --form 'chat_data={ "messages": [ { "role": "user", "content": "Can you summarise the documents?" } ] }' ``` """
Users of your agent/swarm may not always be familiar with its abilities.Providing sample prompts allows them to explore what you have built.Here's how to add sample prompts which they can use before committing to use your agent/swarm.
In your swarmzero_config.toml file, create atop level entry called[sample_prompts] and add a new array to the keyprompts like this:
[sample_prompts]prompts = ["What can you help me do?","Which tools do you have access to?","What are your capabilities?"]
[target_agent_id]model ="gpt-3.5-turbo"timeout =15environment ="dev"enable_multi_modal =trueollama_server_url ='http://123.456.78.90:11434'sample_prompts = ["What can you help me do?","Which tools do you have access to?","What are your capabilities?"]
See./swarmzero_config_example.toml for an example configuration file.
If you want to contribute to the codebase, you would need to set up your dev environment. Follow these steps:
- Create a new file called .env
- Copy the contents of.env.example into your new .env file
- API keys for third-party tools are not provided.
OPENAI_API_KEYfrom OpenAI
- If you don't have Poetry installed, you can install it using the following commands:
curl -sSL https://install.python-poetry.org| python3 -export PATH="$HOME/.local/bin:$PATH"
- Activate the Virtual Environment created by Poetry with the following command:
poetry shell
- Install dependencies.
poetry install --no-root
- Make sure you're in the
tests/directory:
cd tests/- Run the test suite:
pytest
- Run tests for a specific module:
pytest tests/path/to/test_module.py
- Run with verbose output:
pytest -v
- Run with a detailed output of each test (including print statements):
pytest -s
- Run with coverage report:
pip install coverage pytest-covpytest --cov --cov-report=html
Reports filetests/htmlcov/index.html
Openhttp://localhost:8000/docs with your browser to see the Swagger UI of the API.
About
SwarmZero's SDK for building AI agents, swarms of agents and much more.