Free lesson

Planner and read-only tool

Planner and read-only tool — LangGraph: a stateful local agent with review. A closed note catalog; The planner boundary; Bind review to proposal content. Practical assignment: Practice: Planner and read-only tool.

Demo edition. The materials are undergoing editorial review.

Topics covered

  • A closed note catalog
  • The planner boundary
  • Bind review to proposal content

A closed note catalog

A read tool needs a narrow data boundary. The catalog.mjs module contains two fictional notes directly in source. Request validates the selected topic, and readNote independently rejects an unknown key. A topic therefore cannot become an arbitrary filesystem path or URL. The function changes nothing and returns a plain string, making repeated reads safe in this example. Object.freeze prevents accidental table mutation in code; it does not provide operating-system isolation. If you later replace the catalog with files, add an allowed root, path validation and a user with read-only access. Repeated backup requests should return exactly the same text. An unknown topic should raise a controlled error rather than silently choosing the first note. Avoid adding network search as a fallback, because it would expand the data boundary beyond the contract being tested.

// catalog.mjs
const notes = Object.freeze({
  backup: 'Fictional note: stop the lab before copying its checkpoint database.',
  permissions: 'Fictional note: expose only the dedicated read-only lab directory.'
});
export function readNote(topic) {
  if (!Object.hasOwn(notes, topic)) throw new Error('Unknown note');
  return notes[topic];
}

The planner boundary

Create planner.mjs with a plan function. For now it returns an allowed key after validating Request. This is an actual local planner stub, not a fictional service call: the module contains no provider SDK, HTTP request or credential. A future model adapter could propose the same structure, but its response would still require validation before a tool runs. Shape validation does not establish factual accuracy or grant user authorization. Do not introduce a command field or arbitrary toolName when this graph needs neither. The decision is deliberately restricted to two topics and one reader. The expected plan result is either backup or permissions. If a future adapter returns explanatory prose instead of a key, reject it as invalid input rather than executing or interpreting the explanation. This keeps the execution boundary independent of how a proposal was generated.

// planner.mjs
import { Request } from './state.mjs';
export function plan(input) {
  const request = Request.parse(input);
  return request.topic;
}

Bind review to proposal content

Add prepare.mjs. It reads the permitted note, creates a proposal and computes SHA-256 over request.id plus the exact proposal string. The digest detects a review decision intended for different content. It is neither a digital signature nor identity verification: anyone who sees the data can calculate the same hash. A production server must authenticate reviewers outside the graph. The node returns only its updates and explicitly clears previous approval and preview fields. This prevents an old decision from carrying into a new preparation step on the same thread. Expect a nonempty proposal and a 64-character hexadecimal digest. Changing even one character invalidates the previous content binding. Use a new thread_id for a new business request; resuming an existing task should remain a separate operation. Never present a matching hash as evidence of reviewer authority.

// prepare.mjs
import { createHash } from 'node:crypto';
import { plan } from './planner.mjs';
import { readNote } from './catalog.mjs';
export function prepare(state) {
  const note = readNote(plan(state.request));
  const proposal = `Read-only lab summary: ${note}`;
  const digest = createHash('sha256')
    .update(JSON.stringify([state.request.id, proposal])).digest('hex');
  return { note, proposal, digest, approved: false, preview: '' };
}

Practical assignment

Practice: Planner and read-only tool

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