LangChain & LangSmith Workshops

Hands-on notebooks for learning to build agents with Deep Agents and to evaluate them with LangSmith. Every lesson opens in Google Colab and runs top to bottom.

The teaching approach is whole game first: lesson 01 builds a working research agent in about ten lines of code, and the lessons after it take that agent apart one layer at a time. No theory before anything runs.

Before you start

You need one thing: a LangSmith API key. No OpenAI key, no Anthropic key, no credit card, nothing installed locally — models are served through the LangSmith gateway, so a single key covers models, tracing, and Studio for all 17 notebooks.

Prefer your own machine to Colab? Running locally is one uv sync.

Start here → 00 · Setup and preflight

Run it a few days before the workshop, not on the morning of. It checks five things and tells you exactly what to fix if any of them fail — and one of the checks can fail for reasons only a workspace admin can resolve.

Part 1 — Building agents

	Lesson	You build	Key ideas
01	The whole game	a research assistant	create_deep_agent, the harness, tracing, Studio
02	Files as a workspace	the same agent, four ways	context offloading, State/Store/Filesystem/Composite backends
03	Tools	a customer support agent	@tool, docstrings as prompts, error messages, return shape
04	MCP servers	a docs search agent	MultiServerMCPClient, tool budgets, untrusted tool text
05	Subagents	a research team	context isolation, per-subagent tools and models
06	Middleware & HITL	a production support agent	retries, summarization, PII, custom middleware, approvals
07	Memory	an assistant that learns	AGENTS.md, /memories/, namespaces, per-user scoping
08	Skills	a report writer	SKILL.md, progressive disclosure, bundled files
09	Sandboxes	an analyst with a real computer	LangSmithSandbox, execute, serving an artefact you can click
10	Interpreters & PTC	a support analyst that never sees PII	CodeInterpreterMiddleware, ptc=[...], the interpreter as a boundary
11	Under the hood	(nothing new)	create_agent equivalence, LangGraph, checkpointers, time travel

Part 2 — Evaluating agents

Part 2 evaluates one shared deployment, and the organising idea is that an evaluator is a thing you store in LangSmith, not code that lives in your test suite — which is what lets the same check score an experiment today and production traffic at 3am.

	Lesson	You build	Key ideas
12	Deploy it	a real deployment	langgraph.json, the langgraph CLI, LangSmith Deployments, RemoteGraph
13	Datasets from real traffic	your first dataset	traces → examples, splits, versions, a rule that grows a dataset
14	Evaluators that live in LangSmith	stored evaluators	perform_eval, hub-stored judges, rules, retro-scoring an experiment
15	Testing the path	trajectory metrics	path assertions, agentevals match modes, negative assertions
16	Online evals	a production loop	rules on live traffic, backfills, annotation queues, judge alignment
17	Evals in CI	a pytest suite + Actions	smoke vs nightly, baselines, what deserves to block a merge

How the notebooks work

• Self-contained. Each notebook creates everything it needs. No cloning, no downloads, no imports from this repo — open the .ipynb in Colab, add one secret, run.
• Standalone. Lessons build on each other conceptually but not technically. You can open lesson 07 without having run 01–06.
• Key takeaways. Each lesson ends with the points worth remembering, most of which are things that only become obvious after they have bitten you once.

Running locally

Colab is the intended environment, but every lesson runs the same way on your machine. You need uv and nothing else:

git clone https://github.com/langchain-samples/lc-colab-workshops
cd lc-colab-workshops

uv sync                       # the notebook stack, pinned to the same versions Colab installs
cp .env.example .env          # then paste your key into LANGSMITH_API_KEY
uv run jupyter lab notebooks

The setup cell notices there is no Colab and adapts: it skips the %pip install — uv sync has already done it, and a uv venv has no pip to call — and reads the key from .env via python-dotenv instead of Colab Secrets. A missing key raises right there, in the cell that is about the key. Every path in the lessons is relative, so files land beside the notebook rather than in /content.

The gateway key

Model calls go through the LangSmith gateway, which accepts a key of its own: LANGSMITH_GATEWAY_API_KEY. It is optional — leave it unset and the gateway is called with LANGSMITH_API_KEY, which is what a workshop does. Set it (in .env, or as a second Colab secret) only if your workspace issues a separate key for models. Either way LANGSMITH_API_KEY remains the credential for tracing, datasets, and deployments.

For maintainers

uv sync --group dev && uv run lefthook install

Git hooks then strip notebook outputs, run Ruff and ty, lint every notebook, and scan for credentials on each commit. See CONTRIBUTING.md for the notebook conventions.