---
title: "TypeScript SDK"
url: "https://docs.caracal.run/sdks/typescript/"
markdown_url: "https://docs.caracal.run/markdown/sdks/typescript.md"
description: "Public API reference for @caracalai/sdk."
page_type: "page"
concepts: []
requires: []
---

# TypeScript SDK

Canonical URL: https://docs.caracal.run/sdks/typescript/
Markdown URL: https://docs.caracal.run/markdown/sdks/typescript.md
Description: Public API reference for @caracalai/sdk.
Page type: page
Concepts: none
Requires: none

---

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

## Install

```bash
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. |

```ts
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

```ts
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](/sdks/verification-layer/) 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()`.

## Related pages

- [Integrate the TypeScript SDK](/guides/sdk-typescript/)
- [Verification Layer Overview](/sdks/verification-layer/)
- [Enforce, propagate, or attribute](/concepts/authority-model/#enforce-propagate-or-attribute)
- [Agent Delegation](/concepts/delegation/)
- [A2A Transport](/sdks/transport-a2a/)