Building Your First AI Agent: Step-by-Step Tutorial

Building Your First AI Agent: Step-by-Step Tutorial

You've read about agentic AI. You're convinced it's real. Now you want to build one.

This is the guide I wish existed when I started building agents at Oneskai. It walks through building a real, production-relevant AI agent from your laptop to a working deployment—with all the mistakes I made so you don't have to.

By the end of this tutorial, you'll have built a working agent that can handle multiple types of customer inquiries, reason about outcomes, and escalate intelligently. You'll understand the architecture. You'll know what to test before production. And you'll have a template to extend for your own use cases.

This tutorial focuses on CrewAI because it's the most "business-friendly" framework. If you prefer LangChain or AutoGen, the concepts transfer—only the syntax changes.

Prerequisites (What You Need to Know)

• Basic Python experience (you can write a simple script)
• Understanding of APIs and HTTP requests
• Access to an LLM API key (Claude, GPT-4, or Gemini—I recommend Claude for reliability)
• Environment where you can run Python scripts locally
• Understanding of what agentic AI is (if not: read the complete guide first)

Part 1: Environment Setup (15 minutes)

Step 1: Install Python & Dependencies

Assuming you have Python 3.10+:

Create a new project directory and virtual environment:

• mkdir my-first-agent
• cd my-first-agent
• python3 -m venv venv
• source venv/bin/activate (or venv\Scripts\activate on Windows)

Install CrewAI and dependencies:

• pip install crewai
• pip install python-dotenv
• pip install requests (for API calls)

Step 2: Get Your LLM API Key

You need access to a language model. The easiest option is Claude (Anthropic):

• 1. Go to console.anthropic.com and create an account
• 2. Navigate to API Keys and create a new key
• 3. Save it as ANTHROPIC_API_KEY in a .env file:

ANTHROPIC_API_KEY=sk-ant-... your key here ...

Other options: OpenAI API key (gpt-4-turbo) or Google Gemini API key. CrewAI supports all of them.

Step 3: Create Your First Agent Script

Create a file named agent.py with this basic structure:

• import os
• from crewai import Agent, Task, Crew
• from crewai_tools import tool
• from dotenv import load_dotenv
• load_dotenv()

You now have a basic Python script that can import CrewAI. Before we add agent logic, we need to talk about tools.

Part 2: Define Tools (What Your Agent Can Do)

An agent is only as useful as the tools you give it. Tools are functions that your agent can call to interact with external systems.

Common Tools for a Support Agent:

• User database lookup (find customer info)
• Ticket system API (create support tickets)
• Knowledge base search (find answers)
• Billing system API (check subscription status)
• Email system API (send confirmation emails)

Creating Tool Functions

In CrewAI, tools are just Python functions decorated with @tool. Here's a simple example:

• @tool
• def search_knowledge_base(query: str) -> str:
• """Search our knowledge base for answers to customer questions."""
• # This would call your actual knowledge base API
• # For now, returning mock data
• kb_results = {
• "password reset": "Go to login page, click 'Forgot Password'",
• "billing issue": "Check billing portal or contact support@company.com",
• }
• return kb_results.get(query.lower(), "No results found")

Part 3: Define Your Agent (30 minutes)

An Agent is a Role with Specific Instructions

In CrewAI, you define agents with:

• role: What is this agent's job?
• goal: What are they trying to achieve?
• backstory: Context that influences how they behave
• tools: What functions can they call?
• llm: Which language model to use

Here's a real support agent definition:

• support_agent = Agent(
• role="Customer Support Specialist",
• goal="Resolve customer support issues efficiently without escalation",
• backstory="""You are an expert customer support specialist with 5 years
• of experience resolving technical and billing issues. You are authorized to:
• - Reset passwords
• - Process refunds up to $100
• - Offer store credit
• - Create escalations for complex issues
• You prioritize customer satisfaction and follow company policy.""",
• tools=[search_knowledge_base, lookup_customer, process_refund],
• verbose=True, # Show the agent's reasoning
• )

Part 4: Define Tasks (What You Want Done)

A Task is a specific job your agent needs to complete. A task has:

• description: What exactly needs to be done?
• expected_output: What should the result look like?
• agent: Which agent is responsible?

Example task for a support issue:

• customer_inquiry_task = Task(
• description="""Analyze the customer support inquiry and take appropriate action:
• 1. Search knowledge base for potential answers
• 2. Look up customer history and subscription
• 3. If simple issue, solve with knowledge base answer or password reset
• 4. If refund request, analyze if eligible and process or escalate
• 5. Escalate only if customer needs talking to management.""",
• expected_output="Clear resolution with action taken or escalation reason",
• agent=support_agent
• )

Part 5: Create a Crew (Orchestrate Multiple Agents)

A Crew is a group of agents working together. For simple cases, you might have one agent. For complex workflows, you have multiple agents with different roles.

Example with one agent:

• crew = Crew(
• agents=[support_agent],
• tasks=[customer_inquiry_task],
• verbose=True, # Shows all reasoning
• )

Part 6: Execute and Test

Here's the full test script:

• if __name__ == "__main__":
• test_inquiry = """Customer says: I purchased a course on Jan 2 and want a
• refund. It's not meeting my expectations."""
• result = crew.kickoff(inputs={"inquiry": test_inquiry})
• print("\n=== AGENT DECISION ===\n")
• print(result)

Run it: python agent.py

Watch your agent reason through the customer issue, search the knowledge base, look up the customer, and decide whether to refund or escalate.

Part 7: Testing & Iteration (Critical)

Before Production, Test These Scenarios:

• Happy path: Simple issue that should resolve—does it?
• Edge case: Customer purchased 31 days ago but quality issue—does it escalate smartly?
• Tool failure: What if API is down?—does it gracefully degrade?
• Ambiguous request: "I want to cancel"—does it clarify or assume?
• Authority edge: Refund request for $150—does it escalate correctly?

Document each test and the agent's response. You'll find bugs in your tool integration and instructions. This is normal.

Part 8: Monitoring in Production

Once deployed, track:

• Resolution rate: % of issues resolved without escalation
• Tool usage: Which tools is the agent using most?
• Error rate: How often does it make wrong decisions?
• Latency: How long does each decision take?
• Cost: How much are you spending on API calls?

Set up simple logging to understand agent behavior:

• Log every decision the agent makes
• Log every tool call (what it asked for, what it got back)
• Log escalations (why did it escalate?)
• Log errors (what went wrong?)

Common Mistakes (And How to Avoid Them)

Mistake 1: Vague Tool Descriptions

Bad: "Customer database tool"

Good: "Look up customer by email. Returns: name, subscription_status, account_age, total_spent, refund_history."

Precise tool descriptions help the agent use tools correctly.

Mistake 2: Too Many Tools

Each additional tool makes the agent "slower" and more likely to choose the wrong one. Start with 3-4 essential tools. Add more only if the agent gets stuck.

Mistake 3: Not Testing Edge Cases

You test the happy path. The agent encounters edge cases in production. Test at least 50 realistic scenarios before deploying.

Mistake 4: No Guardrails

An agent without constraints is dangerous. Always include in your backstory:

• What decisions can you make autonomously?
• What requires escalation?
• What are the limits of your authority?
• How should you handle edge cases?

Going Deeper: Multi-Agent Systems

For complex workflows, create multiple agents with different expertise:

• Support Specialist Agent: Handles routine support issues
• Billing Expert Agent: Handles payments and subscriptions
• Escalation Manager Agent: Decides when to involve humans

These agents can hand off tasks to each other:

• Customer contacts support with a billing question
• Support Agent recognizes it's billing-related, hands off to Billing Expert
• Billing Expert analyzes and makes decision
• If decision requires human approval, Escalation Manager takes over

Next Steps: Building on This Foundation

Once you've built your first basic agent:

• 1. Add one more tool (choose something directly related to your business)
• 2. Extend the agent instructions with a new capabilit
• 3. Double your test scenarios to 100 edge cases
• 4. Deploy to a staging environment (logs actions, doesn't execute)
• 5. Monitor for one week before production deployment
• 6. Measure success metrics

Learning Resources

• CrewAI Documentation: docs.crewai.com (start with examples)
• Playground: playground.crewai.com (test agents before writing code)
• Claude Documentation: anthropic.com/docs (understand model capabilities)
• LangChain docs: python.langchain.com (if you prefer LangChain)

The biggest learning happens when your agent makes wrong decisions. That's your opportunity to refine instructions and improve tool definitions.