Platform Resources

AI Models & Credentials

View as Markdown

AI configuration has two parts:

  • Models are what hosted agents run, for example openai/gpt-5.
  • Credentials are optional saved BYOK keys. Use them when you want a model call billed to your own provider account.

If you pass a model string, BCTRL uses managed inference. If you pass a model object with auth.credential, BCTRL uses your saved credential. Inline auth.apiKey is also supported for one-off BYOK calls.

List models

1const { data: models } = await bctrl.ai.models.list({
2  engine: "stagehand",
3  managed: true,
4});

Model ids are provider-prefixed, such as openai/gpt-5, anthropic/claude-sonnet-4-6, and google/gemini-2.5-flash.

Create a credential

1const credential = await bctrl.ai.credentials.create({
2  provider: "anthropic",
3  name: "anthropic-prod",
4  apiKey: process.env.ANTHROPIC_API_KEY!,
5  defaultModel: "anthropic/claude-sonnet-4-6",
6  test: true,
7});

Set test: true to validate the key before saving. API keys are encrypted at rest and are never returned in responses.

List, read, update

1const { data } = await bctrl.ai.credentials.list();
2const one = await bctrl.ai.credentials.get(credential.id);
3
4await bctrl.ai.credentials.update(credential.id, {
5  defaultModel: "anthropic/claude-sonnet-4-6",
6});

Test and delete

1const result = await bctrl.ai.credentials.test(credential.id);
2await bctrl.ai.credentials.delete(credential.id);

Use in an agent

Use a managed model by passing a string:

1await bctrl.runtimes.invocations.stagehand.agent(runtime.id, {
2  instruction: "Summarize the dashboard.",
3  model: "openai/gpt-5",
4});

Use a saved BYOK credential by passing a model object:

1await bctrl.runtimes.invocations.stagehand.agent(runtime.id, {
2  instruction: "Summarize the dashboard.",
3  model: {
4    model: "anthropic/claude-sonnet-4-6",
5    auth: { credential: credential.id },
6  },
7});

Next