🤖 Agent Fundamentals

from langchain_ollama import ChatOllama

# The "brain" of our agent
llm = ChatOllama(
    model="qwen2.5:3b",
    temperature=0.2,        # Low for consistent support replies
    base_url="http://localhost:11434"
)

# The LLM decides what to do
response = llm.invoke("Customer says: 'My order is late.' What tool should I use?")
# Output: "I should use the lookup_order tool to check the order status."

from langchain.tools import tool

@tool
def lookup_order(order_id: str) -> dict:
    """Look up an order by its ID and return status, items, and ETA."""
    # In production: query SQL Server database
    # For demo: hardcoded data
    orders = {
        "7845": {"status": "shipped", "eta": "2026-04-29", "items": ["MacBook Air M3"], "total": 89999},
        "7846": {"status": "delivered", "eta": "2026-04-25", "items": ["iPhone 16"], "total": 79999},
    }
    return orders.get(order_id, {"error": f"Order {order_id} not found"})

@tool
def get_refund_policy(issue_type: str) -> str:
    """Retrieve the refund policy for a given issue type."""
    policies = {
        "shipping_delay": "Shipping delay >2 days: ₹200 credit. >7 days: full refund.",
        "wrong_item": "Wrong item: free return pickup + full refund within 48 hours.",
        "damaged": "Damaged product: photo required. Full refund + ₹500 inconvenience credit.",
    }
    return policies.get(issue_type, "Policy not found. Please escalate to supervisor.")

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email to the customer."""
    # In production: use SMTP/SendGrid
    print(f"📧 Sending to {to}: {subject}")
    return f"Email sent successfully to {to}"

# The agent has access to these tools:
tools = [lookup_order, get_refund_policy, send_email]

SYSTEM_PROMPT = """
You are a customer support agent for ShopEasy, an Indian e-commerce platform.

You have access to these tools:
- lookup_order: Check order status by order ID
- get_refund_policy: Get refund/return policy for issue types
- send_email: Send email to customer

Rules:
1. Always look up the order before making any claims about it
2. Always check the refund policy before offering refunds
3. Be empathetic, professional, and concise
4. If you cannot resolve, say: "Let me connect you to a specialist"
5. Never make up information — only use tool results
6. Reference specific order numbers and amounts in your reply
"""

from langchain.tools import tool

@tool
def lookup_order(order_id: str) -> str:
    """Look up an order by its ID. Returns order status, items, total, and ETA.
    Use this when a customer asks about their order status or delivery."""
    
    # Simulate database lookup (production: query SQL Server)
    import json
    orders_db = {
        "7845": {"order_id": "7845", "status": "shipped", "eta": "2026-04-29",
                 "items": ["MacBook Air M3"], "total": 89999, "customer": "Rajesh Kumar"},
        "7846": {"order_id": "7846", "status": "delivered", "eta": "2026-04-25",
                 "items": ["iPhone 16", "AirPods Pro"], "total": 99998, "customer": "Priya Singh"},
    }
    order = orders_db.get(order_id)
    if order:
        return json.dumps(order, indent=2)
    return f"Error: Order #{order_id} not found in the system."

# Check the auto-generated schema
print(lookup_order.name)        # "lookup_order"
print(lookup_order.description) # "Look up an order by its ID..."
print(lookup_order.args_schema.model_json_schema())
# {'properties': {'order_id': {'type': 'string'}}, 'required': ['order_id']}

from langchain.tools import StructuredTool
from pydantic import BaseModel, Field

class RefundPolicyInput(BaseModel):
    """Input for refund policy lookup."""
    issue_type: str = Field(
        description="Type of issue: 'shipping_delay', 'wrong_item', 'damaged', 'defective', 'changed_mind'"
    )
    days_since_delivery: int = Field(
        default=0,
        description="Number of days since the item was delivered (0 if not delivered)"
    )

def get_refund_policy(issue_type: str, days_since_delivery: int = 0) -> str:
    """Get the applicable refund/return policy based on issue type and delivery date."""
    policies = {
        "shipping_delay": {
            "policy": "If delayed >2 days: ₹200 store credit. If >7 days: full refund.",
            "auto_approve": True
        },
        "wrong_item": {
            "policy": "Free return pickup scheduled within 24 hours. Full refund processed in 3-5 days.",
            "auto_approve": True
        },
        "damaged": {
            "policy": "Customer must upload photo of damage. Full refund + ₹500 inconvenience credit.",
            "auto_approve": False,
            "requires": "photo_upload"
        },
        "defective": {
            "policy": "Eligible for replacement or refund within 15 days of delivery.",
            "auto_approve": days_since_delivery <= 15
        },
        "changed_mind": {
            "policy": "Return within 7 days if unused and in original packaging. Customer pays return shipping.",
            "auto_approve": days_since_delivery <= 7
        }
    }
    import json
    result = policies.get(issue_type, {"policy": "Unknown issue. Escalate to supervisor.", "auto_approve": False})
    return json.dumps(result, indent=2)

refund_policy_tool = StructuredTool.from_function(
    func=get_refund_policy,
    name="get_refund_policy",
    description="Get refund/return policy for a specific issue type. Use when customer requests refund or return.",
    args_schema=RefundPolicyInput
)

import requests
from langchain.tools import tool

@tool
def check_shipping_status(tracking_id: str) -> str:
    """Check real-time shipping status using tracking ID.
    Use when customer asks about delivery status or tracking."""
    
    try:
        # Example: call shipping partner API
        # In production: use actual shipping API (Delhivery, BlueDart, etc.)
        response = requests.get(
            f"http://localhost:8000/api/tracking/{tracking_id}",
            timeout=10
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        return "Error: Shipping service is temporarily slow. Please try again."
    except requests.exceptions.RequestException as e:
        return f"Error checking shipping status: Unable to reach shipping service."

@tool
def search_knowledge_base(query: str) -> str:
    """Search the FAQ and policy knowledge base for relevant information.
    Use when you need to find answers about company policies, product info, or procedures."""
    
    # In production: vector search with ChromaDB (Week 3)
    # For now: simple keyword matching
    kb = {
        "return window": "Standard return window is 7 days. Electronics: 15 days.",
        "payment methods": "We accept UPI, credit cards, debit cards, and net banking.",
        "warranty": "All electronics come with 1-year manufacturer warranty.",
        "cancel order": "Orders can be cancelled before shipping. Go to My Orders → Cancel."
    }
    results = []
    for key, value in kb.items():
        if any(word in query.lower() for word in key.split()):
            results.append(f"- {value}")
    return "\n".join(results) if results else "No relevant information found."

from langchain_ollama import ChatOllama
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

# 1. LLM
llm = ChatOllama(model="qwen2.5:3b", temperature=0.2)

# 2. Tools
tools = [lookup_order, refund_policy_tool, check_shipping_status, search_knowledge_base]

# 3. Prompt
prompt = ChatPromptTemplate.from_messages([
    ("system", """You are a customer support agent for ShopEasy.
    
Available tools: lookup_order, get_refund_policy, check_shipping_status, search_knowledge_base

Rules:
- Always verify order details before making claims
- Always check policy before offering refunds
- Be empathetic and professional
- If stuck, say: "Let me connect you to a specialist"
"""),
    MessagesPlaceholder("chat_history", optional=True),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

# 4. Create Agent
agent = create_tool_calling_agent(llm, tools, prompt)

# 5. Agent Executor (runs the loop)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,     # See the reasoning!
    max_iterations=5, # Safety: max 5 tool calls per turn
    handle_parsing_errors=True
)

# 6. Run it!
result = agent_executor.invoke({
    "input": "Hi, my order #7845 hasn't arrived yet. Can you check?"
})
print(result["output"])

> Entering new AgentExecutor chain...

Thought: The customer wants to know about order #7845. I should look it up.
Action: lookup_order
Action Input: {"order_id": "7845"}
Observation: {"order_id": "7845", "status": "shipped", "eta": "2026-04-29", 
              "items": ["MacBook Air M3"], "total": 89999, "customer": "Rajesh Kumar"}

Thought: The order is shipped with ETA April 29. Let me give the customer this info.
Final Answer: Hi Rajesh! I checked your order #7845 — your MacBook Air M3 has been shipped 
and is expected to arrive by April 29th. You can track it in the "My Orders" section. 
Let me know if you need anything else! 😊

> Finished chain.

@tool
def lookup_order(order_id: str) -> str:
    """Look up an order by ID. Returns order details or error message."""
    
    # Validate input
    if not order_id or not order_id.strip():
        return "Error: No order ID provided. Ask the customer for their order number."
    
    # Sanitize input (prevent injection)
    order_id = order_id.strip().replace("'", "").replace(";", "")[:20]
    
    try:
        # Database lookup (simulated)
        order = db_lookup(order_id)  # Your actual DB call
        if order:
            return json.dumps(order)
        return f"Order #{order_id} not found. Please verify the order number with the customer."
    except Exception:
        return "Error: Unable to access order system. Please try again or escalate to support team."

from langchain.memory import ConversationBufferMemory

memory = ConversationBufferMemory(
    memory_key="chat_history",
    return_messages=True
)

# Stores every message
memory.save_context(
    {"input": "My name is Rajesh, order #7845"},
    {"output": "Hi Rajesh! Let me check order #7845 for you."}
)
memory.save_context(
    {"input": "What's the status?"},
    {"output": "Your order #7845 is shipped, arriving April 29th."}
)

# Load everything
print(memory.load_memory_variables({}))
# Returns ALL messages — both user and agent

from langchain.memory import ConversationBufferWindowMemory

memory = ConversationBufferWindowMemory(
    memory_key="chat_history",
    return_messages=True,
    k=5  # Keep last 5 exchange pairs (10 messages)
)

# After 20 messages, only the last 10 are kept
# Good for: real-time support where recent context matters most

from langchain.memory import ConversationSummaryMemory
from langchain_ollama import ChatOllama

llm = ChatOllama(model="qwen2.5:3b")

memory = ConversationSummaryMemory(
    llm=llm,
    memory_key="chat_history",
    return_messages=True
)

# After many messages, the summary might be:
# "Customer Rajesh Kumar contacted about order #7845 (MacBook Air). 
#  Order is shipped, ETA April 29. Customer expressed frustration about 
#  the delay. Agent offered ₹200 credit for the delay. Customer accepted."

# ✅ Compact — captures key facts
# ✅ Fits in small context windows
# ⚠️ Uses extra LLM calls to summarize

# pip install chromadb langchain-chroma
from langchain.memory import VectorStoreRetrieverMemory
from langchain_chroma import Chroma
from langchain_ollama import OllamaEmbeddings

# Setup vector store
embeddings = OllamaEmbeddings(model="nomic-embed-text")
vectorstore = Chroma(
    collection_name="support_memory",
    embedding_function=embeddings,
    persist_directory="./memory_db"
)

# Create memory with retriever
retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
memory = VectorStoreRetrieverMemory(retriever=retriever)

# Save conversations as embeddings
memory.save_context(
    {"input": "I need to return my laptop, order #7845"},
    {"output": "I'll help with the return. Your MacBook Air is within the 15-day window."}
)

# Later, when customer asks about returns:
# The memory searches by MEANING and retrieves the relevant conversation
# Even if the customer says "send it back" instead of "return"

from langchain.memory import CombinedMemory

# Short-term: last 3 exchanges
window_memory = ConversationBufferWindowMemory(
    memory_key="recent_chat",
    return_messages=True,
    k=3
)

# Long-term: vector search
vector_memory = VectorStoreRetrieverMemory(
    retriever=vectorstore.as_retriever(search_kwargs={"k": 2}),
    memory_key="relevant_history"
)

# Combine them
memory = CombinedMemory(memories=[window_memory, vector_memory])

# The agent now gets:
# 1. Last 3 messages (immediate context)
# 2. Most relevant past conversations (semantic search)
# → Best of both worlds!

from langchain_ollama import ChatOllama
from langchain.agents import AgentExecutor, create_react_agent
from langchain_core.prompts import PromptTemplate

llm = ChatOllama(model="qwen2.5:3b", temperature=0.2)

# ReAct-specific prompt template
react_prompt = PromptTemplate.from_template("""
You are a customer support agent. Answer the customer's question using the available tools.

You have access to these tools:
{tools}

Tool names: {tool_names}

Use this EXACT format:

Question: the customer's message
Thought: think about what to do
Action: the tool to use (must be one of [{tool_names}])
Action Input: the input to the tool
Observation: the result from the tool
... (repeat Thought/Action/Observation as needed)
Thought: I now have enough information to answer
Final Answer: your response to the customer

Begin!

Question: {input}
{agent_scratchpad}
""")

# Create ReAct agent
agent = create_react_agent(llm, tools, react_prompt)
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=5,
    handle_parsing_errors=True
)

cot_planning_prompt = """
You are a customer support agent. Before taking any action, think through 
your complete plan step by step.

Customer message: "{message}"

Think step by step:
1. What is the customer's intent?
2. What information do I need?
3. Which tools should I call, in what order?
4. What are the possible outcomes?
5. What's my response plan for each outcome?

Plan:
"""

# After planning, execute the plan
execution_prompt = """
Based on this plan:
{plan}

And these tool results:
{tool_results}

Generate the final response to the customer.
"""

# Step 1: Planner (1 LLM call)
Plan:
  #E1 = lookup_order("7845")           ← get order details
  #E2 = get_refund_policy("wrong_item") ← get policy
  #E3 = search_knowledge_base("return process")  ← get FAQ

# Step 2: Worker (all 3 tool calls run IN PARALLEL)
  #E1 result = {status: "delivered", items: ["AirPods Pro"]}
  #E2 result = {policy: "Free return pickup..."}
  #E3 result = "Return process: schedule pickup → refund in 3-5 days"

# Step 3: Solver (1 LLM call with ALL results)
  Given: #E1, #E2, #E3 → Generate final response

# Total LLM calls: 2 (plan + solve) instead of ReAct's 4-6
# Total time: much faster because tools run in parallel!

agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=5,           # Stop after 5 tool calls
    max_execution_time=30,      # Timeout after 30 seconds
    handle_parsing_errors=True, # Recover from malformed output
    early_stopping_method="generate",  # Generate answer if stuck
)

# Scenario 1: Order Status
User: "Where is my order #7845?"
→ Agent should call lookup_order and give status

# Scenario 2: Refund Request  
User: "My laptop arrived damaged. Order #7845. I want a refund."
→ Agent should: lookup_order → get_refund_policy("damaged") → offer refund

# Scenario 3: Multi-turn with Memory
User: "My name is Rajesh"
User: "Check order #7845"
User: "What's the refund policy for damaged items?"
User: "Ok process the refund"
→ Agent should remember Rajesh's name throughout

# Scenario 4: Unknown Issue (Escalation)
User: "I want to sue your company for negligence"
→ Agent should NOT attempt to handle legal issues; should escalate

# Scenario 5: General Knowledge
User: "What payment methods do you accept?"
→ Agent should search knowledge base