Skip to content

AGENTS.md

Latest commit

 

History

History
422 lines (308 loc) · 20.2 KB

AGENTS.md

File metadata and controls

422 lines (308 loc) · 20.2 KB

Agent Creator Agent Instructions

Agency Swarm is the framework built on the OpenAI Agents SDK. It allows anyone to create a collaborative swarm of agents (Agencies), each with distinct roles and capabilities. Your primary role is to architect tools and agents that fulfill specific needs within the agency. Helpful references for building agents include:

Fetch these resources to familiarize yourself with the framework as needed.

The following steps outline how to build agents from a single prompt:

  1. PRD Creation: Gather information to draft a Product Requirements Document (PRD) for the agency.
  2. Folder Structure and Template Creation: Create the Agent Templates for each agent using the CLI Commands provided below.
  3. Tool Development: Develop each tool and place it in the correct agent's tools folder, ensuring it is robust and ready for production environments.
  4. Agent Creation: Create agent classes and instructions for each agent, ensuring correct folder structure.
  5. Agency Creation: Create the agency class in the agency folder, properly defining the communication flows between the agents.
  6. Testing: Test each tool for the agency, and the agency itself, to ensure they are working as expected.
  7. Iteration: Repeat the above steps as instructed by the user, until the agency performs consistently to the user's satisfaction.

You will find a detailed guide for each of the steps below. Read this entire file first before proceeding.

Step 1: PRD Creation

First, ask the user to provide all necessary details:

  • Agency Name
  • Purpose (a high-level description of what the agency aims to achieve, its target market, and its value proposition)
  • Communication Flows (between agents and from agents to user)
  • Agents (for each agent: name, role, tools with descriptions)

Once you have gathered all details, create the file ./prd.txt using the following template:

# [Agency Name]

---

- **Purpose:** [A high-level description of what the agency aims to achieve, its target market, and the value it offers to its clients.]
- **Communication Flows:**
  - **Between Agents:**
    - [Description of the communication protocols and flows between different agents within the agency, including any shared resources or data.]
    - **Example Flow:**
      - **Agent A -> Agent B:** [Description of the interaction, including trigger conditions and expected outcomes.]
      - **Agent B -> Agent C:** [Description of the interaction, including trigger conditions and expected outcomes.]
  - **Agent to User Communication:** [Description of how agents will communicate with end-users, including any user interfaces or channels used.]

---

## Agent Name

### **Role within the Agency**

[Description of the agent's specific role and responsibilities within the agency.]

### Tools

- **ToolName:**
  - **Description**: [Description on what this tool should do and how it will be used]
  - **Inputs**:
    - [name] (type) - description
  - **Validation**:
    - [Condition] - description
  - **Core Functions:** [List of the main functions the tool must perform.]
  - **APIs**: [List of APIs the tool will use]
  - **Output**: [Description of the expected output of the tool. Output must be a string or a JSON object.]

---

...repeat for each agent

After the user provides the requested details, proceed to drafting the PRD file right away. Provide file path to the PRD file in the response and ask the user to edit it if needed. Once approved, read the PRD file contents again and proceed to the next step.

Best Practices

  • Each tool must perform a specific realistic task: Do not create tools that do not correspond to real world tasks. Each tool should focus on a specific action a human typically would perform. For example, "FetchLeadsFromInstagram" is a valid tool, but "OptimizeEmailSubject" is not. Optimizing email subjects is not a real task. Typically, a tool either: 1) connects to an external API, 2) performs a specific action on local files, 3) uses AI inside.
  • 4-16 Tools Per Agent: Each agent should have between 4 and 16 tools. Avoid breaking down the agency into too many agents, unless their responsibilities are significantly different, or the user has requested it. Avoid creating tools that the user has not requested. If it's unclear what tools the agent will need, ask the user for clarification or continue without them. Note: Each MCP typically contains multiple tools. Count each as 5-10 tools, depending on MCP complexity and capabilities.
  • Ask for API keys before creating any tools: If a tool requires an API key or access token, ask the user to add it to the .env file. Do not proceed with creating the tool until the API key is added, otherwise you will not be able to test them.

Step 2: Folder Structure and Template Creation

After creating the PRD file, setup the folder structure for each agent.

The basic folder structure is already created for you:

├── example_agent/
│   ├── __init__.py
│   ├── example_agent.py
│   ├── instructions.md
│   ├── files/
│   └── tools/
│       ├── ToolName.py
│       ├── ToolName2.py
│       ├── ToolName3.py
│       ├── ...
├── example_agent2/
│   ├── __init__.py
│   ├── example_agent2.py
│   ├── instructions.md
│   ├── files/
│   └── tools/
│       ├── ToolName.py
│       ├── ToolName2.py
│       ├── ToolName3.py
│       ├── ...
├── agency.py
├── shared_instructions.md
├── requirements.txt
├── .env
└──...

Folder Structure Rules:

  • Agency folder must be named in lowercase, with underscores instead of spaces.

  • Each agency and agent has its own dedicated folder.

  • 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.

  • Tool Import Process:

    • Create a file in the 'tools' folder with the same name as the tool class.
    • Tools are automatically imported to the agent class.
    • All new requirements must be added to the requirements.txt file.

  • 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.
    • Create a .env file in the root folder and add a placeholder for OPENAI_API_KEY and any other API keys that are required by the tools for the user to fill in.

Follow this folder structure when further creating or modifying any files. Replace example_agent folders with the actual agents when creating agents for the first time.

Step 3: Tool Creation

Tools are the specific actions that agents can perform. They are defined using pydantic, which provides a convenient interface and automatic type validation. Below is a complete example of a tool file:

# MyCustomTool.py
from agency_swarm.tools import BaseTool
from pydantic import Field
import os
from dotenv import load_dotenv

load_dotenv() # always load the environment variables

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:
        # account_id = "MY_ACCOUNT_ID"
        # api_key = os.getenv("MY_API_KEY") # or access_token = os.getenv("MY_ACCESS_TOKEN")
        # 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 IMMIDIATELY ready to use by the user. It must not contain any mocks, placeholders or hypothetical examples.

Best Practices

  • Use Python Packages: Prefer to use various API wrapper packages and SDKs available on pip, rather than calling these APIs directly using requests.
  • Comments: The code should be well commented, with clear step-by-step explanations of the code. (Eg. "# Step 1: Do something", "# Step 2: Do something else", etc.)
  • Code Reliability: Write actual functional code, without placeholders or hypothetical examples.
  • NEVER include API keys as tool inputs: If a tool needs an API key or access token, always retrieve it from environment variables using the os package inside the run method. Do not define API keys or tokens as input fields for the tool.
  • 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. It will be used to test the tool later.
  • Avoid Redundant Logic: Do not create tools that introduce redundant logic inside. For example, when creating a SQL Database Agent, do not create a tool AnalyzeDatabase that performs some complicated math analysis inside. Instead, simply connect an agent to the database with a QueryDatabase tool, and let the agent perform the analysis.
  • Keep Tools Single-Purpose: Create atomic self-contained tools that perform specific tasks or operations. The agent should then be able to combine these tools autonomously for more complex workflows. In the SQL Database Agent example above, it makes sense to also add a GetMetadata tool, so the agent can use that tool before using the QueryDatabase tool.

Agency Context (Shared State)

Agency context lets your tools and agents share data without passing it in conversation messages.

from agency_swarm.tools import BaseTool

class MyTool(BaseTool):
    value: str = Field(..., description="The value to store in the context")
    def run(self):
        self._context.set("my_key", self.value)
        data = self._context.get("my_key", "default")
        return data

Use agency context for:

  • Large data structures that are expensive to pass between agents
  • Maintaining state across multiple tool calls
  • Sharing data among tools and agents

Best practices:

  • Use descriptive keys to avoid conflicts
  • Provide default values when calling get
  • Clean up unneeded data to keep the context small

MCP Integration

Alternatively to creating custom tools, you can use special MCP servers which already contain predefined tools. In this case, you don't need to create custom tool files for the same functionality or add them to the PRD. You can use MCPs interchangeably with custom tools

from agents.mcp import MCPServerStdio

filesystem_server = MCPServerStdio(
    # This name determines how the agent accesses the tools (e.g., Filesystem_Server.list_files)
    name="Filesystem_Server",
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
    },
    cache_tools_list=True
)
# Attach this server to your Agent via the mcp_servers list:
# my_agent = Agent(..., mcp_servers=[sse_server])
# Reference: https://agency-swarm.ai/core-framework/tools/mcp-integration#step-2-define-sse-server-connection-optional

For remote MCP servers, you can use the MCPServerSse or MCPServerStreamableHttp classes. See documentation for more details.

Important: Prefer creating MCP servers to connect to common platforms like Notion or Hubspot over custom tools. To find the best suited MCP servers, use web search.

Web Search Tool (Built-in)

Agency Swarm has a built-in tool for web searchs. If the agent requires web searchs, you can simply include it in the agent's tools list.

from agents.tool import WebSearchTool

tools = [WebSearchTool()]

Step 4: Agent Creation

To create an agent:

  1. Create an agent module.:

    from agents import ModelSettings
from agency_swarm import Agent
from openai.types.shared import Reasoning

ceo = Agent(
    name="CEO",
    description="Responsible for client communication, task planning and management.",
    instructions="./instructions.md",
    tools_folder="./tools",
    files_folder="./files",
    model="gpt-5",
    model_settings=ModelSettings(
        reasoning=Reasoning(
            effort="medium",
            summary="auto",
        ),
    ),
)
    • 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.
    • model: The model to use for the agent. Use gpt-5 by default, which is already available.
    • tools_folder: Folder containing the tools for the agent. Tool modules are automatically imported. Each tool class must be named the same as the tool file. For example, if the tool class is named MyTool, the tool file must be named MyTool.py.
    • Other Parameters: Additional settings like model_settings or persistence callbacks.

    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.

  2. Create an instructions.md file in the agent's folder.

    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:

    # Role

You are **[insert role, e.g., "a helpful expert" or "a creative storyteller".]**

# Instructions

# [Task Name]

**[Provide a step-by-step instructions process on how this task should be performed. Use a numbered list.]**

[...repeat for each task]

# Additional Notes

- **[Specify any additional notes here, if any. Use bullet points if needed.]**

Best Practices

  • Start Simple: Use concise, verb-driven instructions.
  • Be Specific: Explicitly state desired outputs and formats.
  • Provide Examples: Include concrete examples of expected behavior and tool usage.
  • Use Positive Instructions: Phrase steps as "Do this" rather than "Don't do that".
  • Integrate Tools in Steps: Show exactly when and how to use each tool in the workflow.
  • Use Variables: Parameterize dynamic values with placeholders for clarity.
  • Test Continuously: Refine instructions based on actual test results and feedback.
  • Avoid Speculation: Be conscientious when creating instructions—avoid guessing or making unsupported assumptions. If certain information is not available, simply leave it blank so the user can fill it in.
  • Performance Targets: Include response time or quality targets where appropriate.
  • Output Formats: Specify exact output schemas or formats for agent responses.
  • Preserve Context: Ensure instructions maintain message thread and context for multi-turn conversations.
  • Log Decisions: Instruct agents to log important decisions for audit and traceability.

Step 5: Agency Creation

Agencies are collections of agents that work together to achieve a common goal. They are defined in the agency.py file, which already exists in the root folder.

  1. Import the agents into the agency.py file.

    from dotenv import load_dotenv
from agency_swarm import Agency
from ceo import ceo
from developer import developer
from virtual_assistant import virtual_assistant

load_dotenv()

# do not remove this method, it is used in the main.py file to deploy the agency (it has to be a method)
def create_agency(load_threads_callback=None):
    agency = Agency(
        ceo,
        communication_flows=[
            (ceo, developer),
            (ceo, virtual_assistant),
            (developer, virtual_assistant),
        ],
        shared_instructions="shared_instructions.md",
    )
    return agency

if __name__ == "__main__":
    agency = create_agency()
    agency.terminal_demo()

    Agency must export a create_agency method, which is used for deployment.

    The first argument is the entry point for user communication. The communication flows are defined in the communication_flows parameter.

    A Note on Communication Flows:

    Communication flows are directional. In the communication_flows parameter above, the agent on the left can initiate conversations with the agent on the right.

  2. Define the shared_instructions.md file.

    Shared instructions is a file that contains shared instructions for all agents in the agency. Typically, this file might contain information about the business, ICP, target audience, environment, etc. If user has not provided any information, create a template with headings but leave the content blank for the user to fill in.

Step 6: Testing

The final step is to test each tool and the agency itself, to ensure they are working as expected.

  1. First, install the dependencies for the agency using the following command:

    pip install -r requirements.txt

  2. Then, run each tool file in the tools folder that you created, to ensure they are working as expected.

    python agent_name/tools/tool_name.py

    If any of the tools return an error, you need to fix the code in the tool file.

  3. Once all tools are working as expected, you can test the agency by running the following command:

    python agency.py

    If the terminal demo runs successfully, you have successfully created an agency that works as expected.

Important: Please do not stop on this step until all new tools and agents have been tested and are working as expected. Do not ask for confirmation or wait for the user to respond. Just keep iterating until the agency performs as expected.

Step 7: Iteration

Repeat the above steps as instructed by the user, until the agency performs consistently to the user's satisfaction. First, adjust the tools, then adjust the agents and instructions, then test again. Make sure to repeat each step accordingly.

If the user is not starting their agency from scratch, you can start from one of the steps above accordingly.

Final Notes

  1. 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, check the current folder structure and file contents before proceeding. If you find yourself about to output code in the chat, STOP and reconsider your approach.
  2. Never create files with sample snippets, hypothetical examples or placeholders. When creating custom tools, you must create production-ready functional code.
  3. Ensure all tools are properly tested before submitting your work to the user.
  4. Follow the specified file creation order rigorously: 1. requirements.txt, 2. tools, 3. agents, 4. instructions.md. 5. agency.py.
  5. You can find more documentation in the ./.claude/agents/** for each part of the agent building process accordingly.
  6. Additionally, there is an .cursor/commands/add-mcp.md file that contains the instructions for adding MCP servers your agents.
  7. Before strating to build the new agency, remove example agents.