Principle:CrewAIInc CrewAI Knowledge Attachment

Metadata

Field	Value
Principle Name	Knowledge Attachment
Workflow	Knowledge_RAG_Pipeline
Category	Agent Configuration
Repository	crewAIInc/crewAI
Implemented By	Implementation:CrewAIInc_CrewAI_Knowledge_Attachment_Config

Overview

A configuration pattern for binding knowledge sources to crews or individual agents, enabling automatic knowledge ingestion during initialization and semantic retrieval during task execution. Knowledge Attachment is the bridge between the knowledge pipeline and the agent execution pipeline.

Description

Knowledge Attachment connects the knowledge pipeline to the agent execution pipeline. By attaching knowledge_sources to a Crew or Agent, the framework automatically creates a Knowledge object, ingests the sources, and makes the resulting vector store available during task execution. Crew-level attachment shares knowledge across all agents; agent-level attachment provides agent-specific knowledge.

The attachment mechanism follows a convention over configuration approach:

• Crew-level attachment -- Setting knowledge_sources on a Crew makes that knowledge available to all agents in the crew. The framework automatically creates a Knowledge object with the crew's embedder configuration and a derived collection name.
• Agent-level attachment -- Setting knowledge_sources on an Agent creates knowledge that is available only to that specific agent. This enables agent specialization where different agents have access to different knowledge domains.

When both crew-level and agent-level knowledge are configured, the agent has access to both during task execution. The retrieval process queries all applicable knowledge stores and merges the results.

Theoretical Basis

Knowledge Attachment applies the Dependency Injection pattern to inject knowledge context into the agent's reasoning loop:

• The agent does not need to know how knowledge is ingested or stored
• The framework handles the lifecycle (creation, ingestion, retrieval) automatically
• The agent receives relevant context as part of its prompt during task execution

This separation of concerns allows users to configure knowledge declaratively without modifying agent logic or task definitions.

Attachment Levels

Level	Scope	Collection Name Convention	Use Case
Crew	All agents in the crew	Derived from crew identifier	Shared domain knowledge
Agent	Single agent only	Derived from agent identifier	Agent-specific expertise

Automatic Lifecycle

When knowledge sources are attached, the following lifecycle is managed automatically:

1. Construction -- A Knowledge object is created with the provided sources and embedder
2. Ingestion -- add_sources() is called during Crew or Agent initialization
3. Retrieval -- During task execution, the task description is used as a query against the knowledge store
4. Augmentation -- Retrieved chunks are appended to the agent's prompt as additional context

The user does not need to write any code for steps 2-4; they happen automatically when knowledge_sources is configured.

Usage Context

Knowledge Attachment is the fourth step in the Knowledge RAG Pipeline:

1. Select and configure knowledge sources (see Principle:CrewAIInc_CrewAI_Knowledge_Source_Selection)
2. Configure the embedding provider (see Principle:CrewAIInc_CrewAI_Embedding_Configuration)
3. Ingest sources into vector storage (see Principle:CrewAIInc_CrewAI_Knowledge_Ingestion)
4. Attach knowledge to a Crew or Agent (this principle)
5. Retrieve relevant chunks during task execution (see Principle:CrewAIInc_CrewAI_Semantic_Retrieval)

Design Decisions

• Declarative configuration -- Users attach knowledge by setting fields on Crew or Agent, not by writing ingestion code. This makes knowledge integration a configuration concern rather than a code concern.
• Automatic ingestion -- Sources are ingested during initialization, ensuring knowledge is available before any task starts executing.
• Dual-level attachment -- Supporting both crew-level and agent-level attachment provides flexibility for both shared and specialized knowledge scenarios.
• Embedder propagation -- The embedder configuration set on a Crew is automatically propagated to the Knowledge object, reducing redundant configuration.

Example Scenario

A research team wants all agents to have access to company policies, while giving the legal agent additional access to regulatory documents:

from crewai import Crew, Agent, Task
from crewai.knowledge.source import PDFKnowledgeSource

# Shared knowledge for all agents
company_policies = PDFKnowledgeSource(
    file_paths=["docs/company_policies.pdf"]
)

# Agent-specific knowledge
regulatory_docs = PDFKnowledgeSource(
    file_paths=["docs/regulations.pdf", "docs/compliance_guide.pdf"]
)

legal_agent = Agent(
    role="Legal Advisor",
    goal="Provide legal guidance",
    backstory="Expert in corporate law",
    knowledge_sources=[regulatory_docs],  # Agent-level attachment
)

research_agent = Agent(
    role="Researcher",
    goal="Research topics thoroughly",
    backstory="Experienced researcher",
)

crew = Crew(
    agents=[legal_agent, research_agent],
    tasks=[...],
    knowledge_sources=[company_policies],  # Crew-level attachment
    embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},
)
# Both agents get company_policies; legal_agent also gets regulatory_docs

Related Pages

• Implementation:CrewAIInc_CrewAI_Knowledge_Attachment_Config -- Concrete field definitions on Crew and Agent
• Principle:CrewAIInc_CrewAI_Knowledge_Ingestion -- Previous step: vector store ingestion
• Principle:CrewAIInc_CrewAI_Semantic_Retrieval -- Next step: automatic retrieval during execution
• Principle:CrewAIInc_CrewAI_Direct_Knowledge_Querying -- Alternative: programmatic querying