LangChain Tutorial: Build Your First AI Agent
LangChain gives you a composable Python framework for connecting large language models to external tools, data sources, and multi-step reasoning workflows. This tutorial walks through every core concept: installing the libraries, composing your first chain with the LCEL pipe operator, wiring up tools, building a reasoning agent, adding conversation memory, orchestrating complex flows with LangGraph, and debugging everything with LangSmith. By the end, you will have a working agent that searches the web, reasons about results, and carries context across turns.
What you will build: A tool-calling agent that uses web search to answer questions, maintains conversation history, and logs every step to LangSmith for debugging.
Setup and Installation
Start by creating a project directory and a virtual environment. Isolating dependencies prevents version conflicts with other Python projects on your machine.
That single pip install pulls in the core LangChain library, LangGraph for stateful orchestration, and the OpenAI integration. Both LangChain and LangGraph are MIT licensed, so there is no cost for the framework itself. You will pay only for the LLM API calls your agent makes.
Next, set your API keys as environment variables. Never hardcode API keys in source files.
Load these variables at the top of your Python files with python-dotenv:
Your First Chain with LCEL
Before building an agent, understand how LangChain composes operations. The LangChain Expression Language (LCEL) lets you chain components together using the pipe operator (|). Each component receives the output of the previous one, creating a declarative pipeline.
A chain is a fixed sequence: prompt template goes in, formatted prompt feeds the model, model output gets parsed. No decisions at runtime, just data flowing through a pipeline.
The LCEL pipe operator is the foundation of everything in LangChain. Chains, agents, retrieval pipelines, and even LangGraph nodes use this same composition pattern. Once you internalize prompt | model | parser, every other concept builds on top of it.
Key insight: Chains are predictable and fast because the execution path is fixed at build time. Agents, which we build next, decide their own path at runtime.
Adding Tools
Tools are how agents interact with the outside world. A tool is a Python function with a name, a description (so the LLM knows when to use it), and typed inputs. LangChain includes built-in tools for web search, file operations, code execution, and dozens of API integrations. You can also define your own.
Built-in Web Search Tool
Custom Tool with the @tool Decorator
When built-in tools do not cover your use case, define a custom tool. The @tool decorator turns any Python function into something an agent can call. The function docstring becomes the description the LLM reads to decide whether to invoke it.
Tools can call external APIs, query databases, read files, execute code in sandboxes, or interact with any system your agent needs. The key constraint: every tool must have clear type hints and a descriptive docstring so the LLM can reason about when and how to use it.
Building an Agent
An agent is where LangChain stops being a pipeline and starts being a decision engine. Instead of following a fixed sequence, the agent uses the LLM to reason about which tool to call, evaluates the result, and decides whether to call another tool or return a final answer. This is the create_react_agent pattern: the LLM thinks, acts, observes, and repeats.
LangChain's create_react_agent function is the minimal harness that composes a model, tools, prompt, and middleware into a runnable agent. Under the hood, it builds a LangGraph that handles the think-act-observe loop.
When you run this, the agent will first call the search tool to find the latest LangChain release information, then call the calculate_cost tool to do the math, and finally synthesize both results into a coherent answer. You did not tell it which tool to call first. The LLM decided based on the question.
Adding Memory
Without memory, every agent invocation starts from scratch. The agent has no idea what you asked three messages ago. LangChain supports two categories of memory:
- Short-term memory keeps the conversation history within a single thread. The agent sees all previous messages in the current session.
- Long-term memory persists facts and context across conversations, stored in PostgreSQL, SQLite, or vector stores. Useful for agents that need to remember user preferences or past research.
For this tutorial, we will add short-term thread-scoped memory using LangGraph's built-in checkpointing. This is the simplest path to a conversational agent.
The thread_id is how LangGraph scopes memory. Different thread IDs create separate conversation histories. The same thread ID picks up where it left off. In production, swap MemorySaver() for PostgresSaver or SQLiteSaver so state survives application restarts.
Production note: MemorySaver stores state in RAM and is lost when your process exits. For any deployment beyond local development, use a persistent checkpointer backed by PostgreSQL or SQLite.
LangGraph Orchestration
The create_react_agent function covers most use cases, but when you need fine-grained control over execution flow, LangGraph lets you build the graph yourself. LangGraph models agent workflows as stateful graphs with nodes (functions) and edges (transitions). Unlike simple chains, graphs can have cycles, conditional branching, and human-in-the-loop interrupts.
Here is a minimal custom graph that routes between a search step and a summarization step based on what the user asks:
LangGraph also supports human-in-the-loop workflows via the interrupt() function. You can pause execution at any node to wait for human approval before continuing. This is critical for agents that perform actions with real-world consequences, such as sending emails or modifying databases.
The Deep Agents pattern builds on LangGraph by adding automatic context compression (to stay within token limits), virtual filesystem access, and the ability to spawn subagents for subtasks. Sandbox backends like Daytona, Modal, and Runloop provide secure execution environments for code-generating agents.
Testing and Debugging with LangSmith
Agents are nondeterministic. The same input can produce different tool-call sequences on different runs. This makes debugging significantly harder than with traditional code. LangSmith solves this by capturing a complete trace of every agent execution: the prompt sent to the model, the model's reasoning, which tools it decided to call, the tool outputs, and how it synthesized the final answer.
If you set the LANGSMITH_TRACING=true environment variable during setup, your agent is already logging traces. Open smith.langchain.com to see them.
What to Look for in a Trace
- Tool selection errors: The agent called the wrong tool, or called a tool when it should have answered directly. Fix: improve the tool description or add examples to the system prompt.
- Infinite loops: The agent keeps calling the same tool with the same input. Fix: set max_iterations on your agent or add a conditional edge in LangGraph that forces termination.
- Token budget overruns: Multi-step reasoning consumed more tokens than expected. Fix: use context compression or reduce the number of messages passed to each step.
- Hallucinated tool names: The agent tried to call a tool that does not exist. Fix: ensure all tools are properly registered and their names match what the model expects.
Every LangSmith deployment also exposes an MCP endpoint automatically, which means you can connect other tools and agents to your deployed agent using the Model Context Protocol.
Security reminder: Always sandbox code execution. Never let an agent run arbitrary code on your host machine. Use LangSmith Sandboxes, Daytona, Modal, or Runloop for production code execution. Apply least-privilege principles to every tool: give agents only the permissions they need, nothing more.
Next Steps
You now have a working LangChain agent with tool calling, conversation memory, and observability tracing. Here is where to go from here:
- Add retrieval-augmented generation (RAG): Connect a vector store (Chroma, Pinecone, pgvector) so your agent can search your own documents before answering.
- Build multi-agent workflows: Use LangGraph to create graphs where specialized agents hand off tasks to each other. A research agent finds information, an analysis agent evaluates it, and a writing agent produces the final output.
- Deploy with LangServe: Wrap your agent in a REST API using LangServe, which gives you streaming, batch endpoints, and a playground UI out of the box.
- Add guardrails: Implement input validation to reject prompt injection attempts. Add output validation to ensure your agent never returns sensitive information or harmful content.
- Set up evaluation: Use LangSmith's evaluation framework to create test datasets and automatically score your agent's responses against expected outputs.
Troubleshooting
Video Resources
Go Deeper
Resources from across Tech Jacks Solutions
Agent Frameworks Compared
Side-by-side analysis of LangChain, CrewAI, AutoGen, and more
FREEAgentic AI Compliance Assessment
Compliance checklist for autonomous agent deployments
Prompt Engineering Library
Prompting techniques that get better results from any AI
PREMIUMPre-Deployment Safety Gate
27-point checklist before any AI tool goes live
Model Context Protocol (MCP)
How MCP connects AI agents to external tools and data