Why this matters: Turn a vague reimbursement agent into a bounded, testable workflow. Learners create a responsibility matrix, implement deterministic eligibility and approval gates in Python LangGraph, inject caller and dependency information through runtime context, and identify where LangChain middleware is useful—but not authoritative.

Three implementation paths compare a direct model call, a LangChain agent built on LangGraph, and an explicit state graph with increasing orchestration control.

What you will be able to do

  • Classify implementation data into instructions, runtime context, graph state, configuration, messages, checkpoints/threads, and long-term storage.
  • Create a responsibility matrix that marks which decisions are model-assisted versus deterministically enforced.
  • Implement a Python LangGraph path with explicit validation, policy routing, interrupt/resume, authorization, idempotency, and terminal states.
  • Use LangChain middleware appropriately for lifecycle interception while preserving a deterministic authorization boundary.

From vague request to enforceable boundary

Build decision: should the model be allowed to reimburse an employee?

No. The useful assistant behavior is conversational: extract facts from a receipt, explain policy, ask for missing data, and prepare a request. But eligibility, approver authority, payment submission, and duplicate prevention are system commitments. A model can propose facts; deterministic code must validate them against authoritative systems and decide whether an external side effect is permitted.

Use the current boundaries deliberately. LangChain’s Python create_agent is a high-level agent interface that runs on the LangGraph runtime; middleware runs inside that compiled graph. LangGraph is the layer to use when you need explicit state, nodes, edges, checkpoints, and pause/resume control. LangSmith tracing, evaluation, and LangSmith Deployment are separate optional services; open-source LangGraph execution does not require them. ([docs.langchain.com](https://docs.langchain.com/oss/python/langchain/runtime))

1. Define the contract before the prompt

Assumptions for this practicum: an authenticated employee belongs to one tenant; Finance approvers are authenticated by the host application; the payment gateway supports an idempotency key. These are design assumptions to verify with your organization, not guarantees supplied by LangChain or LangGraph.

  • Goal: produce a reimbursement decision and, only after qualified human approval, submit one payment request.
  • Non-goals: the agent cannot alter policy, select an approver, change bank details, or override a failed authorization check.
  • Trust boundaries: user text and receipts are untrusted; model output is untrusted; the authenticated principal, policy service, employee directory, and payment API are authoritative.
  • Allowed actions: read policy and employee entitlement; create a draft; request approval; submit a validated gateway command.
  • Success measures: 100% of gateway calls have a valid policy result, authenticated approver authorization, and idempotency key; 0 gateway calls occur on denied, unapproved, or malformed requests.
  • Escalation: unsupported receipt, ambiguous merchant/category, policy-service outage, missing approver role, or gateway uncertainty routes to a Finance queue—never to model improvisation.

2. Produce the responsibility matrix

Make every datum have one owner and one lifetime. Messages are the model-visible conversation. Configuration carries run controls such as thread_id, tracing tags, and recursion limit; it is not a safe substitute for authenticated identity. Runtime context is dependency injection for static run-scoped values. Graph state is mutable data that evolves through the workflow. A checkpointer persists snapshots of state for a thread; a Store is an explicit long-term, cross-thread key-value mechanism. ([docs.langchain.com](https://docs.langchain.com/oss/python/langchain/runtime))

Responsibility Owner/location Why
“Be concise; ask for missing receipt details” Instructions / LangChain prompt middleware Behavioral guidance, not a security control.
Caller ID, tenant ID, role claims, policy client, payment client Runtime context Immutable invocation-scoped dependencies; do not let the model write them.
Parsed amount, policy result, normalized request, approval result, gateway result Graph state Mutable workflow facts that nodes must inspect and update.
Thread ID, tags, recursion limit Runnable config Execution addressing and controls, not business authorization.
Approval pause and state history Checkpointer/thread Thread-scoped checkpoint durability and resume.
Employee preferences retained across requests Store or application database Explicit cross-thread persistence with its own retention/access policy.
Eligibility, authorization, currency/amount validation, idempotency, submit Deterministic nodes/application services Must not depend on model compliance.

Implementation practicum: explicit state, route, pause, submit

3. Wire a bounded LangGraph workflow

Start with a graph rather than a free-form agent because the critical paths are finite and inspectable: validate → policy decision → interrupt for review → authorize → submit or escalate. A LangGraph node receives state and may receive a Runtime containing context, Store, stream writer, and execution information. Graph nodes are re-executed from the start after an interrupt or retry, so make side effects idempotent. ([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/graph-api))

from dataclasses import dataclass
from typing import Literal
from typing_extensions import TypedDict

from langgraph.graph import StateGraph, START, END
from langgraph.runtime import Runtime
from langgraph.types import Command, interrupt
from langgraph.checkpoint.memory import InMemorySaver

@dataclass(frozen=True)
class RequestContext:
    employee_id: str
    tenant_id: str
    # Least-privilege application wrappers, not raw credentials:
    policy_service: object
    payment_gateway: object

class RefundState(TypedDict, total=False):
    request_id: str
    amount_cents: int
    currency: str
    category: str
    policy_status: Literal["eligible", "ineligible", "manual_review"]
    approval: Literal["approved", "rejected"]
    payment_id: str
    escalation_reason: str

def validate_request(state: RefundState):
    if state.get("amount_cents", 0) <= 0 or state.get("currency") != "USD":
        return {"escalation_reason": "Invalid amount or unsupported currency"}
    return {}

def policy_check(state: RefundState, runtime: Runtime[RequestContext]):
    result = runtime.context.policy_service.evaluate(
        employee_id=runtime.context.employee_id,
        tenant_id=runtime.context.tenant_id,
        amount_cents=state["amount_cents"], category=state["category"],
    )
    return {"policy_status": result.status}

def route_after_policy(state: RefundState):
    if state.get("escalation_reason") or state["policy_status"] == "manual_review":
        return "escalate"
    return "approval" if state["policy_status"] == "eligible" else "reject"

def approval_node(state: RefundState):
    # The UI must bind the eventual resume to an authenticated Finance user.
    decision = interrupt({"request_id": state["request_id"],
                          "amount_cents": state["amount_cents"],
                          "action": "approve_refund"})
    if decision not in {"approved", "rejected"}:
        return {"escalation_reason": "Malformed approval response"}
    return {"approval": decision}

def authorize_and_submit(state: RefundState, runtime: Runtime[RequestContext]):
    # Application code must independently verify authenticated approver role/scope.
    # Gateway must deduplicate using this stable key.
    key = f"refund:{runtime.context.tenant_id}:{state['request_id']}"
    payment_id = runtime.context.payment_gateway.submit_refund(
        idempotency_key=key, employee_id=runtime.context.employee_id,
        amount_cents=state["amount_cents"], currency=state["currency"],
    )
    return {"payment_id": payment_id}

builder = StateGraph(RefundState, context_schema=RequestContext)
builder.add_node("validate", validate_request)
builder.add_node("policy", policy_check)
builder.add_node("approval", approval_node)
builder.add_node("submit", authorize_and_submit)
builder.add_node("reject", lambda s: {"escalation_reason": "Policy denied"})
builder.add_node("escalate", lambda s: s)
builder.add_edge(START, "validate")
builder.add_edge("validate", "policy")
builder.add_conditional_edges("policy", route_after_policy,
    {"approval": "approval", "reject": "reject", "escalate": "escalate"})
builder.add_conditional_edges("approval",
    lambda s: "submit" if s.get("approval") == "approved" else "reject",
    {"submit": "submit", "reject": "reject"})
for node in ("submit", "reject", "escalate"):
    builder.add_edge(node, END)

graph = builder.compile(checkpointer=InMemorySaver())  # exercise only

Invoke with a thread address in config and identity/dependencies in context. In production, replace the in-memory saver with a durable, appropriately secured checkpointer. A checkpointer records thread-scoped state snapshots; it does not automatically make unrelated application data long-term memory. ([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/persistence))

config = {"configurable": {"thread_id": "refund-req-482"}, "recursion_limit": 20}
result = graph.invoke(
    {"request_id": "482", "amount_cents": 12_500,
     "currency": "USD", "category": "lodging"},
    config=config,
    context=RequestContext(employee_id="emp-7", tenant_id="acme",
                           policy_service=policy_service,
                           payment_gateway=payment_gateway),
)
# On interrupt, authenticate the reviewer in your API/UI, then resume:
graph.invoke(Command(resume="approved"), config=config, context=review_context)

Important implementation gap to close: the sample makes the resume value visible to the node, but your API must authenticate the reviewer and the deterministic authorization layer must verify that reviewer’s role and tenant scope. Do not trust "approved", a client-supplied user ID, or an LLM statement as authorization evidence.

Middleware, testing, observability, and handoff

4. Use middleware as an interceptor—not a policy engine

For a LangChain create_agent used to collect or explain reimbursement details, middleware is the right place to inject tenant-specific guidance, trim messages, filter an otherwise registered tool list, log safe metadata, or validate model output before continuing. Python middleware can access runtime through node-style hooks or through ModelRequest.runtime in wrap-style hooks. Middleware state updates merge into agent state, so document custom fields and test hook ordering. ([docs.langchain.com](https://docs.langchain.com/oss/python/langchain/runtime))

from langchain.agents.middleware import ModelRequest, ModelResponse, wrap_model_call
from collections.abc import Callable

@wrap_model_call
def restrict_tools_for_role(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse],
) -> ModelResponse:
    role = request.runtime.context.role
    safe_tools = [lookup_policy, create_refund_draft]
    # Do not expose payment submission to ordinary employees.
    if role == "finance_operator":
        safe_tools.append(get_refund_status)
    return handler(request.override(tools=safe_tools))

This reduces accidental tool selection and prompt exposure, but it is defense in depth. The tool itself must still authenticate/authorize each call and validate inputs server-side. Keep the actual gateway submit operation behind the deterministic graph node or a capability whose own service enforces authorization and idempotency.

Python/JavaScript note: both current ecosystems expose runtime context and LangGraph persistence/interrupt concepts. Python uses create_agent, context_schema, dataclass-style context, and decorators such as @wrap_model_call; JavaScript uses createAgent, contextSchema, and Zod schemas/create-middleware patterns. Do not copy Python imports or signatures into TypeScript as if the APIs were identical. ([docs.langchain.com](https://docs.langchain.com/oss/python/langchain/runtime))

5. Test paths, then operate the system

  1. Eligible + approved: one interrupt, then exactly one gateway call with the expected idempotency key and payment ID.
  2. Eligible + rejected: terminal rejection; zero gateway calls.
  3. Invalid input / ineligible / policy outage: escalation or rejection; zero gateway calls; a readable reason exists in state.
  4. Resume or retry after submit uncertainty: call the submit path again with the same request ID and assert that the gateway returns the existing payment rather than causing a second payment.
  5. Cross-tenant attempt: employee, approver, or request tenant mismatch is rejected before policy lookup or payment.

Use local unit tests with fake policy and gateway wrappers; inspect get_state/get_state_history during graph debugging when a checkpointer is configured. LangGraph’s native execution provides tracing/debugging hooks; LangSmith can optionally collect traces and support evaluation. Protect traces and checkpoints as potentially sensitive operational data—redact or omit payloads where appropriate. ([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/graph-api))

For deployment terminology, the current product name is LangSmith Deployment, whose runtime is Agent Server. LangGraph/LangChain applications can be deployed with the LangGraph CLI; Agent Server’s execution model includes assistants, threads, and runs. Deployment does not remove your responsibility to provide database/storage configuration, authentication, retention, network controls, secret management, and idempotent downstream services. ([docs.langchain.com](https://docs.langchain.com/langsmith/deployment))

Close-out and sources

Key takeaways

  • Prompt instructions influence behavior; they do not enforce permissions or invariants.
  • Put static identity and dependencies in runtime context, mutable workflow facts in state, thread history in checkpoints, and cross-thread information in an explicit Store/database.
  • Make side-effecting nodes idempotent because retries and interrupt resumes can re-run node code.
  • Use middleware for lifecycle customization and least-privilege tool exposure; retain authoritative policy in deterministic services and graph routing.
  • Ship only after path-based tests demonstrate that all denied, malformed, duplicate, and unauthorized routes produce zero payment calls.

Source list

  • LangChain Python Runtime documentation: runtime context, tools, middleware, execution/server information. ([docs.langchain.com](https://docs.langchain.com/oss/python/langchain/runtime))
  • LangGraph Python Graph API: state, runtime, config, conditional routing, and re-execution/idempotency. ([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/graph-api))
  • LangGraph Python Persistence and Interrupts documentation: checkpoints, threads, stores, pause/resume requirements. ([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/persistence))
  • LangChain Python Custom Middleware documentation: wrap hooks, dynamic tool filtering, trace policy guidance. ([docs.langchain.com](https://docs.langchain.com/oss/python/langchain/middleware/custom))
  • LangSmith Deployment and LangGraph CLI documentation: current deployment/runtime and CLI terminology. ([docs.langchain.com](https://docs.langchain.com/langsmith/deployment))

Practicum: Design a Refund Agent That Cannot Pay Without Proof

Scenario: You are building an internal “Expense Refund Assistant.” It may explain policy and draft a reimbursement request, but it must never submit a payment directly. Finance staff must approve any eligible reimbursement before a separate payment service receives a validated, idempotent command. The vague product request says: “Let employees ask the bot to reimburse travel expenses quickly.”

Work in pairs for 45–60 minutes. First, write the scope and responsibility matrix for the refund request. Second, implement the graph skeleton with fakes for the policy service and payment gateway. Third, force the graph down four paths: approved, rejected, invalid, and duplicate/retry. Capture the state and gateway-call log for each. Finally, hand the matrix, graph contract, test results, and operational risks to another pair; they should be able to identify every action boundary without reading your prompt.

Self-review checklist

  • Write a one-page scope: user, goal, non-goals, trust boundary, allowed actions, success metric, and escalation conditions.
  • Fill in the responsibility matrix before writing prompts.
  • Implement `policy_check` and `authorize_and_submit` as deterministic nodes; make their inputs and outputs typed state fields.
  • Pass caller identity, tenant, and service wrappers in `context`; pass `thread_id` through `configurable` configuration.
  • Add a durable production checkpointer before relying on approval/resume behavior; use `InMemorySaver` only for the exercise/test loop. ([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/persistence))`,`Use an idempotency key derived from a stable request identifier and test a resumed/duplicated submit path.`,`Trace the normal, rejection, approval, and duplicate-request paths; assert that only the authorized approved path invokes the payment gateway.`,`Document retention and access rules for checkpoints, Store data, traces, and external records before deployment.

Module capstone: apply the module in the AI Agentic School Decision Lab below. Mastery unlocks the LearnDash completion control for this topic.

AI Agentic School Decision Lab

Please sign in to submit your module decision and receive feedback.

Key takeaways

  • Treat authorization, money movement, recipient validation, idempotency, and approval eligibility as deterministic application/graph logic—not as prompt-following tasks.
  • Use runtime context for immutable invocation-scoped dependencies and identity; use graph state for mutable workflow facts; use checkpoints/threads for thread-scoped durability; use a Store or application database for explicitly designed cross-thread data.
  • Use LangChain middleware to shape or intercept agent lifecycle behavior, but make a LangGraph node/edge the authority for high-consequence decisions and terminal routes.
  • An interrupt is not a transaction boundary: a resumed node runs from its beginning, so side effects before an interrupt must be idempotent.
  • LangChain `create_agent` is the high-level agent API; LangGraph supplies explicit orchestration, state, persistence, interrupts, and routing; LangSmith services are optional observability/evaluation/deployment infrastructure.

Useful terms

Runtime context
Static, invocation-scoped dependencies and metadata passed to LangGraph/LangChain runtime code, such as identity, tenant, service clients, and configuration.
Graph state
Typed, mutable workflow data read and updated by nodes as a graph executes.
Checkpointer
A persistence component that saves thread-scoped graph state snapshots (checkpoints), enabling resume, state history, and fault-recovery patterns.
Thread
The identifier and accumulated checkpoint history for a stateful graph interaction sequence.

Research & review note

This lesson is built from source-traceable research and reviewed before publication. AI Agentic School uses AI as a research and practice tool, not as a substitute for evidence or editorial judgment.

Sources & further reading