> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI agents

> Meter, enforce and govern every LLM call your product and its agents make, by wrapping the client you already use.

> [!NOTE]
>
> The Stigg Agent SDK is in public beta.

## What it is

The Stigg Agent SDK adds Stigg to the LLM or gateway client you already use. You call `stigg.wrap(client)` once and use the client it returns. From then on, every model call through that client goes through three steps:

1. **[Meter usage](/documentation/ai-agents/usage-metering).** The tokens, and the cost where a gateway reports one, are read from each response and reported to Stigg, straight from the LLM provider or gateway you call.
2. **[Enforce access](/documentation/ai-agents/access-enforcement).** Before a call leaves your process, the SDK checks that the agent has enough credits or metered capacity to perform its task, so an agent that has run out never reaches the provider.
3. **[Govern usage](/documentation/ai-agents/usage-governance).** Each agent gets its own identity and budget, under teams and orgs, so you know which agent spent what and can stop one without stopping the rest.

The wrapped client takes the same arguments, returns the same types, and raises the same errors as the original. The client you passed to `wrap()` is left as it was, so calls through it are not metered or checked.

```bash theme={null}
npm install @stigg/agent-sdk-js
```

> **[stigg-agent-sdk-ts on GitHub](https://github.com/stiggio/stigg-agent-sdk-ts)**
>
> The Agent SDK is open source under the MIT license. Browse the source, run the examples, or contribute a recipe for a new vendor.

```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk';
import { StiggAgentSDK } from '@stigg/agent-sdk-js';

const stigg = new StiggAgentSDK(process.env.STIGG_SERVER_API_KEY);

// Wrap the client once. One wrapped client serves every customer.
const anthropic = stigg.wrap(new Anthropic());

// The same call as before, plus who it is for and what to check it against.
await anthropic.messages.create({
  model: 'claude-opus-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Summarize this ticket' }],
  stiggContext: {
    customerId: 'customer-acme',
    entitlement: { currencyId: 'credits' },
  },
});
```

The `stiggContext` tells Stigg who the call is for. The SDK removes it before the request is sent, so the provider never sees it.

| Field | Required | What it does |
| - | - | - |
| `customerId` | Yes | The customer the call's usage is reported for. |
| `entitlement` | No | The credit type (`currencyId`) or metered feature (`featureId`) to check before the call. Without it, the call is metered but never denied. |
| `agentId` | No | The agent the call is attributed to. See [Usage governance](/documentation/ai-agents/usage-governance). |

You can pass the context in two places:

* **On each call**, as above. One wrapped client then serves every customer, which is what a server handling many customers needs.
* **Once, on `wrap()`**, as the default for every call through that client: `stigg.wrap(new Anthropic(), { stiggContext: { customerId, entitlement } })`. Use this in a process that only serves one customer. A `stiggContext` on a call still takes precedence over the default for the fields it sets.

Either way, every call must end up with a `customerId`.

## Why use it

> **Meter AI usage from the client you already use**
>
> Token counts and gateway costs flow into Stigg as usage events. Price them in a plan, draw them down from a credit balance, or pass them through with a margin.

> **Stop spend before it happens**
>
> Most metering tools tell you a budget was exceeded after the fact. Tell the wrapper which credits or metered feature to enforce, and it checks them before each request leaves, so an agent that has run out never reaches the provider.

> **Charge for what each call actually cost**
>
> If you route calls through an LLM gateway, the wrapper reports what the gateway actually charged for each call, not an estimate from token counts and a price list. When the gateway falls back to a different model, you see which model served the call and what it cost.

> **Your AI calls keep working**
>
> Usage is reported in the background, so it adds no delay to the call. If a report fails, your user still gets their response, and the error goes to your `onError` hook.

## How it works

```mermaid theme={null}
sequenceDiagram
    participant App as Your code
    participant W as Wrapped client
    participant S as Stigg
    participant P as Provider or gateway

    App->>W: Model call
    W->>S: Enough credits or capacity?
    S-->>W: Yes
    W->>P: Model call
    P-->>W: Response
    W-->>App: Response
    W--)S: Report usage
```

* **Recognizes your provider.** `wrap()` detects which provider or gateway the client talks to. If it does not recognize the client, it throws an error instead of returning a client that meters nothing. See [Usage metering](/documentation/ai-agents/usage-metering#supported-providers-and-gateways).
* **Knows who each call is for.** Each call says which customer, and optionally which agent, it belongs to, so one wrapped client can serve them all. You can also set a default on `wrap()`. See [`StiggContext`](/api-and-sdks/references/sdk/backend/rest/agent-sdk#stiggcontext).
* **Checks only when you ask.** Tell the wrapper which credits or metered feature to enforce, and calls without enough left are denied before they reach the provider. Otherwise every call goes through and is only metered. See [Access enforcement](/documentation/ai-agents/access-enforcement).
* **Handles streaming.** Streamed responses are metered when the stream ends, even if your code stops reading early. See [Usage metering](/documentation/ai-agents/usage-metering).

## Example use cases

> **Token pass-through on a usage-based plan**
>
> A developer platform charges per million input and output tokens. Each wrapped call reports `input_tokens` and `output_tokens` as one event, and two metered features in Stigg sum them for the invoice. Adding a new model changes nothing in your code.

> **Credits that burn down with real usage**
>
> A writing assistant sells monthly credit packs. The wrapper converts tokens into credits with a weights table, checks the balance before each call, and shows the user a top-up prompt when the balance runs out instead of an error page.

> **Cost-plus pricing over a gateway**
>
> A company routes all traffic through OpenRouter. The OpenRouter recipe reports the credits OpenRouter actually charged for each call, so the customer is charged real cost plus margin, even when OpenRouter falls back to a different model.

> **Protecting a free tier**
>
> A product offers free AI usage up to a cap. With the cap modeled as a metered feature that the wrapper enforces, calls past the cap are denied before they cost anything.

> **Per-agent budgets in a multi-agent product**
>
> A customer runs a support agent, a research agent and a coding agent from one credit balance. Each agent gets its own monthly budget, so when the research agent loops on a bad prompt, it is stopped at its own budget and the other two keep serving users.


## Related topics

- [Set budgets for AI agents](/guides/ai-agents/set-budgets-for-ai-agents.md)
- [AI Terminal](/api-and-sdks/ai-terminal.md)
- [Agent SDK](/api-and-sdks/references/sdk/backend/graphql/agent-sdk.md)
- [Usage governance](/documentation/ai-agents/usage-governance.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.