Azure Blob

Stores files in Azure Blob Storage containers. For interface details, see WorkspaceFilesystem Interface.

Installation

npm

npm install @mastra/azure

pnpm

pnpm add @mastra/azure

Yarn

yarn add @mastra/azure

Bun

bun add @mastra/azure

Usage

Add an AzureBlobFilesystem to a workspace and assign it to an agent:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AzureBlobFilesystem } from '@mastra/azure/blob'

const workspace = new Workspace({
  filesystem: new AzureBlobFilesystem({
    container: 'my-container',
    connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

Account key

Use an account name and account key when you don't want to pass a full connection string:

import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  accountKey: process.env.AZURE_STORAGE_ACCOUNT_KEY,
})

Shared access signature token

Use a shared access signature (SAS) token with either accountName or endpoint:

import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  sasToken: process.env.AZURE_STORAGE_SAS_TOKEN,
})

DefaultAzureCredential

Use DefaultAzureCredential when your environment provides Azure identity credentials:

import { AzureBlobFilesystem } from '@mastra/azure/blob'

const filesystem = new AzureBlobFilesystem({
  container: 'my-container',
  accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
  useDefaultCredential: true,
})

Install @azure/identity when you use DefaultAzureCredential:

npm

npm install @azure/identity

pnpm

pnpm add @azure/identity

Yarn

yarn add @azure/identity

Bun

bun add @azure/identity

Constructor parameters

container:

string

Azure Blob Storage container name

connectionString?:

string

Full Azure Storage connection string. Takes priority over other authentication options.

accountName?:

string

Azure Storage account name. Required unless you use connectionString or endpoint.

accountKey?:

string

Azure Storage account key.

sasToken?:

string

Shared access signature token. Requires accountName or endpoint.

useDefaultCredential?:

boolean

= false

Use DefaultAzureCredential from @azure/identity.

endpoint?:

string

Custom Blob service endpoint URL. Used for local development with Azurite.

prefix?:

string

Optional prefix for all keys (acts like a subdirectory).

id?:

string

= Auto-generated

Unique identifier for this filesystem instance.

displayName?:

string

Human-friendly display name for the UI.

icon?:

FilesystemIcon

Icon identifier for the UI.

description?:

string

Short description of this filesystem for the UI.

readOnly?:

boolean

= false

When true, all write operations are blocked.

Properties

id:

string

Filesystem instance identifier.

name:

string

Provider name ('AzureBlobFilesystem').

provider:

string

Provider identifier ('azure-blob').

readOnly:

boolean | undefined

Whether the filesystem is in read-only mode.

Methods

AzureBlobFilesystem implements the WorkspaceFilesystem interface, providing all standard filesystem methods:

• readFile(path, options?) - Read file contents
• writeFile(path, content, options?) - Write content to a file
• appendFile(path, content) - Append content to a file
• deleteFile(path, options?) - Delete a file
• copyFile(src, dest, options?) - Copy a file
• moveFile(src, dest, options?) - Move or rename a file
• mkdir(path, options?) - Create a directory
• rmdir(path, options?) - Remove a directory
• readdir(path, options?) - List directory contents
• exists(path) - Check if a path exists
• stat(path) - Get file or directory metadata

init()

Initialize the filesystem. Verifies container access and credentials.

await filesystem.init()

getInfo()

Returns metadata about this filesystem instance.

const info = filesystem.getInfo()
// { id: '...', name: 'AzureBlobFilesystem', provider: 'azure-blob', status: 'ready' }

getContainer()

Returns the underlying Azure Blob Storage ContainerClient.

const container = await filesystem.getContainer()

getMountConfig()

Returns the mount configuration for sandbox providers that support Azure Blob filesystem mounts.

const config = filesystem.getMountConfig()
// { type: 'azure-blob', container: 'my-container', ... }

备注

Azure Blob sandbox mounting depends on sandbox support for azure-blob mount configs. Use filesystem for direct workspace file operations when your sandbox provider doesn't support Azure Blob mounts.

Related

• WorkspaceFilesystem interface
• S3Filesystem reference
• GCSFilesystem reference
• Filesystem