Bring your own Provider

Use a Provider when an Agent should run with your own model credential instead of the platform key. The Provider is Tenant-level configuration; the Agent selects it explicitly with providerId.

Outcome

You will test an unsaved credential, save only its safe Provider metadata, assign it to an Agent, and verify a model response.

Choose one supported Provider type—openai, anthropic, openrouter, google, or custom—and a compatible model. You need an Agent ID, a backend SDK client, and the credential in a server environment variable. Read Models and Providers, Agents, and Security and credentials.

Test an unsaved configuration

Keep Provider credentials on the backend

Never send a Provider API key to browser code. Pass it from a backend environment variable directly to the SDK.

providers.test() performs a live model test without creating a Provider. Both a successful and an unsuccessful test return a result with an ok discriminator.

Save the Provider

Creating the Provider stores the key in the platform's credential store. The response exposes safe metadata such as id, providerType, baseUrl, and the last-four-character keyFragment; it never returns the key or its internal secret reference.

Assign the Provider to an Agent

Agent updates are merge updates, so changing providerId and model preserves fields you do not send. Every accepted update creates a new Agent Version.

Run and verify a Turn

import assert from "node:assert/strict";

const apiKey = process.env.PROVIDER_API_KEY;
assert.ok(apiKey, "Set PROVIDER_API_KEY on the backend");

const tested = await client.providers.test({
  providerType: "openrouter",
  apiKey,
  model: "anthropic/claude-sonnet-4.5",
});
assert.equal(tested.ok, true);

const provider = await client.providers.create({
  name: `Production OpenRouter ${crypto.randomUUID()}`,
  providerType: "openrouter",
  baseUrl: null,
  apiKey,
});
assert.equal(provider.keyFragment, apiKey.slice(-4));
assert.ok(!("apiKey" in provider));

await client.agents.update(agentId, {
  providerId: provider.id,
  model: "anthropic/claude-sonnet-4.5",
});

const turn = await client.completion({ agentId, prompt: "Reply with OK." });
assert.ok((await turn.text).trim().length > 0);

Optionally call client.providers.testStored(provider.id, { model }) after saving to run the same live check with the stored credential.

Rotate or remove credentials

Provider keys and Provider types are immutable. Rotate a key by creating and testing a replacement Provider, repointing every dependent Agent, retesting the stored credential, and then deleting the old Provider. Deletion is rejected while a current Agent still references the Provider. providers.update() changes only the name or base URL; it does not rotate the key.

Review Version Pins before repointing or deleting. A Version stores providerId, not the credential: a pinned historical Version continues to use that live Provider, while deleting it after the current Agent moves away breaks execution of Pins that still name the old ID. Repoint mutable consumers such as Task definitions before deletion. A Session Pin is immutable, so keep the old Provider for as long as that Session may resume.

Production notes

custom Providers require a non-empty baseUrl; the other Provider types have platform-defined defaults when it is omitted.
The Agent's model remains a separate opaque provider/model string. Confirm that the chosen Provider supports it.
Provider tests return safe success metadata or a safe error result. Do not log the environment credential.
Provider-specific model IDs are passed to the selected Provider verbatim. The prefixed OpenRouter model in this guide is valid for OpenRouter; do not reuse that spelling for a native Provider unless its API accepts it.

See Models and Providers, Agents, Security and credentials, and Versions and lifecycle.

SDK and REST reference

The example uses providers.test(), providers.create(), agents.update(), and completion(). Rotation also uses providers.testStored(), providers.update(), and providers.delete().

The matching operations are test Provider configuration, create Provider, test stored Provider, update Provider, delete Provider, update Agent, and generate text.