adding-knowledge

Adding Knowledge to Agents

Overview

Agent2 agents access knowledge through R2R (hybrid search) via Knowledge MCP. You add PDFs or documents to a collection, the agent searches them at runtime. No hardcoding of domain rules — the agent learns from books.

When to Activate

• Agent needs to look up rules, standards, or reference material
• User says "add knowledge", "add books", "ingest documents", "RAG"
• Agent needs different knowledge per client/tenant/context
• User wants to replace hardcoded lookup tables with searchable knowledge

Architecture

PDFs / Documents
  → R2R ingestion (chunking, embedding, indexing)
  → Searchable collection
  → Knowledge MCP server (FastMCP wrapper)
  → Agent calls search() and get_passage() via toolsets=

Step-by-Step

1. Create Collection Directory

mkdir -p knowledge/books/my-collection/
# Place PDFs, markdown, or text files here

2. Register in collections.yaml

# knowledge/collections.yaml
collections:
  my-collection:
    description: "What these documents contain"
    books_dir: books/my-collection/
    agents:
      - my-agent

3. Ingest Documents

# Start the full stack (includes R2R)
docker compose --profile full up -d

# Ingest all collections
python -m shared.ingest --all

# Or a specific collection
python -m shared.ingest --collection my-collection --dir knowledge/books/my-collection/

4. Wire Agent to Knowledge MCP

# agents/my-agent/agent.py
from pydantic_ai.mcp import MCPServerStreamableHTTP

knowledge_mcp_url = os.environ.get("KNOWLEDGE_MCP_URL", "http://localhost:9090/mcp")
knowledge_server = MCPServerStreamableHTTP(knowledge_mcp_url)

agent = create_agent(
    name="my-agent",
    output_type=MySchema,
    instructions="... Use search() to look up relevant information ...",
    toolsets=[knowledge_server],
)

For concurrent or request-scoped agents, create fresh MCPServerStreamableHTTP instances in before_run() and return them as _toolsets; Agent2 passes them to Agent.run(toolsets=...).