Ben Hickman
ask my work⌘KCtrl K
← All writing

3 October 2025· 5 min read· BJH

Getting started with Agentic AI using LangGraph and OpenAI

I’m excited to share agent-spec-lab, a modular Python project that demonstrates how to build a spec-driven, agentic system that answers FAQ-style queries over a local markdown knowledge base. The repo is public on GitHub

Below is a breakdown of what it does, how it works, and how you can use or extend it.

What is Agent Spec Lab?

At a high level, agent-spec-lab is a prototype framework / reference implementation showing how to:

  • Use LangGraph (a framework for graph-structured agents) to piece together retrieval and answer nodes.
  • Store knowledge in markdown files (in data/faq/) and retrieve relevant content.
  • Integrate with OpenAI’s chat models to generate the answer content.
  • Trace execution via LangSmith for observability and debugging.
  • Maintain a typed shared state using Pydantic models across the graph.
  • Enforce good engineering practices (tests, linting, formatting, type-checking) via CI.

In short: it is a “playground” or scaffold for someone who wants to explore how to build more complex, spec-driven multi-agent systems in Python.

Some notable parts:

  • cli.py provides a command-line interface (using Typer) so you can run queries easily.
  • state.py defines a Pydantic class or classes that encode the shared graph state (e.g. what has been retrieved, what context is active).
  • graphs/ & nodes/ contain logic for building the graph: nodes that retrieve, nodes that answer, etc.
  • tools/ has helper utilities, such as loading the markdown files, integrating with OpenAI, and wiring up LangSmith tracing.
  • data/faq/ contains one or more markdown files used as the content base: your agent answers FAQs over these.
  • tests/ holds Pytest tests to validate functionality.
  • The GitHub Actions CI config ensures that on each push, formatting (via Ruff / Black), linting, type-checking (via MyPy), and tests are run.

How to Use It

Here’s how to get started with agent-spec-lab (per README instructions)

Install dependencies

  • python -m venv .venv
  • source .venv/bin/activate
  • pip install -U pip
  • pip install -e .[dev]

Configure environment variables
Copy .env.example to .env and fill in required keys. At a minimum, it expects:

  • OPENAI_API_KEY
  • LANGCHAIN_TRACING_V2 (set to true to enable LangSmith tracing)
  • LANGCHAIN_API_KEY

Develop / extend

  • Add or update your markdown FAQ files in data/faq/.
  • Add more nodes or graph structure in graphs/ / nodes/ to handle more complex workflows or multiple agents.
  • Use the existing tests as templates to ensure new behavior is validated.
  • Monitor the traces via LangSmith to understand how queries traverse nodes.

Continuous integration
The repository’s .github/workflows/ci.yml ensures that every push triggers formatting checks, linting, type checking, and running tests.

What Makes It Interesting / Useful

Here are a few strengths and use cases:

  • Spec-driven architecture
    Rather than ad-hoc chains of prompts, the design encourages building with modular, typed nodes and clearly defined interfaces.
  • Local knowledge base
    Using markdown files means the content is version-controlled, editable, auditable, and easy to maintain.
  • Traceability and observability
    With LangSmith tracing built in, you can inspect how the agent decided on specific nodes or retrievals.
  • Extensibility to multi-agent flows
    Because of the modular graph-based layout, one can expand or branch into more complex orchestration (e.g. having multiple agents collaborate) beyond FAQ answering.
  • Good engineering hygiene
    The inclusion of tests, type-checking, linting, formatting, and CI from the start makes it a healthy scaffold to build on.

Limitations & Considerations

While agent-spec-lab is a strong starting point, here are some caveats and things to watch out for:

  • The knowledge base is limited to static markdown files. It doesn’t natively support dynamic sources (e.g. databases, APIs) out of the box.
  • It currently handles FAQ-style queries; more open-ended or generative dialog might require adapting the graph.
  • Costs & rate limits of OpenAI API apply; for heavier usage, one would need error handling, caching, rate limiting, etc.
  • The project is a “playground” rather than a polished production system, so you may need to augment it with robustness, security, and scaling features.

Ideas for Extensions & Experiments

Here are some possible ways you (or readers) might extend this:

  • Replace / augment markdown with other sources (e.g. JSON, SQLite, APIs) and implement nodes to ingest or query them.
  • Add a “summarize” or “context consolidation” node to compress multiple retrieved documents.
  • Branch into multi-agent patterns: e.g. a “planner” agent, a “retriever” agent, and a “writer” agent, all orchestrated in the graph.
  • Add caching layers or embedding index persistence to speed up repeated queries.
  • Build a web UI or server wrapper to serve queries over HTTP rather than via CLI.
  • Add more diagnostics or visualizations around trace paths or node activations via LangSmith.