Chapter 11 · Knowledge Sources

Chapter goals: Master mounting knowledge_sources (string/text/PDF and other sources), understand agent-level vs crew-level knowledge initialization and storage differences, correctly configure embedders, and clearly differentiate the boundaries between knowledge, tools, and memory.

11.1 What Is Knowledge?

Knowledge gives the agent a "reference library": you hand domain documents (strings, txt, PDF, CSV, Excel, JSON, even web pages) to the framework, and it retrieves relevant fragments at task execution time to inject into context — so answers are evidence-based rather than guessed from the model's parametric memory.

One-sentence difference from Chapter 10's memory: memory is experience accumulated during runtime; knowledge is textbook material prepared before going live.

11.2 Quick Start: String Knowledge Source

python

import os

from crewai import Agent, Crew, Process, Task, LLM
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource

llm = LLM(
    model="openai/deepseek-chat",
    base_url="https://api.deepseek.com/v1",
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    temperature=0,          # low temperature recommended for knowledge Q&A to reduce free-form generation
)

# 1. Create a knowledge source: here using a text block about a user profile
content = "The user's name is Zhang Wei. He is 32 years old, lives in Hangzhou, works as a backend engineer, and prefers Python technical content."
string_source = StringKnowledgeSource(content=content)

agent = Agent(
    role="User Assistant",
    goal="Accurately answer questions about the user based on known information",
    backstory="A rigorous personal assistant who never fabricates information not in the source material.",
    llm=llm,
    allow_delegation=False,
    verbose=True,
)

task = Task(
    description="Answer the following question about the user: {question}",
    expected_output="One accurate English sentence.",
    agent=agent,
)

crew = Crew(
    agents=[agent],
    tasks=[task],
    process=Process.sequential,
    knowledge_sources=[string_source],   # 2. Mount the knowledge source at the crew level
    verbose=True,
)

result = crew.kickoff(inputs={"question": "Which city does Zhang Wei live in? What content does he prefer?"})
print(result.raw)

11.3 File-Based Knowledge Sources and Directory Conventions

File-based knowledge sources are read from the project's knowledge/ directory (relative path):

python

from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource
from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource
from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource

# Project structure:
# your_project/
# ├── knowledge/
# │   ├── handbook.txt
# │   ├── policy.pdf
# │   └── sales.csv
# └── main.py

text_source = TextFileKnowledgeSource(file_paths=["handbook.txt"])
pdf_source = PDFKnowledgeSource(file_paths=["policy.pdf"])      # note: pdf not txt
csv_source = CSVKnowledgeSource(file_paths=["sales.csv"])

crew = Crew(
    ...,
    knowledge_sources=[text_source, pdf_source, csv_source],   # multiple sources can be mixed
)

Path convention

The official docs are explicit: file_paths for file-based sources are relative to the knowledge/ directory. Using absolute paths or placing files in the wrong location is the most common cause of empty retrieval results. Web content can use CrewDoclingSource (requires installing the docling package).

11.4 Agent-Level vs Crew-Level Knowledge

Knowledge can be mounted at two levels. Their initialization timing and storage are independent:

python

from crewai import Agent, Crew, Task
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource

# Agent-level: only this agent can retrieve it, stored independently (collection name = agent's role)
private_knowledge = StringKnowledgeSource(
    content="Internal confidential: the discount cap for the Q4 promotion campaign is 30%."
)
specialist = Agent(
    role="Promotion Planner",
    goal="Design plans within the discount policy",
    backstory="A senior planner well-versed in company promotion policies.",
    knowledge_sources=[private_knowledge],   # agent-private knowledge
    embedder={                               # agents can also have their own embedder
        "provider": "openai",
        "config": {"model_name": "text-embedding-3-small"},
    },
)

# Crew-level: shared by all members (stored in a collection named "crew")
shared_knowledge = StringKnowledgeSource(content="The company's product lines include Series A, B, and C.")

crew = Crew(
    agents=[specialist],
    tasks=[Task(description="Design a Double 11 promotion plan", expected_output="plan highlights", agent=specialist)],
    knowledge_sources=[shared_knowledge],    # crew-shared knowledge
)

The official docs disclose this initialization mechanism: on kickoff(), the framework sets a crew reference on each agent and calls set_knowledge(crew_embedder=...) to initialize knowledge. Agent knowledge and crew knowledge are stored in different collections within the same ChromaDB instance (local path approx ~/.local/share/CrewAI/{project}/knowledge/), so the two levels can coexist independently without contaminating each other.

11.5 Embedder Configuration

Identical to the memory system — knowledge retrieval defaults to OpenAI embedding. Third-party compatible endpoints or local model configuration follows the same pattern as Chapter 10:

python

crew = Crew(
    agents=[agent],
    tasks=[task],
    knowledge_sources=[string_source],
    embedder={                                   # crew-level embedder
        "provider": "openai",
        "config": {
            "model_name": "text-embedding-3-small",
            "api_key": os.getenv("DEEPSEEK_API_KEY"),
        },
    },
)
# Local alternative: change provider to "ollama" and add url to config pointing to local embeddings endpoint

Changing the model = rebuild the index

After changing the embedding model (causing a dimension shift), the old knowledge index cannot be reused. The remedy is identical to memory: run crewai reset-memories --knowledge (or --agent-knowledge) to clear and rebuild.

11.6 Distinction: Knowledge vs Tools vs Memory

All three "supplement information to the model," but timing and certainty are completely different:

Dimension	Knowledge	Tools	Memory
Content source	Static materials prepared before launch	Runtime calls to external systems	Experience accumulated automatically during runtime
Injection method	Framework retrieves and injects deterministically at task time — high certainty	Model autonomously decides whether to call	Framework auto-extracts and recalls
Best for	Product manuals, policies, FAQs, domain facts	Real-time data, write operations, computation	User preferences, historical conclusions
Update frequency	Low (changing material requires rebuilding the index)	High (always fresh values)	Grows continuously

Selection mantra: stable → knowledge; dynamic → tools; experienced → memory. Putting "today's weather" in the knowledge base, or expecting the agent to always proactively call a RAG tool to look up the manual, are typical misuse patterns.

Chapter Summary

knowledge_sources supports String/Text/PDF/CSV/Excel/JSON sources; files go in the knowledge/ directory with relative paths;
Agent-level and crew-level knowledge initialize independently and store in separate collections (local ChromaDB), without interfering;
Embedder configuration is isomorphic with the memory system — supports third-party OpenAI-compatible endpoints or local Ollama;
Changing the embedding model requires crewai reset-memories --knowledge / --agent-knowledge to rebuild;
Knowledge = static textbook (deterministic injection), Tools = dynamic capability (model自主 calls), Memory = experience accumulation (auto-settles).

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. When using TextFileKnowledgeSource, what is the official file path convention?

2. Regarding agent-level vs crew-level knowledge, which statement is correct?

3. A product manual (updated once every six months) is best served to an agent via which mechanism?

4. After switching the embedding model, knowledge retrieval throws an error. Correct remedy?

🛠️ Hands-On Exercises

Mount a familiar PDF manual as a crew-level knowledge source; design 10 questions to test retrieval accuracy; record failing cases and analyze root causes (missed retrieval vs model free-generation).
Construct both "agent-private + crew-shared" two-level knowledge: let the specialist access confidential discount policy while other agents cannot; verify the two-level isolation.
Implement the same Q&A scenario using both "knowledge base" and "RAG tool" (PDFSearchTool from Chapter 7); compare invocation certainty and answer stability; write a selection conclusion.

Next chapter solves "how to make the crew's output directly usable as program data": Chapter 12 · Output Processing.

Chapter 11 · Knowledge Sources ​

11.1 What Is Knowledge? ​

11.2 Quick Start: String Knowledge Source ​

11.3 File-Based Knowledge Sources and Directory Conventions ​

11.4 Agent-Level vs Crew-Level Knowledge ​

11.5 Embedder Configuration ​

11.6 Distinction: Knowledge vs Tools vs Memory ​

Chapter Summary ​

🧪 随堂测验

🛠️ Hands-On Exercises ​

Chapter 11 · Knowledge Sources

11.1 What Is Knowledge?

11.2 Quick Start: String Knowledge Source

11.3 File-Based Knowledge Sources and Directory Conventions

11.4 Agent-Level vs Crew-Level Knowledge

11.5 Embedder Configuration

11.6 Distinction: Knowledge vs Tools vs Memory

Chapter Summary

🛠️ Hands-On Exercises