Graph API vs Functional API

LangGraph has two APIs: the Graph API (StateGraph with nodes and edges) and the Functional API (@entrypoint + @task). Both share the same runtime. This article helps you pick the right one for your use case.

Quick Reference

→Graph API = declarative: define nodes, edges, shared TypedDict state — best for complex branching and parallel execution
→Functional API = imperative: plain Python functions with @entrypoint and @task — best for linear workflows and existing code
→Both share the same runtime: checkpointing, streaming, human-in-the-loop, and memory work identically
→You can combine them: call an @entrypoint from a StateGraph node, or call a compiled graph from inside a @task
→Default choice: start with Functional API for simplicity; migrate to Graph API when you need cycles or complex routing

Quick Decision Guide

Use Graph API when you need	Use Functional API when you want
Complex workflow visualization for debugging	Minimal changes to existing procedural code
Explicit shared state across multiple nodes	Standard control flow (if/else, loops, function calls)
Conditional branching with multiple decision points	Function-scoped state without explicit management
Parallel fan-out/fan-in execution (Send API)	Rapid prototyping with less boilerplate
Team collaboration with visual graph documentation	Linear workflows with simple branching logic

Same runtime — not a tradeoff

This isn't a tradeoff between power and simplicity. Both APIs are equally capable and share the same underlying Pregel runtime. The choice is purely about code style: declarative graph structure vs imperative Python functions.

When to Use the Graph API

The Graph API uses a declarative approach where you define nodes, edges, and shared state as a TypedDict. The structure is explicit — you can visualize it, step through it in Studio, and reason about execution paths upfront.

When to Use the Functional API

The Functional API uses an imperative approach with @entrypoint and @task decorators. You write plain Python — if/else, for loops, function calls — and LangGraph adds persistence, streaming, and human-in-the-loop behind the scenes.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.