Skip to main content

Storage Guide

This guide explains how to use the SDK's Storage module to upload and download files to Azure Blob Storage / Amazon S3 / Google Cloud Storage. A unified API is provided across all 3 providers.

Overview​

The Storage module provides the following features:

  • Upload / Download — Binary, text, and stream support
  • Presigned URLs — Generate temporary download links
  • Bulk Download — Parallel download of multiple files
  • Path Management — Convention-based path generation with StoragePaths
  • Metadata — Attach custom metadata to files

Provider Selection​

config.tomlToml
[storage]
provider = "azure"

[storage.azure]
connection_string = "${AZURE_STORAGE_CONNECTION_STRING}"
container_name = "agent-files"
Python
from agenticstar_platform.storage import AzureBlobStorageClient, AzureBlobConfig

config = AzureBlobConfig(
    connection_string="DefaultEndpointsProtocol=https;...",
    container_name="agent-files",
)
client = AzureBlobStorageClient(config)

Basic Operations​

The same API can be used across all providers.

Upload​

Python
# Upload a text file
result = await client.upload(
    path="reports/2025/summary.md",
    data=b"# Monthly Summary\n...",
    content_type="text/markdown",
    metadata={"author": "agent-001", "version": "1.0"},
)
print(result.path)  # "reports/2025/summary.md"
print(result.size)  # bytes

# Upload a local file
with open("output.pdf", "rb") as f:
    result = await client.upload(
        path="outputs/output.pdf",
        data=f.read(),
        content_type="application/pdf",
    )

Download​

Python
# Download a file
result = await client.download(path="reports/2025/summary.md")
print(result.data.decode("utf-8"))  # Text content
print(result.metadata)              # Custom metadata

# Save to a local file
with open("downloaded.pdf", "wb") as f:
    result = await client.download(path="outputs/output.pdf")
    f.write(result.data)

List Objects​

Python
# List files in a directory
result = await client.list_objects(prefix="reports/2025/")
for obj in result.objects:
    print(f"{obj.path} ({obj.size} bytes, {obj.last_modified})")

Delete​

Python
await client.delete(path="reports/2025/summary.md")

Presigned URLs​

Python
# Generate a temporary download link (expires in 1 hour)
url = await client.generate_presigned_url(
    path="outputs/output.pdf",
    expires_in=3600,
)
print(url)  # https://...signed URL

Bulk Download​

Python
# Download multiple files in parallel
paths = ["file1.pdf", "file2.pdf", "file3.pdf"]
results = await client.bulk_download(paths)
for path, result in zip(paths, results):
    print(f"{path}: {len(result.data)} bytes")

StoragePaths: Path Conventions​

The StoragePaths class generates paths following platform conventions.

Python
from agenticstar_platform.storage import StoragePaths

paths = StoragePaths(conversation_id="conv-001")

# Plan save path
plan_path = paths.plan_path("intent-plan.json")
# -> "plans/conv-001/intent-plan.json"

# File upload path
upload_path = paths.upload_path("user-document.pdf")
# -> "uploads/conv-001/user-document.pdf"

Usage Patterns in Agents​

File Generation -> Download Link Delivery​

Python
from agenticstar_platform.storage import AzureBlobStorageClient
from agenticstar_platform.events import EventEmitter, EventType

async def generate_and_upload_report(emitter: EventEmitter, client: AzureBlobStorageClient):
    # Generate report
    report_content = await generate_report()

    # Upload to storage
    result = await client.upload(
        path="reports/monthly-report.pdf",
        data=report_content,
        content_type="application/pdf",
    )

    # Generate presigned URL
    url = await client.generate_presigned_url(result.path, expires_in=3600)

    # Emit file creation event
    await emitter.emit_event(
        EventType.FILE_CREATED,
        {"file_name": "monthly-report.pdf", "download_url": url},
    )

Path Sanitization​

The Storage module automatically prevents path traversal attacks.

Python
# Dangerous paths are automatically sanitized
result = await client.upload(
    path="../../etc/passwd",  # -> normalized to "etc/passwd"
    data=b"safe content",
)

Next Steps​

SDK API Reference — Storage Module

Complete specifications for StorageClient / UploadResult / DownloadResult

ガイドを見る

Deploy Guide

Setting up storage connection environment variables

ガイドを見る