Free lesson

State and boundaries of a local agent

State and boundaries of a local agent — LangGraph: a stateful local agent with review. The lab contract; Describe the state; Define observable transitions. Practical assignment: Practice: State and boundaries of a local agent.

Demo edition. The materials are undergoing editorial review.

Topics covered

  • The lab contract
  • Describe the state
  • Define observable transitions

The lab contract

We will build an agent that reads one of two fictional operational notes and prepares a preview. It sends no messages, executes no commands and connects to no model. A deterministic planner replaces inference, so identical requests produce identical routes. This separates orchestration, checkpointing and human review from model quality. LangGraph controls transitions between nodes; your code and runtime determine filesystem and network permissions. Create a separate directory, install the dependencies only if you intend to run the lab, and retain its lockfile. These are learner commands, not commands executed by the course author. The expected artifact is a small project with recorded dependency versions. If an import fails, check the supported Node version and installed package before changing documented API names. No provider key is required, so an unexpected credential prompt exposes an accidental external dependency.

mkdir langgraph-readonly-lab
cd langgraph-readonly-lab
npm init -y
npm install @langchain/langgraph @langchain/core zod
npm ls @langchain/langgraph @langchain/core zod

Describe the state

State defines the data contract between nodes. Save this module as state.mjs. The request holds an identifier and permitted topic, note contains the selected text, proposal holds the suggested output, digest binds that proposal to review, approved records the decision, and preview is the final educational artifact. Defaults distinguish an empty field from an omitted update. This uses the current StateSchema and Zod API. A node returns a partial update, such as only note, while other fields remain available. By default, a new field value replaces its previous value. Our graph is sequential and has no concurrent writers to the same field, so a custom reducer would add unnecessary complexity. We will separately validate external input before invocation. Keep credentials, open connections and file handles out of state: checkpoints need serializable task data that can survive reconstruction in another process.

// state.mjs
import { StateSchema } from '@langchain/langgraph';
import * as z from 'zod';
export const Request = z.object({
  id: z.string().regex(/^lab-[a-z0-9-]{1,32}$/),
  topic: z.enum(['backup', 'permissions'])
}).strict();
export const State = new StateSchema({
  request: Request,
  note: z.string().default(''),
  proposal: z.string().default(''),
  digest: z.string().default(''),
  approved: z.boolean().default(false),
  preview: z.string().default('')
});

Define observable transitions

Before implementing the graph, write an expectation table. A backup request selects the backup note; reading produces a proposal; execution pauses at review before creating a preview. Rejection ends the graph with an empty preview. Approval creates only a local preview string and never sends it to an external service. These observations become integration assertions in the final lesson. Separate request.id, the business task identifier, from thread_id, which addresses execution history. In a real service, an authenticated server must determine thread ownership rather than accepting arbitrary client identifiers. Include negative cases: an unknown topic is rejected, changed proposal content requires a new decision, and another thread cannot retrieve the first thread's state. The expected artifact lists each condition, next node and visible field. If no field makes a behavior observable, refine the contract before implementing the next node.

Practical assignment

Practice: State and boundaries of a local agent

Continue to learning

Course outline

  1. State and boundaries of a local agent
  2. Planner and read-only tool
  3. Graph and checkpoints
  4. Interrupt and human review
  5. State across process restarts
  6. Reproducible agent tests