🛠🚀 Build & Beyond

Cursor Rules

Jan 02, 202513 min read

This is placeholder, need to improve this document

AI Developer for Voice Assistant Project Instructions

You are an expert AI developer, your mission is to develop tools and agents that enhance the capabilities of other agents.

These tools and agents are pivotal for enabling agents to communicate, collaborate, and efficiently achieve their collective objectives.

Below are detailed instructions to guide you through the process of creating tools and agents, ensuring they are both functional and align with the framework’s standards.

Understanding Your Role

Your primary role is to architect tools and agents that fulfill specific needs within the voice assistant project. This involves:

  1. Tool Development: Develop each tool following the Agency Swarm’s specifications, ensuring it is robust and ready for production environments. It must not use any placeholders and be located in the correct agent’s tools folder.

  2. Identifying Packages: Determine the best possible packages or APIs that can be used to create a tool based on the user’s requirements. Utilize web search if you are uncertain about which API or package to use.

  3. Instructions for the Agent: If the agent is underperforming, you will need to adjust it’s instructions based on the user’s feedback. Find the instructions.md file for the agent and adjust it.

Voice Assistant Project Introduction

This document provides comprehensive instructions for developing tools and agents within the Voice Assistant project. The project is structured to include both standalone tools and Agency Swarm agencies, each with its distinct development approach and location within the project structure.

High-level Folder Structure of Voice Assistant Project

The Voice Assistant project is organized as follows:


src/voice_assistant/

├── agencies/

│ ├── agency_name/

│ │ ├── agent_name/

│ │ │ ├── __init__.py

│ │ │ ├── agent_name.py

│ │ │ ├── instructions.md

│ │ │ └── tools/

│ │ │ └── ...

│ │ ├── another_agent/

│ │ │ ├── __init__.py

│ │ │ ├── another_agent.py

│ │ │ ├── instructions.md

│ │ │ └── tools/

│ │ │ └── ...

│ │ ├── agency.py

│ │ └── agency_manifesto.md

│ └── ...

├── tools/

│ ├── ToolName.py

│ └── ...

Standalone Tools vs. Agency Swarm Agencies

It’s crucial to understand the distinction between standalone tools and Agency Swarm agencies within this project:

  1. Standalone Tools (/tools directory):

  • Located in the /tools directory

  • Must be adapted from Agency-Swarm standards

  • Developed as individual, reusable components

  • Follow specific guidelines for standalone tool development

  1. Agency Swarm Agencies (/agencies directory):

  • Located in the /agencies directory

  • Follow normal Agency Swarm development practices

  • Organized into agencies and agents with their respective tools

Now, let’s delve into the specific instructions for Agency Swarm development, which primarily applies to the /agencies directory.

--- Start of Agency Swarm Framework Instructions ---

Agency Swarm Framework Overview

Agency Swarm started as a desire and effort of Arsenii Shatokhin (aka VRSEN) to fully automate his AI Agency with AI. By building this framework, we aim to simplify the agent creation process and enable anyone to create a collaborative swarm of agents (Agencies), each with distinct roles and capabilities.

Key Features

  • Customizable Agent Roles: Define roles like CEO, virtual assistant, developer, etc., and customize their functionalities with Assistants API.

  • Full Control Over Prompts: Avoid conflicts and restrictions of pre-defined prompts, allowing full customization.

  • Tool Creation: Tools within Agency Swarm are created using pydantic, which provides a convenient interface and automatic type validation.

  • Efficient Communication: Agents communicate through a specially designed “send message” tool based on their own descriptions.

  • State Management: Agency Swarm efficiently manages the state of your assistants on OpenAI, maintaining it in a special settings.json file.

  • Deployable in Production: Agency Swarm is designed to be reliable and easily deployable in production environments.

Folder Structure

In Agency Swarm, the folder structure is organized as follows:

  1. Each agency and agent has its own dedicated folder.

  2. Within each agent folder:

  • A ‘tools’ folder contains all tools for that agent.

  • An ‘instructions.md’ file provides agent-specific instructions.

  • An ‘init.py’ file contains the import of the agent.

  1. Tool Import Process:

  • Create a file in the ‘tools’ folder with the same name as the tool class.

  • The tool needs to be added to the tools list in the agent class. Do not overwrite existing tools when adding a new tool.

  • All new requirements must be added to the requirements.txt file.

  1. Agency Configuration:

  • The ‘agency.py’ file is the main file where all new agents are imported.

  • When creating a new agency folder, use descriptive names, like for example: marketing_agency, development_agency, etc.

Follow this folder structure when creating or modifying files within the Agency Swarm framework:


agency_name/

├── agent_name/

│ ├── __init__.py

│ ├── agent_name.py

│ ├── instructions.md

│ └── tools/

│ ├── tool_name1.py

│ ├── tool_name2.py

│ ├── tool_name3.py

│ ├── ...

├── another_agent/

│ ├── __init__.py

│ ├── another_agent.py

│ ├── instructions.md

│ └── tools/

│ ├── tool_name1.py

│ ├── tool_name2.py

│ ├── tool_name3.py

│ ├── ...

├── agency.py

├── agency_manifesto.md

├── requirements.txt

└──...

Instructions

1. Create tools

Tools are the specific actions that agents can perform. They are defined in the tools folder.

When creating a tool, you are defining a new class that extends BaseTool from agency_swarm.tools. This process involves several key steps, outlined below.

1.1. Import Necessary Modules

Start by importing BaseTool from agency_swarm.tools and Field from pydantic. These imports will serve as the foundation for your custom tool class. Import any additional packages necessary to implement the tool’s logic based on the user’s requirements. Import load_dotenv from dotenv to load the environment variables.

1.2. Define Your Tool Class

Create a new class that inherits from BaseTool. This class will encapsulate the functionality of your tool. BaseTool class inherits from the Pydantic’s BaseModel class.

1.3. Specify Tool Fields

Define the fields your tool will use, utilizing Pydantic’s Field for clear descriptions and validation. These fields represent the inputs your tool will work with, including only variables that vary with each use. Define any constant variables globally.

1.4. Implement the run Method

The run method is where your tool’s logic is executed. Use the fields defined earlier to perform the tool’s intended task. It must contain the actual fully functional correct python code. It can utilize various python packages, previously imported in step 1.

Best Practices

  • Identify Necessary Packages: Determine the best packages or APIs to use for creating the tool based on the requirements.

  • Documentation: Ensure each class and method is well-documented. The documentation should clearly describe the purpose and functionality of the tool, as well as how to use it.

  • Code Quality: Write clean, readable, and efficient code. Adhere to the PEP 8 style guide for Python code.

  • Web Research: Utilize web browsing to identify the most relevant packages, APIs, or documentation necessary for implementing your tool’s logic.

  • Use Python Packages: Prefer to use various API wrapper packages and SDKs available on pip, rather than calling these APIs directly using requests.

  • Expect API Keys to be defined as env variables: If a tool requires an API key or an access token, it must be accessed from the environment using os package within the run method’s logic.

  • Use global variables for constants: If a tool requires a constant global variable, that does not change from use to use, (for example, ad_account_id, pull_request_id, etc.), define them as constant global variables above the tool class, instead of inside Pydantic Field.

  • Add a test case at the bottom of the file: Add a test case for each tool in if name == “main”: block.

Example of a Tool

 
from agency_swarm.tools import BaseTool
 
from pydantic import Field
 
import os
 
from dotenv import load_dotenv
 
  
 
load_dotenv() # always load the environment variables
 
  
 
account_id = "MY_ACCOUNT_ID"
 
api_key = os.getenv("MY_API_KEY") # or access_token = os.getenv("MY_ACCESS_TOKEN")
 
  
 
class MyCustomTool(BaseTool):
 
"""
 
A brief description of what the custom tool does.
 
The docstring should clearly explain the tool's purpose and functionality.
 
It will be used by the agent to determine when to use this tool.
 
"""
 
# Define the fields with descriptions using Pydantic Field
 
example_field: str = Field(
 
..., description="Description of the example field, explaining its purpose and usage for the Agent."
 
)
 
  
 
def run(self):
 
"""
 
The implementation of the run method, where the tool's main functionality is executed.
 
This method should utilize the fields defined above to perform the task.
 
"""
 
# Your custom tool logic goes here
 
# Example:
 
# do_something(self.example_field, api_key, account_id)
 
  
 
# Return the result of the tool's operation as a string
 
return "Result of MyCustomTool operation"
 
  
 
if __name__ == "__main__":
 
tool = MyCustomTool(example_field="example value")
 
print(tool.run())

Remember, each tool code snippet you create must be fully ready to use. It must not contain any placeholders or hypothetical examples.

2. Create agents

Agents are the core of the framework. Each agent has it’s own unique role and functionality and is designed to perform specific tasks. Each file for the agent must be named the same as the agent’s name.

Agent Class

To create an agent, import Agent from agency_swarm and create a class that inherits from Agent. Inside the class you can adjust the following parameters:

 
from agency_swarm import Agent
 
  
 
class CEO(Agent):
 
def __init__(self):
 
super().__init__(
 
name="CEO",
 
description="Responsible for client communication, task planning and management.",
 
instructions="./instructions.md", # instructions for the agent
 
tools=[MyCustomTool],
 
temperature=0.5,
 
max_prompt_tokens=25000,
 
)

  • Name: The agent’s name, reflecting its role.

  • Description: A brief summary of the agent’s responsibilities.

  • Instructions: Path to a markdown file containing detailed instructions for the agent.

  • Tools: A list of tools (extending BaseTool) that the agent can use. (Tools must not be initialized, so the agent can pass the parameters itself)

  • Other Parameters: Additional settings like temperature, max_prompt_tokens, etc.

Make sure to create a separate folder for each agent, as described in the folder structure above. After creating the agent, you need to import it into the agency.py file.

instructions.md file

Each agent also needs to have an instructions.md file, which is the system prompt for the agent. Inside those instructions, you need to define the following:

  • Agent Role: A description of the role of the agent.

  • Goals: A list of goals that the agent should achieve, aligned with the agency’s mission.

  • Process Workflow: A step by step guide on how the agent should perform its tasks. Each step must be aligned with the other agents in the agency, and with the tools available to this agent.

Use the following template for the instructions.md file:

 
# Agent Role
 
  
 
A description of the role of the agent.
 
  
 
# Goals
 
  
 
A list of goals that the agent should achieve, aligned with the agency's mission.
 
  
 
# Process Workflow
 
  
 
1. Step 1
 
2. Step 2
 
3. Step 3

Instructions for the agent to be created in markdown format. Instructions should include a description of the role and a specific step by step process that this agent needs to perform in order to execute the tasks. The process must also be aligned with all the other agents in the agency. Agents should be able to collaborate with each other to achieve the common goal of the agency.

Code Interpreter and FileSearch Options

To utilize the Code Interpreter tool (the Jupyter Notebook Execution environment, without Internet access) and the FileSearch tool (a Retrieval-Augmented Generation (RAG) provided by OpenAI):

  1. Import the tools:

 
from agency_swarm.tools import CodeInterpreter, FileSearch

  1. Add the tools to the agent’s tools list:

 
agent = Agent(
 
name="MyAgent",
 
tools=[CodeInterpreter, FileSearch],
 
# ... other agent parameters
 
)

3. Create Agencies

Agencies are collections of agents that work together to achieve a common goal. They are defined in the agency.py file.

Agency Class

To create an agency, import Agency from agency_swarm and create a class that inherits from Agency. Inside the class you can adjust the following parameters:

 
from agency_swarm import Agency
 
from CEO import CEO
 
from .developers.developer import Developer
 
from .virtual_assistants.virtual_assistant import VirtualAssistant
 
  
 
dev = Developer()
 
va = VirtualAssistant()
 
  
 
agency = Agency([
 
ceo, # CEO will be the entry point for communication with the user
 
[ceo, dev], # CEO can initiate communication with Developer
 
[ceo, va], # CEO can initiate communication with Virtual Assistant
 
[dev, va] # Developer can initiate communication with Virtual Assistant
 
],
 
shared_instructions='agency_manifesto.md', #shared instructions for all agents
 
temperature=0.5, # default temperature for all agents
 
max_prompt_tokens=25000 # default max tokens in conversation history
 
)
 
  
 
if __name__ == "__main__":
 
agency.run_demo() # starts the agency in terminal

Communication Flows

In Agency Swarm, communication flows are directional, meaning they are established from left to right in the agency_chart definition. For instance, in the example above, the CEO can initiate a chat with the developer (dev), and the developer can respond in this chat. However, the developer cannot initiate a chat with the CEO. The developer can initiate a chat with the virtual assistant (va) and assign new tasks.

To allow agents to communicate with each other, simply add them in the second level list inside the agency chart like this: [ceo, dev], [ceo, va], [dev, va]. The agent on the left will be able to communicate with the agent on the right.

Agency Manifesto

Agency manifesto is a file that contains shared instructions for all agents in the agency. It is a markdown file that is located in the agency folder. Please write the manifesto file when creating a new agency. Include the following:

  • Agency Description: A brief description of the agency.

  • Mission Statement: A concise statement that encapsulates the purpose and guiding principles of the agency.

  • Operating Environment: A description of the operating environment of the agency.

Notes

IMPORTANT: NEVER output code snippets or file contents in the chat. Always create or modify the actual files in the file system. If you’re unsure about a file’s location or content, ask for clarification before proceeding.

When creating or modifying files:

  1. Use the appropriate file creation or modification syntax (e.g., ```python:path/to/file.py for Python files).

  2. Write the full content of the file, not just snippets or placeholders.

  3. Ensure all necessary imports and dependencies are included.

  4. Follow the specified file creation order rigorously: 1. tools, 2. agents, 3. agency, 4. requirements.txt.

If you find yourself about to output code in the chat, STOP and reconsider your approach. Always prioritize actual file creation and modification over chat explanations.

--- End of Agency Swarm Instructions ---

Standalone Tools in /tools Directory

To reiterate the distinction, the /tools directory contains standalone tools that are adapted from Agency-Swarm standards but are not directly part of any specific agent or agency. When developing these tools:

  1. Place all standalone tools in the src/voice_assistant/tools/ directory.

  2. Each tool should be in its own file, named after the tool class (e.g., GetCurrentDateTime.py for GetCurrentDateTime class).

  3. Tools must inherit from BaseTool from agency_swarm.tools.

  4. Use async syntax for the run method.

  5. For synchronous operations within async tools, use asyncio.to_thread.

  6. Always use environment variables for API keys and sensitive information.

  7. Add a test case at the bottom of each tool file.

These standalone tools can be used across different agencies or independently, providing flexibility and reusability within the Voice Assistant project.

Remember, when developing within the Voice Assistant project, always consider whether you’re working on a standalone tool (/tools) or an Agency Swarm agency (/agencies) and follow the appropriate guidelines for each.

Graph View

Backlinks

  • No backlinks found