LangChain Integration Guide

This is a deep integration manual for implementing MachineID into LangChain systems. It is intentionally extensive so it can serve as a single reference for: (1) designing enforceable validation boundaries, (2) modeling devices correctly, and (3) applying remote stop control across distributed execution surfaces.

Everything reduces to a single invariant:

Register. Validate. Work.

If validation fails, work does not begin.

In LangChain, “work begins” at recognizable edges: starting a worker, invoking an agent, calling a tool, and committing side effects. Your job is to choose these boundaries and enforce them consistently.

If your goal is to verify end-to-end enforcement quickly, use the official LangChain starter template. It demonstrates the canonical register/validate flow and hard-gate semantics.

A “device” is an identity representing an execution surface. It is not a machine fingerprint and it is not a secret. It is a stable label you assign so you can enforce limits and revoke execution surgically.

Enforcement without observability is operationally painful. A good device ID should be: stable enough to audit, specific enough to revoke, and readable enough to operate under pressure.

Validation belongs at execution boundaries — points where work begins or commits side effects. LangChain systems naturally contain these boundaries, but they are rarely treated as enforcement points.

• Startup boundary: before a runner/worker starts consuming work
• Invoke boundary: before chain.invoke() / agent.invoke()
• Tool boundary: before a tool call (external API, browse, DB query, queue publish)
• Side-effect boundary: before irreversible actions (writes, sends, payments, deletes)
• High-cost boundary: before entering fan-out, recursion, or batch loops

Revocation and org-wide disable become effective at the next validate. Validation frequency determines how quickly you can stop work.

Treat validation like a safety-critical call. Use short timeouts and fail closed. If permission cannot be confirmed, work should not proceed.

The Python SDK is the simplest and most maintainable integration surface: machineid-io/python-sdk.

pip install machineid-io

import os
from machineid import MachineID

m = MachineID.from_env()

device_id = os.getenv("MACHINEID_DEVICE_ID", "langchain:dev:runner:01")

m.register(device_id)

decision = m.validate(device_id)
if not decision["allowed"]:
    print("Execution denied:", decision.get("code"), decision.get("request_id"))
    raise SystemExit(1)

If you prefer a minimal dependency footprint, you can call the canonical endpoints directly. MachineID’s canonical entry points are POST register and POST validate using the x-org-key header.

POST https://machineid.io/api/v1/devices/register
Headers:
  x-org-key: org_...
Body:
  {"deviceId":"langchain:prod:runner:01"}

POST https://machineid.io/api/v1/devices/validate
Headers:
  x-org-key: org_...
Body:
  {"deviceId":"langchain:prod:runner:01"}

Wrappers let you add enforcement without refactoring the rest of your system. The goal is always the same: validate immediately before the boundary where work begins or side effects commit.

def must_be_allowed(m, device_id, boundary):
    d = m.validate(device_id)
    if not d["allowed"]:
        print(f"Denied at {boundary}:", d.get("code"), d.get("request_id"))
        raise SystemExit(1)
    return d

must_be_allowed(m, device_id, "invoke")
result = agent.invoke({"input": user_prompt})

def tool_call_with_gate(tool_fn, *args, **kwargs):
    must_be_allowed(m, device_id, "before_tool_call")
    return tool_fn(*args, **kwargs)

def commit_side_effect():
    must_be_allowed(m, device_id, "before_side_effect")
    perform_irreversible_action()

Device IDs should be stable enough to audit, but specific enough to revoke. A practical pattern:

langchain:{env}:{role}:{instance}

Examples:

• langchain:dev:runner:01
• langchain:prod:worker:07
• langchain:prod:event-consumer:04
• langchain:prod:cron-nightly:01
• langchain:prod:tool-runner:12

The free tier is enough to model real control boundaries. The objective is to prove: (1) identities are stable, and (2) revoke/disable stops execution at predictable checkpoints.

This tier supports multiple concurrent execution surfaces (replicas, consumers, and scheduled jobs) while keeping device identity manageable and readable.

At this scale, systems typically include autoscaling, per-tenant workflows, event-driven triggers, and fan-out patterns. The dominant requirement is consistent enforcement across many replicas and across time.

At the upper end of standard caps, the dominant failure mode is execution multiplication: retries, event storms, recursive workflows, and large numbers of simultaneous surfaces.

If you need device limits beyond standard tiers, MachineID supports custom device limits. This does not require changes to agent code — the identity model and enforcement boundaries remain the same.

MachineID provides a console at machineid.io/dashboard. The console exists outside your runtime so control does not depend on the process cooperating.

In addition to revoking individual devices, MachineID supports an org-wide disable control. This is a deliberate “stop everything” mechanism that changes validate outcomes across the org.

External control is specifically designed to work from outside the runtime environment: a different laptop, a phone, or a secure ops environment that has no access to the worker process.

Plans are enforced externally and take effect immediately for upgrades and downgrades. Device caps are enforced based on unique device IDs registered to the org.

These patterns defeat the purpose of external enforcement:

• Proceed anyway on validation timeout or error
• Continue for a fixed grace window while enforcement is unavailable
• Fallback to internal flags as an alternate authority path
• Validate only at startup for long-running, tool-heavy runs

Early LangChain deployments often run in a single process with a single agent. In that shape, internal flags and “stop buttons” can appear sufficient.

As systems become more agentic and distributed, execution surfaces multiply: more replicas, more consumers, more scheduled jobs, more tool-driven fan-out, and more long-running loops operating across time.

Internal flags and in-process kill switches rely on cooperation. As systems scale, cooperation becomes inconsistent: multiple services, multiple versions, multiple teams, and multiple execution surfaces.

The prompts below are designed to produce practical integration plans with minimal guesswork. Replace bracketed placeholders and paste into your LLM of choice.

I have a Python LangChain project and I want hard enforcement using MachineID.io

Context:
- My org key: [PASTE ORG KEY]
- My device ID pattern: langchain:{env}:{role}:{instance}
- Fail-closed policy, short timeout (1–3s)
- Validation boundaries required:
  1) Startup (register + validate)
  2) Before invoke (chain.invoke / agent.invoke)
  3) Before tool calls
  4) Before irreversible side effects

Please provide:
1) Exact files/locations to change
2) Copy/paste code blocks
3) Environment variables to add
4) A test plan:
   - revoke one device from dashboard
   - restore it
   - use org-wide disable
   - verify stops occur at the next validate

Help me model MachineID devices for my LangChain system.

Inputs:
- Execution surfaces: [describe: runners, workers, consumers, cron jobs, regions]
- Expected scale: [3 / 25 / 250 / 1000]
- I need readable device IDs and surgical revoke control.

Output:
- A proposed device ID scheme
- A list of device IDs for the target tier
- Where to validate (startup / invoke / tools / side effects)
- A minimal runbook for revoke + org-wide disable

I have a long-running LangChain agent loop that may run for hours.

Goal:
- Add MachineID validate boundaries inside the loop so I can stop it remotely.
- Fail closed on validation failure or timeout.

Please provide:
- Exactly where to place validation calls
- A wrapper pattern that is hard to forget
- A test plan using dashboard revoke and org-wide disable

• LangChain starter template: github.com/machineid-io/langchain-machineid-template
• Python SDK: github.com/machineid-io/python-sdk
• MachineID GitHub org: github.com/machineid-io
• Dashboard: machineid.io/dashboard
• Core enforcement guidance: Implementation Guide and Operational Guarantees
• Control plane rationale: External Identity Control Plane

← Back to Docs