Agent SDK reference - Stigg Documentation

The Stigg Agent SDK is in public beta and its API may change before general availability.

Installation

npm install @stigg/agent-sdk-js

Requires Node.js 22 or later. The package does not depend on any LLM vendor SDK: install only the vendor clients you use.

How it connects to Stigg

The Agent SDK builds on two Stigg clients and picks one for each operation. You never call either of them directly.

Operation	Client	API
A check that names an agent or other dimensions	`@stigg/typescript`	REST `v1-beta` (Governance)
A check with no agent or dimensions	`@stigg/node-server-sdk`, through its entitlement cache	GraphQL
Reporting usage	`@stigg/node-server-sdk`	GraphQL
`register()` and `deregister()`	`@stigg/typescript`	REST `v1-beta` (Governance)

On an account without Governance, the SDK uses the Node server SDK alone, at customer level. For caching, see Caching and accuracy. For concepts, see LLM and gateway wrappers and Agent governance.

StiggAgentSDK

import { StiggAgentSDK } from '@stigg/agent-sdk-js';

const stigg = new StiggAgentSDK(options?);
const stigg = new StiggAgentSDK(apiKey, options?);   // shorthand

Create one instance per Stigg environment and share it. The constructor is synchronous and makes no network calls. The connection to Stigg is set up on the first call that needs it, or up front with init(). If it fails, for example because Stigg is briefly unreachable, a later call tries again after a short wait, so the SDK recovers without a restart. For example, new StiggAgentSDK({ apiKey, baseUrl: 'https://stigg.internal', ingest: 'sync' }). The shorthand takes the API key first and the other options second, for example new StiggAgentSDK(apiKey, { ingest: 'sync' }).

StiggAgentSDKOptions

Optional settings. Every one has a working default.

Show options

string

A Stigg server API key. Omit it to read the STIGG_SERVER_API_KEY environment variable.

string

The Stigg API URL, for an environment other than the hosted API, such as a self-hosted Stigg. With a baseUrl and no key in either place, the SDK runs without a key, for example against a local stand-in.

CacheOptions

How entitlement checks are cached, passed straight to the Node server SDK, for example { redis: { host, port, environmentPrefix } }. See Caching and accuracy. Cannot be combined with client.

Stigg

A Node server SDK client your application already has, used instead of building a new one. The Agent SDK never closes a client you pass in. Cannot be combined with cache.

'allow' | 'deny'

default:"'allow'"

What a call does when a check cannot complete, for example because of a network error. See Fallback strategy.

'async' | 'sync'

default:"'async'"

How usage is reported by default. See Ingest modes.

number

default:"3000"

Timeout for requests to Stigg, in milliseconds.

'console' | 'none' | Logger

default:"'console'"

Where the SDK logs what it did. Pass 'none' to silence it, or your own logger.

(error: EngineError, context: ErrorContext) => void

default:"logs a warning"

Receives every failure the SDK does not throw: failed usage reports, calls whose usage could only partly be measured, and a failed connection to Stigg started in the background by wrap() (with operation: 'start'). context has operation, customerId, idempotencyKey and runId.

number

Deprecated and ignored. The SDK no longer caches decisions itself, and logs a warning when this is set.

Methods

In the order you typically use them: wrap a client, register an agent, check and report anything a wrapped client does not cover, read the summary, flush before the process exits, and deregister agents you no longer need.

wrap

const governed = stigg.wrap(client, options?);

Returns a new client that behaves like client. Every model call it makes is checked before the call (when the context sets entitlement) and its usage is reported after it. The client you passed in is not changed. Synchronous. Each covered method also accepts a stiggContext field in its own parameters, which overrides the client’s default for that call. A client wrapped with no customerId can serve every customer, and then each call must name its own.

object

required

The LLM or gateway client to wrap, for example new Anthropic(). See Supported providers.

ClientOptions

Show options

StiggContext

The default context for every call through this client.

ClientRecipe

The recipe to use instead of automatic recognition. Required for LiteLLM Proxy and for your own vendors.

{ onDecision?, onIngest? }

onDecision is called with every decision this client makes. onIngest is called with every ingest result, including failures.

WrappedClient

The wrapped client. It also has a stigg property with these members:

Show governed.stigg

Promise<AccessDecision>

Checks access without making a call, using the client’s context plus any overrides. See check.

Promise<IngestResult>

Reports usage this client did not observe. See report.

SessionSummary

What this client has done so far. See summary.

Promise<SessionSummary>

Waits for this client’s pending reports, then returns its summary.

Promise<void>

Flushes, then releases the client.

GovernanceHeaders

The x-stigg-* headers for a gateway you operate.

AccessDecision | undefined

The most recent decision this client made.

Throws if no recipe matches the client, or if the client is already wrapped. A call through the wrapped client throws if its stiggContext has a field the SDK does not recognize, such as a misspelled agentId, rather than ignore it.

register

const agentId = await stigg.register(input);

Creates or updates an agent in Governance: its entity and, optionally, its budget and parent. For how to use it, see Agent governance.

string

required

The customer that owns the agent.

string

required

Your stable ID for the agent.

string

required

The Governance entity type to create it as, for example agent. It must already exist. See Setting up governance.

string

A readable name for the agent, shown in the Stigg app instead of its ID.

Record<string, string>

Your own key-value data to store on the agent’s entity, for example { owner: 'research-lead' }. Values must be strings. See Entities.

AgentBudget

The agent’s budget and place in the tree for one credit currency or metered feature (a Governance assignment). Omit it to save only the agent’s entity.

Show budget

{ currencyId } | { featureId }

required

The credit currency or metered feature the budget is set for.

number | null

The budget. A number caps usage, and null tracks usage without blocking. Omit it to leave the current value.

'always' | 'on-create'

default:"'always'"

When limit is saved. 'always' saves it on every call. 'on-create' saves it only if the agent has no budget for this entitlement yet, so a limit an admin changed in the Stigg app is not overwritten on every deploy. With 'on-create', limit is required and must be a number.

string | null

The parent entity for this entitlement. Omit it to leave the current parent, or pass null to make the agent a root.

string

How often the budget resets, as an ISO 8601 duration: PT1H, P1D, P7D or P1M. Required when a budget is created. See Cadence.

Promise<string>

The agent ID you passed in.

Throws GovernanceNotEnabledError when the input sets a budget and Governance is not enabled on the account. Without a budget, it logs a warning instead and returns.

check

const decision = await stigg.check(context, requestedUsage?);

Checks whether a customer or agent has access, without making a model call. Use it for actions a wrapped client does not cover, such as a tool call, or to check before an agent starts a task. See Gating actions that are not model calls.

StiggContext

required

Who the check is for and what it is checked against. Must include customerId and entitlement. See StiggContext.

number

default:"1"

How much the action is about to use. See Requested usage.

Promise<AccessDecision>

The decision. When access is denied, check() returns a decision with hasAccess: false rather than throwing an AccessDeniedError, so you can branch on it directly.

report

const result = await stigg.report(context, metrics);

Reports usage directly. A wrapped client reports the usage of model calls for you. Use this for usage it cannot see, such as the number of searches a tool made.

StiggContext

required

Who the usage is attributed to. Must include customerId. See StiggContext.

Record<string, number>

required

The usage to report, keyed by Stigg feature or credit currency ID, for example { 'feature-web-searches': 1 }.

Promise<IngestResult>

The ingest result. A failed report does not throw: the result has ok: false, and the error is passed to onError.

summary

const summary = governed.stigg.summary();

A method of each wrapped client, not of the SDK instance. Returns what that client has done so far, without waiting for pending reports. To wait for them first, use flush.

SessionSummary

Show properties

number

How many checks the client made.

number

How many usage reports it sent.

number

How many usage reports failed, including calls whose usage could only partly be measured, such as a Gemini call with automatic function calling.

Record<string, number>

Everything the client reported, summed per feature or currency ID. This is what it sent, not what was billed.

AccessDecision | undefined

The most recent decision.

flush

await governed.stigg.flush();            // one wrapped client
await stigg.flush({ close: true });      // every client, then release connections

Waits for pending usage reports. Reports are sent in the background, so call this before a serverless function, request-scoped worker or CLI exits.

boolean

default:"false"

stigg.flush() only. After flushing, also release the SDK’s connections, like close.

Promise<SessionSummary[]>

stigg.flush() returns one summary per wrapped client. governed.stigg.flush() returns that client’s summary.

deregister

await stigg.deregister({ customerId, agentId });

Archives an agent’s entity. Optional for long-lived agents. Deregister ephemeral agents, created for a single task or session, when they finish. See Agent governance.

string

required

The customer that owns the agent.

string

required

The agent to archive.

Other methods

init

const resolution = await stigg.init();

Connects to Stigg up front instead of on the first call, so a wrong API key fails at startup. Optional. Returns which client serves each operation.

close

await stigg.close();

Releases the SDK’s connections. A Node server SDK client you passed in as client is not closed.

denial

const decision = stigg.denial(err);

Returns the decision if err is an AccessDeniedError, otherwise undefined. Use it in a catch block to tell denied access apart from other errors. The same as isAccessDenied(err).

governanceHeaders

const headers = stigg.governanceHeaders(context);

The x-stigg-customer-id, x-stigg-dimensions, x-stigg-attribution-key and x-stigg-run-id headers for a context, with no wrapped client involved. See A gateway you operate.

ingestFromHeaders

const result = await stigg.ingestFromHeaders(req.headers, input);

For a gateway or proxy you operate. Reads the customer and agent from the x-stigg-* request headers and reports the usage the proxy observed. It never checks access.

Record<string, string | string[] | undefined>

required

The incoming request’s headers.

object

required

Show input

unknown

required

The provider’s usage object, as it appeared in the response.

string

required

The upstream request ID, so a retried report is not counted twice.

'anthropic' | 'openai' | 'openai-responses' | 'gemini' | 'typesafe'

The shape of usage. Without it, pass a metrics mapper.

{ currencyId } | { featureId }

default:"{ currencyId: 'credits' }"

What the usage counts against.

MetricsMapper

A usage mapper.

'async' | 'sync'

The ingest mode. Defaults to the SDK’s setting.

{ name: string }

The event name in async mode. Defaults to <vendor>.proxied.

(result: IngestResult) => void

Called with the result, including a failed one.

Promise<IngestResult>

The ingest result.

StiggContext

Says who a call is for and how it is checked and reported. Pass it to wrap() as the default for every call through a client, and inside any call’s own parameters to override it for that call. Every field is optional in either place, but each call must end up with a customerId. A field the SDK does not recognize, such as a misspelled agentId, throws an error rather than being ignored.

string

The Stigg customer the call belongs to.

{ currencyId } | { featureId }

The credit currency or metered feature the call is checked against. Omit it to meter without checking.

string

The agent the call is attributed to. Requires attributionKey. See Agent governance.

string

The attribution key of the agent’s entity type, for example agentId. The agent ID is sent under this key on every check and report.

Record<string, string>

More attribution, such as a user or a model, sent on every check and report. Merged key by key when overridden.

'allow' | 'deny'

Overrides the SDK’s fallback strategy.

(measurement: Measurement) => Record<string, number>

What to report. Defaults to the vendor’s own metrics. See Usage mappers.

'async' | 'sync'

Overrides the SDK’s ingest mode.

{ name: string }

The event name in async mode. Defaults to the vendor call, such as anthropic.messages.create.

string

Deduplicates the report. Defaults to the vendor’s request ID when it has one.

string

Sent as x-stigg-run-id, to correlate work across processes.

AccessDecision

What a check returns: from check(), from stigg.denial(err), and to the onDecision hook.

boolean

Whether access is granted and the call may go ahead. The same as hasAccess in an entitlement check.

string | undefined

The entity whose limit denied access: an agent, a team, or the customer.

string | undefined

Why access was denied, such as BudgetExceeded or InsufficientCredits.

'top-up' | 'raise-budget' | 'subscribe' | 'retry' | undefined

What would let the call through. See Remedies are product decisions.

number | undefined

The smallest budget left anywhere in the chain.

number | null | undefined

The limit of the budget that decided.

number | undefined

The usage of the budget that decided.

'rest' | 'node-sdk' | 'cache' | 'policy' | 'unenforced'

What produced the decision. policy means the check could not complete and the fallback strategy decided. unenforced means no entitlement was set.

number

When the check was made, in epoch milliseconds.

boolean | undefined

Stigg answered from fallback state.

boolean | undefined

The SDK made the decision from live data, not Stigg. For a credit check, Stigg returns the balance and the SDK compares it with the requested usage. Can be true together with isFallback.

string

A sentence to show the user, matched to the remedy.

string

A one-line description for logs.

IngestResult

What a usage report returns.

boolean

true only if every metric was accepted.

Record<string, number>

What was reported, by feature or currency ID.

string

The key the report was deduplicated on.

'async' | 'sync'

Which ingest mode was used.

boolean | undefined

sync only: Stigg had already seen these keys, so nothing was counted again.

number | undefined

sync only: the credits the report used, when what it reported draws a credit balance. Not set when the reported features are not mapped to credits.

unknown

The failure, when ok is false.

Helpers

Export	Description
`anthropicRecipe`, `openAIRecipe`, `geminiRecipe`, `geminiChatRecipe`, `groqRecipe`, `mistralRecipe`, `ollamaRecipe`, `typesafeRecipe`, `openrouterRecipe(options)`, `litellmRecipe(options)`, `bedrockRecipe(options)`	The built-in recipes. See Supported providers.
`weightedMetrics(recipe, target, weights, { per })`	A mapper that converts metrics into one feature or currency using a rate table. Does not round.
`unitsPerTokens(target, tokensPerUnit)`	A mapper that reports one unit per N tokens of any kind. Does not round. Replaces `creditsPerTokens`.
`normalizedMetrics`	A mapper that reports four non-overlapping token counters under `stigg_*` names.
`estimateFromMaxTokens(tokensPerUnit)`, `estimateFromMaxOutputTokens(tokensPerUnit)`, `estimateFromState(tokensPerUnit, charsPerToken)`	Estimates of a call’s usage for Anthropic, Gemini and TypeSafe, used as the requested usage of the check. Each throws when created if a rate is zero or negative.
`GOVERNANCE_HEADERS`, `parseGovernanceHeaders(headers)`	The header names, and a parser for the receiving side.

Errors

Error	When
`AccessDeniedError`	Access was denied for a call through a wrapped client. Its `decision` property is the decision.
`GovernanceNotEnabledError`	`register()` set a `budget` on an account without Governance.
`EngineError`	A failure talking to Stigg. Failed usage reports are passed to `onError` instead of being thrown.

isAccessDenied(err) returns the decision for an AccessDeniedError and undefined otherwise. isGovernanceNotEnabled(err) and isEngineError(err) check the other two. They work without instanceof, so they are safe across bundles.

Get started

Essentials

SDK reference

SDK documentation

API reference

Agent SDK

Installation

How it connects to Stigg

StiggAgentSDK

Methods

wrap

register

check

report

summary

flush

deregister

Other methods

init

close

denial

governanceHeaders

ingestFromHeaders

StiggContext

AccessDecision

IngestResult

Helpers

Errors

​Installation

​How it connects to Stigg

​StiggAgentSDK

​Methods

​wrap

​register

​check

​report

​summary

​flush

​deregister

​Other methods

​init

​close

​denial

​governanceHeaders

​ingestFromHeaders

​StiggContext

​AccessDecision

​IngestResult

​Helpers

​Errors

Installation

How it connects to Stigg

StiggAgentSDK

Methods

wrap

register

check

report

summary

flush

deregister

Other methods

init

close

denial

governanceHeaders

ingestFromHeaders

StiggContext

AccessDecision

IngestResult

Helpers

Errors