deepagents-azure-blob-backend

Azure Blob Storage filesystem backend for LangChain Deep Agents.

Deep Agents exposes a BackendProtocol — a pluggable interface for file operations (read, write, edit, ls, glob, grep) that the agent uses as its virtual filesystem. This package provides an Azure Blob Storage implementation of that interface.

Migrating to langchain-azure-storage

pip uninstall deepagents-azure-blob-backend
pip install "langchain-azure-storage[deepagents]"

The successor drops the AzureBlobConfig dataclass and takes its arguments directly on the constructor. Credentials are Azure SDK credential objects rather than raw key or token strings:

# Before
from deepagents_azure_blob_backend import AzureBlobBackend, AzureBlobConfig

backend = AzureBlobBackend(
    AzureBlobConfig(
        account_url="https://<account>.blob.core.windows.net",
        container_name="agent-workspace",
        prefix="session-001/",
    )
)

# After
from langchain_azure_storage.deepagents import AzureBlobBackend

backend = AzureBlobBackend(
    "https://<account>.blob.core.windows.net",
    "agent-workspace",
    prefix="session-001/",
)

The successor's AzureBlobBackend is currently marked beta upstream and emits a LangChainBetaWarning on construction.

The successor also requires deepagents>=0.7.1, where write overwrites an existing file instead of erroring and delete/adelete are part of BackendProtocol. Python 3.11+ is required for the deepagents extra.

Further reading: backend integrations · design proposal and behavior notes · upstream PR

Installation

pip install deepagents-azure-blob-backend

Or with uv:

uv add deepagents-azure-blob-backend

This package requires deepagents>=0.6.1,<0.7.0, where BackendProtocol exposes structured ls, glob, and grep result types. It does not support the BackendProtocol changes in deepagents 0.7.0 — see Migrating to langchain-azure-storage.

Quick Start

import asyncio
from deepagents import create_deep_agent
from deepagents_azure_blob_backend import AzureBlobBackend, AzureBlobConfig


async def main():
    config = AzureBlobConfig(
        account_url="https://<your-account>.blob.core.windows.net",
        container_name="agent-workspace",
        prefix="session-001/",
    )
    backend = AzureBlobBackend(config)

    agent = create_deep_agent(backend=backend)

    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "Create a hello world script at /hello.py"}]},
    )
    print(result["messages"][-1].content)
    await backend.close()


asyncio.run(main())

Configuration

from deepagents_azure_blob_backend import AzureBlobConfig

config = AzureBlobConfig(
    account_url="https://<account>.blob.core.windows.net",
    container_name="my-container",
    prefix="agent-workspace/",  # Namespace isolation for multi-agent setups
    max_concurrency=8,  # Parallel blob ops for grep/glob
    encoding="utf-8",
)

Authentication

AzureBlobConfig supports five mutually exclusive authentication methods. Set at most one credential source — if none is provided, DefaultAzureCredential is used automatically. account_url is required for all methods except connection string:

# 1. Connection string (e.g., Azurite or Azure Portal)
config = AzureBlobConfig(
    container_name="test",
    connection_string="UseDevelopmentStorage=true",
)

# 2. Account key
config = AzureBlobConfig(
    account_url="https://<account>.blob.core.windows.net",
    container_name="my-container",
    account_key="your-storage-account-key",
)

# 3. SAS token
config = AzureBlobConfig(
    account_url="https://<account>.blob.core.windows.net",
    container_name="my-container",
    sas_token="sv=2021-06-08&ss=b&srt=co&sp=rwdlacitfx&se=...",
)

# 4. Credential object (any Azure credential)
from azure.identity.aio import ClientSecretCredential

config = AzureBlobConfig(
    account_url="https://<account>.blob.core.windows.net",
    container_name="my-container",
    credential=ClientSecretCredential(tenant_id, client_id, client_secret),
)

# 5. Default (AAD) — omit all credential fields
config = AzureBlobConfig(
    account_url="https://<account>.blob.core.windows.net",
    container_name="my-container",
)

The default path uses DefaultAzureCredential, which supports az login, managed identity, workload identity federation (OIDC), and environment variables.

Supported Operations

All methods from BackendProtocol:

Development

# Install dev dependencies
uv sync --group dev

# Run unit tests
uv run pytest tests/unit_tests -v

# Run integration tests (requires Azurite)
docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite azurite-blob --skipApiVersionCheck --blobHost 0.0.0.0
uv run pytest tests/integration_tests -v

# Lint and format
uv run ruff check .
uv run ruff format .

# Type check
uv run ty check

See the examples/ folder for runnable scripts with setup instructions.

License

MIT