Cloud Storage Sources

Load knowledge from S3, Google Cloud Storage, and Azure Blob buckets

Pass a cloud object storage URI as a knowledge source and PraisonAI downloads and indexes it automatically.

from praisonaiagents import Agent

agent = Agent(
    name="Handbook Assistant",
    instructions="Answer questions using the handbook.",
    knowledge=["s3://my-bucket/handbook.pdf"],
)
agent.start("What's the leave policy?")

Quick Start

1. AWS S3

   Install boto3 and pass an s3:// URI.

   pip install boto3

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Handbook Assistant",
       instructions="Answer from the handbook.",
       knowledge=["s3://my-bucket/handbook.pdf"],
   )
   agent.start("What's the leave policy?")

2. Google Cloud Storage

   Install google-cloud-storage and pass a gs:// URI (gcs:// also works).

   pip install google-cloud-storage

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Reports Assistant",
       instructions="Answer from the quarterly report.",
       knowledge=["gs://reports/q4.pdf"],
   )
   agent.start("Summarise Q4 revenue.")

3. Azure Blob

   Install azure-storage-blob and pass an az://container/blob URI or an Azure Blob HTTPS URL.

   pip install azure-storage-blob

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Policy Assistant",
       instructions="Answer from the policy document.",
       knowledge=["https://acct.blob.core.windows.net/docs/policy.pdf"],
   )
   agent.start("What's the refund window?")

Choose Your Provider

Match where your file lives to the right URI form.

Install the Right SDK

Each SDK is imported only when a URI of that scheme is used — installing PraisonAI does not pull in all three.

pip install boto3                    # for s3://

pip install google-cloud-storage     # for gs:// or gcs://

pip install azure-storage-blob       # for az:// or Azure blob URLs
pip install azure-identity           # optional, for Azure managed identity

A missing SDK raises CloudSourceError with the exact pip install … command to run.

Credentials

Each provider uses its SDK’s standard credential discovery — no extra PraisonAI config.

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

export AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=..."

URI Forms

How It Works

A cloud URI is resolved to a local temp file, read by the same reader used for local files, then the temp file is removed.

Design notes worth knowing:

• Extension is preserved. Readers dispatch on file extension — a PDF kept as .pdf is parsed correctly rather than read as plain text.
• Ordering matters. The cloud branch runs before the http(s):// branch, so an Azure blob HTTPS URL is downloaded, not handed to the web fetcher.
• SDKs stay optional. Each cloud SDK is imported only when its scheme is used.
• Temp file removed after indexing. The download lives in a TemporaryDirectory and is cleaned up automatically.
• Original URI kept in metadata. Citations reference the s3://… / gs://… URI, not the meaningless temp path.
• Azure account is bound to the URL. A URL for account A is never served from configured account B — the account named in the URL wins.

Mix Cloud and Local Sources

Cloud URIs, local files, and raw text can share one list.

from praisonaiagents import Agent

agent = Agent(
    name="Research Assistant",
    instructions="Answer from the handbook and local notes.",
    knowledge=[
        "s3://my-bucket/handbook.pdf",
        "gs://reports/q4.pdf",
        "https://acct.blob.core.windows.net/docs/policy.pdf",
        "notes.md",
        "Key fact: launch is in March.",
    ],
)
agent.start("When is the launch?")

Error Reference

CloudSourceError reports the failure instead of silently indexing an empty document.

Best Practices

Related