CrewAI Tutorial (Python): adding tool use for intermediate developers

This tutorial shows you how to add tools to a CrewAI agent in Python so it can do real work beyond plain text generation. You need this when your agent has to fetch live data, query an API, read files, or call internal services instead of guessing from its prompt.

What You'll Need

• •Python 3.10+
• •crewai
• •crewai-tools
• •An OpenAI API key set as OPENAI_API_KEY
• •Basic CrewAI setup knowledge: agents, tasks, and crews
• •A local project folder with a virtual environment

Install the packages first:

pip install crewai crewai-tools

Step-by-Step

1. •Start by defining a tool the agent can call. CrewAI tools are just Python functions wrapped with @tool, which makes them callable by the agent at runtime.

from crewai.tools import tool

@tool("get_customer_status")
def get_customer_status(customer_id: str) -> str:
    """Return a mock customer status for a given customer ID."""
    lookup = {
        "CUST-1001": "active",
        "CUST-1002": "delinquent",
        "CUST-1003": "pending_review",
    }
    return lookup.get(customer_id, "unknown")

2. •Create an agent and attach the tool to it. The important part is the tools=[...] argument; without that, the model cannot call your function even if it knows about it in the prompt.

from crewai import Agent
from crewai.llm import LLM

llm = LLM(model="gpt-4o-mini")

support_agent = Agent(
    role="Customer Support Analyst",
    goal="Check customer status and respond with the correct next action.",
    backstory="You work on an insurance support desk and must use tools when available.",
    llm=llm,
    tools=[get_customer_status],
    verbose=True,
)

3. •Define a task that forces tool usage through the instructions. Keep the task specific so the agent has a reason to call the tool instead of inventing an answer.

from crewai import Task

status_task = Task(
    description=(
        "Given customer ID CUST-1002, check their account status using the tool "
        "and explain whether they should be escalated."
    ),
    expected_output="A short support response with the status and next action.",
    agent=support_agent,
)

4. •Put the task into a crew and run it. This is where CrewAI orchestrates the agent and lets it decide when to invoke the tool.

from crewai import Crew, Process

crew = Crew(
    agents=[support_agent],
    tasks=[status_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result)

5. •If you want more realistic behavior, add a second tool and let the same agent choose between them. This is useful for production workflows where one agent needs multiple capabilities like database lookup plus policy retrieval.

from crewai.tools import tool

@tool("get_policy_summary")
def get_policy_summary(policy_id: str) -> str:
    """Return a mock policy summary."""
    policies = {
        "POL-2001": "Auto policy, active, renewal due in 30 days",
        "POL-2002": "Home policy, active, claim filed last week",
    }
    return policies.get(policy_id, "policy not found")

support_agent.tools.append(get_policy_summary)

Testing It

Run the script and watch the verbose output. You should see CrewAI planning a step, calling get_customer_status, then using that result in its final response.

A good test is to change CUST-1002 to CUST-9999 in the task description. The agent should return unknown instead of fabricating a status.

If you added the second tool, create a second task that mentions POL-2001. That confirms the agent can select different tools based on the request.

For production-style testing, assert on both behavior and failure modes: valid IDs return known values, unknown IDs return safe defaults, and no raw exceptions leak into user-facing output.

Next Steps

• •Add external API tools using requests or your internal SDK
• •Learn how to pass structured inputs with Pydantic models for stricter tool contracts
• •Combine multiple agents so one retrieves data and another drafts 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.