> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Source Types

> What Agent(knowledge=...) accepts today — file paths, plain text, and cloud storage URIs

`Agent(knowledge=...)` accepts local file paths (any UTF-8 text file), plain text, and cloud storage URIs (`s3://`, `gs://`, `az://`, Azure Blob HTTPS) — arbitrary web URLs are not ingested and are skipped with a warning.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Reader",
    instructions="Answer from the provided notes.",
    knowledge=["notes.pdf", "Key fact: launch is in March."],
)
agent.start("When is the launch?")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Knowledge routing (per source in Agent(knowledge=[...]))"
        In[📥 Input string] --> IsCloud{Cloud URI?<br/>s3:// gs:// az://<br/>or Azure blob URL}
        IsCloud -->|Yes| Cloud[☁️ Download & re-enter]
        IsCloud -->|No| IsURL{http:// or<br/>https://?}
        IsURL -->|Yes| Skip[⚠️ Warn & skip]
        IsURL -->|No| KnownExt{Extension in<br/>.pdf .doc .docx .txt<br/>.md .csv .json .xml<br/>.html or media/zip?}
        KnownExt -->|Yes| Handler[📖 Dedicated handler]
        KnownExt -->|No| Exists{Path exists<br/>on disk?}
        Exists -->|Yes, UTF-8 text| ReadText[📄 Read + chunk as text<br/>metadata: file_type, filename]
        Exists -->|Yes, binary| Raise1[🚨 ValueError:<br/>Cannot read as UTF-8]
        Exists -->|No| RawText[📝 Store as raw text]
        Cloud --> Handler
        Handler --> Store[(🗃️ Vector store)]
        ReadText --> Store
        RawText --> Store
    end

    classDef in fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef warn fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef store fill:#10B981,stroke:#7C90A0,color:#fff

    class In in
    class IsCloud,IsURL,KnownExt,Exists decision
    class Cloud,Handler,ReadText,RawText process
    class Skip,Raise1 warn
    class Store store
```

## What Each Source Does

`_process_knowledge` inspects every item and routes it by type.

| Source | Example | Behaviour |
| - | - | - |
| Known-extension file | `"notes.pdf"` | Dedicated handler (`.pdf .doc .docx .txt .md .csv .json .xml .html`, media, `.zip`) — read and indexed |
| Other existing file | `"src/auth.py"`, `"Dockerfile"` | Read as UTF-8 and chunked — metadata records `file_type` and `filename`. Since PraisonAI PR [#4788](https://github.com/MervinPraison/PraisonAI/pull/4788). |
| Plain string (not a path) | `"Key fact: ..."` | `Knowledge.store(text)` — stored as text |
| Cloud URI | `"s3://bucket/handbook.pdf"`, `"gs://…"`, `"az://…"`, Azure blob URL | Downloaded to temp, indexed with the same reader as local files. Original URI preserved in metadata. See [Cloud Sources](/docs/features/knowledge-cloud-sources). |
| Web URL | `"https://example.com"` | **Warns and skips** — not ingested |

<Note>
  Empty files raise `ValueError("Empty text file")` and binary / non-UTF-8 files raise `ValueError("Cannot read <path> as UTF-8 text: ...")` instead of being silently indexed. Since PraisonAI PR [#4788](https://github.com/MervinPraison/PraisonAI/pull/4788).
</Note>

## Indexing Source and Text Together

Mix source files, documents, suffix-less files, and raw strings in one list.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Codebase Assistant",
    instructions="Answer from the indexed files.",
    knowledge=[
        "src/auth.py",                  # source file: read as UTF-8
        "docs/architecture.md",         # markdown: dedicated handler
        "Dockerfile",                   # suffix-less: read as UTF-8
        "Key fact: launch is in March", # raw string: stored as text
    ],
)
agent.start("Summarise how auth is set up.")
```

<Note>
  **Cloud storage URIs are ingested.** `s3://`, `gs://`, `az://`, and Azure Blob HTTPS URLs are downloaded and indexed automatically — see [Cloud Sources](/docs/features/knowledge-cloud-sources). Only ordinary web page URLs are skipped.
</Note>

<Warning>
  Ordinary `http(s)://` web URLs are still skipped. `Agent(knowledge=["https://example.com"])` does not fetch the page. It logs:

  ```
  Knowledge source 'https://example.com...' is a URL; URL knowledge ingestion is not yet implemented in the core SDK. This source will be skipped. Fetch and pass the content as text, or a local file path, instead.
  ```

  Only the scheme and host are logged — credentials and query strings are redacted.
</Warning>

## Fetch, Then Pass Text

Fetch the page yourself and pass the text as a knowledge source.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
from praisonaiagents import Agent

text = requests.get("https://example.com/article").text
agent = Agent(name="Reader", instructions="Summarise the article.", knowledge=[text])
agent.start("Summarise it.")
```

<Note>
  `Knowledge.add(url)` used directly also does not fetch URLs — it raises `NotImplementedError("URL processing not yet implemented")`. Use the fetch-then-text recipe above for both the `Agent` and direct-`Knowledge` paths.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Convert web content to text before ingesting">
    Fetch pages with `requests`, `httpx`, or a scraper, then pass the extracted text as a knowledge string.
  </Accordion>

  <Accordion title="Prefer local files for documents">
    Save PDFs and docs locally and pass the path — `Knowledge.add(path)` reads and chunks them for you.
  </Accordion>

  <Accordion title="Check logs if a source seems missing">
    A skipped URL logs a warning; if answers lack a source you expected, confirm it was a file or text, not a URL.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card icon="book-open" href="/docs/knowledge/features" title="Knowledge Base">
    Chunking, embedding, and search options.
  </Card>

  <Card icon="magnifying-glass" href="/docs/features/rag" title="RAG">
    Retrieval-augmented generation patterns.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.