Resources

AI Connections

View as Markdown

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

1const connections = await bctrl.aiConnections.list();

Create a connection

1const connection = await bctrl.aiConnections.create({
2  provider: "openai",
3  label: "Production OpenAI",
4  apiKey: process.env.OPENAI_API_KEY!,
5  defaultModel: "gpt-4.1",
6});

Update a connection

1await bctrl.aiConnections.update(connection.id, {
2  defaultModel: "gpt-4.1-mini",
3  enabled: true,
4});

Test a connection

1const result = await bctrl.aiConnections.test(connection.id);
2
3if (!result.ok) {
4  throw new Error(result.message);
5}

Mount connections to a space

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

1const space = await bctrl.spaces.create({
2  name: "research-agent",
3  mounts: {
4    ai: {
5      allowConnections: [connection.id],
6      defaults: {
7        stagehand: {
8          connection: connection.id,
9          model: "gpt-4.1",
10        },
11      },
12    },
13  },
14});

Use with an invocation

1await runtime.invocations.create({
2  provider: "stagehand",
3  operation: "agent.execute",
4  input: {
5    instruction: "Summarize the page.",
6  },
7});