Tool Calls

When you call enhance, Bluebag returns an enhanced config with LangChain-compatible tools that your agent can invoke. They show up under stable names prefixed with bluebag_.

The tools are bluebag_bash, bluebag_code_execution, bluebag_computer_use, bluebag_text_editor and bluebag_file_download_url.

Shared output shape

All tools return serialized JSON with the following structure:

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

Bluebag tools serialize their output as JSON.stringify(result, null, 2).

Tools exposed by enhance

bluebag_bash

Execute bash commands & simple code execution (e.g., node your-script.js or python your-script.py) when working with Skills in the Bluebag sandbox. If files are created during execution, the tool result includes metadata (including fileId) about the created file(s) in the artifacts array.

Input

• command (string, required): Shell command to execute inside the sandbox.

Output

• result (string): Standard output from the command.
• exitCode (number): Exit status.
• artifacts (array | null): Created file metadata (fileId, filename, path, size, expiryAt).

bluebag_code_execution

Analyze data, create visualizations, and perform complex calculations when working with Skills in the Bluebag sandbox using Python, JavaScript, or TypeScript. If files are created during execution, the tool result includes metadata (including fileId) about the created file(s) in the artifacts array.

Input

• language ("python" | "javascript" | "typescript", required): Programming language to execute the code in.
• code (string, required): Source code that will be executed.
• files (array, optional): Files to mount into the sandbox before execution.
  • fileId (string, required): File identifier.
  • path (string, required): Target path inside the sandbox.

Output

• result (string): Standard output from the code execution.
• exitCode (number): Exit status.
• artifacts (array | object | null): When files are created, this is an array of file metadata (fileId, filename, path, size, expiryAt). Otherwise it may include execution artifacts like stdout or charts.

bluebag_computer_use

Control the sandbox desktop environment for browser automation and GUI interactions.

Input

• action ("screenshot" | "click" | "type" | "key", required): Action to perform.
• coordinate ([x, y], optional): Screen coordinates for click actions.
• text (string, optional): Text to type or key to press.

Output

• result: Action-specific payload (screenshot data, confirmation, etc.).

bluebag_text_editor

View, create, and edit files in the sandbox via text manipulation.

Input

• command ("view" | "create" | "str_replace", required)
• path (string, required)
• file_text (string, optional): Required for create.
• old_str (string, optional): Required for str_replace.
• new_str (string, optional): Required for str_replace.
• start_line (number, optional): Start line for view.
• end_line (number, optional): End line for view.

Output

• view: file_type, content, numLines, startLine, path, totalLines, isTemp.
• create: path, is_file_update, fileId, size, isTemp, expiryAt.
• str_replace: path, fileId, size, isTemp, expiryAt.

fileId and expiryAt are present when the file path is eligible for persistence.

bluebag_file_download_url

Mint a short-lived download URL for a file by its fileId.

Input

• fileId (string, required)
• ttlSeconds (number, optional): Optional TTL override in seconds (capped server-side).

Output

• result: fileId, downloadUrl, expiresAt.

Handling artifacts

When tools create files, you can access them via the artifacts array in the result:

import { Bluebag } from "@bluebag/langchain";
import { HumanMessage } from "@langchain/core/messages";

const bluebag = new Bluebag({
  apiKey: process.env.BLUEBAG_API_KEY!,
});

const config = await bluebag.enhance({
  model: "openai:gpt-4o",
  messages: [new HumanMessage("Generate a chart")],
});

// After the agent runs and creates files...
// Parse the tool result to get artifact metadata
const toolResult = JSON.parse(lastToolMessage.content);

if (toolResult.artifacts?.length) {
  for (const artifact of toolResult.artifacts) {
    const downloadUrl = await bluebag.files.mintShortLivedDownloadUrl(artifact.fileId);
    console.log(`Download ${artifact.filename}: ${downloadUrl}`);
  }
}