Finished basics of tools and creating tools step by step guide

docs_new/core-framework/tools/advanced-tool-features.mdx → docs_new/core-framework/tools/custom-tools/configuration.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Advanced Tool Features"
+title: "Advanced Tool Configuration"
 description: "Advanced features and patterns for Agency Swarm tools."
 icon: "wand-magic-sparkles"
 ---

docs_new/core-framework/tools/custom-tools/pydantic-is-all-you-need.mdx

@@ -0,0 +1,7 @@
+---
+title: "Pydantic is All You Need"
+description: "How Pydantic solves AI Agent reliability."
+icon: "book"
+---
+
+This guide is based on a youtube video pydantic is all you need by Jason Liu.

docs_new/core-framework/tools/creating-custom-tools.mdx → docs_new/core-framework/tools/custom-tools/step-by-step-guide.mdx

@@ -1,35 +1,144 @@
 ---
-title: "Creating Custom Tools"
+title: "Step-by-Step Guide"
 description: "Learn how to create custom tools in Agency Swarm"
-icon: "hammer"
+icon: "map"
 ---
 
-## Basic Process Overview
+In Agency, tools are Python classes that inherit from `BaseTool`. They are defined using [Pydantic](https://docs.pydantic.dev/latest/), a data validation library. Each BaseTool must implement the `run` method, which is the main method that will be called when the tool is invoked by an agent.
+
+## Step-by-step Guide
+
+To create a custom tool, typically you need to follow these steps:
 
 <Steps>
-  <Step title="Plan the Tool's Purpose and Functionality">
-    Define what the tool will do and how it will be used by agents.
-  </Step>
-  <Step title="Create a New Python Class">
-    Import `BaseTool` and create a new class that extends it.
+  <Step title="Add Import Statements">
+    On top of your tool file, import the necessary modules and classes.
+
+    ```python
+    from agency_swarm.tools import BaseTool
+    from pydantic import Field, model_validator
+    # ... other imports
+    ```
   </Step>
-  <Step title="Write a Clear Docstring">
-    This docstring is crucial as it helps agents understand how to use the tool.
+
+  <Step title="Define the Tool Class and Docstring">
+    Create a new class that inherits from `BaseTool`. Write a clear docstring describing the tool's purpose. **This docstring is crucial as it helps agents understand how to use the tool.**
+
+    ```python
+    class Calculator(BaseTool):
+        """
+        A simple calculator tool that evaluates mathematical expressions.
+        """
+    ```
   </Step>
+
   <Step title="Define Input Fields">
-    Use Pydantic's `Field` to define the tool's input parameters.
+    Use Pydantic fields to define the inputs your tool will accept.
+
+    ```python
+    expression: str = Field(..., description="The mathematical expression to evaluate.")
+    ```
+
+    <Accordion title="Custom Validation Logic (Optional)" icon="hammer">
+      You can use [Pydantic's validators](https://docs.pydantic.dev/latest/concepts/validators/) to verify the inputs. This can be extremely effective to avoid hallucinations or other errors in production.
+      ```python
+      @model_validator(mode="after")
+      def validate_expression(self):
+          if self.expression.endswith("/0"):
+              raise ValueError("Division by zero is not permitted")
+      ```
+    </Accordion>
   </Step>
+
   <Step title="Implement the run Method">
-    Write the code that executes the tool's functionality.
+    Add the functionality that will be executed when the tool is called.
+
+    ```python
+    def run(self):
+        # Implement the tool's functionality
+        result = eval(self.expression)
+        return str(result)
+    ```
+
+    The `run` method should return a string, which is the tool's output that the agent will see and use in its response.
   </Step>
-  <Step title="Test the Tool">
-    Ensure the tool works as expected before integrating it.
+
+  <Step title="Test the Tool Independently">
+    Test the tool independently to ensure it behaves as expected. We recommend adding a `if __name__ == "__main__":` block at the end of the tool file:
+
+    ```python
+    if __name__ == "__main__":
+        calc = Calculator(expression="2 + 2 * 3")
+        print(calc.run())  # Output should be '8'
+    ```
   </Step>
-  <Step title="Add to Agent's Toolset">
-    Include the tool in the agent's list of available tools.
+
+  <Step title="Add the Tool to an Agent">
+    After your tool works as expected, simply add it to an agent's list of `tools`.
+
+    ```python
+    from agency_swarm import Agent
+    from .tools.calculator import Calculator
+
+    agent = Agent(
+        name="MathAgent",
+        tools=[Calculator],
+        # Other agent parameters
+    )
+    ```
+
+    <Accordion title="Using tools folder" icon="folder">
+      Alternatively, you can simply place the tool file in the `tools_folder` directory and it will be automatically added to the agent.
+
+      ```python
+      from agency_swarm import Agent
+      agent = Agent(
+          name="MathAgent",
+          tools_folder="./tools",
+          # Other agent parameters
+      )
+      ```
+
+      <Note>
+        Each file in the `tools_folder` should contain a class that is named exactly the same as the file name. For example, `Calculator.py` should contain a `Calculator` class.
+      </Note>
+    </Accordion>
   </Step>
 </Steps>
 
+## Full Code Example
+
+Below is the full code example for a calculator tool above.
+
+```python
+# calculator.py
+from agency_swarm.tools import BaseTool
+from pydantic import Field, model_validator
+
+class Calculator(BaseTool):
+    """
+    A simple calculator tool that evaluates mathematical expressions.
+    """
+    expression: str = Field(..., description="The mathematical expression to evaluate.")
+
+    @model_validator(mode="after")
+    def validate_expression(self):
+        if self.expression.endswith("/0"):
+            raise ValueError("Division by zero is not permitted")
+
+    def run(self):
+        result = eval(self.expression)
+        return str(result)
+
+if __name__ == "__main__":
+    calc = Calculator(expression="2 + 2 * 3")
+    print(calc.run())  # Output should be '8'
+```
+
+## Next Steps
+
+- Read [Why Pydantic?](./pydantic-is-all-you-need)
+
 ## Creating Your First Tool
 
 Let's walk through creating a simple tool step by step.
@@ -219,3 +328,36 @@ Remember to:
 </Check>
 
 ---
+
+
+## Built-in Tools
+
+Agency Swarm comes with several built-in tools to enhance agent capabilities:
+
+<Accordion title="Code Interpreter" icon="code">
+- **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
+  )
+  ```
+</Accordion>
+
+<Accordion title="File Search" icon="magnifying-glass">
+- **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
+  )
+  ```
+</Accordion>