AI Agent Development Complete Guide: Building Your First Intelligent Agent from Scratch
Estimated Learning Time: 3 hours
Difficulty Level: Intermediate
Word Count: 3,200 words
Preface
AI Agent (Artificial Intelligence Agent) is one of the hottest technology trends in 2026. Unlike ordinary chatbots, Agents can autonomously plan, use tools, and execute multi-step tasks. This tutorial will guide you from scratch to build a fully functional AI Agent using Python and LangChain.
Learning Objectives: - Understand core concepts and architecture of AI Agents - Master the LangChain Agent development framework - Be able to integrate external tools and APIs - Implement memory functions and error handling
Prerequisites: - Python basics (functions, classes, async programming) - Experience using OpenAI API - Basic HTTP and API concepts
Preparation
Environment Setup
Step 1: Create Project Directory
mkdir ai-agent-tutorial
cd ai-agent-tutorial
python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
```text
**Step 2: Install Dependencies**
```bash
pip install langchain langchain-openai langchain-community
pip install python-dotenv requests
Step 3: Configure Environment Variables
Create .env file:
OPENAI_API_KEY=your_openai_api_key_here
TAVILY_API_KEY=your_tavily_api_key_here
```text
**Expected Results:**
- Virtual environment activated successfully
- All packages installed without errors
- Environment variables file created
---
## Main Tutorial Steps
### Step 1: Understanding Agent Architecture
**What is an AI Agent?**
An AI Agent is a system capable of autonomous decision-making and task execution. Its core workflow is:
User Input → Thought → Action → Observation → Answer
**ReAct Pattern (Reasoning + Acting):**
The Agent loops through the following steps until the task is complete:
1. **Thought**: Analyze the current situation and decide the next action
2. **Action**: Select and execute a tool
3. **Observation**: Get the tool execution result
4. **Final Answer**: Integrate all information to provide an answer
### Step 2: Create Basic Agent
**Code Example:**
```python
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain.prompts import PromptTemplate
from langchain.tools import Tool
# Load environment variables
load_dotenv()
# Initialize LLM
llm = ChatOpenAI(
model="gpt-4o-mini",
temperature=0.7
)
# Define simple tools
def search_web(query: str) -> str:
"""Simulate web search"""
# In real projects, use Tavily, SerpAPI, etc.
return f"Search results: Latest information about '{query}'..."
def calculate(expression: str) -> str:
"""Perform mathematical calculations"""
try:
result = eval(expression)
return f"Calculation result: {result}"
except:
return "Calculation error, please check the expression"
# Create tool list
tools = [
Tool(
name="WebSearch",
func=search_web,
description="Tool for searching web information, input should be search keywords"
),
Tool(
name="Calculator",
func=calculate,
description="Tool for mathematical calculations, input should be expressions like '2+2' or '10*5'"
)
]
# ReAct prompt template
react_template = """You are a helpful AI assistant. Answer the following questions as best you can.
You have access to the following tools:
{tools}
Use the following format:
Question: the input question you must answer
Thought: you should always think about what to do
Action: the action to take, should be one of [{tool_names}]
Action Input: the input to the action
Observation: the result of the action
... (this Thought/Action/Action Input/Observation can repeat N times)
Thought: I now know the final answer
Final Answer: the final answer to the original input question
Begin!
Question: {input}
Thought:{agent_scratchpad}"""
prompt = PromptTemplate.from_template(react_template)
# Create Agent
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True, # Show execution process
handle_parsing_errors=True
)
# Run Agent
if __name__ == "__main__":
result = agent_executor.invoke({
"input": "Who won the 2024 Nobel Prize? Then calculate 2024 divided by 4."
})
print("\nFinal Answer:", result["output"])
Expected Output:
> Entering new AgentExecutor chain...
Thought: I need to search for information about 2024 Nobel Prize winners, then perform the calculation.
Action: WebSearch
Action Input: 2024 Nobel Prize winners
Observation: Search results: Latest information about '2024 Nobel Prize winners'...
Thought: Now I need to perform the calculation.
Action: Calculator
Action Input: 2024/4
Observation: Calculation result: 506.0
Thought: I now know the final answer
Final Answer: The 2024 Nobel Prize winners are [info from search results], and 2024 divided by 4 equals 506.
> Finished chain.
Final Answer: The 2024 Nobel Prize winners are...
Step 3: Integrate Real Search Tools
Using Tavily Search Engine:
from langchain_community.tools.tavily_search import TavilySearchResults
# Replace simulated search with real search
tavily_tool = TavilySearchResults(
max_results=3,
search_depth="advanced"
)
tools = [
tavily_tool,
Tool(
name="Calculator",
func=calculate,
description="Tool for mathematical calculations"
)
]
# Recreate Agent
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
```text
**Getting Tavily API Key:**
1. Visit https://tavily.com
2. Register an account
3. Get free API Key (1,000 calls per month)
### Step 4: Add Memory Function
**Why Memory is Needed?**
Agents need to remember previous conversation content to handle multi-turn conversations and complex tasks.
**Implementation Code:**
```python
from langchain.memory import ConversationBufferMemory
from langchain.agents import create_react_agent
from langchain.prompts import PromptTemplate
# Create memory component
memory = ConversationBufferMemory(
memory_key="chat_history",
return_messages=True
)
# Prompt template with memory
template_with_memory = """You are a helpful AI assistant with memory of our conversation.
Previous conversation:
{chat_history}
You have access to the following tools:
{tools}
Use the following format:
Question: the input question you must answer
Thought: you should always think about what to do
Action: the action to take, should be one of [{tool_names}]
Action Input: the input to the action
Observation: the result of the action
... (this Thought/Action/Action Input/Observation can repeat N times)
Thought: I now know the final answer
Final Answer: the final answer to the original input question
Begin!
Question: {input}
Thought:{agent_scratchpad}"""
prompt = PromptTemplate.from_template(template_with_memory)
# Create Agent with memory
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
memory=memory,
verbose=True
)
# Multi-turn conversation example
if __name__ == "__main__":
# Round 1
result1 = agent_executor.invoke({"input": "My name is John, please remember"})
print(result1["output"])
# Round 2 (Agent should remember user's name)
result2 = agent_executor.invoke({"input": "What is my name?"})
print(result2["output"])
Step 5: Create Custom Tools
Develop Weather Query Tool:
import requests
from langchain.tools import BaseTool
from pydantic import BaseModel, Field
class WeatherInput(BaseModel):
city: str = Field(description="City name, e.g., 'Beijing', 'Shanghai'")
class WeatherTool(BaseTool):
name = "WeatherQuery"
description = "Query current weather for a specified city"
args_schema = WeatherInput
def _run(self, city: str) -> str:
"""Synchronous execution"""
# Use OpenWeatherMap API or other weather services
api_key = os.getenv("OPENWEATHER_API_KEY")
url = f"http://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units=metric&lang=en"
try:
response = requests.get(url)
data = response.json()
if response.status_code == 200:
temp = data["main"]["temp"]
desc = data["weather"][0]["description"]
return f"Current weather in {city}: {desc}, temperature {temp}°C"
else:
return f"Unable to get weather information for {city}"
except Exception as e:
return f"Query error: {str(e)}"
async def _arun(self, city: str) -> str:
"""Asynchronous execution"""
return self._run(city)
# Add to tool list
weather_tool = WeatherTool()
tools.append(weather_tool)
```text
### Step 6: Error Handling and Optimization
**Add Error Handling:**
```python
from langchain.agents import AgentExecutor
from langchain_core.exceptions import OutputParserException
class RobustAgentExecutor(AgentExecutor):
"""Enhanced Agent executor with error handling"""
def invoke(self, inputs, **kwargs):
try:
return super().invoke(inputs, **kwargs)
except OutputParserException as e:
# Handle output parsing errors
return {
"output": "Sorry, I encountered a problem processing your request. Please try rephrasing your question."
}
except Exception as e:
# Log error and return friendly message
print(f"Agent execution error: {e}")
return {
"output": f"Execution error: {str(e)}. Please check your input or try again later."
}
# Use enhanced executor
agent_executor = RobustAgentExecutor(
agent=agent,
tools=tools,
memory=memory,
verbose=True,
max_iterations=10, # Maximum iterations
early_stopping_method="generate" # Handling method after timeout
)
Advanced Content
Multi-Agent Collaboration System
from langchain.agents import AgentType, initialize_agent
from langchain.schema import SystemMessage
# Create specialist Agent
def create_specialist_agent(role: str, tools: list):
system_message = SystemMessage(content=f"You are a {role} specialist.")
return initialize_agent(
tools=tools,
llm=llm,
agent=AgentType.CHAT_CONVERSATIONAL_REACT_DESCRIPTION,
system_message=system_message,
verbose=True
)
# Research Agent
research_agent = create_specialist_agent(
"research",
[tavily_tool]
)
# Analysis Agent
analysis_agent = create_specialist_agent(
"data analysis",
[calculator_tool]
)
# Collaboration workflow
def collaborative_workflow(query: str):
# 1. Research phase
research_result = research_agent.run(f"Research the following topic: {query}")
# 2. Analysis phase
analysis_result = analysis_agent.run(f"Analyze the following research results: {research_result}")
# 3. Integrate output
return f"Research Conclusions: {research_result}\n\nAnalysis Results: {analysis_result}"
```text
### Deploy as API Service
```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import uvicorn
app = FastAPI(title="AI Agent API")
class QueryRequest(BaseModel):
query: str
session_id: str = "default"
class QueryResponse(BaseModel):
answer: str
execution_time: float
@app.post("/query", response_model=QueryResponse)
async def query_agent(request: QueryRequest):
import time
start_time = time.time()
try:
result = agent_executor.invoke({"input": request.query})
execution_time = time.time() - start_time
return QueryResponse(
answer=result["output"],
execution_time=execution_time
)
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
Practical Problem Solving
Problem 1: Agent Gets Stuck in Loop
Symptoms: Agent repeats the same action and cannot reach a conclusion.
Solution:
# Limit iteration count
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
max_iterations=5, # Maximum 5 rounds
max_execution_time=30, # Maximum 30 seconds
early_stopping_method="force" # Force stop
)
```text
### Problem 2: Wrong Tool Selection
**Symptoms:** Agent selects inappropriate tools.
**Solution:**
```python
# Optimize tool descriptions
tools = [
Tool(
name="WebSearch",
func=search_web,
description="""
For searching latest information, news, factual content.
Input: specific keywords or questions
Use case: Need real-time information, latest updates, specific facts
Do NOT use for: mathematical calculations, restating known information
"""
)
]
Problem 3: API Call Failures
Symptoms: External API returns errors or times out.
Solution:
```python import functools import time
def retry_on_error(max_retries=3, delay=1): """Retry decorator""" def decorator(func): @functools.wraps(func) def wrapper(args, kwargs): for attempt in range(max_retries): try: return func(args, **kwargs) except Exception as e: if attempt == max_retries - 1: raise e time.sleep(delay * (attempt + 1)) return None return wrapper return decorator
class WeatherTool(BaseTool): @retry_on_error(max_retries=3) def _run(self, city: str) -> str: # Tool implementation pass ```text
Summary
Key Takeaways:
- Agent Architecture - Understand the Thought-Action-Observation loop
- Tool Integration - Learn to create and integrate custom tools
- Memory Management - Implement multi-turn conversations and context retention
- Error Handling - Build robust Agent systems
- Deployment - Package Agent as accessible services
Next Steps:
- Explore LangGraph for building complex Agent workflows
- Learn multi-agent collaboration and competition patterns
- Study Agent security and alignment issues
Keywords: AI Agent, LangChain, Python, Intelligent Agent, ReAct, LLM Application Development
Related Resources: - LangChain Official Documentation - OpenAI API Documentation - Building RAG Systems Tutorial
Last Updated: March 6, 2026