LangBot Day 10: Agents and Tool Calling — Let the LLM Decide What to Do

if user_input.startswith("/search"):
    # explicit search
    ...
elif wants_list(user_input):
    # list mode
    ...
else:
    docs = search_docs(vector_store, user_input, k=3)
    if docs:
        # RAG
        ...
    else:
        # regular chat
        ...

Day 12: chat history persistence → new code path
Day 13: caching → new code path
Day 14: guardrails → new code path, possibly before everything else
Day 15: multi-modal input → new code path
Day 18: hybrid search → new code path that replaces RAG routing

from langchain.tools import tool

@tool
def search_docs_tool(query: str) -> str:
    """Search the company document library for policies, benefits, and procedures.
    Use this when the user asks about company policies, benefits, HR questions,
    remote work rules, or anything likely to be in internal documents."""
    docs = search_docs(vector_store, query, k=3)
    if not docs:
        return "No relevant documents found."
    return format_context(docs)

uv add langchain-community

from langchain.tools import tool

@tool
def search_docs_tool(query: str) -> str:
    """Search the company document library for policies, benefits, and procedures.

    Use this when the user asks about company policies, benefits, HR questions,
    remote work rules, expenses, time off, or anything likely to be in internal
    documents. Do NOT use this for general knowledge questions (capital cities,
    math, coding help) — those don't need document retrieval."""
    docs = search_docs(vector_store, query, k=3)
    if not docs:
        return "No relevant documents found."
    return format_context(docs)

@tool
def list_suggestions_tool(topic: str, count: int = 5) -> str:
    """Generate a list of suggestions or recommendations on a topic.

    Use this when the user explicitly asks for a list, suggestions, recommendations,
    top N items, or ideas. Examples: 'list 5 programming books', 'suggest weekend
    activities', 'recommend sci-fi movies'. Do NOT use this for factual questions
    or document searches."""
    items = list_chain.invoke({"input": f"List {count} {topic}", "history": messages})
    if not items:
        return "Could not generate suggestions."
    lines = [f"  {i}. {item}" for i, item in enumerate(items, 1)]
    return "\n".join([f"Here are {len(items)} {topic} suggestions:"] + lines)

from langchain.agents import create_tool_calling_agent, AgentExecutor

# 🆕 Day 10: The agent prompt — tells the model HOW to behave as an agent
AGENT_SYSTEM_PROMPT = """You are LangBot, a witty and slightly sarcastic AI assistant.
You love bad puns, you use emojis sparingly, and you always keep responses
under three sentences. If you don't know something, you admit it with style.

You have access to tools. Use them when they are relevant:
- search_docs_tool: for questions about company policies, benefits, or internal docs
- list_suggestions_tool: when the user asks for a list, suggestions, or recommendations

If neither tool is relevant, just respond directly — no tool call needed.

When you use search_docs_tool and find relevant documents:
- Answer from the provided context
- Cite which document(s) you used
- If the context doesn't contain the answer, say so honestly

Be decisive. If a tool would help, use it immediately. Don't ask the user
whether they want you to search — just search and answer."""

# 🆕 Day 10: Assemble the agent prompt
agent_prompt = ChatPromptTemplate.from_messages([
    ("system", AGENT_SYSTEM_PROMPT),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"),
])

# 🆕 Day 10: Create the agent — LLM + tools + prompt
tools = [search_docs_tool, list_suggestions_tool]
agent = create_tool_calling_agent(llm, tools, agent_prompt)

# 🆕 Day 10: AgentExecutor — runs the agent loop
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=False,          # Set True during debugging to see agent reasoning
    handle_parsing_errors=True,
    max_iterations=3,       # Prevent infinite loops
)

while True:
    user_input = input("\nYou: ").strip()

    if user_input.lower() in ("quit", "exit", "q"):
        print("👋 Goodbye!")
        break

    if not user_input:
        continue

    # ── Day 8: /search command (kept for explicit searches) ──
    if user_input.startswith("/search"):
        query = user_input.removeprefix("/search").strip()
        if not query:
            print("\n⚠ Usage: /search <your query>")
            continue
        if vector_store is None:
            print("\n⚠ Vector store not available.")
            continue

        results = search_docs(vector_store, query, k=3)
        if not results:
            print(f"\n📭 No relevant documents found for: \"{query}\"")
        else:
            print(f"\n📖 Top {len(results)} results for: \"{query}\"")
            print("─" * 40)
            for i, doc in enumerate(results, 1):
                source = doc.metadata.get("source", "unknown")
                preview = doc.page_content[:200].replace("\n", " ")
                print(f"\n  [{i}] 📄 {source}")
                print(f"      {preview}...")
            print(f"\n─" * 40)

        messages.append(HumanMessage(content=user_input))
        summary = f"Searched for '{query}': found {len(results)} document(s)."
        messages.append(AIMessage(content=summary))
        continue

    # ═══════════════════════════════════════════════════════════
    # 🆕 Day 10: Agent handles everything — chat, RAG, lists
    # ═══════════════════════════════════════════════════════════

    print(f"\nLangBot: ", end="", flush=True)

    full_response = ""
    for chunk in agent_executor.stream({
        "input": user_input,
        "history": messages,
    }):
        # agent_executor.stream() yields dicts with "output" key
        if "output" in chunk:
            text = chunk["output"]
            print(text, end="", flush=True)
            full_response += text

    print()

    # Day 2: Store the exchange in history
    messages.append(HumanMessage(content=user_input))
    messages.append(AIMessage(content=full_response))

# langbot.py — Day 10: Agents and tool calling
from dotenv import load_dotenv
from pydantic import BaseModel, Field
from enum import Enum
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_core.messages import HumanMessage, AIMessage
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.output_parsers import CommaSeparatedListOutputParser
from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_pinecone import PineconeVectorStore
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain.tools import tool

load_dotenv()


# ── Day 5: Mood enum ───────────────────────────────────────────────
class Mood(str, Enum):
    """Emotional tones LangBot can express."""
    CHEERFUL = "cheerful"
    SARCASTIC = "sarcastic"
    THOUGHTFUL = "thoughtful"
    APOLOGETIC = "apologetic"


# ── Day 5: Response model ──────────────────────────────────────────
class LangBotResponse(BaseModel):
    """Every LangBot reply is a typed object, not raw text."""
    message: str = Field(description="LangBot's actual reply to the user")
    mood: Mood = Field(description="The emotional tone LangBot chose for this response")
    confidence: float = Field(
        description="How sure LangBot is about this response. 0.0 = total guess, 1.0 = absolutely certain.",
        ge=0.0,
        le=1.0,
    )


# ═══════════════════════════════════════════════════════════════════
# Day 8: Document retrieval infrastructure (unchanged)
# ═══════════════════════════════════════════════════════════════════

def load_documents(docs_dir: str = "docs") -> list:
    """Load all .txt and .md files from a directory. Returns a list of Documents."""
    documents = []
    for pattern in ["**/*.txt", "**/*.md"]:
        try:
            loader = DirectoryLoader(docs_dir, glob=pattern, loader_cls=TextLoader,
                                     silent_errors=True)
            documents.extend(loader.load())
        except Exception:
            pass
    return documents


def chunk_documents(documents: list, chunk_size: int = 500, chunk_overlap: int = 50) -> list:
    """Split long documents into smaller, overlapping chunks for better retrieval."""
    splitter = RecursiveCharacterTextSplitter(
        chunk_size=chunk_size,
        chunk_overlap=chunk_overlap,
        separators=["\n\n", "\n", ". ", " ", ""],
    )
    return splitter.split_documents(documents)


def setup_vector_store(chunks: list, index_name: str = "langbot-docs"):
    """Embed all chunks and store them in Pinecone. Returns the vector store."""
    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
    vector_store = PineconeVectorStore.from_documents(
        documents=chunks,
        embedding=embeddings,
        index_name=index_name,
    )
    return vector_store


def search_docs(vector_store, query: str, k: int = 3) -> list:
    """Search the vector store for the k most relevant document chunks."""
    if vector_store is None:
        return []
    return vector_store.similarity_search(query, k=k)


# ═══════════════════════════════════════════════════════════════════
# Day 9: RAG context formatting (unchanged)
# ═══════════════════════════════════════════════════════════════════

def format_context(docs: list) -> str:
    """Format retrieved documents into a context string for the prompt."""
    if not docs:
        return "No relevant documents found."
    parts = []
    for i, doc in enumerate(docs, 1):
        source = doc.metadata.get("source", "unknown")
        parts.append(f"[Document {i} — {source}]\n{doc.page_content}")
    return "\n\n---\n\n".join(parts)


def main():
    llm = ChatOpenAI(model="gpt-4.1-mini", temperature=0.7)

    # Day 3: Personality (used by list_chain, agent has its own prompt)
    SYSTEM_PROMPT = """You are LangBot, a witty and slightly sarcastic AI assistant.
You love bad puns, you use emojis sparingly, and you always keep responses
under three sentences. If you don't know something, you admit it with style.

Choose your mood for each response:
- cheerful: when the conversation is light, the user is happy, or you're making a joke
- sarcastic: when you're being playfully snarky or the user said something ridiculous
- thoughtful: when the question is deep, technical, or deserves a careful answer
- apologetic: when you realize you got something wrong or don't know the answer

Set confidence based on how sure you are. Factual answers = high confidence.
Opinions and jokes = moderate confidence. Guesses = low confidence."""

    # Day 3: Chat prompt template (still used by list_chain)
    prompt = ChatPromptTemplate.from_messages([
        ("system", SYSTEM_PROMPT),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
    ])

    # Day 5: Structured output chain
    structured_llm = llm.with_structured_output(LangBotResponse)
    chat_chain = prompt | structured_llm

    # Day 6: List-mode output parser
    list_parser = CommaSeparatedListOutputParser()

    # Day 6: List-specific prompt
    LIST_SYSTEM_PROMPT = SYSTEM_PROMPT + "\n\n" + list_parser.get_format_instructions()

    list_prompt = ChatPromptTemplate.from_messages([
        ("system", LIST_SYSTEM_PROMPT),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
    ])

    # Day 6: List chain — prompt → raw LLM → comma-split parser → list[str]
    list_chain = list_prompt | llm | list_parser

    # ═══════════════════════════════════════════════════════════
    # Day 8: Set up document retrieval at startup
    # ═══════════════════════════════════════════════════════════
    vector_store = None
    chunk_count = 0

    print("📚 Loading documents from docs/ ...")
    try:
        documents = load_documents()
        if documents:
            doc_count = len(documents)
            chunks = chunk_documents(documents)
            chunk_count = len(chunks)
            print(f"   Loaded {doc_count} document(s) → split into {chunk_count} chunks")

            print("🔢 Embedding chunks and storing in Pinecone ...")
            vector_store = setup_vector_store(chunks)
            print(f"   ✓ Vector store ready ({chunk_count} vectors indexed)")
        else:
            print("   (No documents found in docs/ — search will be unavailable)")
            print("   (Create docs/*.txt or docs/*.md files and restart)")
    except Exception as e:
        print(f"   ⚠ Vector store setup skipped: {e}")
        print("   (Make sure PINECONE_API_KEY is set and the index exists)")

    # ═══════════════════════════════════════════════════════════
    # 🆕 Day 10: Define tools for the agent
    # ═══════════════════════════════════════════════════════════

    @tool
    def search_docs_tool(query: str) -> str:
        """Search the company document library for policies, benefits, and procedures.

        Use this when the user asks about company policies, benefits, HR questions,
        remote work rules, expenses, time off, or anything likely to be in internal
        documents. Do NOT use this for general knowledge questions (capital cities,
        math, coding help) — those don't need document retrieval."""
        docs = search_docs(vector_store, query, k=3)
        if not docs:
            return "No relevant documents found."
        return format_context(docs)

    @tool
    def list_suggestions_tool(topic: str, count: int = 5) -> str:
        """Generate a list of suggestions or recommendations on a topic.

        Use this when the user explicitly asks for a list, suggestions,
        recommendations, top N items, or ideas. Examples: 'list 5 programming
        books', 'suggest weekend activities', 'recommend sci-fi movies'.
        Do NOT use this for factual questions or document searches."""
        items = list_chain.invoke({
            "input": f"List {count} {topic}",
            "history": messages,
        })
        if not items:
            return "Could not generate suggestions."
        lines = [f"  {i}. {item}" for i, item in enumerate(items, 1)]
        return "\n".join([f"Here are {len(items)} {topic} suggestions:"] + lines)

    # ═══════════════════════════════════════════════════════════
    # 🆕 Day 10: Build the agent
    # ═══════════════════════════════════════════════════════════

    AGENT_SYSTEM_PROMPT = """You are LangBot, a witty and slightly sarcastic AI assistant.
You love bad puns, you use emojis sparingly, and you always keep responses
under three sentences. If you don't know something, you admit it with style.

You have access to tools. Use them when they are relevant:
- search_docs_tool: for questions about company policies, benefits, or internal docs
- list_suggestions_tool: when the user asks for a list, suggestions, or recommendations

If neither tool is relevant, just respond directly — no tool call needed.

When you use search_docs_tool and find relevant documents:
- Answer from the provided context
- Cite which document(s) you used
- If the context doesn't contain the answer, say so honestly

Be decisive. If a tool would help, use it immediately. Don't ask the user
whether they want you to search — just search and answer."""

    agent_prompt = ChatPromptTemplate.from_messages([
        ("system", AGENT_SYSTEM_PROMPT),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])

    tools = [search_docs_tool, list_suggestions_tool]
    agent = create_tool_calling_agent(llm, tools, agent_prompt)

    agent_executor = AgentExecutor(
        agent=agent,
        tools=tools,
        verbose=False,
        handle_parsing_errors=True,
        max_iterations=3,
    )

    # Day 2: Conversation history
    messages = []

    print("🤖 LangBot (type 'quit' to exit)")
    print("─" * 40)
    print("  Agent mode — LangBot decides whether to search, list, or chat")
    print("  Just ask naturally — the agent picks the right tool 🤖🔧")
    print("─" * 40)

    while True:
        user_input = input("\nYou: ").strip()

        if user_input.lower() in ("quit", "exit", "q"):
            print("👋 Goodbye!")
            break

        if not user_input:
            continue

        # ── Day 8: /search command (kept for explicit searches) ──
        if user_input.startswith("/search"):
            query = user_input.removeprefix("/search").strip()
            if not query:
                print("\n⚠ Usage: /search <your query>")
                continue
            if vector_store is None:
                print("\n⚠ Vector store not available.")
                continue

            results = search_docs(vector_store, query, k=3)
            if not results:
                print(f"\n📭 No relevant documents found for: \"{query}\"")
            else:
                print(f"\n📖 Top {len(results)} results for: \"{query}\"")
                print("─" * 40)
                for i, doc in enumerate(results, 1):
                    source = doc.metadata.get("source", "unknown")
                    preview = doc.page_content[:200].replace("\n", " ")
                    print(f"\n  [{i}] 📄 {source}")
                    print(f"      {preview}...")
                print(f"\n─" * 40)

            messages.append(HumanMessage(content=user_input))
            summary = f"Searched for '{query}': found {len(results)} document(s)."
            messages.append(AIMessage(content=summary))
            continue

        # ═══════════════════════════════════════════════════════
        # 🆕 Day 10: Agent handles everything — chat, RAG, lists
        # ═══════════════════════════════════════════════════════

        print(f"\nLangBot: ", end="", flush=True)

        full_response = ""
        for chunk in agent_executor.stream({
            "input": user_input,
            "history": messages,
        }):
            if "output" in chunk:
                text = chunk["output"]
                print(text, end="", flush=True)
                full_response += text

        print()

        # Day 2: Store the exchange in history
        messages.append(HumanMessage(content=user_input))
        messages.append(AIMessage(content=full_response))


if __name__ == "__main__":
    main()

python langbot.py

📚 Loading documents from docs/ ...
   Loaded 3 document(s) → split into 14 chunks
🔢 Embedding chunks and storing in Pinecone ...
   ✓ Vector store ready (14 vectors indexed)
🤖 LangBot (type 'quit' to exit)
────────────────────────────────────────
  Agent mode — LangBot decides whether to search, list, or chat
  Just ask naturally — the agent picks the right tool 🤖🔧
────────────────────────────────────────

You: How much PTO do I get?

LangBot: According to the remote work policy, you get 2 days of PTO per month,
up to a maximum of 24 days per year. 🏖️

You: Suggest 5 weekend activities

LangBot: Here are 5 weekend activities suggestions:
  1. Go for a hike or nature walk
  2. Visit a local museum or art gallery
  3. Try a new recipe or bake something
  4. Have a movie marathon with friends
  5. Start a DIY project or craft
Weekend, sorted! 🎨🥾

You: What's the capital of France?

LangBot: Paris — and no, I didn't need to search any documents for that one. 🇫🇷

You: What health insurance plans does the company offer?

LangBot: The company offers three plans — HMO, PPO, and HDHP with HSA — per the
benefits document. The company covers 80% of your premium. 🏥

You: Tell me a joke

LangBot: Why do programmers prefer dark mode? Because light attracts bugs! 🐛💡

You: /search remote work

📖 Top 3 results for: "remote work"
────────────────────────────────────────

  [1] 📄 docs/remote-work-policy.txt
      Remote Work Policy — Section 1: Eligibility All full-time employees...

  [2] 📄 docs/benefits.txt
      ...home office stipend of $500 per year for eligible remote employees...

  [3] 📄 docs/engineering.txt
      ...remote pairing sessions are encouraged but not mandatory...

────────────────────────────────────────

You: quit
👋 Goodbye!

for chunk in agent_executor.stream({"input": user_input, "history": messages}):
    if "output" in chunk:
        text = chunk["output"]
        print(text, end="", flush=True)
        full_response += text

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression. Use for arithmetic, unit conversions, percentages."""
    ...

tools = [search_docs_tool, list_suggestions_tool, calculator]  # +1 tool

# Wrong — too vague, the agent won't know when to call this
@tool
def search_docs_tool(query: str) -> str:
    """Search documents."""
    ...

# Right — specific guidance about when (and when not) to use it
@tool
def search_docs_tool(query: str) -> str:
    """Search the company document library for policies, benefits, and procedures.
    Use this when the user asks about company policies, benefits, HR questions,
    remote work rules, expenses, time off, or anything likely to be in internal
    documents. Do NOT use for general knowledge questions."""
    ...

# Wrong — missing agent_scratchpad
agent_prompt = ChatPromptTemplate.from_messages([
    ("system", AGENT_SYSTEM_PROMPT),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
    # Missing: MessagesPlaceholder(variable_name="agent_scratchpad")
])

# Error: KeyError: 'agent_scratchpad' when running the agent

# Wrong — printing ALL chunks, including tool calls
for chunk in agent_executor.stream({"input": user_input, "history": messages}):
    print(chunk, end="", flush=True)
    # User sees: "{'actions': [ToolAgentAction(...)], 'messages': [...]}"

agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=100,   # Danger — a confused agent can loop forever
)