Skip to main content
The Functional API wraps ordinary functions with LangGraph runtime features (persistence, memory, human-in-the-loop, and streaming). Use it when you already have existing code or are using a different framework and want to deploy it on LangSmith without rewriting that agent as a graph. Prefer the Graph API for building new agents. This page is the concept reference for entrypoints, tasks, checkpointing, and resume rules. For the wrap-and-deploy how-to, see Deploy other frameworks. The Functional API uses two building blocks:
  • @entrypoint: Marks a function as the start of a workflow. It manages execution, interrupts, and checkpointing.
  • @task: Marks a discrete unit of work (for example, an API call). Tasks return a future-like object that you can await or resolve with .result().

When to use the Functional API

Compared with the Graph API, the Functional API uses ordinary language control flow (if / else, loops, and calls), keeps values scoped to the entrypoint and tasks instead of a shared state schema, saves task results on the entrypoint checkpoint rather than after each super-step, and has no static graph visualization.

Entrypoint

The @entrypoint decorator creates a workflow from a function. It manages long-running work and interrupts.

Definition

Pass a checkpointer when you need persistence or human-in-the-loop. Identify each run with a thread_id in config. A thread is the durable identity for one conversation or workflow run. An entrypoint is a function decorated with @entrypoint. The function must accept a single positional argument as the workflow input. To pass multiple values, use a dictionary (or similar) as that argument. Decorating the function produces a workflow object (a Pregel instance). Call invoke or ainvoke to run it.
Serialization Entrypoint inputs and outputs must be JSON-serializable when a checkpointer is configured. See Serialization.

Run and resume

Call invoke or ainvoke for a final result. For streams, see Streaming. Resume after interrupt by passing a resume value in Command. For recipes, see Interrupts. After an error, resume the same thread_id with None.

Short-term memory

When an entrypoint has a checkpointer, successive invocations on the same thread id store state in checkpoints. Add a keyword-only previous parameter. LangGraph sets it to the last value saved on this thread. On the first run it is None. To save a different value for the next run, use entrypoint.final.

Injectable parameters

You can skip this until you add memory or custom streaming. When declaring an entrypoint, you can request additional parameters that LangGraph injects at runtime:
Declare injectable parameters with the appropriate name and type annotation.

Task

A task is a discrete unit of work (for example, an API call or data step). Tasks have two key properties:
  • Concurrent execution: Calling a task starts it immediately. The entrypoint blocks only when you wait for the result, so independent tasks can overlap.
  • Checkpointing: Task results are saved so resume can restore them. See persistence.

Definition

Define tasks with the @task decorator:
Serialization: Task outputs must be JSON-serializable to support checkpointing.

Execution

Call tasks only from an entrypoint, another task, or a Graph API node. Do not call them from application code outside the workflow. Calling a task returns a future immediately. Resolve it with .result() (sync) or await (async).

When to use a task

Use tasks when you need:
  • Checkpointing: Save a long-running result so resume does not recompute it.
  • Human-in-the-loop: Wrap work you should not redo after a pause in a task, for example an LLM call. Resume after an interrupt restores the result. For randomness, see Determinism.
  • Parallel execution: Run independent I/O-bound work concurrently.
  • Observability: Track discrete steps in LangSmith.
  • Retries: Apply retry policies to discrete units of work. See Fault tolerance.

Resume and checkpointing

Resume replay depends on serialization, determinism, and idempotency.

Serialization

Two rules apply when a checkpointer is configured:
  1. entrypoint inputs and outputs must be JSON-serializable.
  2. task outputs must be JSON-serializable.
Use Python primitives such as dictionaries, lists, strings, numbers, and booleans. Serialization is what makes task results and intermediate values restorable for human-in-the-loop, fault tolerance, and parallel execution. Non-serializable values raise a runtime error when a checkpointer is configured.

Determinism

Resume does not continue from the exact line where execution stopped. Execution returns to a checkpoint boundary and replays forward until it hits the pause again. For the Functional API, replay starts at the beginning of the entrypoint. LangGraph restores completed task and subgraph results from the checkpointer instead of recomputing them. That preserves step order across pauses, including for long-running or non-deterministic task outputs. For human-in-the-loop, put non-deterministic work (for example, random values) and side effects (for example, file writes or API calls) in tasks. Different runs can produce different results. Resuming a specific thread should replay the same persisted task and subgraph results. Guidelines:
  • Avoid repeating work: Give each side effect in an entrypoint its own task so resume restores outputs instead of re-running them.
  • Encapsulate non-deterministic operations: Keep values that change between attempts (random numbers, wall-clock time) inside tasks.
  • Use idempotent operations: For partial failures and retries, see Idempotency.

Idempotency

Idempotency means running the same operation more than once has the same effect as running it once. Place API calls and other writes inside tasks, and design those tasks to be safe if they run again. On resume, LangGraph restores completed task results. A task that started but did not finish may run again, so use idempotency keys or check existing results before writing.

Pause for human review

This workflow writes an essay and interrupts for human review:
Invoke with a topic such as "cat". The run writes the essay, then pauses at interrupt. The pause can last indefinitely. Resume starts at the beginning of the entrypoint. The write_essay task result is restored, not recomputed. For stream, resume, and tool-call review, see Interrupts.

Common pitfalls

Handling side effects

Put side effects (writing a file, sending an email) in tasks so resume does not run them again.
The file write runs in the entrypoint, so resume executes it a second time.

Non-deterministic control flow

Encapsulate time and randomness in tasks so resume returns the same values.
  • In a task: Get random number (5) → interrupt → resume → (returns 5 again) → …
  • Not in a task: Get random number (5) → interrupt → resume → get new random number (7) → …
With multiple interrupt calls, LangGraph matches resume values by index to each interrupt. If resume changes the order of interrupts, a resume value can attach to the wrong interrupt. See Determinism.
Reading the clock in the entrypoint can change which branch runs on resume.

Learn more