@bluebag/langchain

@bluebag/langchain integrates Bluebag with LangChain so you can inject sessions, Skills, and tools into your agents.

Installation

npm install @bluebag/langchain langchain @langchain/openai

Peer dependency

@bluebag/langchain requires @langchain/core ^0.3.0 as a peer dependency.

Exports

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

`Bluebag` class

The Bluebag class is the main entry point for using Bluebag with LangChain.

import { Bluebag } from "@bluebag/langchain";
import { createAgent } from "langchain";
import { HumanMessage } from "@langchain/core/messages";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

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"],
});

// Your custom tool
const getWeather = tool(
  ({ city }) => `Sunny in ${city}`,
  {
    name: "get_weather",
    description: "Get the weather",
    schema: z.object({ city: z.string() }),
  }
);

const config = await bluebag.enhance({
  model: "openai:gpt-4o",
  tools: [getWeather],
  systemMessage: "You are a helpful assistant.",
  messages: [new HumanMessage("Analyze this data")],
});

const agent = createAgent({
  model: config.model,
  tools: config.tools,
  systemPrompt: config.systemMessage,
});

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 image parts with matching MIME types before upload.

Methods

Method	Description
`enhance(config?)`	Returns an enhanced LangChain config for your agent.
`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 LangChain config.

import { createAgent } from "langchain";
import { HumanMessage } from "@langchain/core/messages";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

// Your custom tool
const getWeather = tool(
  ({ city }) => `Sunny in ${city}`,
  {
    name: "get_weather",
    description: "Get the weather",
    schema: z.object({ city: z.string() }),
  }
);

const config = await bluebag.enhance({
  model: "openai:gpt-4o",
  messages: [new HumanMessage("Analyze this data")],
  tools: [getWeather],
  systemMessage: "You are a data analyst.",
});

const agent = createAgent({
  model: config.model,
  tools: config.tools,
  systemPrompt: config.systemMessage,
});

const result = await agent.invoke({ messages: config.messages });

Input (BluebagConfigShape):

Property	Type	Description
`messages`	`BaseMessage[]`	Optional. Processed for file attachments.
`tools`	`StructuredToolInterface[]`	Optional. Merged with Bluebag tools.
`systemMessage`	`string`	Optional. Merged with Bluebag's system prompt.

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 bluebag = new Bluebag({
  apiKey: process.env.BLUEBAG_API_KEY!,
});

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

// Get a download URL
const downloadUrl = 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/langchain

On this page