Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Finished custom tools section and framework comparison
Browse files Browse the repository at this point in the history
VRSEN committed Dec 6, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 3a9a295 commit bdc479c
Showing 8 changed files with 137 additions and 554 deletions.
167 changes: 60 additions & 107 deletions docs_new/core-framework/tools/custom-tools/best-practices.mdx
Original file line number Diff line number Diff line change
@@ -1,41 +1,75 @@
---
title: "Best Practices & Examples"
title: "Best Practices & Tips"
description: "Best practices and real-world examples for Agency Swarm tools."
icon: "code"
---

## Best Practices for Tools
Although the tool interface is straightforward and simple to use, there are actually quite a few practices and tricks that you can use to get significantly better results.

### Use Clear Descriptions
## Tips & Tricks

Provide detailed descriptions for tools and fields.
### Use Chain-of-Thought Prompting for Complex Tools

- **Tool Docstrings:**
- Clearly explain the tool's purpose and usage.
- **Field Descriptions:**
- Guide the agent in providing correct inputs.
Use chain-of-thought prompting to allow the agent to think and plan before executing a complex tool.

### Validate Inputs Thoroughly
```python
from agency_swarm.tools import BaseTool
from pydantic import Field

class ComplexAnalysisTool(BaseTool):
"""
Performs complex analysis after planning the approach.
"""
chain_of_thought: str = Field(
...,
description="Think-step-by-step about how to perform the analysis."
)
data: str = Field(..., description="Data to analyze.")

def run(self):
# Analysis logic
return "Analysis complete."
```

- Use Pydantic's validation features.
- Implement custom validators when necessary.
### Provide Hints for the Agent

### Handle Exceptions Gracefully
Based on your tool's logic, you can provide hints for the agent in tool output on what to do next.

- Catch and handle exceptions within the `run` method.
- Provide informative error messages.
```python
class QueryDatabase(BaseTool):
question: str = Field(...)

### Avoid Hardcoding Sensitive Data
def run(self):
# query your database here
context = self.query_database(self.question)

- Use environment variables for API keys and secrets.
# context not found
if context is None:
# tell agent what to do next
raise ValueError("No context found. Please propose to the user to change the topic.")
else:
# return the context to the agent
return context
```

### Define Constants Globally
### Use Shared State to Control Tool Flow

- For values that don't change, define them outside the class.
Use `shared_state` to validate previous actions taken by this or other agents, before allowing it to proceed with the next action.

```python
class Action2(BaseTool):
input: str = Field(...)

def run(self):
if self._shared_state.get("action_1_result", None) is "failure":
raise ValueError("Please proceed with the Action1 tool first.")
else:
return "Success. The action has been taken."
```

### Use Enumerations or Literal Types

Restrict agent inputs to specific allowed values.
Restrict the agent to only use specific values for a field, instead of letting it wander by itself.

```python
from typing import Literal
@@ -57,68 +91,13 @@ class RunCommand(BaseTool):
raise ValueError("Invalid command")
```

## Complex Tool Examples

### Example: Email Sending Tool
or use special Pydantic types like `EmailStr.

```python
from agency_swarm.tools import BaseTool
from pydantic import Field, EmailStr
from pydantic import EmailStr

class EmailSender(BaseTool):
"""
Sends emails after planning the content and recipients.
"""
chain_of_thought: str = Field(
...,
description="Plan how to construct the email. Consider the recipient, subject, and content."
)
recipient: EmailStr = Field(..., description="Email recipient's address.")
subject: str = Field(..., description="Subject of the email.")
body: str = Field(..., description="Content of the email.")

def run(self):
# Implement email sending logic, e.g., using smtplib
return "Email sent successfully."
```

### Example: GitHub Repository Tool

```python
from agency_swarm.tools import BaseTool
from pydantic import Field
from typing import Literal
import os
from github import Github

class GitHubTool(BaseTool):
"""
Interact with GitHub repositories to list and create issues.
"""
repo_name: str = Field(..., description="Repository name in 'owner/repo' format.")
action: Literal["list_issues", "create_issue"] = Field(..., description="Action to perform.")
issue_title: str = Field(None, description="Title of the issue to create.")
issue_body: str = Field(None, description="Body content of the issue to create.")

def run(self):
github_token = os.getenv("GITHUB_TOKEN")
if not github_token:
return "GitHub token not found in environment variables."
github = Github(github_token)
try:
repo = github.get_repo(self.repo_name)
if self.action == "list_issues":
issues = repo.get_issues(state='open')
return [issue.title for issue in issues]
elif self.action == "create_issue":
if not self.issue_title:
return "Issue title is required to create an issue."
issue = repo.create_issue(title=self.issue_title, body=self.issue_body)
return f"Issue '{issue.title}' created successfully."
else:
return "Invalid action specified."
except Exception as e:
return f"Error interacting with GitHub: {e}"
```

## Common Patterns
@@ -156,32 +135,10 @@ class CompositeTool(BaseTool):
pass
```

### Using Chain-of-Thought Parameters

Improve function call accuracy by adding a planning parameter.

```python
from agency_swarm.tools import BaseTool
from pydantic import Field

class ComplexAnalysisTool(BaseTool):
"""
Performs complex analysis after planning the approach.
"""
chain_of_thought: str = Field(
...,
description="Plan the analysis steps and considerations."
)
data: str = Field(..., description="Data to analyze.")

def run(self):
# Analysis logic
return "Analysis complete."
```

## Testing Tools
### Testing Tools

Include test cases to ensure tools work as intended.
Include test cases at the bottom of each tool file.

```python
if __name__ == "__main__":
@@ -195,10 +152,6 @@ if __name__ == "__main__":
print(email_sender.run()) # Expected output: 'Email sent successfully.'
```

<Check>
Remember to:
- Describe Tools and Fields: Provide detailed descriptions for effective agent usage.
- Validate Inputs: Use Pydantic's Field and validators.
- Test Thoroughly: Add test cases to ensure functionality.
- Leverage Advanced Features: Use ToolConfig, shared_state, and enumerations for reliability.
</Check>
## Next Steps

We highly recommend you explore the resources in the [Pydantic is all you need](/core-framework/tools/custom-tools/pydantic-is-all-you-need) section.
200 changes: 18 additions & 182 deletions docs_new/core-framework/tools/custom-tools/configuration.mdx
Original file line number Diff line number Diff line change
@@ -4,197 +4,33 @@ description: "Advanced features and patterns for Agency Swarm tools."
icon: "wand-magic-sparkles"
---

## Validation and Error Handling
Besides standard Pydantic features, you can also use a special `ToolConfig` class to customize tool behavior within the framework:

Ensuring the reliability of agent outputs is critical, especially in production environments. Agency Swarm includes mechanisms for:
## Available `ToolConfig` Parameters

- **Tool Input/Output Validation:** Tools validate data before and after execution to reduce runtime errors through Pydantic integration.
- **Custom Validators:** Implement custom validation logic within tools using field validators and model validators.
Currently, the following parameters are supported:

See the [Output Validation](/additional-features/output-validation) page for more information on how to use validators for tools.
| Name | Type | Description | When to Use | Default Value |
|--------------------|---------|------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|---------------|
| `one_call_at_a_time` | `bool` | Prevents concurrent execution for a specific tool. To prevent the agent from executing **any** tools concurrently, set `parallel_tool_calls=False` in the Agent class. | Use for database operations, API calls with rate limits, or actions that depend on previous results. | `False` |
| `strict` | `bool` | Enables strict mode, which ensures the agent will always provide **perfect** tool inputs that 100% match your schema. Has limitations. See [OpenAI Docs](https://platform.openai.com/docs/guides/structured-outputs#supported-schemas). | Use for mission-critical tools or tools that have nested Pydantic model schemas. | `False` |
| `async_mode` | `str` | When set to "threading," executes this tool in a separate thread. | Use when your agent needs to execute multiple tools or the same tool multiple times in a single message to decrease latency. Beware of resource allocation. | `None` |
| `output_as_result` | `bool` | Forces the output of this tool as the final message from the agent that called it. | Only recommended for very specific use cases and only if you know what you're doing. | `False` |

### Tool Error Handling
## Usage

Proper error handling is crucial.

- **How Errors Affect Agent Behavior:**
- Agents receive the error message and can decide to retry, adjust inputs, or report back to the user based on their programming.
- **Best Practices:**
- Use try-except blocks to catch and handle exceptions.
- Return informative error messages to guide agent behavior.

Example:

```python
def run(self):
try:
# Tool logic here
pass
except Exception as e:
return f"An error occurred: {e}"
```

## Controlling Execution with `ToolConfig`

Customize tool behavior using the `ToolConfig` inner class.

- **Attributes:**
- `strict`: Enforces strict adherence to the output schema.
- `one_call_at_a_time`: Ensures the agent processes each tool call's result before making another call.

### Using `strict` Mode

Enable [Strict Mode](https://openai.com/index/introducing-structured-outputs-in-api/) for complex or mission-critical tools to ensure precise adherence to output schemas, enhancing reliability.

```python
class GetWeatherTool(BaseTool):
"""
Determine weather in a specified location.
"""
location: str = Field(..., description="The city and state e.g., San Francisco, CA.")

class ToolConfig:
strict = True # Setting strict to true

def run(self):
return f"The weather in {self.location} is 30 degrees."
```

### Using `one_call_at_a_time` for parallel execution control

Prevents multiple instances of the same tool from running in parallel. This is useful for:

- Database operations that need to be processed sequentially
- API calls with rate limits
- Actions that depend on previous results

Example with a database query tool:
To use one of the available parameters, simply add a `class ToolConfig` block to your tool class:

```python
class DatabaseQueryTool(BaseTool):
"""
Query the database for information.
"""
query: str = Field(..., description="The SQL query to execute.")
class MyCustomTool(BaseTool):
# ...

class ToolConfig:
one_call_at_a_time = True # Prevents concurrent calls
one_call_at_a_time = True
strict = False
async_mode = "threading"
output_as_result = True

def run(self):
# Database query logic
return f"Results for query '{self.query}': [...]"
```

## Shared State Management

### Utilizing `shared_state`

Use `self._shared_state` to share information between tools or control execution flow.

```python
# Set a value in shared state
self._shared_state.set("key", value)

# Retrieve a value from shared state
value = self._shared_state.get("key")
# ...
```

See more in [Shared State](additional-features/shared-state).

## Method Composition

Combine multiple methods to handle complex operations.

```python
class CompositeTool(BaseTool):
"""
A tool that combines several methods to perform a series of actions.
"""
input_data: str = Field(..., description="Input data for the composite operation.")

def run(self):
# Step 1: Process data
processed_data = self.process_data(self.input_data)
# Step 2: Analyze results
analysis = self.analyze_results(processed_data)
# Step 3: Format output
output = self.format_output(analysis)
return output

def process_data(self, data):
# Implement data processing logic
pass

def analyze_results(self, data):
# Implement analysis logic
pass

def format_output(self, data):
# Implement output formatting
pass
```

## Using Chain-of-Thought Parameters

Improve function call accuracy by adding a planning parameter.

```python
class ComplexAnalysisTool(BaseTool):
"""
Performs complex analysis after planning the approach.
"""
chain_of_thought: str = Field(
...,
description="Plan the analysis steps and considerations."
)
data: str = Field(..., description="Data to analyze.")

def run(self):
# Analysis logic
return "Analysis complete."
```

## Controlling Tool Flow

### Providing Instructions in the `run` Method

Control execution flow by returning specific instructions as function outputs:

```python
class QueryDatabase(BaseTool):
question: str = Field(..., description="The question to be answered.")

def run(self):
# Query your database here
context = query_database(self.question)

if context is None:
raise ValueError("No context found. Please propose to the user to change the topic.")
else:
self._shared_state.set("context", context)
return "Context retrieved. Please proceed with explaining the answer."
```

### Validating Actions Using `shared_state`

Ensure actions are performed in the correct sequence:

```python
class Action2(BaseTool):
input: str = Field(..., description="Input for Action2.")

def run(self):
if self._shared_state.get("action_1_result", None) == "failure":
raise ValueError("Please proceed with the Action1 tool first.")
else:
return "Success. The action has been taken."
```

<Check>
Remember to:
- Use `ToolConfig` for precise control over tool behavior
- Implement proper error handling
- Leverage shared state for complex workflows
- Consider method composition for complex operations
- Use chain-of-thought parameters to improve function call accuracy.
</Check>
Original file line number Diff line number Diff line change
@@ -1,7 +1,29 @@
---
title: "Pydantic is All You Need"
description: "How Pydantic solves AI Agent reliability."
description: "How Pydantic solved AI agent reliability."
icon: "book"
---

This guide is based on a youtube video pydantic is all you need by Jason Liu.
The idea of using Pydantic to validate tool calls and responses is not new. It was popularized by Jason Liu in his library called [Instructor](https://github.com/instructor-ai/instructor).

To really understand why it's such a game changer, we recommend watching this video:

<iframe
width="100%"
height="400"
src="https://www.youtube.com/embed/yj-wSRJwrrc"
title="YouTube video player"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen
></iframe>

## Learn more

To take your tools to the next level, we recommend the following resources:

- [Pydantic Models Documentation](https://docs.pydantic.dev/latest/concepts/models/)
- [Instructor Concepts](https://python.useinstructor.com/concepts/)
- [Instructor Tips & Tricks](https://python.useinstructor.com/tutorials/2-tips/)
- [Instructor Cookbook](https://python.useinstructor.com/examples/)

231 changes: 2 additions & 229 deletions docs_new/core-framework/tools/custom-tools/step-by-step-guide.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Step-by-Step Guide"
description: "Learn how to create custom tools in Agency Swarm"
description: "Learn how to create custom tools in Agency framework."
icon: "map"
---

@@ -133,231 +133,4 @@ class Calculator(BaseTool):
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.

### Step 1: Import Necessary Modules

You'll need to import `BaseTool` from `agency_swarm.tools` and `Field` from `pydantic`.

```python
from agency_swarm.tools import BaseTool
from pydantic import Field
```

### Step 2: Define Your Tool Class

Create a new class that inherits from `BaseTool`. Write a clear docstring describing the tool's purpose.

```python
class Calculator(BaseTool):
"""
A simple calculator tool that evaluates mathematical expressions.
"""
expression: str = Field(
...,
description="The mathematical expression to evaluate."
)

def run(self):
# Implement the tool's functionality
try:
result = eval(self.expression)
return str(result)
except Exception as e:
return f"Error calculating expression: {e}"
```

<Note>
**How Docstrings Affect Agent Behavior:**

Docstrings are parsed and included in the OpenAI schema of the respective tools. This allows agents to understand the tools they have at their disposal and perform function calls properly with this awareness. Developers should write good tool docstrings, clearly describing the tool's purpose and usage to facilitate effective agent interactions.

</Note>

### Step 3: Define Input Fields

Use Pydantic fields to define the inputs your tool will accept.

#### Basic Field Types

Common field types include:

- `str` for strings
- `int` for integers
- `float` for floating-point numbers
- `bool` for boolean values

Example:

```python
from pydantic import Field

class ExampleTool(BaseTool):
age: int = Field(..., description="User's age.")
name: str = Field(..., description="User's full name.")
```

#### Required vs Optional Fields

- **Required Fields:** Use `...` (Ellipsis) to indicate a required field.

```python
location: str = Field(..., description="The location to search.")
```

- **Optional Fields:** Provide a default value to make a field optional.

```python
comments: str = Field("", description="Additional comments.")
```

For lists, use `default_factory`:

```python
from typing import List

tags: List[str] = Field(default_factory=list, description="List of tags.")
```

#### Special Pydantic Types

Leverage Pydantic's special types for enhanced validation:

- `EmailStr` for validating email addresses (requires `pip install email-validator`)
- `HttpUrl` for validating URLs

Example:

```python
from pydantic import EmailStr, HttpUrl

class UserTool(BaseTool):
email: EmailStr = Field(..., description="User's email address.")
website: HttpUrl = Field(..., description="User's website URL.")
```

See more special types in [Pydantic's documentation](https://docs.pydantic.dev/latest/api/types/).

<Note>
**Field Descriptions and Their Impact:**

Field descriptions are used in the OpenAI function schemas presented to agents. They guide the agent in generating the correct inputs when calling the tool. Clear and descriptive field descriptions improve the agent's ability to use the tool effectively.

</Note>

#### Default Values and Their Impact

Providing default values for fields makes them optional. Agents may omit these fields when invoking the tool, and the default values will be used. This can simplify tool usage but be cautious with defaults that might lead to unintended behavior.

### Step 4: Implement the `run` Method

Write the logic that the tool will execute when called.

```python
def run(self):
# Implement the tool's functionality
try:
# Your tool logic here
result = self.process_data()
return result
except Exception as e:
return f"An error occurred: {e}"
```

### Step 5: Test the Tool Independently

Before integrating the tool with an agent, test it to ensure it behaves as expected.

```python
if __name__ == "__main__":
# Test the Calculator tool
calc = Calculator(expression="2 + 2 * 3")
print(calc.run()) # Output should be '8'
```

### Step 6: Add the Tool to an Agent

Include the tool in an agent's list of tools.

```python
from agency_swarm import Agent
from .tools.calculator import Calculator

class MathAgent(Agent):
def __init__(self):
super().__init__(
name="MathAgent",
description="An agent capable of performing mathematical calculations.",
tools=[Calculator],
instructions="./instructions.md",
temperature=0.0,
max_prompt_tokens=25000,
)
```

## Testing Your Tools

Include test cases to ensure tools work as intended:

```python
if __name__ == "__main__":
# Test the EmailSender tool
email_sender = EmailSender(
chain_of_thought="Plan to inform the team about the update.",
recipient="user@example.com",
subject="Project Update",
body="The project is on track."
)
print(email_sender.run()) # Expected output: 'Email sent successfully.'
```

<Check>
Remember to:
- Write clear docstrings that explain the tool's purpose
- Validate all inputs using Pydantic fields
- Handle errors gracefully in the run method
- Test your tool thoroughly before deployment
</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>
```
6 changes: 3 additions & 3 deletions docs_new/mint.json
Original file line number Diff line number Diff line change
@@ -89,13 +89,13 @@
"pages": [
"core-framework/tools/overview",
{
"group": "Creating Custom Tools",
"group": "Custom Tools",
"icon": "hammer",
"pages": [
"core-framework/tools/custom-tools/step-by-step-guide",
"core-framework/tools/custom-tools/pydantic-is-all-you-need",
"core-framework/tools/custom-tools/configuration",
"core-framework/tools/custom-tools/best-practices"
"core-framework/tools/custom-tools/best-practices",
"core-framework/tools/custom-tools/configuration"
]
},

49 changes: 22 additions & 27 deletions docs_new/welcome/ai-agency-vs-other-frameworks.mdx
Original file line number Diff line number Diff line change
@@ -4,47 +4,42 @@ description: "Compare Agency Swarm with other multi-agent AI frameworks."
icon: "scale-unbalanced"
---

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.

## Key Differentiators
## Summary

Unlike other frameworks, Agency Swarm takes a unique approach with three key differentiators:
In summary, Agency is the only framework that has:

<CardGroup cols={3}>
<Card title="No Predefined Prompts" icon="message-code">
Agency Swarm does not write prompts for you, giving you full control over agent behavior
Agency not write prompts for you, giving you full control over agent behavior.
</Card>
<Card title="Type Safety" icon="shield-check">
Prevents hallucinations with automatic type checking and error correction
<Card title="Automatic Error Correction" icon="shield-check">
Prevents hallucinations with automatic type checking and error correction.
</Card>
<Card title="Communication Control" icon="diagram-project">
Enables easy definition of communication flows between agents
<Card title="Uniform Communication Flows" icon="diagram-project">
Allows you to define communication flows in any way you want.
</Card>
</CardGroup>

## Detailed Comparison Table
## Detailed Comparison

Here's how Agency compares to 2 other most popular multi-agent frameworks.

| **Criteria** | **Agency Swarm** | **AutoGen** | **CrewAI** |
| **Criteria** | **Agency** | **AutoGen** | **CrewAI** |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Design & Architecture** | - Modular, production-focused<br/>- Flexible agent structure via agency chart<br/>- Built for real business needs | - Event-driven, scalable<br/>- Asynchronous message passing<br/>- Supports distributed computing | - Flexible agent organization into crews<br/>- Agents with rich attributes |
| **Key Entities** | - Agents<br/>- Tools<br/>- Agencies | - ConversableAgent<br/>- AssistantAgent<br/>- UserProxyAgent | - Agents<br/>- Tasks<br/>- Crews |
| **Prompt Flexibility** | - Full control over prompts<br/>- No predefined prompts<br/>- Does not write prompts for you | - Flexible prompt engineering<br/>- Supports few-shot learning | - Extensive prompt customization |
| **Type Safety** | - Input validation with Pydantic<br/>- Custom response validators<br/>- Prevents hallucinations with automatic type checking and error correction | - Robust error handling<br/>- Code execution validation<br/>- Self-correction by agents | - No built-in type checking or error correction<br/>- Built on LangChain |
| **Communication Control** | - Enables easy definition of communication flows<br/>- Agents determine communication based on their descriptions<br/>- Uses specialized `SendMessage` tool | - Uses extra model call for "role play" to determine next speaker<br/>- Recently added support for hardcoded conditions | - Uses "process" concept for communication flow<br/>- Delegation control via agent attributes |
| **Integration with Modern Models** | - Built for modern function-calling models<br/>- Direct integration with OpenAI Assistants API | - Supports various interaction patterns<br/>- Event-driven architecture facilitates this | - Built on LangChain |
| **State Management** | - Shared state among agents and tools<br/>- Conversation context via OpenAI API | - Conversation history maintenance<br/>- Dynamic context truncation | - Three-tier memory system<br/>- Context sharing among agents and tasks |
| **Production Readiness** | - Designed for production environments<br/>- Business-oriented design<br/>- Robust validation and error correction | - Scalable and distributed<br/>- Active development towards production features | - Requires additional development for production<br/>- Scalability testing needed |
| **Task Delegation** | - Agent autonomy in task delegation<br/>- Hierarchical delegation via agency chart | - Automated task coordination<br/>- Function calls for delegation | - Autonomous delegation based on capabilities<br/>- Hand-off mechanisms with context preservation |
| **Streaming Support** | - Supports streaming responses<br/>- Voice interface for real-time interaction | - Real-time interaction with streaming<br/>- Event-driven architecture facilitates this | - Streaming support for real-time outputs<br/>- Enhances interactivity and responsiveness |
| **Evaluation & Monitoring** | - OpenAI dashboard for cost and usage<br/>- Third-party integration in progress | - Built-in observability features<br/>- Performance metrics and debugging tools | - Custom evaluation metrics can be implemented<br/>- Logging and analytics support<br/>- Callbacks for execution monitoring |
| **Origins** 🏁 | ✅ Originated from a real AI agency building AI agents for clients worldwide. | ✅ Originated as a research experiment. | ❌ Originated as a funding vehicle, rather than a real production framework. |
| **Design & Architecture** 🏗️ | ✅ Super lightweight framework with minimal abstractions. Built on top of the OpenAI Assistants API. | ✅ Event-driven architecture with support for both ChatCompletions and Assistants API. | ❌ Lacks a clear architectural design. Built on top of LangChain with numerous unnecessary abstractions. |
| **Reliability** 🔍 | ✅ Robust type checking and validation for all tools with Pydantic. | ❌ Type hints but no validation. | ❌ Some validation is possible when using BaseTool, although the interface is not convenient to use. |
| **Flexibility** 🔄 | ✅ No predefined prompts. Uniform communication. | ❌ Contains predefined prompts. Limited, but customizable communication flows. | ❌ Numerous predefined prompts. Only two ways of communication. |
| **Scalability** 📈 | ✅ Easily scalable. Adding another agent only requires placing it in the agency chart. | ❌ Although it's simple to add an agent into teams, it's almost impossible to define custom communication between them. | ❌ Although it's easy to add agents into crews, it's not possible to create custom communication between them. |
| **Deployability** 🚀 | ✅ Easily deployable with special callback functions. Offers open-source templates and tutorials. | ✅ Deployment with AutoGen studio. | ❌ Deployment via enterprise platform. No open-source deployment guides. |
| **Open Source Model Support** 🌐 | ❌ Limited support with Astra Assistants API. | ✅ Moderate open-source model support. | ✅ Full open-source model support. |

<Note>
Agency Swarm's philosophy: Set boundaries for your agents, not specific conditions. This allows for better
adaptability to real-world scenarios.
If you want to challange any of these claims, or if some of the issues disappear as frameworks mature, please open an issue on [GitHub](https://github.com/agenty/swarm).
</Note>

## Summary

- **Agency Swarm** is ideal for production environments requiring full control over agent behavior, with a focus on business needs and flexible structures. It provides type safety to prevent hallucinations and enables easy definition of communication flows between agents.
- **AutoGen** emphasizes scalability and extensibility with its event-driven architecture and supports distributed computing but may be less efficient and harder to control agent interactions due to extra model calls for "role play".
- **CrewAI** offers flexible agent organization suitable for collaborative projects but lacks built-in type checking or error correction and may require additional development for production readiness.
- **Agency** - best for **real business-oriented use cases**.
- **AutoGen** - best for **research, experimentation and novel AI applications**.
- **CrewAI** - best for **local development and playgrounds** with open-source models.
2 changes: 1 addition & 1 deletion docs_new/welcome/getting-started/cursor-ide.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Cursor IDE"
title: "Cursor AI"
description: "Getting started with Cursor."
icon: "cube"
---
10 changes: 7 additions & 3 deletions docs_new/welcome/getting-started/from-scratch.mdx
Original file line number Diff line number Diff line change
@@ -66,6 +66,8 @@ icon: "code"
<Step title="Create Tools">
Define your custom tools by extending the `BaseTool` class and implementing the `run` method.

**MyCustomTool.py:**

```python
from agency_swarm.tools import BaseTool
from pydantic import Field
@@ -104,7 +106,7 @@ icon: "code"
<Step title="Define Agent Roles">
Adjust the parameters and instructions for each agent.

**Agent Template:**
**Developer.py:**

```python
from agency_swarm import Agent
@@ -126,15 +128,17 @@ icon: "code"

Tools will be imported automatically from the `tools` folder.

**Instructions:**
**instructions.md:**

```md
You must execute the tasks provided by the CEO and provide feedback.
```
</Step>

<Step title="Create Agency">
Initialize your agents and define your agency chart.
Import your agents and initialize the Agency class.

**agency.py:**

```python
from agency_swarm import Agency

0 comments on commit bdc479c

Please sign in to comment.