Add output validation page, openapi schemas page, deployment guide

docs_new/advanced-features/deployment-to-production.mdx

@@ -0,0 +1,128 @@
+---
+title: "Deploying Your Agency to Production"
+description: "Step-by-step guide for deploying your agency smoothly."
+icon: "rocket-launch"
+---
+
+Deploying your Agency to a production environment can seem daunting, but with the right guidance, it's a straightforward process. This comprehensive guide will walk you through the essential steps to get your agency up and running in production effectively.
+
+## Key Steps for Deployment
+
+1. **Dynamic Loading of Agents and Threads**: Tailor your agency's behavior based on users or sessions by dynamically loading agents and conversation threads.
+2. **Deploy Agents and Tools on a Production Server**: Choose the deployment strategy that best fits your needs, whether deploying tools together with agents or as separate services.
+
+## Step 1: Dynamically Loading Agents and Threads
+
+To ensure your agency is responsive to different users or sessions, dynamically load agents and their conversation histories (threads). This guarantees each user has a personalized experience and that conversations persist across sessions.
+
+### Understanding Callbacks
+
+Agency Swarm provides `threads_callbacks` and `settings_callbacks` to manage the retrieval and storage of agents and threads dynamically. These callbacks are functions you define to interface with your chosen database or storage system.
+
+### Implementing Settings Callbacks
+
+The **settings** represent the state of all agents in your agency. By implementing settings callbacks, you can load agent configurations specific to a user or session.
+
+**Example:**
+
+```python
+def load_settings(user_id):
+    # Load settings from your database using the user_id
+    settings = load_settings_from_db(user_id)
+    return settings
+
+def save_settings(new_settings):
+    # Save the updated settings to your database
+    save_settings_to_db(new_settings)
+```
+
+### Implementing Threads Callbacks
+
+The **threads** contain the conversation histories between agents and users. Handling threads callbacks ensures users can seamlessly continue previous conversations.
+
+**Example:**
+
+```python
+def load_threads(chat_id):
+    # Load conversation threads from your database using the chat_id
+    threads = load_threads_from_db(chat_id)
+    return threads
+
+def save_threads(new_threads):
+    # Save the updated threads to your database
+    save_threads_to_db(new_threads)
+```
+
+> **Note:** Ensure that the data structures you load and save match the expected formats used by the agency.
+
+### Putting It All Together
+
+Initialize your agency by passing the defined callbacks. Include necessary identifiers like `user_id` or `chat_id` to fetch the correct data.
+
+**Example:**
+
+```python
+agency = Agency(
+    [ceo],  # Replace 'ceo' with your primary agent(s)
+    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)
+    },
+    settings_path='my_settings.json'  # Optional path to save settings locally
+)
+```
+
+With this setup, your agency will dynamically load user-specific agents and conversation histories, providing a tailored experience for each user.
+
+## Step 2: Deploying Agents and Tools on a Production Server
+
+To streamline deployment, you have multiple options depending on your application's architecture and requirements.
+
+<Accordion title="Option 1: Deploy Agents Together with Tools" defaultOpen={true}>
+
+Simplify deployment by deploying your agents and tools together using our ready-made deployment template.
+
+#### Use the Railway Deployment Template
+
+Leverage our Railway deployment template to quickly deploy your agency as a web service. Railway is a platform that simplifies deploying applications without the overhead of managing servers.
+
+<Card
+    title="API Railway Template"
+    color="#F3A78B"
+    href="https://github.com/VRSEN/agency-swarm-api-railway-template"
+    icon="train"
+    iconType="duotone"
+>
+    Click here to access the template and follow the instructions to get your agency deployed.
+</Card>
+
+Find more detailed instructions in the video below:
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/53_e3lmk6Mo?si=kASCTtxfa6ljqGNy&amp;start=806" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+</Accordion>
+
+<Accordion title="Option 2: Deploy Tools as Separate API Endpoints" defaultOpen={false}>
+
+Alternatively, you can deploy your tools as separate API endpoints (e.g., serverless functions) and integrate them into your agents using [OpenAPI schemas](/advanced-features/openapi-schemas). This approach allows for greater scalability and modularity, especially if you plan to reuse tools across different agents or services.
+
+Deploying tools separately allows for greater flexibility and scalability. You can deploy individual tools as serverless functions on platforms like AWS Lambda, Google Cloud Functions, or Azure Functions. This approach provides on-demand scalability and cost efficiency. Alternatively, you can host your tools as custom API endpoints using frameworks like FastAPI or Flask and deploy them on platforms such as Heroku, DigitalOcean, Railway, or your own servers.
+
+<Note>
+When deploying tools separately, ensure proper authentication and secure communication between your agents and the tool APIs.
+</Note>
+
+</Accordion>
+
+### Choosing the Right Approach
+
+Consider your application's requirements when choosing a deployment strategy:
+
+- **Deploying Together**: Ideal for simpler deployments where all components are managed within the same environment.
+- **Deploying Separately**: Suitable for larger, modular applications needing flexibility, independent scaling, or sharing tools among multiple agents.
+
+By understanding these options, you can select the deployment method that best fits your project's needs.

docs_new/advanced-features/openapi-schemas.mdx

@@ -0,0 +1,71 @@
+---
+title: "OpenAPI Schemas"
+description: "Integrate OpenAPI schemas into your agents for seamless API interaction."
+icon: "brackets-curly"
+---
+
+OpenAPI schemas enable your agents within the Agency Swarm framework to interact with external APIs in a structured, reliable manner. By converting OpenAPI schemas into tools, agents can perform API calls with proper parameter validation and error handling, significantly enhancing their capabilities without compromising on robustness.
+
+### How to Integrate OpenAPI Schemas
+
+Agency Swarm offers built-in support for converting OpenAPI schemas into tools that your agents can use directly. This automatic conversion makes agents aware of API endpoints, parameters, and expected data types as defined in the OpenAPI specifications.
+
+#### Option 1: Using the Schemas Folder
+
+A straightforward way to integrate OpenAPI schemas is by specifying a `schemas_folder` when initializing your agent. Agency Swarm will automatically scan this folder and convert any OpenAPI schemas it finds into `BaseTool` instances.
+
+```python
+from agency_swarm import Agent
+
+agent = Agent(
+    name='MyAgent',
+    schemas_folder='schemas',
+    api_params={'api_schema.json': {'param1': 'value1'}},
+    api_headers={'api_schema.json': {'Authorization': 'Bearer token'}}
+)
+```
+
+In this example:
+
+- `schemas_folder`: Designates the directory containing your OpenAPI schema files.
+- `api_params`: Provides additional parameters for specific schemas.
+- `api_headers`: Allows custom headers, such as authentication tokens, to be included in API calls.
+
+<Note type="info">
+By automatically converting OpenAPI schemas into tools, your agents perform type checking on all API parameters **before** making API calls, reducing errors and improving reliability.
+</Note>
+
+#### Option 2: Using the ToolFactory Class
+
+Alternatively, you can use the `ToolFactory` class to convert OpenAPI schemas from local files or URLs.
+
+<Accordion title="Converting from a Local Schema File">
+```python
+from agency_swarm.tools import ToolFactory
+
+with open("schemas/api_schema.json") as f:
+    tools = ToolFactory.from_openapi_schema(f.read())
+```
+</Accordion>
+
+<Accordion title="Converting from a Remote Schema URL">
+```python
+from agency_swarm.tools import ToolFactory
+import requests
+
+response = requests.get("https://api.example.com/openapi.json")
+tools = ToolFactory.from_openapi_schema(response.json())
+```
+</Accordion>
+
+### Best Practices
+
+<Check>
+- **Keep Schemas Updated**: Regularly update your OpenAPI schema files to align with the latest API definitions.
+- **Secure API Access**: Use `api_headers` to securely manage authentication tokens and sensitive information.
+- **Implement Error Handling**: Ensure your agents gracefully handle failed API calls and provide fallback responses.
+</Check>
+
+<Note>
+When integrating external APIs, be cautious of rate limits, authentication requirements, and data privacy considerations.
+</Note>

docs_new/advanced-features/output-validation.mdx

@@ -0,0 +1,111 @@
+---
+title: "Output Validation"
+description: "Implementing validators for agents and tools."
+icon: "check"
+---
+
+In Agency Swarm, validating the outputs of agents and tools is crucial for building reliable and secure AI agents. Validators help ensure data integrity and tackle LLM hallucinations.
+
+### Agent Response Validator
+
+Agents can include a `response_validator` method to check their responses before sending them to the user or other agents. This method should raise an error if the response is invalid, allowing the agent to handle the error and generate a corrected response.
+
+**Example:**
+
+```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.lower():
+            raise ValueError("Please avoid using inappropriate language.")
+        return message
+```
+
+In this example, `MyAgent` checks the response for any inappropriate language before it is sent. If the validation fails, a `ValueError` is raised.
+
+### Field-Level Validators vs. Model Validators
+
+When defining tools and agents, Pydantic validators help enforce rules on input data. Understanding the difference between field-level and model-level validators allows you to implement effective validation logic.
+
+#### Field Validators
+
+- **Purpose:** Validate individual fields independently.
+- **Usage:** Use the `@field_validator` decorator on methods, specifying the field(s) to validate.
+
+**Example:**
+
+```python
+from pydantic import field_validator
+from agency_swarm import BaseTool
+
+class User(BaseTool):
+    username: str
+
+    @field_validator('username')
+    @classmethod
+    def validate_username(cls, value):
+        if ' ' in value:
+            raise ValueError('Username must not contain spaces.')
+        return value
+```
+
+This example ensures that the `username` field does not contain spaces using a field validator.
+
+#### Model Validators
+
+- **Purpose:** Validate the entire model, allowing checks involving multiple fields.
+- **Usage:** Use the `@model_validator` decorator on methods.
+
+**Example:**
+
+```python
+from pydantic import model_validator
+from agency_swarm import BaseTool
+
+class User(BaseTool):
+    password: str
+    confirm_password: str
+
+    @model_validator(mode='after')
+    def check_passwords_match(self):
+        if self.password != self.confirm_password:
+            raise ValueError('Passwords do not match.')
+        return self
+```
+
+In this example, a model validator checks that `password` and `confirm_password` match, which requires access to multiple fields.
+
+### Using `llm_validator`
+
+The `llm_validator` is a powerful decorator provided by Agency Swarm that leverages Large Language Models (LLMs) for validation based on natural language rules.
+
+- **Key Features:**
+  - Uses LLMs to validate against natural language rules.
+  - Can auto-correct invalid values when `allow_override=True` is set.
+  - Provides detailed reasoning for why validation failed.
+
+**Example:**
+
+```python
+from agency_swarm import BaseTool, llm_validator
+from pydantic import Field
+
+class User(BaseTool):
+    name: str = llm_validator("The name must be a full name in all lowercase letters.")
+    age: int = Field(..., description="The user's age.")
+
+try:
+    user = User(name="Jason Liu", age=20)
+except ValidationError as e:
+    print(e)
+```
+
+Here, `llm_validator` checks that the `name` field complies with the specified natural language rule. If the input does not meet the criteria, a `ValidationError` is raised with an explanation.
+
+<Note>
+Since `llm_validator` uses LLMs for validation, it may incur additional costs and latency due to the extra API calls. Use it for fields that require complex validation beyond simple checks.
+</Note>
+
+By combining agent response validators, field-level validators, model validators, and `llm_validator`, you can create robust validation logic to ensure your agents and tools perform reliably.

docs_new/core-entities/agents.mdx

@@ -46,22 +46,7 @@ agent = Agent(
 
 ### 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'}}
-)
-```
-
-<Note type="info">
-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.
-</Note>
+See the [OpenAPI Schemas](../advanced-features/openapi-schemas) page for more information on how to use OpenAPI schemas to create tools for your agents.
 
 ### Fine-Tuned Models
 
@@ -73,22 +58,6 @@ 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:
@@ -193,3 +162,8 @@ 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.
+
+
+### Response Validator
+
+See the [Response Validators](../advanced-features/response-validators) page for more information on how to use response validators to validate the response before sending it to the user or another agent.