> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# AI Models & Credentials

> Choose managed models or bring your own provider keys for hosted agents.

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

```ts
const { data: models } = await bctrl.ai.models.list({
  engine: "stagehand",
  managed: true,
});
```

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

## Create a credential

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

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

## List, read, update

```ts
const { data } = await bctrl.ai.credentials.list();
const one = await bctrl.ai.credentials.get(credential.id);

await bctrl.ai.credentials.update(credential.id, {
  defaultModel: "anthropic/claude-sonnet-4-6",
});
```

## Test and delete

```ts
const result = await bctrl.ai.credentials.test(credential.id);
await bctrl.ai.credentials.delete(credential.id);
```

## Use in an agent

Use a managed model by passing a string:

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

Use a saved BYOK credential by passing a model object:

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

## Next

* [Hosted agents](/sdk/hosted-agents) - choose models for agents
* [Invocations](/sdk/invocations) - the underlying call
* [Vault](/sdk/vault) - other secrets, stored separately