LangChain Tutorial (Python): testing agents locally for beginners

This tutorial shows you how to run and test a LangChain agent locally in Python without wiring it into an app or deploying anything. You need this when you want to debug tool calls, inspect agent decisions, and catch bad prompts before the code touches a real user flow.

What You'll Need

• •Python 3.10+
• •A virtual environment
• •langchain
• •langchain-openai
• •python-dotenv
• •An OpenAI API key in your environment or .env file
• •Basic familiarity with LangChain chat models and tools

Install the packages:

pip install langchain langchain-openai python-dotenv

Step-by-Step

1. •Start by setting up your environment and loading your API key from .env. This keeps secrets out of your code and makes local testing repeatable.

from dotenv import load_dotenv

load_dotenv()

import os

api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY is not set")
print("API key loaded")

2. •Create a simple tool the agent can call locally. For beginners, a calculator-style tool is enough to prove the agent can choose between answering directly and using a function.

from langchain_core.tools import tool

@tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b

print(multiply.invoke({"a": 6, "b": 7}))

3. •Build the agent with a chat model and attach the tool. The important part here is using create_tool_calling_agent, which gives you a modern agent setup that works well for local testing.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import create_tool_calling_agent, AgentExecutor

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = [multiply]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a precise assistant. Use tools when needed."),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

4. •Run a few local test prompts and inspect the output. Use one prompt that should trigger the tool and one that should not, so you can see both behaviors.

tests = [
    "What is 6 times 7?",
    "Explain why 6 times 7 equals 42 in one sentence.",
]

for query in tests:
    result = executor.invoke({"input": query})
    print("\nQUERY:", query)
    print("ANSWER:", result["output"])

5. •Add a small test harness so you can repeat checks while changing prompts or tools. This is where local testing becomes useful: you can verify expected behavior before integrating the agent into an API or UI.

def run_case(question: str) -> str:
    result = executor.invoke({"input": question})
    return result["output"]

cases = {
    "2 x 9": "18",
    "12 x 5": "60",
}

for question, expected in cases.items():
    answer = run_case(f"What is {question}?")
    print(f"{question} -> {answer}")
    assert expected in answer, f"Expected {expected} in response"

Testing It

Run the script from your terminal and watch for two things: the tool invocation log from verbose=True and the final response text. If the agent is wired correctly, multiplication questions should route through the tool instead of being guessed by the model.

If you want stronger verification, keep the assert checks in place and add more cases as you introduce new tools. For debugging agent behavior locally, this is usually enough to catch prompt mistakes, broken tool signatures, or unexpected model responses.

Next Steps

• •Add more tools, then test which ones the agent selects for different prompts.
• •Learn how to use LangSmith tracing to inspect intermediate steps.
• •Replace AgentExecutor with structured output tests once you need stricter validation for production workflows.

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.