diff --git a/docs_new/advanced-features/custom-communication-flows/common-use-cases.mdx b/docs_new/advanced-features/custom-communication-flows/common-use-cases.mdx new file mode 100644 index 00000000..90e9ec13 --- /dev/null +++ b/docs_new/advanced-features/custom-communication-flows/common-use-cases.mdx @@ -0,0 +1,135 @@ +--- +title: "Common Use Cases" +description: "Explore common use cases for custom communication flows in Agency Swarm." +icon: "code" +--- + +In the following sections, we'll look at some common use cases for extending the `SendMessageBase` tool and how to implement them, so you can learn how to create your own SendMessage tools and use them in your own applications. + +#### 1. Adjusting parameters and descriptions + +The most basic use case is if you want to use your own parameter descriptions, such as if you want to change the docstring or the description of the `message` parameter. This can help you better customize how the agents communicate with each other and what information they relay. + +Let's say that instead of sending messages, I want my agents to send tasks to each other. In this case, I can change the docstring and the `message` parameter to a `task` parameter to better fit the nature of my application. + +```python +from pydantic import Field +from agency_swarm.tools.send_message import SendMessageBase + +class SendMessageTask(SendMessageBase): + """Use this tool to send tasks to other agents within your agency.""" + chain_of_thought: str = Field( + ..., + description="Please think step-by-step about how to solve your current task, provided by the user. Then, break down this task into smaller steps and issue each step individually to the recipient agent via the task parameter." + ) + task: str = Field( + ..., + description="Specify the task required for the recipient agent to complete. Focus on clarifying what the task entails, rather than providing exact instructions. Make sure to include all the relevant information needed to complete the task." + ) + + def run(self): + return self._get_completion(message=self.task) +``` + +To remove the chain of thought, you can simply remove the `chain_of_thought` parameter. + +#### 2. Adding custom validation logic + +Now, let's say that I need to ensure that my message is sent to the correct recipient agent. (This is a very common hallucination in production.) In this case, I can add a custom validator to the `recipient` parameter, which is defined in the `SendMessageBase` class. Since I don't want to change any other parameters or descriptions, I can inherit the default `SendMessage` class and only add this new validation logic. + +```python +from agency_swarm.tools.send_message import SendMessage +from pydantic import model_validator + +class SendMessageValidation(SendMessage): + @model_validator(mode='after') + def validate_recipient(self): + if "customer support" not in self.message.lower() and self.recipient == "CustomerSupportAgent": + raise ValueError("Messages not related to customer support cannot be sent to the customer support agent.") + return self +``` + +You can, of course, also use GPT for this: + +```python +from agency_swarm.tools.send_message import SendMessage +from agency_swarm.util.validators import llm_validator +from pydantic import model_validator + +class SendMessageLLMValidation(SendMessage): + @model_validator(mode='after') + def validate_recipient(self): + if self.recipient == "CustomerSupportAgent": + llm_validator( + statement="The message is related to customer support." + )(self.message) + return self +``` + +In this example, the `llm_validator` will throw an error if the message is not related to customer support. The caller agent will then have to fix the recipient or the message and send it again! This is extremely useful when you have a lot of agents. + +#### 3. Summarizing previous conversations with other agents and adding to context + +Sometimes, when using default `SendMessage`, the agents might not relay all the necessary details to the recipient agent, especially when the previous conversation is too long. In this case, you can summarize the previous conversation with GPT and add it to the context, instead of the additional instructions. I will extend the `SendMessageQuick` class, which already contains the `message` parameter, as I don't need chain of thought or files in this case. + +```python +from agency_swarm.tools.send_message import SendMessageQuick +from agency_swarm.util.oai import get_openai_client + +class SendMessageSummary(SendMessageQuick): + def run(self): + client = get_openai_client() + thread = self._get_main_thread() # get the main thread (conversation with the user) + + # get the previous messages + previous_messages = thread.get_messages() + previous_messages_str = "\n".join([f"{m.role}: {m.content[0].text.value}" for m in previous_messages]) + + # summarize the previous conversation + summary = client.chat.completions.create( + model="gpt-4o-mini", + messages=[ + {"role": "system", "content": "You are a world-class summarizer. Please summarize the following conversation in a few sentences:"}, + {"role": "user", "content": previous_messages_str} + ] + ) + + # send the message with the summary + return self._get_completion(message=self.message, additional_instructions=f"\n\nPrevious conversation summary: '{summary.choices[0].message.content}'") +``` + +With this example, you can add your own custom logic to the `run` method. It does not have to be a summary; you can also use it to add any other information to the context. For example, you can even query a vector database or use an external API. + +#### 4. Running each agent in a separate API call + +If you are a PRO, and you have managed to deploy each agent in a separate API endpoint, instead of using `_get_completion()`, you can call your own API and let the agents communicate with each other over the internet. + +```python +import requests +from agency_swarm.tools.send_message import SendMessage + +class SendMessageAPI(SendMessage): + def run(self): + response = requests.post( + "https://your-api-endpoint.com/send-message", + json={"message": self.message, "recipient": self.recipient} + ) + return response.json()["message"] +``` + +This is very powerful, as you can even allow your agents to collaborate with agents outside your system. More on this is coming soon! + + +If you have any ideas for new communication flows, please either adjust this page in docs, or add your new send message tool in the `agency_swarm/tools/send_message` folder and open a PR! + + +**After implementing your own `SendMessage` tool**, simply pass it into the `send_message_tool_class` parameter when initializing the `Agency` class: + +```python +agency = Agency( + ... + send_message_tool_class=SendMessageAPI +) +``` + +That's it! Now, your agents will use your own custom `SendMessageAPI` class for communication! diff --git a/docs_new/advanced-topics/advanced-communication-flows.mdx b/docs_new/advanced-features/custom-communication-flows/overview.mdx similarity index 51% rename from docs_new/advanced-topics/advanced-communication-flows.mdx rename to docs_new/advanced-features/custom-communication-flows/overview.mdx index 97a6a611..a4ff4bec 100644 --- a/docs_new/advanced-topics/advanced-communication-flows.mdx +++ b/docs_new/advanced-features/custom-communication-flows/overview.mdx @@ -1,10 +1,10 @@ --- -title: "Advanced Communication Flows" +title: "Overview" description: "Learn how to customize communication flows for your agency." icon: "comments" --- -Multi-agent communication is the core functionality of any Multi-Agent System. Unlike in all other frameworks, Agency Swarm not only allows you to define communication flows in any way you want (uniform communication flows), but to also configure the underlying logic for this feature. This means that you can create entirely new types of communication, or adjust it to your own needs. Below you will find a guide on how to do all this, along with some common examples. +Multi-agent communication is the core functionality of any Multi-Agent System. Unlike in all other frameworks, Agency Swarm not only allows you to define communication flows in any way you want (uniform communication flows), but also to configure the underlying logic for this feature. This means that you can create entirely new types of communication or adjust it to your own needs. Below you will find a guide on how to do all this, along with some common examples. ## Pre-Made SendMessage Classes @@ -14,7 +14,7 @@ Agency Swarm contains multiple commonly requested classes for communication flow | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `SendMessage` (default) | This is the default class for sending messages to other agents. It uses synchronous communication with basic COT (Chain of Thought) prompting and allows agents to relay files and modify system instructions for each other. | Suitable for most use cases. Balances speed and functionality. | [link](https://github.com/VRSEN/agency-swarm/blob/main/agency_swarm/tools/send_message/SendMessage.py) | | `SendMessageQuick` | A variant of the SendMessage class without Chain of Thought prompting, files, and additional instructions. It allows for faster communication without the overhead of COT. | Use for simpler use cases or when you want to save tokens and increase speed. | [link](https://github.com/VRSEN/agency-swarm/blob/main/agency_swarm/tools/send_message/SendMessageQuick.py) | -| `SendMessageAsyncThreading` | Similar to `SendMessage` but with `async_mode='threading'`. Each agent will execute asynchronously in a separate thread. In the meantime, the caller agent can continue the conversation with the user and check the results later. | Use for asynchronous applications or when sub-agents take singificant amounts of time to complete their tasks. | [link](https://github.com/VRSEN/agency-swarm/blob/main/agency_swarm/tools/send_message/SendMessageAsyncThreading.py) | +| `SendMessageAsyncThreading` | Similar to `SendMessage` but with `async_mode='threading'`. Each agent will execute asynchronously in a separate thread. In the meantime, the caller agent can continue the conversation with the user and check the results later. | Use for asynchronous applications or when sub-agents take significant amounts of time to complete their tasks. | [link](https://github.com/VRSEN/agency-swarm/blob/main/agency_swarm/tools/send_message/SendMessageAsyncThreading.py) | | `SendMessageSwarm` | Instead of sending a message to another agent, it replaces the caller agent with the recipient agent, similar to [OpenAI's Swarm](https://github.com/openai/swarm). The recipient agent will then have access to the entire conversation. | When you need more granular control. It is not able to handle complex multi-step, multi-agent tasks. | [link](https://github.com/VRSEN/agency-swarm/blob/main/agency_swarm/tools/send_message/SendMessageSwarm.py) | **To use any of the pre-made `SendMessage` classes**, simply put it in the `send_message_tool_class` parameter when initializing the `Agency` class: @@ -32,11 +32,11 @@ That's it! Now, your agents will use your own custom `SendMessageQuick` class fo ## Creating Your Own Unique Communication Flows -To create you own communication flow, you will first need to extend the `SendMessageBase` class. This class extends the `BaseTool` class, like any other tools in Agency Swarm, and contains the most basic parameters required for communication, such as the `recipient_agent`. +To create your own communication flow, you will first need to extend the `SendMessageBase` class. This class extends the `BaseTool` class, like any other tools in Agency Swarm, and contains the most basic parameters required for communication, such as the `recipient_agent`. ### Default `SendMessage` Class -By defualt, Agency Swarm uses the following tool for communication: +By default, Agency Swarm uses the following tool for communication: ```python from pydantic import Field, field_validator, model_validator @@ -58,7 +58,7 @@ class SendMessage(SendMessageBase): ) message: str = Field( ..., - description="Specify the task required for the recipient agent to complete. Focus on clarifying what the task entails, rather than providing exact instructions. Make sure to inlcude all the relevant information needed to complete the task." + description="Specify the task required for the recipient agent to complete. Focus on clarifying what the task entails, rather than providing exact instructions. Make sure to include all the relevant information needed to complete the task." ) message_files: list[str] | None = Field( default=None, @@ -97,138 +97,10 @@ When creating your own `SendMessage` tools, you can use the above components as ### Common Use Cases -In the following sections, we'll look at some common use cases for extending the `SendMessageBase` tool and how to implement them, so you can learn how to create your own SendMessage tools and use them in your own applications. - -#### 1. Adjusting parameters and descriptions - -The most basic use case is if you want to use your own parameter descriptions, such as if you want to change the docstring or the description of the `message` parameter. This can help you better customize how the agents communicate with each other and what information they relay. - -Let's say that instead of sending messages, I want my agents to send tasks to each other. In this case, I can change the docstring and the `message` parameter to a `task` parameter to better fit the nature of my application. - -```python -from pydantic import Field -from agency_swarm.tools.send_message import SendMessageBase - -class SendMessageTask(SendMessageBase): - """Use this tool to send tasks to other agents within your agency.""" - chain_of_thought: str = Field( - ..., - description="Please think step-by-step about how to solve your current task, provided by the user. Then, break down this task into smaller steps and issue each step individually to the recipient agent via the task parameter." - ) - task: str = Field( - ..., - description="Specify the task required for the recipient agent to complete. Focus on clarifying what the task entails, rather than providing exact instructions. Make sure to inlcude all the relevant information needed to complete the task." - ) - - def run(self): - return self._get_completion(message=self.task) -``` - -To remove the chain of thought, you can simply remove the `chain_of_thought` parameter. - -#### 2. Adding custom validation logic - -Now, let's say that I need to ensure that my message is sent to the correct recepient agent. (This is a very common hallucination in production.) In this case, I can add custom validator to the `recipient` parameter, which is defined in the `SendMessageBase` class. Since I don't want to change any other parameters or descriptions, I can inherit the default `SendMessage` class and only add this new validation logic. - -```python -from agency_swarm.tools.send_message import SendMessage -from pydantic import model_validator - -class SendMessageValidation(SendMessage): - @model_validator(mode='after') - def validate_recipient(self): - if "customer support" not in self.message.lower() and self.recipient == "CustomerSupportAgent": - raise ValueError("Messages not related to customer support cannot be sent to the customer support agent.") - return self -``` - -You can, of course, also use GPT for this: - -```python -from agency_swarm.tools.send_message import SendMessage -from agency_swarm.util.validators import llm_validator -from pydantic import model_validator - -class SendMessageLLMValidation(SendMessage): - @model_validator(mode='after') - def validate_recipient(self): - if self.recipient == "CustomerSupportAgent": - llm_validator( - statement="The message is related to customer support." - )(self.message) - return self -``` - -In this example, the `llm_validator` will throw an error if the message is not related to customer support. The caller agent will then have to fix the recipient or the message and send it again! This is extremely useful when you have a lot of agents. - -#### 3. Summarizing previous conversations with other agents and adding to context - -Sometimes, when using default `SendMessage`, the agents might not relay all the necessary details to the recipient agent. Especially, when the previous conversation is too long. In this case, you can summarize the previous conversation with GPT and add it to the context, instead of the additional instructions. I will extend the `SendMessageQuick` class, which already contains the `message` parameter, as I don't need chain of thought or files in this case. - -```python -from agency_swarm.tools.send_message import SendMessageQuick -from agency_swarm.util.oai import get_openai_client - -class SendMessageSummary(SendMessageQuick): - def run(self): - client = get_openai_client() - thread = self._get_main_thread() # get the main thread (conversation with the user) - - # get the previous messages - previous_messages = thread.get_messages() - previous_messages_str = "\n".join([f"{m.role}: {m.content[0].text.value}" for m in previous_messages]) - - # summarize the previous conversation - summary = client.chat.completions.create( - model="gpt-4o-mini", - messages=[ - {"role": "system", "content": "You are a world-class summarizer. Please summarize the following conversation in a few sentences:"}, - {"role": "user", "content": previous_messages_str} - ] - ) - - # send the message with the summary - return self._get_completion(message=self.message, additional_instructions=f"\n\nPrevious conversation summary: '{summary.choices[0].message.content}'") -``` - -With this example, you can add your own custom logic to the `run` method. It does not have to be a summary; you can also use it to add any other information to the context. For example, you can even query a vector database or use an external API. - -#### 4. Running each agent in a separate API call - -If you are a PRO, and you have managed to deploy each agent in a separate API endpoint, instead of using `_get_completion()`, you can call your own API and let the agents communicate with each other over the internet. - -```python -import requests -from agency_swarm.tools.send_message import SendMessage - -class SendMessageAPI(SendMessage): - def run(self): - response = requests.post( - "https://your-api-endpoint.com/send-message", - json={"message": self.message, "recipient": self.recipient} - ) - return response.json()["message"] -``` - -This is very powerful, as you can even allow your agents to collaborate with agents outside your system. More on this is coming soon! - -!!! tip "Contributing" - - If you have any ideas for new communication flows, please either adjust this page in docs, or add your new send message tool in the `agency_swarm/tools/send_message` folder and open a PR! - -**After implementing your own `SendMessage` tool**, simply pass it into the `send_message_tool_class` parameter when initializing the `Agency` class: - -```python -agency = Agency( - ... - send_message_tool_class=SendMessageAPI -) -``` - -That's it! Now, your agents will use your own custom `SendMessageAPI` class for communication! +For detailed **Common Use Cases**, please refer to the [Common Use Cases](./common-use-cases) subpage. ## Conclusion Agency Swarm has been designed to give you, the developer, full control over your systems. It is the only framework that does not hard-code any prompts, parameters, or even worse, agents for you. With this new feature, the last part of the system that you couldn't fully customize to your own needs is now gone! -So, I want to encourage you to keep experimenting and designing your own unique communication flows. While the examples above should serve as a good starting point, they do not even merely scratch the surface of what's possible here! I am looking forward to seeing what you will create. Please share it in our [Discord server](https://discord.gg/7HcABDpFPG) so we can all learn from each other. +So, we want to encourage you to keep experimenting and designing your own unique communication flows. While the examples above should serve as a good starting point, they do not even merely scratch the surface of what's possible here! We are looking forward to seeing what you will create. Please share it in our [Discord server](https://discord.gg/7HcABDpFPG) so we can all learn from each other. diff --git a/docs_new/advanced-features/few-shot-examples.mdx b/docs_new/advanced-features/few-shot-examples.mdx new file mode 100644 index 00000000..9a451141 --- /dev/null +++ b/docs_new/advanced-features/few-shot-examples.mdx @@ -0,0 +1,101 @@ +--- +title: "Few-Shot Examples" +description: "Guide agent responses using few-shot prompting." +icon: "clone" +--- + +**Few-shot prompting** is a powerful technique where you provide a small number of sample interactions (typically 2 to 5) to guide your agent's behavior. This method helps the agent understand the desired output format and task requirements by learning from the given examples, thereby improving performance even without extensive training data. + +## Defining Few-Shot Examples + +In the **Agency Swarm** framework, few-shot examples are structured using the [OpenAI message object format](https://platform.openai.com/docs/api-reference/messages/createMessage), including the `role` and `content` fields: + +```python +examples = [ + { + "role": "user", + "content": "Hello!", + }, + { + "role": "assistant", + "content": "Hi there! How can I assist you today?", + }, + { + "role": "user", + "content": "I'm interested in learning about your services.", + }, + { + "role": "assistant", + "content": "Certainly! We offer a range of solutions to meet your needs. Could you tell me more about what you're looking for?", + } +] +``` + +**Note**: The optional fields `attachments` and `metadata` can be included if needed but are not required for basic examples. + +## Incorporating Examples into Your Agent + +You can add few-shot examples to your agent either during initialization or afterward. + + + + + ```python + from agency_swarm import Agent + + agent = Agent( + name="CustomerSupportAgent", + description="Assists customers with inquiries and provides detailed information.", + examples=examples + ) + ``` + + + + + ```python + agent = Agent(name="CustomerSupportAgent") + agent.examples = examples + ``` + + + + +## Crafting Effective Examples + +- **Provide Clear Task Demonstrations**: Use examples that clearly illustrate the tasks your agent should perform. +- **Use Realistic and Diverse Scenarios**: Include interactions that mirror actual conversations your agent will handle, covering a range of situations. +- **Maintain Consistent Tone and Style**: Ensure the assistant's replies in your examples match the desired tone, whether professional, friendly, or empathetic. + +## Example: Technical Support Agent + +Let's customize an agent to provide detailed, empathetic troubleshooting assistance: + +```python +examples = [ + { + "role": "user", + "content": "My device won't turn on.", + }, + { + "role": "assistant", + "content": "I'm sorry to hear that. Let's try some troubleshooting steps. First, please press and hold the power button for at least 10 seconds.", + }, + { + "role": "user", + "content": "I tried that, but it still won't turn on.", + }, + { + "role": "assistant", + "content": "Thank you for trying that. Please connect your device to a charger and check if any lights appear. Let me know what you observe.", + } +] + +technical_support_agent = Agent( + name="TechnicalSupportAgent", + description="Provides empathetic and detailed technical support to users.", + examples=examples +) +``` + +By providing these few-shot examples, your agent learns to handle support queries with empathy and step-by-step guidance, enhancing the user experience. diff --git a/docs_new/advanced-topics/asynchronous-execution.mdx b/docs_new/advanced-topics/asynchronous-execution.mdx deleted file mode 100644 index a5856682..00000000 --- a/docs_new/advanced-topics/asynchronous-execution.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -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. - - -```python -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"`. - - -```python -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. 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 deleted file mode 100644 index 8976209b..00000000 --- a/docs_new/advanced-topics/customizing-prompts-and-few-shot-learning.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: "Customizing Prompts and Few-Shot Learning" -description: "Fine-tune agent behavior by customizing prompts and providing few-shot examples." -icon: "gear" ---- - -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. - - -```markdown -# 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. - - -```python -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/production-readiness.mdx b/docs_new/advanced-topics/production-readiness.mdx deleted file mode 100644 index d37c2bae..00000000 --- a/docs_new/advanced-topics/production-readiness.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Production Readiness" -description: "Prepare your agency for production by enhancing reliability, scalability, and security." -icon: "check" ---- - - -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. - diff --git a/docs_new/core-entities/agencies.mdx b/docs_new/core-entities/agencies.mdx index f2a77014..5d3bd99c 100644 --- a/docs_new/core-entities/agencies.mdx +++ b/docs_new/core-entities/agencies.mdx @@ -1,32 +1,44 @@ --- title: "Agencies" description: "Understanding agencies in Agency Swarm." +icon: "sitemap" --- -An **Agency** is a collection of agents that can communicate with one another. +An **Agency** is a collection of agents that can communicate with one another, working collaboratively to achieve complex tasks efficiently. ## Benefits of Using an Agency Using an Agency instead of individual agents offers several advantages: - -1. **Fewer Hallucinations**: Agents within an agency can supervise each other, reducing mistakes and handling unexpected scenarios more effectively. -2. **More Complex Tasks**: Adding more agents allows for longer sequences of actions, enabling the completion of more intricate tasks before delivering results to the user. -3. **Scalability**: Agencies can grow in complexity by adding more agents, accommodating increasing integration demands. - + + + +Agents within an agency can supervise each other, reducing mistakes and handling unexpected scenarios more effectively. + + + +Adding more agents allows for longer sequences of actions, enabling the completion of more intricate tasks before delivering results to the user. + + + +Agencies can grow in complexity by adding more agents, accommodating increasing integration demands. + Start with a minimal number of agents. Fine-tune them to ensure they function correctly before adding more. Introducing too many agents initially can make debugging and understanding interactions challenging. + + ## Communication Flows -In Agency Swarm, communication flows are **user-defined** and highly **flexible**, set up in the `agency_chart` as a directed graph where permissions to initiate communication flow from left to right. Agents listed at the top level of `agency_chart` can interact directly with the user. +In Agency Swarm, communication flows are **user-defined** and highly **flexible**. They are set up in the `agency_chart` as a directed graph, allowing permissions to initiate communication to flow from left to right. Agents listed at the top level of `agency_chart` can interact directly with the user. -For example: +### Example Configuration ```python from agency_swarm import Agency + agency = Agency([ ceo, dev, # Agents that can interact directly with the user [ceo, dev], # CEO can initiate communication with Developer @@ -35,14 +47,14 @@ agency = Agency([ ]) ``` -In this configuration: +**In this configuration:** - The **CEO** can initiate conversations with the **Developer** and **Virtual Assistant**. - The **Developer** can communicate with the **Virtual Assistant**, but cannot initiate communication with the **CEO**. ## Async Mode -Agency Swarm supports asynchronous execution in two modes: `'threading'` and `'tools_threading'`. +Agency Swarm supports asynchronous execution in two modes: `'threading'` and `'tools_threading'`. These modes enhance the efficiency and responsiveness of agent interactions. ### Agents - Threading @@ -52,11 +64,14 @@ Enable asynchronous communication between agents by setting `async_mode` to `'th agency = Agency([ceo], async_mode='threading') ``` -With this mode, responses from the `SendMessage` tool are returned instantly as system notifications with status updates. The recipient agent will then continue the task in the background. The caller agent can check the task status (if the task is in progress) or the response (if the task is complete) using the `GetResponse` tool. +With this mode: +- **Immediate Notifications**: Responses from the `SendMessage` tool are returned instantly as system notifications with status updates. +- **Background Processing**: The recipient agent continues the task in the background. +- **Status Checks**: The caller agent can check the task status (if the task is in progress) or retrieve the response (if the task is complete) using the `GetResponse` tool. ### Tools - Threading -Enable concurrent execution of tools by setting `async_mode` to `'tools_threading'`. This is beneficial for I/O-bound tasks, as it allows tools to run in separate threads, speeding up the workflow. +Enable concurrent execution of tools by setting `async_mode` to `'tools_threading'`. This is beneficial for I/O-bound tasks, allowing tools to run in separate threads and speeding up the workflow. ```python agency = Agency([ceo], async_mode='tools_threading') @@ -72,7 +87,7 @@ agency = Agency([ceo], shared_files='shared_files') ### Settings Path -Use the `settings_path` parameter to specify a custom settings file. This file replaces the default `settings.json` and stores all agent settings, including Assistant IDs for OpenAI and the tools in use. If the specified file does not exist, it will be created automatically. +Specify a custom settings file using the `settings_path` parameter. This file replaces the default `settings.json` and stores all agent settings, including Assistant IDs for OpenAI and the tools in use. If the specified file does not exist, it will be created automatically. ```python agency = Agency([ceo], settings_path='my_settings.json') @@ -80,7 +95,7 @@ agency = Agency([ceo], settings_path='my_settings.json') ### Temperature and Max Token Controls -You can control the behavior of all agents in your agency by setting default parameters: +Control the behavior of all agents in your agency by setting default parameters: - `temperature`: Controls the randomness of responses (0.0-1.0, default 0.3) - `top_p`: Controls diversity via nucleus sampling (0.0-1.0, default 1.0) @@ -121,7 +136,7 @@ response = agency.get_completion( print(response) ``` -**Parameters (optional)**: +**Parameters (optional):** - `additional_instructions`: Additional directives for the task. - `tool_choice`: Specify tools like functions to use. diff --git a/docs_new/core-entities/agents.mdx b/docs_new/core-entities/agents.mdx new file mode 100644 index 00000000..a8b4e150 --- /dev/null +++ b/docs_new/core-entities/agents.mdx @@ -0,0 +1,195 @@ +--- +title: "Agents" +description: "Understanding Agents in Agency Swarm." +icon: "robot" +--- + +Agents are the core building blocks of the Agency Swarm framework. Each agent is a specialized entity designed to play a specific role and perform a specific set of tasks. + +Agents essentially act as wrappers for [OpenAI Assistants](https://platform.openai.com/docs/assistants/deep-dive#creating-assistants). The `Agent` class includes many convenience methods to help you manage the state of your assistant, upload files, attach tools, and more. + +## 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. + +## Advanced Parameters + +While the parameters inside the `Agent` class primarily follow the same structure as OpenAI's Assistants API, there are several additional parameters you can use to customize your agent. + +### Parallel Tool Calls + +Control whether to run tools in parallel or sequentially by setting the `parallel_tool_calls` parameter. By default, this parameter is set to `True`. + +```python +from agency_swarm import Agent + +agent = Agent(name='MyAgent', parallel_tool_calls=False) +``` + +With `parallel_tool_calls=False`, the agent will run all tools sequentially. + +### File Search Configuration + +Specify the file search configuration as described in the [OpenAI documentation](https://platform.openai.com/docs/api-reference/assistants/createAssistant#assistants-createassistant-tools). + +```python +from agency_swarm import Agent + +agent = Agent( + name='MyAgent', + file_search={'max_num_results': 25}, + tool_resources={'file_search': {'vector_store_ids': ["your-vector-store-id"]}} +) # max_num_results must be between 1 and 50 +``` + +### Schemas Folder + +Define the folder where the agent will look for OpenAPI schemas to convert into tools. You can also add `api_params` and `api_headers` to pass additional parameters and headers to the API call. + +```python +from agency_swarm import Agent + +agent = Agent( + name='MyAgent', + schemas_folder='schemas', + api_params={'my_schema.json': {'param1': 'value1'}}, + api_headers={'my_schema.json': {'Authorization': 'Bearer token'}} +) +``` + + +The `schemas_folder` automatically converts any OpenAPI schemas into `BaseTool`s. This ensures that your agents type-check all API parameters **before** calling the API, significantly reducing the chances of errors. + + +### Fine-Tuned Models + +Use any previously fine-tuned model by specifying the `model` parameter in the agent. + +```python +from agency_swarm import Agent + +agent = Agent(name='MyAgent', model='gpt-4o-mini-model-name') +``` + +### Response Validator + +Provide a response validator function to validate the response before sending it to the user or another agent. This function should raise an error if the response is invalid. + +```python +from agency_swarm import Agent + +class MyAgent(Agent): + def response_validator(self, message: str) -> str: + """Validate the response before sending it.""" + if "bad word" in message: + raise ValueError("Please avoid using inappropriate language.") + return message +``` + + +## Creating Agents + +When creating an agent, you need to: + +- **Define Agent Classes**: Extend the base `Agent` class and customize parameters. +- **Set Instructions**: Provide detailed instructions to guide agent behavior. +- **Assign Tools**: Equip agents with tools relevant to their roles. + +There are two ways to create an agent: +- Define an agent directly in code +- Create an agent template using the CLI + +### Defining an Agent Directly in Code + +Instantiate the `Agent` class directly in your code and pass the required parameters. + +```python +from agency_swarm import Agent + +agent = Agent( + name="MyAgent", + description="This is a description of my agent.", + instructions="These are the instructions for my agent.", + tools=[ToolClass1, ToolClass2], + temperature=0.3, + max_prompt_tokens=25000 +) +``` + +### Creating an Agent Template Using the CLI + +Simplify the process of creating a structured environment for each agent using the CLI command. + +#### Command Syntax + +```bash +agency-swarm create-agent-template --name "AgentName" --description "Agent Description" [--path "/path/to/directory"] [--use_txt] +``` + +#### Folder Structure + +Running the `create-agent-template` command generates the following folder structure for your agent: + +``` +/your-specified-path/ +├── agency_manifesto.md or .txt # Agency's guiding principles (created if not exists) +└── AgentName/ # Directory for the specific agent + ├── files/ # Files to be uploaded to OpenAI + ├── schemas/ # OpenAPI schemas to be converted into tools + ├── tools/ # Tools to be imported by default + ├── AgentName.py # Main agent class file + ├── __init__.py # Initializes the agent folder as a Python package + └── instructions.md or .txt # Instruction document for the agent +``` + +- **files**: Store files to be uploaded to OpenAI. Acceptable formats are listed in [File Search](https://platform.openai.com/docs/assistants/tools/file-search#supported-files) and [Code Interpreter](https://platform.openai.com/docs/assistants/tools/code-interpreter#supported-files). Uploaded files receive an ID to prevent re-uploading. +- **schemas**: Store OpenAPI schemas to be automatically converted into tools. Place the schema in this folder and specify it when initializing your agent. +- **tools**: Store tools as Python files. Each file must have the same name as the tool class (e.g., `ExampleTool.py` must contain a class called `ExampleTool`). + +#### Agent Template + +The `AgentName.py` file contains: + +```python +from agency_swarm import Agent + +class AgentName(Agent): + def __init__(self): + super().__init__( + name="agent_name", + description="agent_description", + instructions="./instructions.md", + files_folder="./files", + schemas_folder="./schemas", + tools_folder="./tools", + temperature=0.3, + max_prompt_tokens=25000, + examples=[] + ) + + def response_validator(self, message: str) -> str: + """Validate the response before sending it.""" + if "bad word" in message: + raise ValueError("Please avoid using inappropriate language.") + return message +``` + +To initialize the agent: + +```python +from AgentName import AgentName + +agent = AgentName() +``` + +### Importing Existing Agents + +For complex use cases, you can import pre-made agents. Run the following CLI command: + +```bash +agency-swarm import-agent --name "AgentName" --destination "/path/to/directory" +``` + +This copies all source files of the agent locally. You can then import the agent as shown above. To check available agents, simply run the command without any arguments. diff --git a/docs_new/directory-structure/directory-structure.mdx b/docs_new/directory-structure/directory-structure.mdx deleted file mode 100644 index f2a7d23d..00000000 --- a/docs_new/directory-structure/directory-structure.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Directory Structure" -description: "Learn how to organize your agency projects using the recommended directory structure." -icon: "folder-open" ---- - -Organize your agency projects using the recommended directory 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 -├── agency_manifesto.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. -- **agency_manifesto.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 deleted file mode 100644 index 7350406a..00000000 --- a/docs_new/framework-overview/communication-flows.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "Communication Flows" -description: "Learn how to define communication flows for your agency." -icon: "comments" ---- - -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/design-and-architecture.mdx b/docs_new/framework-overview/design-and-architecture.mdx deleted file mode 100644 index 45eaa941..00000000 --- a/docs_new/framework-overview/design-and-architecture.mdx +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: "Design and Architecture" -description: "Learn about Agency Swarm's modular architecture and how its components work together" -icon: "cube" ---- - -Agency Swarm employs a **modular architecture** that facilitates the flexible configuration and dynamic management of AI agents. This architecture is meticulously designed to enable seamless collaboration, communication, and coordination among agents, empowering them to tackle complex, multifaceted tasks efficiently. - -## Core Components - - -At the core of the framework lies the `Agency` class, responsible for managing the collective of agents. It initializes with a list of agents, each potentially containing sub-agents, and references shared instructions to maintain consistency across the agency. - - - -Agents are the fundamental units within Agency Swarm, each designed with distinct roles and capabilities. They operate based on predefined roles that guide their interactions and decision-making processes. Agents can autonomously execute tasks, modify files, and utilize various tools to enhance their functionality. - -Key characteristics of agents: - -- **Role-Based**: Agents function according to their designated roles. -- **Custom Instructions**: Each agent can be configured with unique instructions, enabling specialized behavior. -- **Tools and Functions**: Agents can be equipped with various tools to extend their capabilities. -- **Communication**: Agents communicate with each other using the `SendMessage` tool, enabling synchronous interactions. - - - -Tools extend the capabilities of agents by providing them with specialized functions or actions they can perform. They are crucial for allowing agents to interact with the environment, process data, communicate, and execute complex tasks. - -### Types of Tools - - - - Developed by developers to provide agents with functionalities tailored to specific tasks or integrations with external systems. Custom tools are fixed and assigned to agents based on their roles. - - - The framework includes built-in tools that are readily available for agents: - - **File Search**: Provided by OpenAI, allows agents to search and retrieve information from files. Useful for Retrieval-Augmented Generation (RAG). - - **Code Interpreter**: Provided by OpenAI, allows agents to execute code within a sandboxed environment. - - - -### Tool Integration - -Tools are integrated into agents based on their roles and the tasks they need to perform. This integration is typically done during the agent's initialization. - -```python Example Agent with Tools -from agency_swarm import Agent -from agency_swarm.tools import CodeInterpreter - -class DeveloperAgent(Agent): - def __init__(self): - super().__init__( - name="DeveloperAgent", - description="An agent responsible for developing and testing code.", - tools=[CodeInterpreter], - instructions="./instructions.md", - temperature=0.5, - max_prompt_tokens=2500, - ) -``` - -In this example, the `DeveloperAgent` is equipped with the `CodeInterpreter` tool, enabling it to execute code. - - -## Communication Flow - - - - Agents communicate using the `SendMessage` tool, which facilitates synchronous interactions. - - - The `AgencyEventHandler` intercepts and processes messages based on type: - - **Function Calls**: Queued and executed - - **Text Messages**: Directly relayed to recipients - - - -## Agency Creation and Finalization - - - The framework includes specialized agents like `GenesisCEO` and `ToolCreator`, which are responsible for setting up the agency structure and creating necessary tools. - - - - The `ToolCreator` agent automates the development and testing of tools, ensuring that each tool is functional and integrates seamlessly with the agents. - - - - Once all agents and tools are set up, the `FinalizeAgency` tool ensures that the agency is properly configured and ready for deployment. - - -## Getting Started - -To get started with Agency Swarm, navigate to the agency folder and run: - -```bash -python agency.py -``` - -## Further Enhancements - - -- **Tool Expansion**: Continuously develop and integrate new tools to expand agent capabilities. -- **Scalability**: Optimize the framework to handle larger agencies with more complex agent interactions. -- **User Customization**: Allow users to define custom agent roles and tool integrations based on specific needs. - - ---- - -## Related Documentation - - - Learn how to create and use tools to enhance your agents' capabilities. - - - - Understand how to define and configure agents within your agency. - - - - Step-by-step guide on creating custom tools for your agents. - - - - Enhance agent capabilities by integrating OpenAI's Code Interpreter and File Search tools. - diff --git a/docs_new/framework-overview/framework-comparison.mdx b/docs_new/framework-overview/framework-comparison.mdx deleted file mode 100644 index 9b6a1593..00000000 --- a/docs_new/framework-overview/framework-comparison.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Framework Comparison" -description: "Compare Agency Swarm with other multi-agent AI frameworks." -icon: "compass" ---- - -This section compares **Agency Swarm** with other multi-agent AI frameworks like **AutoGen** and **CrewAI**. The comparison highlights key features and differences to help you understand how Agency Swarm stands out. - -## Overview - -| **Criteria** | **Agency Swarm** | **AutoGen** | **CrewAI** | -| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| **Design & Architecture** | - Modular, production-focused
- Hierarchical agent structure via agency chart
- Built for real business needs | - Event-driven, scalable
- Asynchronous message passing
- Supports distributed computing | - Flexible agent organization into crews
- Agents with rich attributes
- Emphasis on collaboration | -| **Key Entities** | - Agents
- Tools
- Agencies | - ConversableAgent
- AssistantAgent
- UserProxyAgent | - Agents
- Tasks
- Crews | -| **Agent Structure** | - Hierarchical (supervisor-subordinate)
- Customizable communication flows | - Supports sequential, group, and nested structures | - Supports various workflows (sequential, hierarchical, asynchronous) | -| **Tool Integration** | - Python-based tools with Pydantic validation
- Easy tool creation and integration | - Extensive tool support
- Function calling for task delegation | - Built-in and custom tools
- Caching mechanisms for performance | -| **State Management** | - Shared state among agents and tools
- Conversation context via OpenAI API | - Conversation history maintenance
- Dynamic context truncation | - Three-tier memory system
- Context sharing among agents and tasks | -| **Production Readiness** | - Designed for production environments
- Business-oriented design
- Robust validation and error correction | - Scalable and distributed
- Active development towards production features | - Requires additional development for production
- Scalability testing needed | -| **Prompt Flexibility** | - Full control over prompts
- No hardcoded interactions
- Markdown instructions for agents | - Flexible prompt engineering
- Supports few-shot learning | - Extensive prompt customization
- Supports multiple languages | -| **Output Validation & Reliability** | - Input validation with Pydantic
- Custom response validators
- Auto-correction using LLM capabilities | - Robust error handling
- Code execution validation
- Self-correction by agents | - Custom validation logic
- Reliability features: retries, exception handling
- Multiple validation layers including human review | -| **Conversation Context Management** | - Managed via OpenAI Assistants API
- Separate threads for communication flows
- Built-in RAG support | - Conversation modes: static, dynamic, human-in-the-loop
- Context-aware responses | - Memory systems manage context
- Context sharing among agents and tasks | -| **Task Delegation** | - Agent autonomy in task delegation
- `SendMessage` tool for communication
- Hierarchical delegation via agency chart | - Automated task coordination
- Function calls for delegation
- Various interaction patterns | - Delegation control via agent attributes
- Autonomous delegation based on capabilities
- Hand-off mechanisms with context preservation | -| **Streaming Support** | - Supports streaming responses
- Voice interface for real-time interaction | - Real-time interaction with streaming
- Event-driven architecture facilitates this | - Streaming support for real-time outputs
- Enhances interactivity and responsiveness | -| **Evaluation & Monitoring** | - OpenAI dashboard for cost and usage
- Third-party integration in progress | - Built-in observability features
- Performance metrics and debugging tools | - Custom evaluation metrics can be implemented
- Logging and analytics support
- Callbacks for execution monitoring | - -## Summary - -- **Agency Swarm** is ideal for production environments requiring full control over agent behavior, with a focus on business needs and hierarchical structures. -- **AutoGen** emphasizes scalability and extensibility with its event-driven architecture and supports distributed computing. -- **CrewAI** offers flexible agent organization suitable for collaborative projects but may require additional development for production readiness. - -## Next Steps -- **[Getting Started](../getting-started/installation)** -- **[Creating Agents](../how-to-guides/creating-agents)** diff --git a/docs_new/framework-overview/output-validation-and-reliability.mdx b/docs_new/framework-overview/output-validation-and-reliability.mdx deleted file mode 100644 index 73fece69..00000000 --- a/docs_new/framework-overview/output-validation-and-reliability.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Output Validation and Reliability" -description: "Learn how Agency Swarm ensures the reliability of agent outputs." -icon: "check" ---- - -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. diff --git a/docs_new/quickstart/cursor-ai.mdx b/docs_new/getting-started/cursor-ai.mdx similarity index 100% rename from docs_new/quickstart/cursor-ai.mdx rename to docs_new/getting-started/cursor-ai.mdx diff --git a/docs_new/quickstart/from-scratch.mdx b/docs_new/getting-started/from-scratch.mdx similarity index 100% rename from docs_new/quickstart/from-scratch.mdx rename to docs_new/getting-started/from-scratch.mdx diff --git a/docs_new/quickstart/genesis-agency.mdx b/docs_new/getting-started/genesis-agency.mdx similarity index 62% rename from docs_new/quickstart/genesis-agency.mdx rename to docs_new/getting-started/genesis-agency.mdx index a5039122..ebbdee3d 100644 --- a/docs_new/quickstart/genesis-agency.mdx +++ b/docs_new/getting-started/genesis-agency.mdx @@ -4,7 +4,7 @@ description: "Quick start guide using the Genesis Agency." icon: "wand-sparkles" --- -Genesis Agency is an AI-powered agency architect that helps you design and create custom agent swarms. It was developed to automate the process of building collaborative AI agent networks. The agency consists of specialized agents that work together to: +Genesis Agency is an AI-powered agency architect that helps you design and create custom agent swarms. It automates the process of building collaborative AI agent networks. The agency consists of specialized agents that work together to: - Design your agency's structure and communication flows - Generate agent templates with appropriate roles and instructions @@ -15,9 +15,9 @@ Genesis Agency is an AI-powered agency architect that helps you design and creat - This command initializes the Genesis Agency in your terminal and generates your agent templates. + Initialize the Genesis Agency in your terminal and generate your agent templates. - #### **Command Syntax:** + **Command Syntax:** ```bash agency-swarm genesis [--openai_key "YOUR_API_KEY"] @@ -26,12 +26,16 @@ Genesis Agency is an AI-powered agency architect that helps you design and creat Provide comprehensive context to the Genesis Agency by including: - - **Your mission and goals.** + - **Your agency's mission and goals.** - **The agents you wish to involve and their communication flows.** - **Tools or APIs each agent should have access to, if any.** - + + After executing the `genesis` command, specialized agents such as `GenesisCEO` and `ToolCreator` will begin constructing your agency's structure and developing the required tools. + + + Once Genesis has created your agents, you'll find all the agent folders in the directory where you ran the `genesis` command. Fine-tune the agents and tools as needed by following these steps: 1. **Adjust Tools**: Modify the tools in each agent's `tools` directory to meet your requirements. @@ -39,8 +43,11 @@ Genesis Agency is an AI-powered agency architect that helps you design and creat 3. **Run Agency**: Execute the `agency.py` file, dispatch your tasks, and monitor their performance. 4. **Repeat**: Continue refining until your agents perform optimally. - !!! note "Agent Development is an Iterative Process" - Currently, agent development requires ongoing monitoring and adjustments to ensure desired performance. As larger and more advanced models become available, this process will become more streamlined. + + **Agent Development is an Iterative Process** + + Currently, agent development requires ongoing monitoring and adjustments to ensure desired performance. As larger and more advanced models become available, this process will become more streamlined. + diff --git a/docs_new/quickstart/quickstart.mdx b/docs_new/getting-started/quickstart.mdx similarity index 68% rename from docs_new/quickstart/quickstart.mdx rename to docs_new/getting-started/quickstart.mdx index 7b269358..10185230 100644 --- a/docs_new/quickstart/quickstart.mdx +++ b/docs_new/getting-started/quickstart.mdx @@ -27,8 +27,16 @@ When it comes to getting started with Agency Swarm, you have three options: -## Next Steps +## Next Steps: Learn About Core Entities -- Learn how to create more Tools, Agents, and Agencies -- Deploy in Production -- Check out the [Tutorials](../tutorials) section for detailed tutorials + + Learn how to create and use tools to enhance your agents' capabilities. + + + + Learn how to define and configure agents within your agency. + + + + Learn how to create and manage agencies to coordinate multiple agents. + diff --git a/docs_new/introduction/design-principles.mdx b/docs_new/introduction/design-principles.mdx deleted file mode 100644 index f41ecd10..00000000 --- a/docs_new/introduction/design-principles.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: "Design Principles" -description: "Learn about the design principles of Agency Swarm." -icon: "cube" ---- - -## 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. diff --git a/docs_new/introduction/key-features.mdx b/docs_new/introduction/key-features.mdx deleted file mode 100644 index 3dc68a47..00000000 --- a/docs_new/introduction/key-features.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Key Features" -description: "Learn about the key features of Agency Swarm." -icon: "gem" ---- - -- **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. diff --git a/docs_new/key-entities/agents.mdx b/docs_new/key-entities/agents.mdx deleted file mode 100644 index aefe23ac..00000000 --- a/docs_new/key-entities/agents.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Agents" -description: "Learn about the core building blocks of Agency Swarm." -icon: "robot" ---- - -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) guide. diff --git a/docs_new/mint.json b/docs_new/mint.json index d51c3e43..42bb6384 100644 --- a/docs_new/mint.json +++ b/docs_new/mint.json @@ -67,42 +67,41 @@ ] }, { - "group": "Quick Start", + "group": "Getting Started", "pages": [ - "quickstart/quickstart", - "quickstart/from-scratch", - "quickstart/genesis-agency", - "quickstart/cursor-ai" + "getting-started/quickstart", + "getting-started/from-scratch", + "getting-started/genesis-agency", + "getting-started/cursor-ai" ] }, { "group": "Core Entities", "pages": [ - "core-entities/agencies", + "core-entities/tools", "core-entities/agents", - "core-entities/tools" - ] - }, - { - "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" + "core-entities/agencies" ] }, { "group": "Advanced Features", "pages": [ - "advanced-features/streaming", "advanced-features/asynchronous-execution", - "advanced-features/customizing-prompts-and-few-shot-learning", + "advanced-features/shared-state", + "advanced-features/openapi-schemas", + "advanced-features/few-shot-examples", + "advanced-features/response-validators", + "advanced-features/streaming", + "advanced-features/observability", "advanced-features/open-source-models", - "advanced-features/production-readiness" + { + "group": "Custom Communication Flows", + "pages": [ + "advanced-features/custom-communication-flows/overview", + "advanced-features/custom-communication-flows/common-use-cases" + ] + }, + "advanced-features/deployment-to-production" ] }, { diff --git a/docs_new/welcome/overview.mdx b/docs_new/welcome/overview.mdx index c5ffe1c0..e177b995 100644 --- a/docs_new/welcome/overview.mdx +++ b/docs_new/welcome/overview.mdx @@ -41,6 +41,6 @@ Unlike other frameworks, Agency Swarm focuses on setting boundaries for agents r ## Next Steps - - **[Installation Guide](../getting-started/installation)**: Detailed setup instructions + - **[Getting Started](../getting-started/quickstart)**: Learn how to install Agency Swarm and create your first agent - **[Tutorials](../tutorials)**: Explore sample use cases - - **[API Reference](../api-reference/api-reference)**: Full API documentation + - **[API Reference](../api)**: Full API documentation