CrewAI Tutorial (Python): testing agents locally for beginners

This tutorial shows you how to run a CrewAI agent locally, inspect its output, and test it like normal Python code. You need this when you want deterministic checks before wiring the agent into a larger app, CI pipeline, or production workflow.

What You'll Need

• •Python 3.10 or newer
• •A virtual environment tool: venv, uv, or conda
• •crewai
• •python-dotenv
• •An OpenAI API key set as an environment variable
• •Basic familiarity with Python files, imports, and running scripts

Step-by-Step

1. •Create a clean project and install dependencies.
   Keep this isolated so your tests are reproducible and you can pin versions later.

mkdir crewai-local-testing
cd crewai-local-testing
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install crewai python-dotenv pytest

2. •Add your API key in a .env file.
   CrewAI reads model credentials from environment variables, so this keeps secrets out of your code.

cat > .env << 'EOF'
OPENAI_API_KEY=your_openai_api_key_here
EOF

3. •Define one agent and one task in Python.
   This is the smallest useful unit to test locally: a single agent with a narrow instruction set and a clear expected output.

from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process

load_dotenv()

researcher = Agent(
    role="Research Assistant",
    goal="Summarize the benefits of local testing for AI agents",
    backstory="You are careful, concise, and write for developers.",
    verbose=True,
)

task = Task(
    description=(
        "Write 5 bullet points explaining why developers should test "
        "CrewAI agents locally before using them in production."
    ),
    expected_output="A short bullet list with practical reasons.",
    agent=researcher,
)

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

4. •Run the crew from a script entry point.
   Save the file as app.py, then execute it directly so you can see the raw agent output in your terminal.

if __name__ == "__main__":
    result = crew.kickoff()
    print("\n--- FINAL OUTPUT ---\n")
    print(result)

5. •Add a basic local test with pytest.
   For beginners, the first test should verify that the crew returns something non-empty and that the output contains one of your expected ideas.

from app import crew

def test_crew_returns_output():
    result = crew.kickoff()
    text = str(result).strip()

    assert text != ""
    assert "testing" in text.lower() or "production" in text.lower()

6. •Run the script and then run the test suite.
   This gives you two layers of confidence: manual inspection for behavior and automated checking for regressions.

python app.py
pytest -q

Testing It

When the script runs correctly, you should see verbose agent logs followed by a final answer printed to the terminal. If the API key is missing or invalid, CrewAI will fail early, which is useful because your setup problem is exposed immediately.

Your pytest check should pass without needing any mocks for this simple case. If you want stricter tests later, assert on structure instead of exact wording, because LLM output changes across runs.

A good local test verifies three things:

• •The crew executes without exceptions.
• •The response is non-empty.
• •The response includes domain-relevant content you expect from the task prompt.

Next Steps

• •Add more agents and switch from Process.sequential to multi-agent workflows.
• •Replace direct .kickoff() calls with mocks so your tests do not hit external APIs every run.
• •Learn how to validate structured outputs with Pydantic models instead of free-form text.

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.