@bluebag/ai-sdk

@bluebag/ai-sdk wraps the Vercel AI SDK so Bluebag can inject sessions, Skills, and tool handlers into your AI calls.

Installation

npm install @bluebag/ai-sdk

See API Keys for setting up your API key.

Exports

Bluebag — The main client class
Types: BluebagClientOptions, BluebagConfigShape, BluebagSession, BluebagErrorResponse, ToolExecutionResult

`Bluebag` class

The Bluebag class is the main entry point for using Bluebag with the Vercel AI SDK.

import { Bluebag } from '@bluebag/ai-sdk';
import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const apiKey = process.env.BLUEBAG_API_KEY;
if (!apiKey) {
  throw new Error('Missing BLUEBAG_API_KEY');
}

const bluebag = new Bluebag({
  apiKey,
  stableId: 'user-123',
  activeSkills: ['pdf-processing'],
});

const config = await bluebag.enhance({
  model: anthropic('claude-3-5-sonnet-20241022'),
  messages: [{ role: 'user', content: 'Hello from Bluebag.' }],
});

const result = streamText(config);

Constructor options

BluebagClientOptions:

Option	Type	Description
`apiKey`	`string`	Your Bluebag API key (required).
`apiBaseUrl`	`string`	Override the Bluebag API base URL.
`fetchImpl`	`typeof fetch`	Provide a custom `fetch` implementation if your runtime lacks one.
`stableId`	`string`	Stable identifier for per-user session isolation.
`activeSkills`	`string[]`	Limit the session to specific Skill IDs.
`stripMimeTypes`	`string[]`	Remove file parts with matching MIME types before upload.

Methods

Method	Description
`enhance(config)`	Enhances an AI SDK config with Bluebag tools and session.
`initSession()`	Manually initialize a session (called automatically by enhance).
`getSessionId()`	Get the current session ID.
`setStableId(id)`	Set the stable ID for session isolation.
`setActiveSkills(skills)`	Set which Skills are available for the session.

`enhance()` method

The enhance method initializes a Bluebag session and merges Bluebag tools into your AI SDK config.

const config = await bluebag.enhance({
  model: anthropic('claude-3-5-sonnet-20241022'),
  messages: [{ role: 'user', content: 'Analyze this file.' }],
  system: 'You are a helpful assistant.', // optional: merged with Bluebag's system prompt
  tools: { myTool: customTool }, // optional: merged with Bluebag tools
});

const result = streamText(config);

Input (BluebagConfigShape):

Property	Type	Description
`model`	`LanguageModel`	The AI SDK model to use.
`messages`	`ModelMessage[]`	Array of messages for the conversation.
`system`	`string`	Optional system prompt (merged).
`tools`	`Record<string, Tool>`	Optional tools (merged with Bluebag's).

Return value: The same config object enhanced with Bluebag session, tools, and system prompt.

Files API

bluebag.files exposes file helpers from @bluebag/core. Use them to upload files, persist artifacts, and generate download links for files created by Skills.

Method	Description
`files.create`	Upload a file and return metadata (includes `fileId`).
`files.retrieveMetadata`	Fetch metadata for a file by `fileId`.
`files.download`	Download the raw file as a Blob.
`files.persist`	Persist a file beyond its default expiry.
`files.mintShortLivedDownloadUrl`	Generate a signed download URL for a file.

const uploaded = await bluebag.files.create({
  file: myFile,
  filename: 'report.pdf',
  mediaType: 'application/pdf',
});

const download = await bluebag.files.mintShortLivedDownloadUrl(uploaded.fileId);

Tools

Bluebag exposes the following tools to your agent:

Tool	Description	Input Schema
`bluebag_bash`	Execute bash commands in the sandbox	`{ command: string }`
`bluebag_code_execution`	Run Python, JavaScript, or TypeScript code	`{ language: "python" \| "javascript" \| "typescript", code: string, files?: Array<{fileId, path}> }`
`bluebag_computer_use`	Control the sandbox desktop	`{ action: "screenshot" \| "click" \| "type" \| "key", coordinate?: [x, y], text?: string }`
`bluebag_text_editor`	View, create, and edit files	`{ command: "view" \| "create" \| "str_replace", path: string, ... }`
`bluebag_file_download_url`	Get signed download URLs	`{ fileId: string, ttlSeconds?: number }`

See Tool Calls for detailed input/output schemas.

Types

`ToolExecutionResult<T>`

type ToolExecutionResult<T> = {
  result: T;
  exitCode?: number;
  artifacts?: Array<{
    fileId: string;
    filename: string;
    path: string;
    size: number;
    expiryAt: string;
  }>;
};

`BluebagSession`

Re-exported from @bluebag/core. Contains session metadata.

`BluebagErrorResponse`

Re-exported from @bluebag/core. Error response shape from the API.

@bluebag/ai-sdk

On this page