From 65112a647347b2852d23bf98bbd9cfce0bc705f2 Mon Sep 17 00:00:00 2001 From: Nick Bobrowski <39348559+bonk1t@users.noreply.github.com> Date: Tue, 19 Nov 2024 02:12:17 +0000 Subject: [PATCH] Add Mintlify docs --- agency-swarm.md | 473 ++++++++++++++++++ .../asynchronous-execution.mdx | 46 ++ ...tomizing-prompts-and-few-shot-learning.mdx | 71 +++ .../open-source-models-support.mdx | 79 +++ .../advanced-topics/production-readiness.mdx | 56 +++ docs_new/api-reference/api-reference.mdx | 50 ++ docs_new/contributing/contributing.mdx | 95 ++++ docs_new/examples.mdx | 93 ++++ docs_new/faq/faq.mdx | 35 ++ docs_new/favicon.svg | 9 + .../folder-structure/folder-structure.mdx | 38 ++ .../communication-flows.mdx | 21 + .../conversation-context-management.mdx | 9 + .../design-and-architecture.mdx | 5 + .../output-validation-and-reliability.mdx | 8 + .../framework-overview/prompt-flexibility.mdx | 8 + .../framework-overview/state-management.mdx | 7 + .../framework-overview/streaming-support.mdx | 7 + docs_new/getting-started/installation.mdx | 51 ++ docs_new/getting-started/quickstart.mdx | 103 ++++ docs_new/how-to-guides/creating-agencies.mdx | 40 ++ docs_new/how-to-guides/creating-agents.mdx | 52 ++ docs_new/how-to-guides/creating-tools.mdx | 48 ++ .../defining-agent-instructions.mdx | 29 ++ docs_new/how-to-guides/deployment.mdx | 31 ++ .../managing-communication-flows.mdx | 20 + .../using-code-interpreter-and-filesearch.mdx | 34 ++ docs_new/introduction/design-principles.mdx | 16 + docs_new/introduction/key-features.mdx | 11 + docs_new/introduction/overview.mdx | 35 ++ docs_new/key-entities/agents.mdx | 20 + docs_new/key-entities/tasks-and-functions.mdx | 15 + docs_new/key-entities/tools.mdx | 20 + docs_new/mint.json | 147 ++++++ docs_new/mintlify.cursorrules | 424 ++++++++++++++++ 35 files changed, 2206 insertions(+) create mode 100644 agency-swarm.md create mode 100644 docs_new/advanced-topics/asynchronous-execution.mdx create mode 100644 docs_new/advanced-topics/customizing-prompts-and-few-shot-learning.mdx create mode 100644 docs_new/advanced-topics/open-source-models-support.mdx create mode 100644 docs_new/advanced-topics/production-readiness.mdx create mode 100644 docs_new/api-reference/api-reference.mdx create mode 100644 docs_new/contributing/contributing.mdx create mode 100644 docs_new/examples.mdx create mode 100644 docs_new/faq/faq.mdx create mode 100644 docs_new/favicon.svg create mode 100644 docs_new/folder-structure/folder-structure.mdx create mode 100644 docs_new/framework-overview/communication-flows.mdx create mode 100644 docs_new/framework-overview/conversation-context-management.mdx create mode 100644 docs_new/framework-overview/design-and-architecture.mdx create mode 100644 docs_new/framework-overview/output-validation-and-reliability.mdx create mode 100644 docs_new/framework-overview/prompt-flexibility.mdx create mode 100644 docs_new/framework-overview/state-management.mdx create mode 100644 docs_new/framework-overview/streaming-support.mdx create mode 100644 docs_new/getting-started/installation.mdx create mode 100644 docs_new/getting-started/quickstart.mdx create mode 100644 docs_new/how-to-guides/creating-agencies.mdx create mode 100644 docs_new/how-to-guides/creating-agents.mdx create mode 100644 docs_new/how-to-guides/creating-tools.mdx create mode 100644 docs_new/how-to-guides/defining-agent-instructions.mdx create mode 100644 docs_new/how-to-guides/deployment.mdx create mode 100644 docs_new/how-to-guides/managing-communication-flows.mdx create mode 100644 docs_new/how-to-guides/using-code-interpreter-and-filesearch.mdx create mode 100644 docs_new/introduction/design-principles.mdx create mode 100644 docs_new/introduction/key-features.mdx create mode 100644 docs_new/introduction/overview.mdx create mode 100644 docs_new/key-entities/agents.mdx create mode 100644 docs_new/key-entities/tasks-and-functions.mdx create mode 100644 docs_new/key-entities/tools.mdx create mode 100644 docs_new/mint.json create mode 100644 docs_new/mintlify.cursorrules diff --git a/agency-swarm.md b/agency-swarm.md new file mode 100644 index 00000000..5fbcf36a --- /dev/null +++ b/agency-swarm.md @@ -0,0 +1,473 @@ +Agency-Swarm is an open-source framework designed to facilitate the creation and orchestration of multi-agent AI systems. Here's a detailed overview of its key components and functionalities: + +## Design and Architecture + +Agency-Swarm employs a modular architecture that allows for flexible configuration of AI agents. The framework is built on top of OpenAI's Assistants API and focuses on creating a collaborative environment where multiple specialized agents can work together to accomplish complex tasks. + +The framework in short for your understanding: connecting assistants with SendMessage tool, thus enabling them to call other agents as tools. + +## Key Entities and Definitions + +### Agents + +Agents are the core building blocks of the Agency-Swarm framework. Each agent is a specialized entity designed to perform specific tasks or handle particular aspects of a problem. Agents can be configured with: + +- Custom instructions +- Specific tools or functions they can use +- Unique personalities or roles + +### Tools and Functions + +Agents can be equipped with various tools and functions to enhance their capabilities. These can include: + +- Web searching +- Data analysis +- File manipulation +- API interactions + +Tools are defined as Python functions that agents can call to perform specific actions. + +### Tasks + +Tasks represent the work units that agents need to complete. They can be high-level objectives broken down into subtasks, allowing for complex problem-solving through collaboration between agents. + +## Agent Interaction and Task Delegation + +Agency-Swarm supports a flexible system for task handoff and delegation between agents. This allows for: + +- Hierarchical structures: Supervisor agents can delegate tasks to subordinate agents +- Dynamic allocation: Agents can decide which other agent is best suited for a particular subtask + +The framework facilitates smooth transitions between agents, ensuring that context and relevant information are preserved during handoffs. + +## Conversation Context Management + +Agency-Swarm maintains conversation context through a shared memory system. This allows agents to: + +- Access previous interactions and decisions +- Build upon information gathered by other agents +- Maintain coherence in multi-turn conversations + +## State Management + +While Agency-Swarm provides basic state management through its shared memory system, it does not have a sophisticated built-in state management solution. Developers may need to implement custom state handling for more complex applications. + +## Output Validation and Reliability + +The framework includes basic output validation mechanisms, but the reliability of results largely depends on the quality of the underlying language models and the specific implementation. Developers are encouraged to implement additional validation and error-handling routines for production use. + +## Framework Structure + +Hierarchical: Supervisor agents manage and delegate to subordinate agents + +## Production-Readiness + +As of my knowledge cutoff, Agency-Swarm is primarily an experimental framework and may not be fully production-ready. It is designed more for research and prototyping rather than large-scale deployment. Users should thoroughly test and potentially extend the framework for production use. + +## Streaming Support + +Agency-Swarm does support streaming responses from language models, allowing for real-time interaction and output generation. + +## Prompt Flexibility + +The framework offers high flexibility in prompt design. There are no hardcoded prompts or interactions, allowing developers to fully customize agent behaviors and interactions through custom instructions and configurations. + +--- + +## 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](https://platform.openai.com/docs/assistants/overview). +- **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. + +3. 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. + +4. 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. 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. + +#### 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. + +#### 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. + +#### 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 + +```python +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: + +```python +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: + +```md +# 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: + + ```python + from agency_swarm.tools import CodeInterpreter, FileSearch + + ``` + +2. Add the tools to the agent's tools list: + + ```python + 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: + +```python +from agency_swarm import Agency +from CEO import CEO +from Developer import Developer +from VirtualAssistant 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. + +--- +--- + + +Comprehensive Description of the Agency Swarm Framework + +Overview + +The Agency Swarm Framework is an open-source orchestration platform designed to manage AI agents in complex, multi-agent environments. It leverages OpenAI’s Assistance API (with support for other LLMs) to create highly customizable and efficient workflows for production-grade AI applications. This framework abstracts the complexities of low-level agent interactions while providing users with complete control over tasks, tools, and communication flows. + +Key Design Principles + +1. Full Customization and Modularity + + • No Hardcoded Prompts: Unlike many frameworks, Agency Swarm provides users with complete control over prompts, ensuring flexibility and adaptability for various use cases. + • Dynamic Agent Setup: Agents are not predefined; users can create, configure, and link agents based on specific roles and tasks. + +2. Production-Readiness + + • Designed for real-world applications with robust error handling, asynchronous execution, and advanced monitoring. + • Streamlined setup processes allow seamless integration with various AI models, from proprietary to open-source. + +Key Entities and Their Definitions + +1. Agents + +Agents are the core units of the framework, each specializing in a specific task or role. They communicate through structured interactions and can leverage various tools to accomplish their objectives. + • CEO Agent: Responsible for task delegation and high-level decision-making. + • Developer Agent: Focused on code generation, debugging, and technical tasks. + • Virtual Assistant (VA) Agent: Handles routine tasks like scheduling, drafting emails, or managing budgets. + • Custom Agents: Users can define agents tailored to unique workflows, leveraging different LLMs or specialized tools. + +Key Features of Agents: + • Role Descriptions: Each agent operates based on its predefined role, which guides its interactions. + • Few-Shot Learning: Agents can be initialized with example conversations or task outputs for consistent behavior. + • Response Validation: Ensures agents return expected outputs by validating responses against predefined rules. + +2. Tools + +Tools are modular functions that agents can call to perform specific tasks. + • Custom Tools: User-defined functions that extend the agent’s capabilities. + • Predefined Tools: Built-in functionalities like web search, file management, and proposal generation. + • OpenAPI Schema Integration: Converts external APIs into tools, ensuring seamless integration with external systems. + +Key Features of Tools: + • Parallel Execution: Tools can run in separate threads to reduce latency. + • Validation: Tools validate input/output based on predefined schemas, reducing runtime errors. + +3. Tasks and Functions + +Tasks are high-level operations delegated by agents, typically involving one or more tools. Functions allow agents to break down complex tasks into manageable actions, leveraging asynchronous execution and parallel processing. + +Core Features + +1. Asynchronous Execution + +The framework supports asynchronous modes to enhance performance: + • Threading Mode for Agents: Allows agents to run independently, improving multitasking. + • Tools Threading: Enables parallel execution of tools, significantly reducing latency for I/O-bound operations. + +2. Task Delegation and Agent Communication + +Agents communicate and delegate tasks based on predefined communication flows: + • Hierarchical Structure: Certain agents (e.g., CEO) delegate tasks to sub-agents (e.g., Developer or VA). + • Function Calling: Agents interact using structured function calls, ensuring efficient and clear task delegation. + +3. Conversation Context Management + + • Dynamic Context Truncation: OpenAI’s truncation strategies are leveraged to maintain relevant context in long conversations. + • Max Tokens Management: Controls prompt and completion length for efficient token usage. + • State Management: Shared states between tools and agents ensure consistent task execution, preventing redundant or conflicting operations. + +4. Output Validation and Reliability + + • Response Validators: Validate agent outputs to ensure they meet specified criteria (e.g., responses must include emojis for a customer support agent). + • Tool Input/Output Validation: Validates data before and after tool execution, reducing runtime errors. + • Error Handling: Agents are designed to self-correct based on validation errors, improving reliability in production. + +5. Streaming and Real-Time Interaction + + • The framework supports streaming responses, providing real-time feedback during task execution. However, some features may be limited for certain open-source models. + +Advanced Features + +1. Support for Multiple LLMs + + • OpenAI Assistance API: Full compatibility with the latest features, including parallel tool calls and fine-tuned models. + • Open-Source Models: Integration with models like Llama 3, Anthropic Claude, and Google Gemini via Light LLM and Astra Assistance API. + +2. Flexible Prompts + • Few-Shot Learning: Customize agent behavior by providing example prompts. + +3. Evaluation and Monitoring + + • Task and Response Logging: Tracks all agent interactions and tool calls. + • Performance Metrics: Provides insights into agent and tool efficiency, highlighting bottlenecks or errors. + • Debugging Tools: Integrated with developer-friendly interfaces like Gradio for real-time interaction testing. + +Framework Structure + +1. Hierarchical Communication + +Agents operate within a hierarchy, where task delegation flows from top-level agents (e.g., CEO) to specialized agents. + +2. Shared State Management + + • Agents and tools share a global state to manage intermediate data and context. + • Example: A file creation task stores file paths in the shared state for subsequent tasks. + + +Setting Up and Running the Framework + +1. Installation + + • Install the latest version from the GitHub repository. + • Supports OpenAI, Light LLM, and Astra Assistance API for integration with multiple models. + +2. Configuration + + • Define agents, tools, and their communication flows. + • Set parameters like max_prompt_tokens, parallel_tool_calls, and response_format. + +3. Deployment + + • Suitable for both cloud-based and local deployments. + • Production-ready features ensure reliability, scalability, and minimal latency. + +Conclusion + +The Agency Swarm Framework is a powerful tool for orchestrating AI agents in complex workflows. With its emphasis on customization, asynchronous execution, and advanced validation, it is well-suited for production environments. Its flexibility in supporting multiple LLMs and integration with external APIs makes it an indispensable asset for AI-driven projects. diff --git a/docs_new/advanced-topics/asynchronous-execution.mdx b/docs_new/advanced-topics/asynchronous-execution.mdx new file mode 100644 index 00000000..e592f186 --- /dev/null +++ b/docs_new/advanced-topics/asynchronous-execution.mdx @@ -0,0 +1,46 @@ +--- +title: "Asynchronous Execution" +description: "Enhance the performance of your agency by running agents and tools asynchronously." +icon: "bolt" +--- + + +Asynchronous execution allows agents and tools to operate concurrently, improving overall efficiency. + + +## Enabling Asynchronous Agents + +To enable asynchronous execution for agents, set the `async_mode` parameter to `"threading"` when initializing the agency. + + +agency = Agency(agents=[ceo], async_mode='threading') + + +**Benefits**: + +- Agents operate independently without waiting for others to complete tasks. +- Improved performance in multi-agent setups. + +## Enabling Asynchronous Tools + +To enable asynchronous execution for tools, set the `async_mode` parameter to `"tools_threading"`. + + +agency = Agency(agents=[ceo], async_mode='tools_threading') + + +**Benefits**: + +- Tools execute concurrently, reducing latency for I/O-bound operations. +- Enhanced responsiveness of agents utilizing tools. + +## Considerations + + +When using asynchronous execution, be mindful of concurrency issues. + + +- **Concurrency Control**: Ensure thread-safe operations to prevent race conditions. Use thread locks or other synchronization mechanisms if necessary. + +- **Resource Management**: Monitor system resources to avoid overconsumption due to multiple threads. Keep an eye on CPU and memory usage. + \ No newline at end of file diff --git a/docs_new/advanced-topics/customizing-prompts-and-few-shot-learning.mdx b/docs_new/advanced-topics/customizing-prompts-and-few-shot-learning.mdx new file mode 100644 index 00000000..8673e215 --- /dev/null +++ b/docs_new/advanced-topics/customizing-prompts-and-few-shot-learning.mdx @@ -0,0 +1,71 @@ +--- +title: "Customizing Prompts and Few-Shot Learning" +description: "Fine-tune agent behavior by customizing prompts and providing few-shot examples." +icon: "magic" +--- + +Fine-tune agent behavior by customizing prompts and providing few-shot examples. + + +Custom prompts and few-shot learning help your agents understand the desired response style and content, leading to more accurate and tailored outputs. + + +## Custom Prompts + +### Modify Instructions + +Adjust the `instructions.md` file associated with your agent to change how it responds. + + +# Agent Instructions + +You are a friendly assistant that helps users with booking flights and hotels. + + +### Dynamic Prompts + +Programmatically alter prompts based on context or user input. + + +base_instructions = "You are an assistant who provides technical support." + +additional_context = "Assist the user with troubleshooting network issues." + +agent = Agent( + name="SupportAgent", + prompt=f"{base_instructions}\n\n{additional_context}" +) + + +## Few-Shot Examples + +Few-shot examples provide sample interactions to guide agent responses. + +### Implementation + + +```python +examples = [ + {"role": "user", "content": "Hi!"}, + {"role": "assistant", "content": "Hello! How can I assist you today?"}, + {"role": "user", "content": "I need help resetting my password."}, + {"role": "assistant", "content": "Sure, I can help with that. Have you tried using the 'Forgot Password' feature?"} +] + +agent = Agent(name="Helper", examples=examples) +``` + + + +These examples help the agent understand the expected conversation flow and response style. + + +## Benefits + + + +- **Consistency**: Ensures agents produce consistent and predictable outputs aligned with your desired style. + +- **Adaptability**: Tailors agent responses to specific domains, improving user experience. + + diff --git a/docs_new/advanced-topics/open-source-models-support.mdx b/docs_new/advanced-topics/open-source-models-support.mdx new file mode 100644 index 00000000..ca4f1363 --- /dev/null +++ b/docs_new/advanced-topics/open-source-models-support.mdx @@ -0,0 +1,79 @@ +--- +title: "Open-Source Models Support" +description: "Utilize open-source models to provide flexibility and control over your AI agents." +icon: "code-fork" +--- + +While OpenAI models are recommended, Agency Swarm supports open-source models through projects that mimic the Assistants API. + + +Utilizing open-source models allows for more flexibility and control over your AI agents. + + +## Supported Projects + + + + +Best option for running open-source models. Supports Assistants API V2. + + + +Fully local and stable, supports Assistants API V1. + + + + +## Integration Steps + + + + +Use pip to install necessary packages. + + +pip install astra-assistants-api gradio + + + + +Configure your API clients to use the open-source models. + + +from openai import OpenAI +from astra_assistants import patch +from agency_swarm import set_openai_client + +client = patch(OpenAI()) +set_openai_client(client) + + + + +Instantiate your agents using the open-source models. + + +ceo = Agent(name="CEO", model='ollama/llama3') + + + + +Start your agency with the configured agents. + + +agency = Agency([ceo]) +agency.run_demo() + + + + + +## Limitations + + +Be aware of the limitations when using open-source models. + + +- **Function Calling**: Not supported by most open-source models. +- **Retrieval-Augmented Generation**: Often limited; consider custom implementations. +- **Code Interpreter**: Not supported in current open-source assistants. \ No newline at end of file diff --git a/docs_new/advanced-topics/production-readiness.mdx b/docs_new/advanced-topics/production-readiness.mdx new file mode 100644 index 00000000..39437821 --- /dev/null +++ b/docs_new/advanced-topics/production-readiness.mdx @@ -0,0 +1,56 @@ +--- +title: "Production Readiness" +description: "Prepare your agency for production by enhancing reliability, scalability, and security." +icon: "check-circle-o" +--- + + +Ensuring your agency is production-ready involves careful planning and implementation of best practices. + + +## Key Considerations + + + + +Implement comprehensive error handling within agents and tools to gracefully handle unexpected issues. + + +Use try-except blocks and logging to capture and manage exceptions. + + + + +Secure API keys, enforce access controls, and sanitize inputs to protect against vulnerabilities. + + +Never hard-code API keys or sensitive information in your code. + + + + +Use monitoring tools to track performance and detect anomalies. Maintain logs for auditing and debugging. + + + + +Design for horizontal scaling to handle increased loads efficiently. + + +Consider using cloud services that support auto-scaling features. + + + + + +## Best Practices + + + +- **Testing**: Thoroughly test agents and tools under various conditions, including edge cases. + +- **Documentation**: Maintain clear documentation for maintenance and onboarding of new team members. + +- **Continuous Integration/Continuous Deployment (CI/CD)**: Set up pipelines for automated testing and deployment to streamline updates. + + \ No newline at end of file diff --git a/docs_new/api-reference/api-reference.mdx b/docs_new/api-reference/api-reference.mdx new file mode 100644 index 00000000..618ed611 --- /dev/null +++ b/docs_new/api-reference/api-reference.mdx @@ -0,0 +1,50 @@ +--- +title: "API Reference" +description: "Gain a deeper understanding of the core classes and methods available in Agency Swarm." +icon: "book" +--- + +## Agents + + +::: agency_swarm.agents.agent +::: + + +## Agency + + +::: agency_swarm.agency.agency +::: + + +## ToolFactory + + +::: agency_swarm.tools.ToolFactory +::: + + +## Agents (Agent Class Methods) + + +```python +::: agency_swarm.agents.agent.Agent +``` + + +## Agency (Agency Class Methods) + + +```python +::: agency_swarm.agency.agency.Agency +``` + + +## ToolFactory (ToolFactory Class Methods) + + +```python +::: agency_swarm.tools.ToolFactory +``` + diff --git a/docs_new/contributing/contributing.mdx b/docs_new/contributing/contributing.mdx new file mode 100644 index 00000000..a0a6c421 --- /dev/null +++ b/docs_new/contributing/contributing.mdx @@ -0,0 +1,95 @@ +--- +title: "Contributing to Agency Swarm" +description: "Learn how to contribute to Agency Swarm" +--- + +We welcome contributions to Agency Swarm! Here's how you can contribute: + + +By contributing to the project, you help improve the tool for everyone. + + +## Contributing Agents and Tools + + + + +Place new agents in the `agency_swarm/agents/` directory within an appropriate category. + + +agency_swarm/ +└── agents/ + └── your_agent_category/ + └── YourAgentName/ + ├── __init__.py + ├── YourAgentName.py + ├── instructions.md + └── tools/ + ├── ToolName.py + └── ... + + + + +Add new tools to the `agency_swarm/tools/` directory under a relevant category. + + +agency_swarm/ +└── tools/ + └── your_tool_category/ + ├── __init__.py + ├── ToolName.py + └── ... + + + + + +## Adding Tests + + +Testing ensures that your contributions work as intended and do not break existing functionality. + + +- **Location**: Place tests in the `agency_swarm/tests/` directory. + + +def test_my_custom_tool(): + tool = MyCustomTool(input_field="test") + result = tool.run() + assert "expected_output" in result + + +## Submitting Changes + + + + +Create a fork of the Agency Swarm repository on GitHub. + + + +Work on a feature branch for your changes. + + +git checkout -b feature/your-feature-name + + + + +Describe your changes and submit a pull request for review. + + + + +## Guidelines + + + +- **Code Quality**: Follow PEP 8 style guidelines for Python code. + +- **Documentation**: Update or add documentation for your contributions to help others understand your work. + +- **Testing**: Ensure all new and existing tests pass before submitting your pull request. + + \ No newline at end of file diff --git a/docs_new/examples.mdx b/docs_new/examples.mdx new file mode 100644 index 00000000..1f9b939d --- /dev/null +++ b/docs_new/examples.mdx @@ -0,0 +1,93 @@ +--- +title: "Examples" +description: "Explore practical examples and tutorials to get the most out of Agency Swarm." +icon: "code" +--- + + + + + +Create a basic agent that responds to user input. + + +from agency_swarm import Agent, Agency + +assistant = Agent(name="Assistant", role="Provide helpful responses.") + +agency = Agency(agents=[assistant]) +agency.run_demo() + + + + + + +Set up multiple agents that communicate with each other. + + +```python +from agency_swarm import Agent, Agency + +agent1 = Agent(name="Agent1", role="Send messages to Agent2.") +agent2 = Agent(name="Agent2", role="Respond to messages from Agent1.") + +agency_chart = { + "Agent1": ["Agent2"], + "Agent2": [] +} + +agency = Agency(agents=[agent1, agent2], agency_chart=agency_chart) +agency.run_demo() +``` + + + + + + +Create custom tools for agents to perform specific tasks. + + +from agency_swarm import Agent, Agency, Tool + +class CalculatorTool(Tool): + def run(self, input): + return str(eval(input)) + +calculator = CalculatorTool(name="Calculator") + +agent = Agent(name="MathAssistant", tools=[calculator]) + +agency = Agency(agents=[agent]) +agency.run_demo() + + + + + + +Examples of agencies can be found in the [agency-swarm-lab](https://github.com/VRSEN/agency-swarm-lab) repository: + +- [WebDevCrafters](https://github.com/VRSEN/agency-swarm-lab/tree/main/WebDevCrafters) - A web development agency that builds responsive web applications using Next.js, React, and MUI. +- [CodeGuardiansAgency](https://github.com/VRSEN/agency-swarm-lab/tree/main/CodeGuardiansAgency) - An agency that runs on the backend using GitHub Actions and submits code reviews on pull requests, according to your SOPs. + + + + + +- **Browsing Agent for QA Testing Agency**: Learn how to use a browsing agent with GPT-4 Vision inside a QA testing agency. [Watch on YouTube](https://youtu.be/Yidy_ePo7pE?si=WMuWpb9_DVckIkP6). The notebook is available [here](https://github.com/VRSEN/agency-swarm/blob/main/notebooks/web_browser_agent.ipynb). +- **Genesis Agency**: Discover how to create agents using the Genesis Agency. [Watch on YouTube](https://youtu.be/qXxO7SvbGs8?si=uosmTSzzz6id_lLl). The notebook is available [here](https://github.com/VRSEN/agency-swarm/blob/main/notebooks/genesis_agency.ipynb). + +*More examples coming soon...* + + + + + + + +- **[API Reference](./api-reference/api-reference.md)** +- **[Advanced Topics](./advanced-topics)** + + diff --git a/docs_new/faq/faq.mdx b/docs_new/faq/faq.mdx new file mode 100644 index 00000000..8c4f9e76 --- /dev/null +++ b/docs_new/faq/faq.mdx @@ -0,0 +1,35 @@ +--- +title: "FAQ" +description: "Find answers to common questions about Agency Swarm." +icon: "question-circle" +--- + +Find answers to common questions about Agency Swarm. + + + + +**A**: Agency Swarm is an open-source framework designed to facilitate the creation and orchestration of multi-agent AI systems. + + + +**A**: Install via pip using: + + +pip install agency-swarm + + + + +**A**: Yes, you can integrate open-source models or custom language models that mimic the OpenAI Assistants API. + + + +**A**: Agents communicate using the `SendMessage` tool, with communication flows defined in the `agency_chart` parameter of the `Agency` class. + + + +**A**: Examples are available in the [agency-swarm-lab](https://github.com/VRSEN/agency-swarm-lab) repository and on the [YouTube channel](https://youtube.com/@vrsen). + + + diff --git a/docs_new/favicon.svg b/docs_new/favicon.svg new file mode 100644 index 00000000..2972b2ed --- /dev/null +++ b/docs_new/favicon.svg @@ -0,0 +1,9 @@ + + logo + + + + + + \ No newline at end of file diff --git a/docs_new/folder-structure/folder-structure.mdx b/docs_new/folder-structure/folder-structure.mdx new file mode 100644 index 00000000..494ced79 --- /dev/null +++ b/docs_new/folder-structure/folder-structure.mdx @@ -0,0 +1,38 @@ +# Folder Structure + +Organize your agency projects using the recommended folder structure for clarity and maintainability. + +## Recommended Structure + +``` +AgencyName/ +├── AgentName/ +│ ├── __init__.py +│ ├── AgentName.py +│ ├── instructions.md +│ └── tools/ +│ ├── ToolName1.py +│ ├── ToolName2.py +│ └── ... +├── AnotherAgent/ +│ ├── __init__.py +│ ├── AnotherAgent.py +│ ├── instructions.md +│ └── tools/ +│ ├── ToolName1.py +│ ├── ToolName2.py +│ └── ... +├── Agency.py +├── AgencyManifesto.md +├── requirements.txt +└── ... +``` + +## Components + +- **AgencyName**: Root directory for your agency. +- **AgentName**: Directory for each agent, containing code and instructions. +- **Tools**: Directory within each agent for tools specific to that agent. +- **Agency.py**: Main file where agents are imported and the agency is defined. +- **AgencyManifesto.md**: Shared instructions and guidelines for all agents. +- **requirements.txt**: File listing all dependencies. diff --git a/docs_new/framework-overview/communication-flows.mdx b/docs_new/framework-overview/communication-flows.mdx new file mode 100644 index 00000000..eff3e38b --- /dev/null +++ b/docs_new/framework-overview/communication-flows.mdx @@ -0,0 +1,21 @@ +# Communication Flows + +Communication flows in Agency Swarm are flexible and user-defined. Unlike other frameworks, they are **not strictly hierarchical** or **sequential**. Communication permissions are established from left to right inside the `agency_chart`. + +For example: + +```python +from agency_swarm import Agency +agency = Agency([ + ceo, # CEO is the entry point for user communication + [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 +]) +``` + +In this setup: + +- The **CEO** can initiate conversations and assign tasks to the **Developer** and **Virtual Assistant**. +- The **Developer** cannot initiate a conversation with the **CEO**, but can communicate with the **Virtual Assistant**. +- Agents added at the top level (e.g., `ceo`) can interact directly with the user. diff --git a/docs_new/framework-overview/conversation-context-management.mdx b/docs_new/framework-overview/conversation-context-management.mdx new file mode 100644 index 00000000..26b481d1 --- /dev/null +++ b/docs_new/framework-overview/conversation-context-management.mdx @@ -0,0 +1,9 @@ +# Conversation Context Management + +Agency Swarm maintains conversation context through a shared memory system. This allows agents to: + +- **Access Previous Interactions**: Agents can refer to earlier messages and decisions to maintain coherence. +- **Build Upon Information**: Agents can utilize data gathered by others, enhancing collaboration. +- **Maintain Multi-Turn Conversations**: Ensures that agents can engage in meaningful dialogues over multiple turns. + +The framework leverages dynamic context truncation strategies to manage long conversations efficiently, keeping the most relevant information accessible. \ No newline at end of file diff --git a/docs_new/framework-overview/design-and-architecture.mdx b/docs_new/framework-overview/design-and-architecture.mdx new file mode 100644 index 00000000..b625aab7 --- /dev/null +++ b/docs_new/framework-overview/design-and-architecture.mdx @@ -0,0 +1,5 @@ +# Design and Architecture + +Agency Swarm employs a modular architecture that allows for flexible configuration of AI agents. The framework connects assistants with a `SendMessage` tool, enabling them to call other agents as tools. This design facilitates a collaborative environment where agents can communicate and coordinate to solve complex tasks. + +Agents within Agency Swarm are designed to communicate and collaborate, enabling the creation of complex, multi-agent systems that can solve sophisticated problems by working together. \ No newline at end of file diff --git a/docs_new/framework-overview/output-validation-and-reliability.mdx b/docs_new/framework-overview/output-validation-and-reliability.mdx new file mode 100644 index 00000000..d9f6fd73 --- /dev/null +++ b/docs_new/framework-overview/output-validation-and-reliability.mdx @@ -0,0 +1,8 @@ +# Output Validation and Reliability + +Ensuring the reliability of agent outputs is critical, especially in production environments. Agency Swarm includes mechanisms for: + +- **Response Validation**: Agents can validate outputs against predefined rules or schemas before returning them. +- **Error Handling**: Agents are designed to self-correct based on validation errors, improving reliability. +- **Tool Input/Output Validation**: Tools validate data before and after execution to reduce runtime errors. +- **Custom Validators**: Developers can implement custom validation logic within agents and tools. \ No newline at end of file diff --git a/docs_new/framework-overview/prompt-flexibility.mdx b/docs_new/framework-overview/prompt-flexibility.mdx new file mode 100644 index 00000000..5d37ec5b --- /dev/null +++ b/docs_new/framework-overview/prompt-flexibility.mdx @@ -0,0 +1,8 @@ +# Prompt Flexibility + +The framework offers high flexibility in prompt design: + +- **Custom Instructions**: Agents can be configured with unique instructions tailored to their roles. +- **Few-Shot Learning**: Agents can be initialized with example conversations or task outputs for consistent behavior. +- **Dynamic Prompts**: Prompts can be adjusted programmatically based on context or specific needs. +- **No Hardcoded Constraints**: Developers have full control over the interaction flows and language used. \ No newline at end of file diff --git a/docs_new/framework-overview/state-management.mdx b/docs_new/framework-overview/state-management.mdx new file mode 100644 index 00000000..2b020c25 --- /dev/null +++ b/docs_new/framework-overview/state-management.mdx @@ -0,0 +1,7 @@ +# State Management + +Agency Swarm provides basic state management through its shared memory system, enabling agents and tools to share global state. This ensures consistent task execution and prevents redundant or conflicting operations. + +- **Shared State**: Agents and tools can read and write to a shared state to coordinate actions. +- **State Persistence**: States can be persisted across sessions, allowing for long-term task management. +- **Customization**: Developers can implement custom state handling for more complex applications. \ No newline at end of file diff --git a/docs_new/framework-overview/streaming-support.mdx b/docs_new/framework-overview/streaming-support.mdx new file mode 100644 index 00000000..1675a8d3 --- /dev/null +++ b/docs_new/framework-overview/streaming-support.mdx @@ -0,0 +1,7 @@ +# Streaming Support + +Agency Swarm supports streaming responses from language models, providing real-time feedback during task execution. + +- **Real-Time Interaction**: Enables agents to process and respond to inputs immediately. +- **Event Handlers**: Custom event handlers can be defined to manage and display streaming data. +- **Asynchronous Execution**: Combined with asynchronous modes, streaming enhances the efficiency of multi-agent communication. \ No newline at end of file diff --git a/docs_new/getting-started/installation.mdx b/docs_new/getting-started/installation.mdx new file mode 100644 index 00000000..573ff2d4 --- /dev/null +++ b/docs_new/getting-started/installation.mdx @@ -0,0 +1,51 @@ +--- +title: "Installation" +description: "Instructions on how to install Agency Swarm." +icon: "download" +--- + +Set up Agency Swarm in a few simple steps. + + + Make sure you have `Python >=3.10 <=3.12` installed on your system before you proceed. + + +## Step-by-Step Installation + + + + + + +pip install agency-swarm + + + + + + +python -c "import agency_swarm; print('Agency Swarm is installed successfully.')" + + + + + + +from agency_swarm import Agent, Agency + +agent = Agent(name="Assistant", role="Provide helpful responses.") + +agency = Agency(agents=[agent]) +agency.run_demo() + + + + + +## Troubleshooting + + +If you encounter issues during installation, ensure that your Python and pip versions meet the requirements. + + +If problems persist, check the [FAQ](../faq/faq.md) or [submit an issue](https://github.com/VRSEN/agency-swarm/issues). diff --git a/docs_new/getting-started/quickstart.mdx b/docs_new/getting-started/quickstart.mdx new file mode 100644 index 00000000..bfb995e1 --- /dev/null +++ b/docs_new/getting-started/quickstart.mdx @@ -0,0 +1,103 @@ +--- +title: "Quickstart" +description: "Get started quickly with Agency Swarm." +icon: "rocket" +--- + +Get up and running with Agency Swarm quickly by following these steps: + +## Import Modules and Set Up + +1. **Import the necessary modules**: + ```python + from agency_swarm import Agent, Agency ``` + +2. **Set Your OpenAI Key**: + ```python + from agency_swarm import set_openai_key + set_openai_key("YOUR_API_KEY") ``` + +## Start from Scratch + +1. **Create Tools**: Define your custom tools with [Instructor](https://github.com/jxnl/instructor). + All tools must extend the `BaseTool` class and implement the `run` method. + ```python + from agency_swarm.tools import BaseTool + from pydantic import Field + + 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. + """ + + 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. + """ + # Your custom tool logic goes here + do_something(self.example_field) + return "Result of MyCustomTool operation" + ``` + +2. **Define Agent Roles**: Create your agents with specific roles and responsibilities. + ```python + from agency_swarm import Agent + + ceo = Agent( + name="CEO", + description="Responsible for client communication, task planning, and management.", + instructions="path/to/instructions.md", # can be a string or file path + tools=[], + temperature=0.5, + max_prompt_tokens=25000, + ) + + developer = Agent( + name="Developer", + description="Responsible for executing tasks and providing feedback.", + instructions="You must execute the tasks provided by the CEO and provide feedback.", + tools=[MyCustomTool] + ) ``` + +3. **Create an Agency**: + ```python + agency = Agency([ + ceo, + [ceo, developer], + ], shared_instructions='You are a part of an AI development agency.\n\n') ``` + + !!! note "Note on Communication Flows" + Communication flows are directional, established from left to right in the agency_chart definition. The CEO can initiate a chat with the developer (dev) who can respond, but the developer cannot initiate a chat with the CEO. + +4. **Run the Agency**: + Choose your preferred interface: + + - **Web interface**: + ```python + agency.demo_gradio(height=900) ``` + + - **Terminal version**: + ```python + agency.run_demo() ``` + + - **Backend version**: + ```python + completion_output = agency.get_completion("Please create a new website for our client.", yield_messages=False) ``` + +## Use Genesis Agency + +1. **Run the `genesis` command**: + ```bash + agency-swarm genesis [--openai_key "YOUR_API_KEY"] ``` + +## Next Steps + +- Learn how to create more Tools, Agents, and Agencies +- Deploy in Production +- Check out the [Examples](examples.md) section for detailed tutorials \ No newline at end of file diff --git a/docs_new/how-to-guides/creating-agencies.mdx b/docs_new/how-to-guides/creating-agencies.mdx new file mode 100644 index 00000000..d092c101 --- /dev/null +++ b/docs_new/how-to-guides/creating-agencies.mdx @@ -0,0 +1,40 @@ +# Creating Agencies + +An agency is a collection of agents working collaboratively. Setting up an agency involves defining agents and their communication flows. + +## Steps to Create an Agency + +1. **Import Agents and Agency Class**: + ```python + from agency_swarm import Agency + from CEO import CEO + from Developer import Developer + from VirtualAssistant import VirtualAssistant ``` + +2. **Instantiate Agents**: + ```python + ceo = CEO() + dev = Developer() + va = VirtualAssistant() ``` + +3. **Define the Agency**: + ```python + agency = Agency([ + ceo, + [ceo, dev], + [ceo, va], + [dev, va] + ], + shared_instructions='agency_manifesto.md', + temperature=0.5, + max_prompt_tokens=25000) ``` + +4. **Run the Agency**: + ```python + if __name__ == "__main__": + agency.run_demo() ``` + +## Shared Instructions + +- **Agency Manifesto**: A `agency_manifesto.md` file containing shared instructions and guidelines. +- **Purpose**: Aligns all agents with common goals and operating principles. \ No newline at end of file diff --git a/docs_new/how-to-guides/creating-agents.mdx b/docs_new/how-to-guides/creating-agents.mdx new file mode 100644 index 00000000..ef856739 --- /dev/null +++ b/docs_new/how-to-guides/creating-agents.mdx @@ -0,0 +1,52 @@ +--- +title: "Creating Agents" +description: "Learn how to create custom agents for your agency." +icon: "user-plus" +--- + +Agents are central to the Agency Swarm framework. Creating custom agents allows you to define specialized roles tailored to specific tasks. + +## Steps to Create an Agent + +1. **Import the Agent Class**: + ```python + from agency_swarm import Agent ``` + +2. **Define the Agent Class**: + ```python + class CEO(Agent): + def __init__(self): + super().__init__( + name="CEO", + description="Responsible for client communication, task planning, and management.", + instructions="./instructions.md", + tools=[MyCustomTool], + temperature=0.5, + max_prompt_tokens=25000, + ) ``` + +3. **Provide Instructions**: + + Create an `instructions.md` file with detailed instructions for the agent. + ```markdown + # Agent Role + + As the CEO, you are responsible for overseeing all operations. + + # Goals + + - Communicate with clients. + - Delegate tasks to other agents. + - Ensure project deadlines are met. + + # Process Workflow + + 1. Receive client requests. + 2. Assign tasks to appropriate agents. + 3. Monitor progress and report back. ``` + +4. **Initialize the Agent**: + ```python + ceo = CEO() ``` + +For more details on defining agent instructions and configurations, refer to the [Defining Agent Instructions](how-to-guides/defining-agent-instructions.md) guide. \ No newline at end of file diff --git a/docs_new/how-to-guides/creating-tools.mdx b/docs_new/how-to-guides/creating-tools.mdx new file mode 100644 index 00000000..e05e2130 --- /dev/null +++ b/docs_new/how-to-guides/creating-tools.mdx @@ -0,0 +1,48 @@ +--- +title: "Creating Tools" +description: "Learn how to create custom tools for your agents." +icon: "wrench" +--- + +Tools are crucial for extending the functionality of agents. They allow agents to perform actions ranging from simple computations to complex API interactions. + +## Steps to Create a Tool + +1. **Import Necessary Modules**: + ```python + from agency_swarm.tools import BaseTool + from pydantic import Field + ``` + +2. **Define the Tool Class**: + ```python + class MyCustomTool(BaseTool): + """ + Description of what the tool does. + """ + input_field: str = Field(..., description="Description of the input field.") + + def run(self): + # Implement the tool's functionality here + return "Result of the tool operation" + ``` + +3. **Add Validators (Optional)**: + + Use Pydantic validators for input validation. + + ```python + @validator('input_field') + def check_input(cls, v): + if not v: + raise ValueError('Input cannot be empty') + return v + ``` + +4. **Test the Tool**: + + ```python + if __name__ == "__main__": + tool = MyCustomTool(input_field="test input") + print(tool.run()) + ``` diff --git a/docs_new/how-to-guides/defining-agent-instructions.mdx b/docs_new/how-to-guides/defining-agent-instructions.mdx new file mode 100644 index 00000000..2dff9ae9 --- /dev/null +++ b/docs_new/how-to-guides/defining-agent-instructions.mdx @@ -0,0 +1,29 @@ +# Defining Agent Instructions + +Agent instructions guide the behavior of agents, shaping how they interact with users and other agents. Clear instructions are vital for consistent and expected outcomes. + +## Creating Instructions + +- **File Format**: Instructions are typically provided in a markdown (`.md`) file. +- **Structure**: + ```markdown + # Agent Role + + Describe the role and responsibilities. + + # Goals + + - List primary objectives. + - Align goals with the agency's mission. + + # Process Workflow + + 1. Step-by-step process outlining agent actions. + 2. Include decision-making criteria. + ``` + +## Best Practices + +- **Clarity**: Be explicit about expectations and responsibilities. +- **Alignment**: Ensure instructions align with the overall agency objectives. +- **Collaboration**: Define how the agent should interact with others. \ No newline at end of file diff --git a/docs_new/how-to-guides/deployment.mdx b/docs_new/how-to-guides/deployment.mdx new file mode 100644 index 00000000..7f000fb0 --- /dev/null +++ b/docs_new/how-to-guides/deployment.mdx @@ -0,0 +1,31 @@ +# Deployment + +Deploying your agency to a production environment involves several considerations to ensure scalability and reliability. + +## Deployment Steps + +1. **Dynamic Loading**: Load agents and threads dynamically based on user sessions or specific conditions. +2. **Microservices Architecture (Optional)**: Deploy each agent as a separate microservice to scale independently. +3. **Persistence**: Implement `threads_callbacks` and `settings_callbacks` to load and save agent states and conversations. + ```python + agency = Agency( + agents=[ceo], + threads_callbacks={ + 'load': lambda: load_threads(chat_id), + 'save': lambda new_threads: save_threads(new_threads) + }, + settings_callbacks={ + 'load': lambda: load_settings(user_id), + 'save': lambda new_settings: save_settings(new_settings) + } + ) ``` + +4. **Asynchronous Execution**: Utilize asynchronous modes to enhance performance. + ```python + agency = Agency(agents=[ceo], async_mode='threading') ``` + +## Considerations + +- **Security**: Ensure that agents do not have unintended access to sensitive data. +- **Scaling**: Plan for horizontal scaling if expecting high load. +- **Monitoring**: Implement logging and monitoring to track performance and issues. \ No newline at end of file diff --git a/docs_new/how-to-guides/managing-communication-flows.mdx b/docs_new/how-to-guides/managing-communication-flows.mdx new file mode 100644 index 00000000..c0518728 --- /dev/null +++ b/docs_new/how-to-guides/managing-communication-flows.mdx @@ -0,0 +1,20 @@ +# Managing Communication Flows + +Effective communication between agents is essential for collaboration. Agency Swarm allows you to define custom communication flows. + +## Defining Communication Flows + +- **Agency Chart**: Communication permissions are set using the `agency_chart` parameter in the `Agency` class. + ```python + agency = Agency([ + ceo, # Entry point for user communication + [ceo, dev], # CEO can communicate with Developer + [dev, va], # Developer can communicate with Virtual Assistant + ]) ``` + +- **Directionality**: Communication is directional, established from left to right. + +## Best Practices + +- **Intentional Design**: Define communication flows that reflect organizational hierarchies or workflows. +- **Limit Unnecessary Access**: Restrict communication paths to prevent information overload or confusion. \ No newline at end of file diff --git a/docs_new/how-to-guides/using-code-interpreter-and-filesearch.mdx b/docs_new/how-to-guides/using-code-interpreter-and-filesearch.mdx new file mode 100644 index 00000000..cf8e36d5 --- /dev/null +++ b/docs_new/how-to-guides/using-code-interpreter-and-filesearch.mdx @@ -0,0 +1,34 @@ +# Using Code Interpreter and FileSearch + +Enhance agent capabilities by integrating the Code Interpreter and FileSearch tools. + +## Code Interpreter + +- **Purpose**: Allows agents to execute code within a Jupyter Notebook environment (without internet access). +- **Integration**: + ```python + from agency_swarm.tools import CodeInterpreter + + agent = Agent( + name="DataAnalyst", + tools=[CodeInterpreter], + # Other agent parameters + ) ``` + +## FileSearch + +- **Purpose**: Enables Retrieval-Augmented Generation (RAG) by allowing agents to search files. +- **Integration**: + ```python + from agency_swarm.tools import FileSearch + + agent = Agent( + name="Researcher", + tools=[FileSearch], + # Other agent parameters + ) ``` + +## Usage Considerations + +- **Permissions**: Ensure agents have access to necessary files and resources. +- **Security**: Be cautious of code execution to prevent unintended actions. \ No newline at end of file diff --git a/docs_new/introduction/design-principles.mdx b/docs_new/introduction/design-principles.mdx new file mode 100644 index 00000000..cbb68fd0 --- /dev/null +++ b/docs_new/introduction/design-principles.mdx @@ -0,0 +1,16 @@ +# Design Principles + +## Full Customization and Modularity + +- **No Hardcoded Prompts**: Ensures flexibility and adaptability for various use cases by providing users with complete control over prompts. +- **Dynamic Agent Setup**: Agents are not predefined; users can create, configure, and link agents based on specific roles and tasks. + +## Production-Readiness + +- **Robust Error Handling**: Designed for real-world applications with robust error handling, asynchronous execution, and advanced monitoring. +- **Seamless Integration**: Streamlined setup processes allow seamless integration with various AI models, from proprietary to open-source. + +## Collaborative Multi-Agent Systems + +- **Hierarchical Structures**: Supervisor agents can delegate tasks to subordinate agents, enabling complex task orchestration. +- **Dynamic Allocation**: Agents can decide which other agent is best suited for a particular subtask, facilitating flexible collaboration. \ No newline at end of file diff --git a/docs_new/introduction/key-features.mdx b/docs_new/introduction/key-features.mdx new file mode 100644 index 00000000..ecb3cc41 --- /dev/null +++ b/docs_new/introduction/key-features.mdx @@ -0,0 +1,11 @@ +# Key Features + +- **Customizable Agent Roles**: Define roles like CEO, virtual assistant, developer, etc., and customize their functionalities with OpenAI's Assistants API. +- **Full Control Over Prompts**: Avoid conflicts and restrictions of pre-defined prompts, allowing full customization of agent behavior. +- **Tool Creation**: Tools within Agency Swarm are created using Pydantic, providing 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**: Efficiently manages the state of your assistants, maintaining it in a special `settings.json` file. +- **Production-Ready**: Designed to be reliable and easily deployable in production environments. +- **Streaming Support**: Supports streaming responses from language models, allowing for real-time interaction and output generation. +- **Prompt Flexibility**: Offers high flexibility in prompt design, allowing developers to fully customize agent behaviors and interactions. +- **Evaluation and Monitoring**: Provides basic logging and debugging features, with the ability to implement custom solutions for performance tracking and system analysis. \ No newline at end of file diff --git a/docs_new/introduction/overview.mdx b/docs_new/introduction/overview.mdx new file mode 100644 index 00000000..e21d17db --- /dev/null +++ b/docs_new/introduction/overview.mdx @@ -0,0 +1,35 @@ +--- +title: "Overview" +description: "An introduction to Agency Swarm and its capabilities." +icon: "info-circle" +--- + +Welcome to **Agency Swarm**, an open-source framework for creating and orchestrating multi-agent AI systems. + + +Agency Swarm makes it easy to build collaborative AI systems by providing tools for agent coordination, task management, and communication. + + +## Key Features + + + + Flexible configuration of AI agents built on OpenAI's Assistants API + + + Create swarms of specialized agents that work together to accomplish complex tasks + + + Simple tools and APIs for coordinating multiple AI agents + + + Customize agent roles, capabilities and interactions to fit your needs + + + + + + - **[Installation Guide](../getting-started/installation.md)**: Detailed setup instructions + - **[Examples](../examples.md)**: Explore sample use cases + - **[API Reference](../api-reference/api-reference.md)**: Full API documentation + diff --git a/docs_new/key-entities/agents.mdx b/docs_new/key-entities/agents.mdx new file mode 100644 index 00000000..44d062e7 --- /dev/null +++ b/docs_new/key-entities/agents.mdx @@ -0,0 +1,20 @@ +# Agents + +Agents are the core building blocks of the Agency Swarm framework. Each agent is a specialized entity designed to perform specific tasks or handle particular aspects of a problem. + +## Characteristics of Agents + +- **Role-Based**: Agents operate based on predefined roles that guide their interactions and decision-making processes. +- **Custom Instructions**: Each agent can be configured with unique instructions, enabling specialized behavior. +- **Tools and Functions**: Agents can be equipped with various tools to enhance their capabilities. +- **Communication**: Agents communicate with each other and can delegate tasks, forming complex collaboration networks. + +## Creating Agents + +Agents can be created by: + +- **Defining Agent Classes**: Extend the base `Agent` class and customize parameters. +- **Setting Instructions**: Provide detailed instructions to guide agent behavior. +- **Assigning Tools**: Equip agents with tools relevant to their roles. + +For detailed instructions on creating agents, refer to the [Creating Agents](../how-to-guides/creating-agents.md) guide. \ No newline at end of file diff --git a/docs_new/key-entities/tasks-and-functions.mdx b/docs_new/key-entities/tasks-and-functions.mdx new file mode 100644 index 00000000..cb7c73c5 --- /dev/null +++ b/docs_new/key-entities/tasks-and-functions.mdx @@ -0,0 +1,15 @@ +# Tasks and Functions + +Tasks represent units of work that agents need to complete. Functions allow agents to break down complex tasks into manageable actions. + +## Tasks + +- **Definition**: High-level objectives that can be broken down into subtasks. +- **Delegation**: Agents can delegate tasks to other agents better suited for specific subtasks. +- **Management**: Tasks can be tracked and managed across agents within an agency. + +## Functions + +- **Purpose**: Enable agents to perform specific actions or computations. +- **Implementation**: Defined as methods within agents or as standalone tools. +- **Asynchronous Execution**: Functions can be executed asynchronously to improve efficiency. \ No newline at end of file diff --git a/docs_new/key-entities/tools.mdx b/docs_new/key-entities/tools.mdx new file mode 100644 index 00000000..173419eb --- /dev/null +++ b/docs_new/key-entities/tools.mdx @@ -0,0 +1,20 @@ +# Tools + +Tools are modular functions that agents can call to perform specific tasks. They extend the capabilities of agents, allowing them to interact with the environment or perform computations. + +## Characteristics of Tools + +- **Modular**: Tools are independent functions that can be reused across agents. +- **Typed Parameters**: Use Pydantic for clear parameter definitions and validation. +- **Response Handling**: Tools can process inputs and produce outputs that agents use in decision-making. +- **Error Handling**: Built-in mechanisms to handle exceptions and validate outputs. + +## Creating Tools + +Tools are created by: + +- **Extending the `BaseTool` Class**: Implement the `run` method with custom logic. +- **Defining Parameters**: Specify input fields using Pydantic's `Field`. +- **Implementing Validation**: Use Pydantic validators for input/output validation. + +For detailed instructions on creating tools, refer to the [Creating Tools](../how-to-guides/creating-tools.md) guide. \ No newline at end of file diff --git a/docs_new/mint.json b/docs_new/mint.json new file mode 100644 index 00000000..62bed7f7 --- /dev/null +++ b/docs_new/mint.json @@ -0,0 +1,147 @@ +{ + "name": "Agency Swarm", + "theme": "venus", + "logo": { + "dark": "agency_swarm_logo.png", + "light": "agency_swarm_logo.png", + "href": "https://github.com/VRSEN/agency-swarm" + }, + "favicon": "favicon.svg", + "colors": { + "primary": "#EB6658", + "light": "#F3A78B", + "dark": "#C94C3C", + "anchors": { + "from": "#737373", + "to": "#EB6658" + } + }, + "seo": { + "indexHiddenPages": false + }, + "modeToggle": { + "default": "dark", + "isHidden": false + }, + "feedback": { + "suggestEdit": true, + "raiseIssue": true, + "thumbsRating": true + }, + "topbarCtaButton": { + "type": "github", + "url": "https://github.com/VRSEN/agency-swarm" + }, + "primaryTab": { + "name": "Get Started" + }, + "tabs": [ + { + "name": "Examples", + "url": "examples" + } + ], + "anchors": [ + { + "name": "Discord Community", + "icon": "discourse", + "url": "https://discord.gg/cw2xBaWfFM" + }, + { + "name": "Changelog", + "icon": "timeline", + "url": "https://github.com/VRSEN/agency-swarm/releases" + } + ], + "navigation": [ + { + "group": "Introduction", + "pages": [ + "introduction/overview", + "introduction/key-features", + "introduction/design-principles" + ] + }, + { + "group": "Getting Started", + "pages": [ + "getting-started/installation", + "getting-started/quickstart" + ] + }, + { + "group": "Framework Overview", + "pages": [ + "framework-overview/design-and-architecture", + "framework-overview/communication-flows", + "framework-overview/conversation-context-management", + "framework-overview/state-management", + "framework-overview/output-validation-and-reliability", + "framework-overview/streaming-support", + "framework-overview/prompt-flexibility" + ] + }, + { + "group": "Key Entities", + "pages": [ + "key-entities/agents", + "key-entities/tools", + "key-entities/tasks-and-functions" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "how-to-guides/creating-tools", + "how-to-guides/creating-agents", + "how-to-guides/defining-agent-instructions", + "how-to-guides/managing-communication-flows", + "how-to-guides/using-code-interpreter-and-filesearch", + "how-to-guides/creating-agencies", + "how-to-guides/deployment" + ] + }, + { + "group": "API Reference", + "pages": [ + "api-reference/api-reference" + ] + }, + { + "group": "Folder Structure", + "pages": [ + "folder-structure/folder-structure" + ] + }, + { + "group": "Contributing", + "pages": [ + "contributing/contributing" + ] + }, + { + "group": "FAQ", + "pages": [ + "faq/faq" + ] + }, + { + "group": "Advanced Topics", + "pages": [ + "advanced-topics/asynchronous-execution", + "advanced-topics/customizing-prompts-and-few-shot-learning", + "advanced-topics/open-source-models-support", + "advanced-topics/production-readiness" + ] + } + ], + "search": { + "prompt": "Search Agency Swarm docs" + }, + "footerSocials": { + "website": "https://vrsen.ai", + "x": "https://x.com/__vrsen__", + "github": "https://github.com/VRSEN/agency-swarm", + "youtube": "https://youtube.com/@vrsen" + } +} \ No newline at end of file diff --git a/docs_new/mintlify.cursorrules b/docs_new/mintlify.cursorrules new file mode 100644 index 00000000..fcf133ac --- /dev/null +++ b/docs_new/mintlify.cursorrules @@ -0,0 +1,424 @@ +Mintlify Docs Cheatsheet + +# General + +Start each page with a metadata block: + +```mdx +--- +title: "Page Title" +description: "Brief description of the page" +icon: "icon-name" +--- +``` + +# Getting Started + +## Global Settings (`mint.json`) + +Your Mintlify site requires a `mint.json` file containing core configurations. + +### Key Properties + +#### Styling + +- **name** (`string`, required): Your company or project name. +- **logo** (`string` or `Logo`, optional): Path to logo image(s). + - For example: + ```json + "logo": "/path/to/logo.svg" + ``` + - For light/dark modes: + ```json + "logo": { + "light": "/path/to/light-logo.svg", + "dark": "/path/to/dark-logo.svg", + "url": "/" + } + ``` +- **favicon** (`string`, optional): Path to your favicon image. +- **colors** (`Colors`, optional): Hex color codes for your theme. +- **theme** (`"venus"` | `"quill"` | `"prism"`, optional): Preset theme configurations. +- **layout** (`"topnav"` | `"sidenav"` | `"solidSidenav"`, optional): Global layout style. +- **background** (`Background`, optional): Decorative background settings. +- **font** (`FontDetailsType` or `{ headings?: FontDetailsType, body?: FontDetailsType }`, optional): Custom fonts. +- **modeToggle** (`ModeToggle`, optional): Customize the dark mode toggle. +- **sidebar** (`Sidebar`, optional): Customize sidebar components. +- **topbar** (`Topbar`, optional): Styling for the topbar. +- **search** (`Search`, optional): Configure the search bar location. +- **rounded** (`"default"` | `"sharp"`, optional): Style of rounded edges in the UI. +- **codeBlock** (`CodeBlock`, optional): Style code blocks in the documentation. + +#### Structure + +- **navigation** (`Navigation[]`, required): Define your site's navigation structure. + ```json + "navigation": [ + { + "group": "Getting Started", + "pages": ["quickstart"] + } + ] + ``` +- **topbarLinks** (`TopbarLink[]`, optional): Links to include in the topbar. + ```json + "topbarLinks": [ + { + "name": "Community", + "url": "https://mintlify.com/community" + } + ] + ``` +- **topbarCtaButton** (`Call to Action`, optional): Configuration for the topbar CTA button. + ```json + "topbarCTA": { + "name": "Get Started", + "url": "https://mintlify.com/get-started" + } + ``` +- **versions** (`string[]`, optional): Doc versions for localization or versioning. +- **anchors** (`Anchor[]`, optional): Anchors for quick links to sections or external URLs. +- **topAnchor** (`Anchor`, optional): Override the default top anchor. +- **tabs** (`Tabs[]`, optional): Navigational tabs. + ```json + "tabs": [ + { + "name": "API References", + "url": "api-references" + }, + { + "name": "Content", + "url": "content" + } + ], + "primaryTab": { + "name": "Home" + } + ``` +- **footer** (`FooterSocials`, `FooterLinksColumn[]`, optional): Configure footer socials and links. +- **feedback** (`Feedback`, optional): Enable feedback buttons. + +#### API Configurations + +- **api** (`API`, optional): API settings configuration. +- **openapi** (`string` | `string[]`, optional): Paths or URLs to your OpenAPI files. + ```json + "openapi": "https://example.com/openapi.json" + ``` + Or multiple OpenAPI files: + ```json + "openapi": [ + "https://example.com/openapi1.json", + "./path/to/openapi2.json" + ] + ``` +- **integrations** (`Integrations`, optional): Third-party integrations (excluding analytics). +- **analytics** (`Analytics`, optional): Third-party analytics integrations. + +#### Redirects + +- **redirects** (`Redirect[]`, optional): Configure URL redirects. + ```json + "redirects": [ + { + "source": "/old-path", + "destination": "/new-path" + } + ] + ``` + +#### SEO + +- **seo** (`SEO`, optional): Search Engine Optimization settings. + - **indexHiddenPages** (`boolean`, default `false`): Index pages not included in navigation. + ```json + "seo": { + "indexHiddenPages": true + } + ``` + +--- + +# Writing Content + +## Page Titles and Metadata + +Begin each MDX page with metadata: + +```mdx +--- +title: "Page Title" +description: "Brief description of the page" +icon: "icon-name" +--- +``` + +### Additional Metadata Options + +- **sidebarTitle**: Display a different title in the sidebar. + ```mdx + --- + title: "Long Page Title" + sidebarTitle: "Short Title" + --- + ``` +- **icon** and **iconType**: Include icons for sidebar items. + ```mdx + --- + title: "Code Block" + icon: "rectangle-code" + iconType: "solid" + --- + ``` +- **mode**: Customize page layout. + - `"default"`: Standard layout with table of contents. + - `"wide"`: Hide the table of contents. + - `"custom"`: Minimalist layout with only the top bar. + ```mdx + --- + mode: "wide" + --- + ``` +- **url**: Create external links in the sidebar. + ```mdx + --- + title: "External Resource" + url: "https://www.example.com" + --- + ``` + +## Content Formatting + +### Headers + +Structure your content with headers: + +```markdown +## Title (H2) +### Subtitle (H3) +``` + +### Text Formatting + +- **Bold**: `**text**` → **text** +- *Italic*: `_text_` → _text_ +- ~~Strikethrough~~: `~text~` → ~~text~~ + +### Links + +- **External**: `[Link Text](https://example.com)` +- **Internal**: `[Link Text](/path/to/page)` + +### Images + +- **Markdown Syntax**: + ```markdown + ![Alt Text](/path/image.jpg) + ``` +- **Disable Zoom**: + ```html + + ``` +- **Linking Images**: + ```html + + + + ``` + +### Code Blocks + +- **Inline Code**: `` `code` `` +- **Fenced Code Blocks**: + ```language + // Code here + ``` +- **Named Code Blocks**: + ```javascript Example.js + // JavaScript code + ``` +- **Line Highlighting**: + ```javascript {1,3-5} + // Code with specific lines highlighted + ``` +- **Code Groups**: + ```mdx + + ```python example.py + # Python code + ``` + ```javascript example.js + // JavaScript code + ``` + + ``` + +--- + +# Components + +## Accordion + +Create collapsible sections: + +```mdx + + Content inside the accordion. + +``` + +- **Props**: + - `title` (string): Title displayed on the accordion. + - `defaultOpen` (boolean): If `true`, accordion is open by default. + +## Tabs + +Switch between different content sections: + +```mdx + + + Content for the first tab. + + + Content for the second tab. + + +``` + +## Cards + +Highlight key points or links: + +```mdx + + Card content goes here. + +``` + +- **Props**: + - `title` (string): Title of the card. + - `icon` (string): Font Awesome icon name (examples: address-book, at, clipboard-user, code, database, eye, file-code, file-csv, file-lines, file-pdf, file-word, file-xml, fire-flame, folder-tree, folders, gear-code, github, globe-pointer, globe-stand, google, image, magnifying-glass-location, markdown, people-group, rocket-launch, screen-users, screwdriver-wrench, signal-stream, spider-web, terminal, toolbox, wrench, youtube). + - `href` (string): URL to navigate when card is clicked. + - `horizontal` (boolean): Display card in horizontal layout. + - `img` (string): Path to an image displayed on the card. + +## Steps + +Display step-by-step instructions: + +```mdx + + + Instructions for step one. + + + Instructions for step two. + + +``` + +## Tooltips + +Show additional information on hover: + +```mdx +Hover over this text +``` + +--- + +# API Components + +## ParamField + +Define API parameters: + +```mdx + + The unique identifier of the user. + +``` + +- **Props**: + - `param` (string): Parameter name. + - `type` (string): Data type. + - `required` (boolean): Indicates if parameter is required. + - `default` (string): Default value. + - `placeholder` (string): Placeholder text. + - `deprecated` (boolean): Indicates if parameter is deprecated. + +## ResponseField + +Define API response fields: + +```mdx + + Status of the response. + +``` + +- **Props**: + - `name` (string): Field name. + - `type` (string): Data type. + - `required` (boolean): Indicates if field is required. + - `default` (string): Default value. + +## Expandable + +Toggle the display of nested fields: + +```mdx + + User ID + User Email + +``` + +--- + +# Sidebar Code Examples + +Use `` and `` to display code in the sidebar. + +```mdx + + ```javascript Example Request + fetch('https://api.example.com/users') + .then(response => response.json()) + .then(data => console.log(data)); + ``` + + + + ```json + { + "users": [ + { "id": "1", "name": "Alice" }, + { "id": "2", "name": "Bob" } + ] + } + ``` + +``` + +--- + +# Diagrams + +## Mermaid Diagrams + +Create diagrams using Mermaid syntax: + +```markdown +```mermaid +graph TD + A[Start] --> B[Process] + B --> C[End] +``` +``` + +--- + +This cheatsheet provides practical guidance for using Mintlify to create documentation sites with various components and configurations. +