> 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 full documentation content, see https://platform.bctrl.ai/llms-full.txt.

# AI Connections

> Manage AI provider connections that spaces and hosted agents use.

AI connections give hosted agent flows access to LLM providers such as OpenAI, Anthropic, and Google. Use them with invocations and runtime agent helpers.

Access AI connections through `bctrl.aiConnections`.

## List connections

```ts
const connections = await bctrl.aiConnections.list();
```

## Create a connection

```ts
const connection = await bctrl.aiConnections.create({
  provider: "openai",
  label: "Production OpenAI",
  apiKey: process.env.OPENAI_API_KEY!,
  defaultModel: "gpt-4.1",
});
```

## Update a connection

```ts
await bctrl.aiConnections.update(connection.id, {
  defaultModel: "gpt-4.1-mini",
  enabled: true,
});
```

## Test a connection

```ts
const result = await bctrl.aiConnections.test(connection.id);

if (!result.ok) {
  throw new Error(result.message);
}
```

## Mount connections to a space

Spaces can allow specific AI connections and set defaults for hosted agent providers.

```ts
const space = await bctrl.spaces.create({
  name: "research-agent",
  mounts: {
    ai: {
      allowConnections: [connection.id],
      defaults: {
        stagehand: {
          connection: connection.id,
          model: "gpt-4.1",
        },
      },
    },
  },
});
```

## Use with an invocation

```ts
await runtime.invocations.create({
  provider: "stagehand",
  operation: "agent.execute",
  input: {
    instruction: "Summarize the page.",
  },
});
```

## Related

* [Invocations](/sdk/core-concepts/invocations)
* [Mounts & Inheritance](/sdk/core-concepts/mounts-inheritance)
* [API Reference: AI Connections](/api/api-reference/ai-connections/list)