Bring your own vendor

The SDK is not limited to the vendors it ships with. Every built-in vendor is supported through a recipe: a small, plain-data description of which client methods make model calls, and where the response says how much they used. The same interface is open to you, so you can meter and gate any client:

A vendor the SDK does not support yet.
Your own models, or an internal AI service with its own client.
A client you got from somewhere else, such as an open-source library.

Write a recipe and pass it to wrap(). Everything else, checking before each call and reporting after it, works exactly as it does for the built-in vendors.

Write a recipe

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

const myRecipe: ClientRecipe<'input_tokens' | 'output_tokens'> = {
  vendor: 'my-vendor',
  metrics: ['input_tokens', 'output_tokens'],
  methods: [
    {
      path: ['generate'],
      extractUsage: (result) => ({
        metrics: { input_tokens: result.usage.in, output_tokens: result.usage.out },
      }),
    },
  ],
};

Field	What it is
`vendor`	A name for the vendor. Events are named after it, for example `my-vendor.generate`.
`metrics`	The names of the metrics this recipe reports. These are the names you meter on in Stigg.
`methods`	Every client method that makes a model call. Methods not listed here are passed through without checks or reporting.
`methods[].path`	Where the method lives on the client. `['generate']` is `client.generate()`, and `['chat', 'completions', 'create']` is `client.chat.completions.create()`.
`methods[].extractUsage`	A function that receives the method’s result and returns what to report: `{ metrics }`, and optionally `dimensions` to add to the event, `raw` usage fields, and an `idempotencyKey`, such as the vendor’s own request ID. Check the vendor’s API docs for where its response reports usage.
`methods[].attachStream`	Optional. For a method that streams, reads usage from the stream and reports it once the stream finishes.
`methods[].estimate`	Optional. An estimate of the call’s usage, used as the requested usage of the check.
`methods[].event`	Optional. The event name for this method, instead of one built from `vendor` and `path`.
`matches`	Optional. A function that recognizes the vendor’s client, so `wrap()` can pick this recipe automatically.
`totalTokensMetric`	Optional. The name of a metric that is the vendor’s total, if it reports one.

You can also start from a built-in recipe and change part of it, for example to add an estimate to every method of anthropicRecipe. See Requested usage for an example.

Use it

Pass the recipe to wrap(), then call the client as usual:

const client = stigg.wrap(myVendorClient, { recipe: myRecipe });

await client.generate({
  prompt,
  stiggContext: { customerId: 'customer-acme', entitlement: { currencyId: 'credits' } },
});

Make one call, then open the customer in the Stigg app and check that a usage event arrived with the metrics you expect.

Contribute your recipe

The Agent SDK is open source, and the built-in recipes are written exactly the way yours is. If you wrote a recipe for a vendor other developers use too, contribute it to the Agent SDK on GitHub. Once it is merged, the SDK recognizes that vendor automatically and no one needs to pass a recipe for it.

Usage without a client

Wrapping works when you call a model through a client object. Sometimes there is nothing to wrap: for example, you call a model over plain HTTP, or the usage is not a model call at all, such as a paid web-search API your agent uses. In that case, count the usage yourself and send it to Stigg with stigg.report():

await stigg.report({ customerId: 'customer-acme' }, { 'feature-web-searches': 1 });

The keys are the IDs of the Stigg features or credit currencies to report against. To check before the call, use stigg.check(). For a full example, see Gating actions that are not model calls. Need a vendor we do not support yet? Let us know.

Getting started

Developer tools

Governance (Beta)

AI agents and LLMs (Beta)

Modeling your pricing in Stigg

Entitlements

Managing customers, subscriptions and contracts

Getting usage data into Stigg

Snap-in widgets

Importing and exporting data

Going live

Workflow automation

Rolling out pricing changes with confidence

Price localization

Managing your account

High-availability and scale

Security & compliance

Write a recipe

Use it

Contribute your recipe

Usage without a client

​Write a recipe

​Use it

​Contribute your recipe

​Usage without a client

Write a recipe

Use it

Contribute your recipe

Usage without a client