Install & Compatibility
Where this runs
tested against v1.15.18 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 51.6s
py 3.11
✕ build_error
✓ 42.3s
py 3.12
✕ build_error
✓ 37.2s
py 3.13
✕ build_error
✓ 36.5s
py 3.9
✕ build_error
✕ build_error
930MB installed
● package 930MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FileReadTool
✓ from crewai_tools import FileReadTool
SerperDevTool
✓ from crewai_tools import SerperDevTool
ScrapeWebsiteTool
✓ from crewai_tools import ScrapeWebsiteTool
This quickstart demonstrates how to initialize and use two common `crewai-tools`: `FileReadTool` and `SerperDevTool`. It shows how to assign these tools to `crewai` agents, define tasks for the agents, and then run a simple sequential crew to perform research and content creation. Note that `SERPER_API_KEY` must be set for `SerperDevTool` to function, and `crewai` must also be installed.
import os
from crewai import Agent, Task, Crew, Process
from crewai_tools import FileReadTool, SerperDevTool
# Set your Serper API key as an environment variable or pass directly
# os.environ["SERPER_API_KEY"] = "YOUR_SERPER_API_KEY"
# Initialize tools
read_tool = FileReadTool(file_path='./my_document.txt')
search_tool = SerperDevTool()
# Define Agents
researcher = Agent(
role='Senior Researcher',
goal='Uncover the latest trends in AI and provide a summary',
backstory='An expert in AI research, known for insightful analysis.',
verbose=True,
allow_delegation=False,
tools=[search_tool] # Agent has access to the search tool
)
writer = Agent(
role='Content Writer',
goal='Craft engaging content based on research findings',
backstory='A talented writer who transforms complex data into compelling narratives.',
verbose=True,
allow_delegation=False,
tools=[read_tool] # Agent has access to the file read tool
)
# Define Tasks
research_task = Task(
description='Conduct a comprehensive search on current AI trends and identify key developments.',
expected_output='A bullet-point summary of 3-5 major AI trends.',
agent=researcher
)
write_task = Task(
description='Write a short blog post (approx. 300 words) based on the AI trends summary provided.',
expected_output='A well-structured and engaging blog post.',
agent=writer
)
# Assemble a Crew
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, write_task],
process=Process.sequential,
verbose=2
)
# Ensure 'my_document.txt' exists for the FileReadTool example
with open('./my_document.txt', 'w') as f:
f.write('Initial context about AI: AI is rapidly advancing, with new models and applications emerging constantly.')
# Kick off the crew's work
print("Crew starting to work...")
result = crew.kickoff()
print("\n\nCrew finished with results:")
print(result)
Debug
Known issues
breakingChanges within the core CrewAI framework (e.g., in output types for tasks/crews, event system refactors) can indirectly affect how tools are integrated and how their outputs are processed. Always review CrewAI's changelog when upgrading `crewai-tools`.fixConsult the official CrewAI documentation and release notes for migration guides. Adapt agent and task definitions to align with new CrewAI API expectations, especially regarding `TaskOutput` and `CrewOutput` types.
affects: All versions, due to tight coupling with crewai updates.
gotchaMany powerful tools (e.g., `SerperDevTool`, `GithubSearchTool`, various RAG tools) require API keys or specific credentials to be set as environment variables (e.g., `SERPER_API_KEY`, `GITHUB_PAT`) or passed directly. Failure to configure these will lead to runtime errors.fixRefer to the specific tool's documentation for required environment variables or initialization parameters. Ensure all necessary API keys are securely configured before execution.
affects: All versions using API-dependent tools.
deprecatedCVEs (Common Vulnerabilities and Exposures) in underlying dependencies (e.g., `cryptography`, `transformers`, `litellm`) are frequently patched in `crewai-tools` releases. Running outdated versions may expose your application to known security risks.fixRegularly update `crewai-tools` to the latest stable version. Monitor release notes for security fixes and dependency updates to ensure your environment is protected.
affects: <1.14.2a1 (for cryptography), <1.14.1 (for transformers), <1.14.0a4 (for litellm), and potentially others.
gotchaWhen creating custom tools, if your tool involves asynchronous operations (e.g., network requests), you must implement the `_arun` method instead of the synchronous `_run` method. Using `_run` with `async` logic will lead to blocking behavior or errors.fixFor asynchronous custom tools, subclass `BaseTool` and implement `async def _arun(self, *args, **kwargs): ...`. Ensure `crewai` agents and tasks are configured for asynchronous execution if applicable.
affects: All versions when implementing custom asynchronous tools.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'crewai_tools'
The 'crewai-tools' package is not installed or not accessible in the current Python environment.
fixEnsure the 'crewai-tools' package is installed. If using CrewAI's project structure, it's often installed via `pip install 'crewai[tools]'` or `uv add crewai'[tools]'` if using UV.
ImportError: cannot import name 'Tool' from 'crewai.tools'
The `Tool` class is intended to be imported from `crewai_tools` for pre-built tools, or custom tools should use `BaseTool` or the `@tool` decorator from `crewai.tools` or `crewai_tools` depending on the exact implementation. This specific error often happens when trying to import `Tool` directly from `crewai.tools` which is not where the generic `Tool` class resides for common usage.
fixFor pre-built tools, import them directly (e.g., `from crewai_tools import SerperDevTool`). For custom tools, use `from crewai.tools import BaseTool, tool` and either inherit from `BaseTool` or decorate a function with `@tool` from `crewai.tools`.
ValueError: Invalid tool type: <class 'function'>. Tool must be an instance of BaseTool or an object with 'name', 'func', and 'description' attributes.
You are attempting to pass a raw Python function directly as a tool to an Agent without properly wrapping it as a CrewAI tool. CrewAI expects tools to be instances of `BaseTool` or functions decorated with `@tool` that adhere to a specific structure.
fixWrap your function using the `@tool` decorator from `crewai.tools` or define it as a class inheriting from `BaseTool`.
AttributeError: 'StructuredTool' object has no attribute 'model_fields'
This error typically arises from an incompatibility between the versions of `crewai`, `crewai-tools`, and underlying libraries like Pydantic. It indicates a change in how tool schemas or validation are handled internally.
fixEnsure that `crewai` and `crewai-tools` (and potentially Pydantic) are compatible versions. Often, upgrading both `crewai` and `crewai-tools` to their latest versions, or downgrading to known stable combinations, can resolve this. For example, `pip install -U crewai crewai-tools`.
1 validation error for SerperDevToolSchema search_query. Input should be a valid string [type=string_type, input_value={'description': '...', 'type': 'str'}, input_type=dict]
This validation error indicates that the Large Language Model (LLM) is not providing the `SerperDevTool` (or similar tools) with the expected input format for the `search_query` argument. Instead of a simple string, it's passing a dictionary, which the tool cannot process.
fixThis often points to the LLM's inability to correctly format the tool input. Experiment with a more capable LLM or refine the agent's instructions (goal, backstory, task description) to guide it toward providing a plain string for the search query. Ensure `SERPER_API_KEY` is correctly set in environment variables.
Upgrade
Version history
1.15.18latest on PyPI · released Aug 27, 2026
Audit
Dependencies
crewairequiredCore framework that utilizes these tools. 'crewai-tools' is an extension to 'crewai'.
beautifulsoup4optionalUsed by various web scraping and parsing tools.
requestsoptionalCommon dependency for tools making HTTP requests.
tiktokenoptionalUsed for token counting, relevant for LLM interactions.