Agno Knowledge 入门实战：从 Basic RAG 到 Agentic RAG 的完整落地指南

本指南基于 agno 仓库中的 cookbook/07_knowledge/01_getting_started 入门示例，系统讲解如何用 Agno 的 Knowledge 能力为 Agent 接入文档知识库：先对比"自动注入上下文"的 Basic RAG 与"由 Agent 自主决定检索时机"的 Agentic RAG 两种模式，再逐步演示本地文件、URL、原始文本、主题（Wikipedia/ArXiv）与批量加载等全部内容来源，最后进阶到从 sitemap 逐页灌入整个网站并支持按页溯源。读完你将能够独立搭建一个可运行、可扩展的 RAG 问答系统，并理解 add_knowledge_to_context、search_knowledge 等核心参数在源码层面对 Agent 行为的真实影响。

目录概览：这一节里有什么

文件	演示内容
01_basic_rag.py	传统 RAG：检索后自动注入上下文
02_agentic_rag.py	Agentic RAG：由 Agent 自主决定何时检索
03_loading_content.py	从文件、URL、文本、主题与批量加载内容
05_website_per_page.py	依据站点 sitemap 逐页加载网页，并保留按页引用来源

说明：入门目录的 README 中还列出了一份"组件选型决策指南（04_choosing_components.md）"，用于在向量数据库、Embedder 与切块策略之间做选择；当前仓库快照中该文件未同步落地，相关内容可结合 07_knowledge 总览 中介绍的组件选项自行决策。

运行前置条件

在运行任何示例前，需要完成两件事：

1. 启动 Qdrant 向量数据库。仓库提供了现成脚本：

   ./cookbook/scripts/run_qdrant.sh
   

   脚本位于 cookbook/scripts/run_qdrant.sh，会在本地拉起 Qdrant 服务，默认监听地址为 http://localhost:6333（与各示例中硬编码的 qdrant_url 一致）。

2. 设置 OPENAI_API_KEY 环境变量。示例统一使用 OpenAI 生态：

   export OPENAI_API_KEY=your-api-key
   

   因为示例同时依赖 OpenAI 的 Embedder（text-embedding-3-small）与对话模型（OpenAIResponses），所以在启动前必须确保该变量可用。

快速起步：先跑通两个最小示例

按照仓库约定，cookbook 示例通常在 .venvs/demo 虚拟环境中运行：

# Basic RAG（最简单、模式单一）
.venvs/demo/bin/python cookbook/07_knowledge/01_getting_started/01_basic_rag.py

# Agentic RAG（生产环境推荐）
.venvs/demo/bin/python cookbook/07_knowledge/01_getting_started/02_agentic_rag.py

两个示例的结构完全对称：先构造 Knowledge 对象（绑定 Qdrant 集合与 OpenAI Embedder），再把它挂到 Agent 上，最后用 knowledge.ainsert(...) 灌入一份远程 PDF，随后即可向 Agent 提问。其中 02 示例会额外追加一道"三道菜泰餐"的多段式问题，用来观察 Agent 多次检索的行为。

两种 RAG 模式的本质区别

Agno 为"给 Agent 挂载知识库"提供了两种工作方式，README 用一张简洁的对照表做了归纳：

模式	核心参数	工作方式
Basic RAG	add_knowledge_to_context=True	上下文被自动抓取并注入 prompt，简单、可预期，但每次都执行检索
Agentic RAG	search_knowledge=True	Agent 获得一个检索工具，自行决定何时检索，可多次检索、可改写查询、也可完全跳过

在源码层面，这两套行为的默认值位于 libs/agno/agno/agent/agent.py：

• add_knowledge_to_context: bool = False（第 165 行）：默认关闭，只有在 Basic RAG 场景下显式开启；
• search_knowledge: bool = True（第 215 行）：默认开启，因此当你向 Agent 传入 knowledge 而不再做任何设置时，得到的就是 Agentic RAG；
• 另有 add_search_knowledge_instructions: bool = True（第 217 行），控制是否把检索说明写入系统提示词。

Agentic 模式下，Agno 会为 Agent 动态装配一个名为 search_knowledge_base 的工具，其构建逻辑位于 libs/agno/agno/agent/_default_tools.py（"Create a unified search_knowledge_base tool"）。这意味着"是否检索、检索几次、用什么查询词"变成了大模型自主的工具调用决策，而非固定的流水线。

两种模式的选择标准可概括为：简单的文档问答、希望行为完全可控时用 Basic RAG；问题复杂、检索意图不明显或需要多轮多次查询时用 Agentic RAG——后者也是官方推荐的生产默认值。

模式一：Basic RAG——自动上下文注入

01_basic_rag.py 展示了最简单的"上下文注入"范式：系统自动抓取相关内容并注入到系统提示词中，Agent 不需要任何检索能力即可作答。

构建知识库

knowledge = Knowledge(
    vector_db=Qdrant(
        collection="basic_rag",
        url=qdrant_url,
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

关键点拆解：

• Knowledge 是 Agno RAG 框架的顶层门面，类定义位于 libs/agno/agno/knowledge/knowledge.py。它负责整条流水线：读取文档 → 切块 → 嵌入 → 存入向量库 → 检索（见 cookbook/07_knowledge/README.md 的说明）。
• Qdrant 指定向量存储；collection="basic_rag" 为该示例单独建了一个集合，避免与其它示例数据互相污染。
• SearchType.hybrid 是检索方式。从 libs/agno/agno/vectordb/search.py 可以看到它实际有三种取值：vector（纯向量）、keyword（纯关键词）、hybrid（混合检索，向量 + 关键词）。
• OpenAIEmbedder(id="text-embedding-3-small") 负责将文本转为向量，Embedder 实现在 agno.knowledge.embedder.openai 模块中。

创建 Agent 并注入上下文

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    knowledge=knowledge,
    add_knowledge_to_context=True,
    search_knowledge=False,
    markdown=True,
)

这里刻意做了两步设定：

• add_knowledge_to_context=True：打开"自动注入"通道，每次生成前都会检索知识库并把命中的片段放进上下文；
• search_knowledge=False：显式关闭工具式检索，避免 Agent 既被注入上下文又拥有搜索工具的冗余行为。

如文件顶部 docstring 所强调，这种模式"简单、可预期，Agent 不需要决定是否检索——它总是能拿到相关上下文"，非常适合文档上的单轮问答。

灌入文档并提问

async def main():
    await knowledge.ainsert(
        url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"
    )
    agent.print_response(
        "How do I make chicken and galangal in coconut milk soup",
        stream=True,
    )

ainsert 是异步插入接口（同步版为 insert），url 参数会触发底层 Reader 自动抓取并解析该 PDF，随后切块、嵌入并写入 Qdrant。之后用户只需提问，命中内容就会随 prompt 一起交给模型。

模式二：Agentic RAG——Agent 自主驱动的检索

02_agentic_rag.py 与 Basic 版本共享几乎相同的知识库配置（仅集合名改为 agentic_rag），差异完全体现在 Agent 的构建上：

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    knowledge=knowledge,
    search_knowledge=True,
    markdown=True,
)

在 Basic 模式里需要"手动显式开启"的 add_knowledge_to_context 不再出现；Agent 只拿到一个 search_knowledge_base 工具，由模型自行决定是否调用、调用几次、如何改写查询词。示例脚本随后提出两道问题来展示这种灵活性：

1. 单点问答："How do I make chicken and galangal in coconut milk soup"——Agent 会先检索知识库，再基于检索结果组织回答；
2. 多段式综合问题：让 Agent 推荐"三道菜泰餐（汤 + 主菜咖喱 + 甜点）"——由于回答需要覆盖多个菜系片段，Agent 往往需要多次搜索、逐步拼接才能给出完整方案。

这正是 Agentic RAG 相对 Basic RAG 的核心价值：不再是"一次检索、一个 prompt"，而是把检索内化为 Agent 的推理与工具调用链条，检索质量、次数与时机都由模型按需编排。

加载内容：覆盖全部来源类型

实际项目中知识来源多种多样，03_loading_content.py 一口气演示了 Knowledge 支持的 5 类内容来源，并在 docstring 中明确指出"生产环境通常只需选用其中一到两种模式"。

1. 从本地文件加载

await knowledge.ainsert(
    name="CV",
    path="cookbook/07_knowledge/testing_resources/cv_1.pdf",
    metadata={"source": "local_file"},
)

path 指向本地文件（该测试样例确实存在于 cookbook/07_knowledge/testing_resources 目录中）；metadata 可为该内容挂任意键值标签，便于后续过滤。接着即可向 Agent 提问文档中人物的技能。

2. 从 URL 加载

await knowledge.ainsert(
    name="Recipes",
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
    metadata={"source": "url"},
)

同一份泰餐 PDF 换成 url 参数传入，Knowledge 会自动抓取远程资源并走同一套切块嵌入流程。

3. 从原始文本加载

await knowledge.ainsert(
    name="Company Info",
    text_content="Acme Corp was founded in 2020. They build AI tools for developers.",
    metadata={"source": "text"},
)

当数据是代码里动态生成的字符串（如接口返回、用户输入）而非实体文件时，用 text_content 直接注入最方便。

4. 从主题（Wikipedia / ArXiv）加载

from agno.knowledge.reader.wikipedia_reader import WikipediaReader
# Also available: from agno.knowledge.reader.arxiv_reader import ArxivReader

await knowledge.ainsert(
    topics=["Retrieval-Augmented Generation"],
    reader=WikipediaReader(),
)

传 topics 列表并配合一个 reader，即可按主题拉取公开资料。示例中用的是 wikipedia_reader.py；把导入语句换成 arxiv_reader 的 arxiv_reader.py，就可以改为检索论文。

5. 批量加载多个来源

await knowledge.ainsert_many(
    [
        {"name": "Doc 1", "text_content": "Python is a programming language.",
         "metadata": {"topic": "programming"}},
        {"name": "Doc 2", "text_content": "TypeScript adds types to JavaScript.",
         "metadata": {"topic": "programming"}},
    ]
)

ainsert_many 接收一个"内容字典列表"，一次性入库多份文档。示例的收尾问题是"Compare Python and TypeScript"——由于两段内容分属不同的行（row），这个提问恰好能检验 Agent 是否能跨多条知识碎片完成聚合推理。

同步 / 异步 API 对照

脚本 docstring 特别提示：以上全部使用异步方法（ainsert、ainsert_many），同步等价物（insert、insert_many）同样可用。在源码层面，Knowledge 对两组接口均有完整实现，例如 libs/agno/agno/knowledge/knowledge.py 中 insert/insert_many 与 ainsert/ainsert_many 成对出现，方便你在阻塞式脚本与 asyncio 架构之间自由切换。

进阶：按 sitemap 逐页加载整个网站并溯源

当知识库的体量从"几份 PDF"升级为"一整个官网"时，05_website_per_page.py 给出了更精细的摄取方案：一个网页对应一行内容记录，并保留其来源 URL。由此获得两个直接收益：Agent 可以引用它作答的那一页；重新摄取时只刷新发生变化的页面。

引入内容库与逐页 Reader

knowledge = Knowledge(
    name="Agno Docs",
    contents_db=SqliteDb(db_file="tmp/agno_docs_contents.db"),
    vector_db=Qdrant(
        collection="website-pages",
        url="http://localhost:6333",
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

与前面所有示例相比，这里多了一个 contents_db 参数。按脚本注释的解释：contents db 负责保存"每页一条"的行记录（以及用于增量刷新判断的摘要 digest）——没有它，向量库中就只存向量。contents_db 在 libs/agno/agno/knowledge/knowledge.py 中被定义为可选字段，支持任何实现 BaseDb/AsyncBaseDb 的数据库，这里用的是 Agno 自带的 SqliteDb。删除该站点的内容行时，其全部页面与向量也会一并清除。

灌入阶段使用 SitemapReader：

await knowledge.ainsert(
    url="https://docs.agno.com",
    reader=SitemapReader(max_pages=25),
)

Reader 实现位于 sitemap_reader.py，docstring 表明它会从站点的 sitemap 发现页面（自动跟随 robots.txt 与 sitemap 索引），并逐页完整抓取。max_pages=25 用于控制本次最大抓取页数，避免一次性拉取整站。脚本还指出：直接传入一个裸的 sitemap URL（如 url="https://docs.agno.com/sitemap.xml"）会自动选中该 Reader，无需显式指定。

让 Agent 回答时带引用来源

agent = Agent(
    model=OpenAIResponses(id="gpt-5.6-luna"),
    knowledge=knowledge,
    search_knowledge=True,
    instructions="Answer from the knowledge base and cite the source URL of the page you used.",
    markdown=True,
)

这条 instructions 是溯源能力的点睛之笔：因为每条知识都携带独立 source URL，指令让模型"只依据知识库作答并引用所用页面的 URL"，从而在输出中天然呈现可点击、可复核的引用来源，显著提升回答的可信度与可审计性。

更进一步：组件选型与延伸阅读

本目录解决的是"从 0 到 1 跑通 RAG"，而把知识库推向生产还要在三个维度做选型，Agno 已在框架层抽象好对应组件（选项清单见 cookbook/07_knowledge/README.md）：

• Readers（读取器）：PDF、DOCX、CSV、JSON、Web、YouTube、ArXiv 等，决定"文件怎么变成文本"；
• Chunking（切块策略）：Fixed、Recursive、Semantic、Code、Markdown、Agentic 等，决定"文本怎么切分才能召回得准"；
• Embedders（嵌入模型）：OpenAI、Cohere、Bedrock、Ollama 等十多种，决定"语义向量怎么算"；
• Vector DBs（向量库）：Qdrant、LanceDB、ChromaDB、Pinecone 等十多种，决定"向量存哪、怎么搜"；
• Rerankers（重排器）：Cohere、SentenceTransformer、Bedrock、Infinity 等，在召回后二次打分提升质量。

想要继续深入，可以沿两条主线展开：一是 cookbook/07_knowledge/02_building_blocks 目录，逐个剖析切块策略对比、混合检索、两阶段重排、过滤表达式与 Embedder 对比；二是 cookbook/07_knowledge/03_production 目录，学习多来源混合 RAG、知识生命周期管理（增/删/改/跟踪）、多租户隔离与容错摄取等生产级模式。整个 cookbook 的目录树与快速入口都收录在 07_knowledge 的 README 中，可作为后续学习的导航页。

小结

从 add_knowledge_to_context=True 的"全自动注入"，到 search_knowledge=True（框架默认）的"Agent 自主检索"，再到文件 / URL / 文本 / 主题 / 批量 / 整站 sitemap 六种内容摄入方式，这一章已经覆盖了用 Agno 构建 RAG 问答系统的全部基础动作。上手路径很简单：启动 Qdrant、设置 OPENAI_API_KEY、依次运行 01_basic_rag.py 与 02_agentic_rag.py，对照两版代码观察差异；随后用 03_loading_content.py 接入你自己的数据源，即可完成首个可交互的文档知识 Agent。