CrewAI Tutorial (Python): adding tool use for beginners

This tutorial shows you how to give a CrewAI agent access to a real Python tool, then wire that tool into a task so the agent can call it when needed. You need this when the LLM should fetch data, inspect local systems, or perform deterministic actions instead of guessing.

What You'll Need

• •Python 3.10+
• •crewai
• •crewai-tools
• •An OpenAI API key set as OPENAI_API_KEY
• •Basic familiarity with Agent, Task, and Crew
• •A terminal and a project folder

Install the packages first:

pip install crewai crewai-tools

Set your API key:

export OPENAI_API_KEY="your-key-here"

Step-by-Step

1. •Start with a minimal CrewAI setup.
   We’ll create one agent and one task, then add a tool in the next step.

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Research Assistant",
    goal="Answer questions using tools when needed",
    backstory="You are careful and prefer using tools over guessing.",
    verbose=True,
)

task = Task(
    description="Find the current date and explain why it matters for planning.",
    expected_output="A short explanation with the current date.",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.sequential,
)

2. •Create a simple custom tool.
   CrewAI tools are just Python callables wrapped with @tool. Keep them deterministic and focused on one job.

from datetime import datetime
from crewai_tools import tool

@tool("get_current_date")
def get_current_date() -> str:
    """Return today's date in ISO format."""
    return datetime.utcnow().date().isoformat()

3. •Attach the tool to the agent.
   This is the key step: without listing the tool in tools=[...], the agent cannot call it.

from crewai import Agent

researcher = Agent(
    role="Research Assistant",
    goal="Answer questions using tools when needed",
    backstory="You are careful and prefer using tools over guessing.",
    verbose=True,
    tools=[get_current_date],
)

4. •Run the crew with a task that requires the tool.
   The prompt should clearly tell the agent to use the tool, otherwise it may answer from memory.

from crewai import Task, Crew, Process

task = Task(
    description=(
        "Use the get_current_date tool to find today's date, "
        "then explain how knowing the date affects planning."
    ),
    expected_output="A concise answer that includes today's date.",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.sequential,
)

result = crew.kickoff()
print(result)

5. •Add a more practical tool example for real work.
   In production, tools usually read files, query internal APIs, or fetch records from databases. Here’s a local file reader you can extend later.

from pathlib import Path
from crewai_tools import tool

@tool("read_text_file")
def read_text_file(file_path: str) -> str:
    """Read and return text from a local file."""
    path = Path(file_path)
    if not path.exists():
        return f"File not found: {file_path}"
    return path.read_text(encoding="utf-8")

Then attach both tools:

researcher.tools = [get_current_date, read_text_file]

Testing It

Run the script from your terminal and watch the verbose output. If tool use is working, you should see the agent decide to call get_current_date before answering.

For the file tool, create a small text file like notes.txt and ask the agent to summarize it using read_text_file. If it returns "File not found", check your working directory and file path.

If the model answers without calling a tool, tighten the task description so it explicitly requires tool usage. In production, I also recommend logging tool inputs and outputs so you can debug bad calls quickly.

Next Steps

• •Learn how to build custom tools around internal APIs and databases.
• •Add error handling and timeouts to tools that touch external systems.
• •Explore multi-agent setups where one agent gathers data with tools and another writes the final response.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.