@runplane/runplane-sdk

Official SDK for the Runplane control plane — runtime governance for AI agent actions.

Runplane sits between your AI agents and execution. Every action passes through guard(), which enforces a decision before your code runs.

Installation

npm install @runplane/runplane-sdk

Quick Start (CommonJS)

require("dotenv").config()
const { Runplane } = require("@runplain/runplane-sdk");
const runplane = new Runplane({
  apiKey: process.env.RUNPLANE_API_KEY,
})

// guard() intercepts execution and enforces the decision
await runplane.guard(
  "transfer_funds",
  "finance-system",
  { fromAccountId: "acc_1", toAccountId: "acc_2", amount: 400 },
  async () => {
    return await executeTransfer()
  }
)

How It Works

guard() calls the Runplane API over the network before executing your handler:

Sends action + target + context to Runplane
Runplane evaluates policies and risk
Returns one of three decisions:
- ALLOW → handler executes immediately
- BLOCK → throws RunplaneError, handler never runs
- REQUIRE_APPROVAL → throws RunplaneError, awaits human decision

API Reference

`new Runplane(config)`

Create a new Runplane client.

const runplane = new Runplane({
  apiKey: "your_api_key",           // Required
  baseUrl: "https://runplane.ai",   // Optional, defaults to https://runplane.ai
})

`guard(action, target, context, handler)`

The primary integration method. Wraps your action with Runplane enforcement.

const result = await runplane.guard(
  "delete_record",           // action type
  "hr_system",               // target resource
  { employeeId: "emp_123" }, // context
  async () => {
    // Your code here - only runs if ALLOW
    return await deleteEmployee("emp_123")
  }
)

Returns: The result of handler() if decision is ALLOW.

Throws: RunplaneError if decision is BLOCK or REQUIRE_APPROVAL.

`decide(payload)`

Low-level method to request a decision without automatic enforcement.

const result = await runplane.decide({
  action: "send_email",
  target: "marketing_list",
  context: { recipients: 1200 },
})

console.log(result.decision) // "ALLOW" | "BLOCK" | "REQUIRE_APPROVAL"

Handling Decisions

const { Runplane, RunplaneError } = require("@runplane/runplane-sdk")

try {
  await runplane.guard("action", "target", {}, async () => {
    // ...
  })
} catch (err) {
  if (err instanceof RunplaneError) {
    if (err.code === "BLOCK") {
      console.error("Action blocked by policy")
    } else if (err.code === "REQUIRE_APPROVAL") {
      console.log("Waiting for human approval...")
      console.log("Request ID:", err.runplane.requestId)
    }
  }
}

Decision Types

Decision	Behavior
`ALLOW`	Handler executes immediately, result returned
`BLOCK`	Throws `RunplaneError` with code `"BLOCK"`
`REQUIRE_APPROVAL`	Throws `RunplaneError` with code `"REQUIRE_APPROVAL"`

Error Object

When guard() throws, the error includes:

{
  message: "Runplane blocked this action",
  code: "BLOCK",               // "BLOCK" | "REQUIRE_APPROVAL" | "API_ERROR"
  runplane: {                  // Full decision response
    decision: "BLOCK",
    reason: "Policy: destructive action on production database",
    requestId: "req_abc123",
    riskScore: 91,
  }
}

Requirements

Node.js 18+
Valid Runplane API key
Network access to https://runplane.ai

License

MIT