Skip to content

TypeScript SDK

@caracalai/sdk is the main TypeScript package for agent lifecycle, delegation, Gateway routing, and Caracal context propagation.

Install

npm install @caracalai/sdk

The package is ESM-only and targets Node >=22. To consume it from a CommonJS project, use a dynamic await import('@caracalai/sdk') or set "type": "module" in your package.json.

Connect and Configure

API	Use it when
`new Caracal()`	You want auto-detection from explicit options, `CARACAL_CONFIG`, the default profile, or environment variables.
`Caracal.fromEnv()`	You want environment-only startup.
`Caracal.fromConfig(path)`	You want to load a runtime profile.
`Caracal.fromClientSecret(options)`	You want service-root token refresh through STS client-secret exchange.

import { Caracal } from "@caracalai/sdk";

const caracal = new Caracal();

Core methods

Method	Purpose
`spawn(fn, options?)`	Create an agent session and bind context while `fn` runs; pass `grant: Grant.narrow(...)` to bound the child’s authority.
`spawnService(options?)`	Start a long-lived service agent; returns a handle with `heartbeat()` and `close()`. Pass `grant: Grant.narrow(...)` to bound the handle’s authority.
`delegate(options, fn)`	Create a delegation edge to an existing agent session.
`headers(options?)`	Project the current bound context into HTTP headers synchronously.
`headersAsync(options?)`	Project headers when a root token may require async refresh.
`bindFromHeaders(headers, fn, options?)`	Bind inbound Caracal envelope headers to the current async context.
`transport(options?)`	Return a fetch-compatible function that injects Caracal headers and Gateway routing.
`gatewayRequest(resourceId, path?)`	Build a Gateway URL and `X-Caracal-Resource` header.
`current()`	Return the currently bound `CaracalContext`, if present.

Context Propagation

import { Grant } from "@caracalai/sdk";

await caracal.spawn(async () => {
  await fetch("https://api.example.com/tickets", {
    headers: await caracal.headersAsync(),
  });
}, {
  grant: Grant.narrow(["tickets:read"], {
    resourceId: "https://api.example.com/tickets",
    constraints: {
      maxHops: 1,
      budget: 5,
      policyApproved: true,
    },
    ttlSeconds: 600,
  }),
});

DelegationConstraints uses camelCase fields: resources, maxDepth, maxHops, ttlSeconds, budget, policyApproved, expiresAt, and broadReason.

Protect Inbound Requests

Use bindFromHeaders() to propagate a Caracal context after an upstream Gateway, connector, or transport verifier has accepted the inbound mandate. Use Verification Layer Overview when the TypeScript service must enforce mandate signatures, scopes, targets, agent identity, delegation, or revocation at its own boundary.

Header and transport helpers refuse to fall back to the application root token unless you pass { allowRoot: true }. Use that option only for trusted service-root ingress or setup calls. Normal agent work should run inside spawn(), delegate(), or bindFromHeaders().