CrewAI BedrockKBRetrieverTool 实战详解为 Agent 接入 Amazon Bedrock 知识库检索【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI本文基于 CrewAI 仓库中crewai-tools包的 Bedrock 知识库工具文档lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/README.md及其对应源码实现撰写。读完后你将掌握BedrockKBRetrieverTool的安装与配置、全部构造参数的取值规则与校验逻辑、在 CrewAI Agent 中的接入方式以及该工具底层对bedrock-agent-runtime.retrieve()的调用链与响应解析机制。1. 工具定位与核心能力BedrockKBRetrieverTool让 CrewAI 智能体能够用自然语言查询natural language query从 Amazon Bedrock 知识库中检索信息是典型的 RAG检索增强生成接入点Agent 负责推理与任务编排知识库检索负责提供来自企业私有数据的事实依据。工具实现在 retriever_tool.py类定义继承自crewai.tools.BaseTool并暴露给 LLM 的输入 Schema 只有一个字段class BedrockKBRetrieverToolInput(BaseModel): Input schema for BedrockKBRetrieverTool. query: str Field( ..., descriptionThe query to retrieve information from the knowledge base )也就是说Agent 侧只需要生成一句查询语句工具内部完成其余所有工作。工具在包内的导出路径为 knowledge_base/init.py并向上聚合到 bedrock/init.py 与 aws/init.py因此既可以从crewai_tools.aws.bedrock.knowledge_base导入也可以直接从crewai_tools.aws导入。2. 安装与环境要求2.1 安装pip install crewai[tools]2.2 前置条件已配置 AWS 凭据环境变量或 AWS CLI 均可依赖boto3与python-dotenv包。源码层面工具声明了package_dependencies: list[str] Field(default_factorylambda: [boto3])且模块导入时执行load_dotenv()因此.env文件中的配置会自动被加载具备目标 Amazon Bedrock 知识库的访问权限。2.3 环境变量BEDROCK_KB_IDyour-knowledge-base-id # 可作为 knowledge_base_id 参数的替代 AWS_REGIONyour-aws-region # 默认 us-east-1 AWS_ACCESS_KEY_IDyour-access-key # AWS 鉴权所需 AWS_SECRET_ACCESS_KEYyour-secret-key # AWS 鉴权所需从源码看__init__中的参数回退逻辑为self.knowledge_base_id knowledge_base_id or os.getenv(BEDROCK_KB_ID)即构造参数优先未显式传入时才回退到BEDROCK_KB_ID环境变量见 retriever_tool.py#L59-L60。Region 的解析链为AWS_REGION→AWS_DEFAULT_REGION→ 兜底us-east-1见 retriever_tool.py#L194-L200。3. 在 CrewAI Agent 中的完整用法以下示例继承自工具 README展示初始化工具 → 挂载到 Agent → 定义 Task → 运行 Crew的完整链路from crewai import Agent, Task, Crew from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockKBRetrieverTool # 初始化工具 kb_tool BedrockKBRetrieverTool( knowledge_base_idyour-kb-id, number_of_results5 ) # 创建使用该工具的 CrewAI Agent researcher Agent( roleKnowledge Base Researcher, goalFind information about company policies, backstoryI am a researcher specialized in retrieving and analyzing company documentation., tools[kb_tool], verboseTrue ) # 为 Agent 创建任务 research_task Task( descriptionFind our companys remote work policy and summarize the key points., agentresearcher ) # 创建包含该 Agent 的 Crew crew Crew( agents[researcher], tasks[research_task], verbose2 ) # 运行 result crew.kickoff() print(result)工具初始化后其description会被动态改写为Retrieves information from Amazon Bedrock Knowledge Base {knowledge_base_id} given a query这样 Agent 在决策是否调用工具时能明确感知具体查询的是哪个知识库。4. 参数详解与校验规则4.1 构造参数参数类型必填默认值说明knowledge_base_idstr是*None知识库唯一标识0–10 位字母数字字符可用环境变量BEDROCK_KB_ID替代number_of_resultsint否5返回的最大结果数retrieval_configurationdict否None自定义知识库查询配置guardrail_configurationdict否None内容过滤Guardrail设置next_tokenstr否None分页游标用于获取下一批结果* 若通过BEDROCK_KB_ID环境变量提供则构造参数可省略。4.2 参数校验逻辑源码级_validate_parameters()在__init__末尾被调用校验失败会抛出BedrockValidationError定义于 exceptions.py继承自BedrockError基类。具体约束见 retriever_tool.py#L89-L124knowledge_base_id非空、必须是字符串、长度 ≤ 10、仅允许字母数字字符next_token若非空必须是字符串、长度在 1–2048 之间、不能包含空格number_of_results必须是整数且 0。4.3 retrieval_configuration 的自动生成如果没有显式传入retrieval_configuration工具会根据number_of_results自动构造def _build_retrieval_configuration(self) - dict[str, Any]: vector_search_config {} if self.number_of_results is not None: vector_search_config[numberOfResults] self.number_of_results return {vectorSearchConfiguration: vector_search_config}即默认等价于{vectorSearchConfiguration: {numberOfResults: 5}}。5. 高级用法自定义检索配置与 Guardrail5.1 混合检索HYBRID显式传入retrieval_configuration时工具会原样使用该配置不再自动构造kb_tool BedrockKBRetrieverTool( knowledge_base_idyour-kb-id, retrieval_configuration{ vectorSearchConfiguration: { numberOfResults: 10, overrideSearchType: HYBRID } } ) policy_expert Agent( rolePolicy Expert, goalAnalyze company policies in detail, backstoryI am an expert in corporate policy analysis with deep knowledge of regulatory requirements., tools[kb_tool] )5.2 内容过滤Guardrail与分页guardrail_configuration与next_token分别映射到 Bedrock API 的guardrailConfiguration与nextToken字段用于对检索内容做合规过滤和分批拉取kb_tool BedrockKBRetrieverTool( knowledge_base_idkb123, guardrail_configuration{ guardrailIdentifier: your-guardrail-id, guardrailVersion: DRAFT, trace: ENABLED, } )响应中的guardrailAction字段会回传 Guardrail 的处理动作便于在 Agent 侧感知内容是否被干预。6. 底层调用链_run()的完整执行流程_run(query)是 Agent 调用工具时的实际入口执行流程可拆解为六步见 retriever_tool.py#L183-L250懒加载 boto3import boto3失败时抛出ImportError提示执行uv add boto3创建客户端boto3.client(bedrock-agent-runtime, region_name...)AWS 鉴权由 SDK 自动从环境读取组装请求参数retrieve_params { knowledgeBaseId: self.knowledge_base_id, retrievalQuery: {text: query}, } if self.retrieval_configuration: retrieve_params[retrievalConfiguration] self.retrieval_configuration if self.guardrail_configuration: retrieve_params[guardrailConfiguration] self.guardrail_configuration if self.next_token: retrieve_params[nextToken] self.next_token发起检索bedrock_agent_runtime.retrieve(**retrieve_params)逐条后处理对response[retrievalResults]中每条记录调用_process_retrieval_result()标准化序列化返回结果为空时返回{message: No results found for the given query.}否则输出results列表如响应中存在nextToken、guardrailAction则一并透传最终以json.dumps(..., indent2)返回给 Agent。异常处理分两层botocore.exceptions.ClientError会被解包出Code与Message后抛出BedrockKnowledgeBaseError(Error ({code}): {message})其他异常统一包装为BedrockKnowledgeBaseError(Unexpected error: ...)。这两个异常类型均定义在 exceptions.py 中可在业务代码中精确捕获知识库错误而不影响其他工具调用。7. 响应格式与来源映射机制7.1 标准化响应工具对外返回 JSON 字符串{ results: [ { content: Retrieved text content, content_type: text, source_type: S3, source_uri: s3://bucket/document.pdf, score: 0.95, metadata: { additional: metadata } } ], nextToken: pagination-token, guardrailAction: NONE }字段说明content/content_type检索片段文本及其类型默认textsource_type/source_uri数据源类型与定位地址见 7.2 的映射表score相关性分数仅当 API 返回时存在metadata知识库附加元数据仅当返回时存在此外_process_retrieval_result()还会把二进制片段映射为byte_content来自byteContent、结构化行映射为row_content来自row用于 SQL 等非文本数据源。7.2 八种数据源的 URI 映射_process_retrieval_result()内置了一张 Bedrock 位置类型 → 工具输出类型 → URI 取字段的映射表见 retriever_tool.py#L144-L153Bedrock 位置字段输出 source_typeURI 取值字段s3LocationS3uriconfluenceLocationConfluenceurlsalesforceLocationSalesforceurlsharePointLocationSharePointurlwebLocationWeburlcustomDocumentLocationCustomDocumentidkendraDocumentLocationKendraDocumenturisqlLocationSQLquery这意味着该工具天然覆盖 Bedrock 知识库支持的多种数据源Amazon S3、Confluence、Salesforce、SharePoint、网页、自定义文档位置、Amazon Kendra 与 SQL 数据库Agent 拿到的每条结果都带有可追溯的来源信息。8. 典型应用场景工具 README 归纳了五类落地场景均围绕让 Agent 的推理扎根于企业真实数据展开企业知识集成Agent 直接访问组织私有知识而不暴露敏感数据基于内部政策、流程与文档做决策领域专家知识无需微调模型即可让 Agent 接入法律、医疗、技术等垂直领域知识库复用 AWS 环境中已有的知识资产数据驱动决策以实际业务数据为回答依据减少幻觉可扩展的信息访问无需将数 TB 级知识嵌入模型按任务动态检索相关片段合规与治理Agent 的回答对齐已批准的内部文档且source_uri/metadata可形成可审计的信息来源记录配合 Guardrail 进一步控制访问边界。9. 小结BedrockKBRetrieverTool的实现非常聚焦一个query输入 Schema、五条构造参数、一次retrieve()调用、一套八源映射的结果标准化逻辑。它的工程价值在于把 Bedrock 知识库检索封装成 CrewAI 工具协议BaseTool下的普通成员——Agent 通过tools[kb_tool]即可挂载无需感知 boto3 细节而参数校验、错误包装、来源映射等健壮性逻辑保证了它在生产链路中可预测、可调试。相关源码索引工具实现retriever_tool.py异常定义exceptions.py模块文档README.md【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CrewAI BedrockKBRetrieverTool 实战详解为 Agent 接入 Amazon Bedrock 知识库检索【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI本文基于 CrewAI 仓库中crewai-tools包的 Bedrock 知识库工具文档lib/crewai-tools/src/crewai_tools/aws/bedrock/knowledge_base/README.md及其对应源码实现撰写。读完后你将掌握BedrockKBRetrieverTool的安装与配置、全部构造参数的取值规则与校验逻辑、在 CrewAI Agent 中的接入方式以及该工具底层对bedrock-agent-runtime.retrieve()的调用链与响应解析机制。1. 工具定位与核心能力BedrockKBRetrieverTool让 CrewAI 智能体能够用自然语言查询natural language query从 Amazon Bedrock 知识库中检索信息是典型的 RAG检索增强生成接入点Agent 负责推理与任务编排知识库检索负责提供来自企业私有数据的事实依据。工具实现在 retriever_tool.py类定义继承自crewai.tools.BaseTool并暴露给 LLM 的输入 Schema 只有一个字段class BedrockKBRetrieverToolInput(BaseModel): Input schema for BedrockKBRetrieverTool. query: str Field( ..., descriptionThe query to retrieve information from the knowledge base )也就是说Agent 侧只需要生成一句查询语句工具内部完成其余所有工作。工具在包内的导出路径为 knowledge_base/init.py并向上聚合到 bedrock/init.py 与 aws/init.py因此既可以从crewai_tools.aws.bedrock.knowledge_base导入也可以直接从crewai_tools.aws导入。2. 安装与环境要求2.1 安装pip install crewai[tools]2.2 前置条件已配置 AWS 凭据环境变量或 AWS CLI 均可依赖boto3与python-dotenv包。源码层面工具声明了package_dependencies: list[str] Field(default_factorylambda: [boto3])且模块导入时执行load_dotenv()因此.env文件中的配置会自动被加载具备目标 Amazon Bedrock 知识库的访问权限。2.3 环境变量BEDROCK_KB_IDyour-knowledge-base-id # 可作为 knowledge_base_id 参数的替代 AWS_REGIONyour-aws-region # 默认 us-east-1 AWS_ACCESS_KEY_IDyour-access-key # AWS 鉴权所需 AWS_SECRET_ACCESS_KEYyour-secret-key # AWS 鉴权所需从源码看__init__中的参数回退逻辑为self.knowledge_base_id knowledge_base_id or os.getenv(BEDROCK_KB_ID)即构造参数优先未显式传入时才回退到BEDROCK_KB_ID环境变量见 retriever_tool.py#L59-L60。Region 的解析链为AWS_REGION→AWS_DEFAULT_REGION→ 兜底us-east-1见 retriever_tool.py#L194-L200。3. 在 CrewAI Agent 中的完整用法以下示例继承自工具 README展示初始化工具 → 挂载到 Agent → 定义 Task → 运行 Crew的完整链路from crewai import Agent, Task, Crew from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockKBRetrieverTool # 初始化工具 kb_tool BedrockKBRetrieverTool( knowledge_base_idyour-kb-id, number_of_results5 ) # 创建使用该工具的 CrewAI Agent researcher Agent( roleKnowledge Base Researcher, goalFind information about company policies, backstoryI am a researcher specialized in retrieving and analyzing company documentation., tools[kb_tool], verboseTrue ) # 为 Agent 创建任务 research_task Task( descriptionFind our companys remote work policy and summarize the key points., agentresearcher ) # 创建包含该 Agent 的 Crew crew Crew( agents[researcher], tasks[research_task], verbose2 ) # 运行 result crew.kickoff() print(result)工具初始化后其description会被动态改写为Retrieves information from Amazon Bedrock Knowledge Base {knowledge_base_id} given a query这样 Agent 在决策是否调用工具时能明确感知具体查询的是哪个知识库。4. 参数详解与校验规则4.1 构造参数参数类型必填默认值说明knowledge_base_idstr是*None知识库唯一标识0–10 位字母数字字符可用环境变量BEDROCK_KB_ID替代number_of_resultsint否5返回的最大结果数retrieval_configurationdict否None自定义知识库查询配置guardrail_configurationdict否None内容过滤Guardrail设置next_tokenstr否None分页游标用于获取下一批结果* 若通过BEDROCK_KB_ID环境变量提供则构造参数可省略。4.2 参数校验逻辑源码级_validate_parameters()在__init__末尾被调用校验失败会抛出BedrockValidationError定义于 exceptions.py继承自BedrockError基类。具体约束见 retriever_tool.py#L89-L124knowledge_base_id非空、必须是字符串、长度 ≤ 10、仅允许字母数字字符next_token若非空必须是字符串、长度在 1–2048 之间、不能包含空格number_of_results必须是整数且 0。4.3 retrieval_configuration 的自动生成如果没有显式传入retrieval_configuration工具会根据number_of_results自动构造def _build_retrieval_configuration(self) - dict[str, Any]: vector_search_config {} if self.number_of_results is not None: vector_search_config[numberOfResults] self.number_of_results return {vectorSearchConfiguration: vector_search_config}即默认等价于{vectorSearchConfiguration: {numberOfResults: 5}}。5. 高级用法自定义检索配置与 Guardrail5.1 混合检索HYBRID显式传入retrieval_configuration时工具会原样使用该配置不再自动构造kb_tool BedrockKBRetrieverTool( knowledge_base_idyour-kb-id, retrieval_configuration{ vectorSearchConfiguration: { numberOfResults: 10, overrideSearchType: HYBRID } } ) policy_expert Agent( rolePolicy Expert, goalAnalyze company policies in detail, backstoryI am an expert in corporate policy analysis with deep knowledge of regulatory requirements., tools[kb_tool] )5.2 内容过滤Guardrail与分页guardrail_configuration与next_token分别映射到 Bedrock API 的guardrailConfiguration与nextToken字段用于对检索内容做合规过滤和分批拉取kb_tool BedrockKBRetrieverTool( knowledge_base_idkb123, guardrail_configuration{ guardrailIdentifier: your-guardrail-id, guardrailVersion: DRAFT, trace: ENABLED, } )响应中的guardrailAction字段会回传 Guardrail 的处理动作便于在 Agent 侧感知内容是否被干预。6. 底层调用链_run()的完整执行流程_run(query)是 Agent 调用工具时的实际入口执行流程可拆解为六步见 retriever_tool.py#L183-L250懒加载 boto3import boto3失败时抛出ImportError提示执行uv add boto3创建客户端boto3.client(bedrock-agent-runtime, region_name...)AWS 鉴权由 SDK 自动从环境读取组装请求参数retrieve_params { knowledgeBaseId: self.knowledge_base_id, retrievalQuery: {text: query}, } if self.retrieval_configuration: retrieve_params[retrievalConfiguration] self.retrieval_configuration if self.guardrail_configuration: retrieve_params[guardrailConfiguration] self.guardrail_configuration if self.next_token: retrieve_params[nextToken] self.next_token发起检索bedrock_agent_runtime.retrieve(**retrieve_params)逐条后处理对response[retrievalResults]中每条记录调用_process_retrieval_result()标准化序列化返回结果为空时返回{message: No results found for the given query.}否则输出results列表如响应中存在nextToken、guardrailAction则一并透传最终以json.dumps(..., indent2)返回给 Agent。异常处理分两层botocore.exceptions.ClientError会被解包出Code与Message后抛出BedrockKnowledgeBaseError(Error ({code}): {message})其他异常统一包装为BedrockKnowledgeBaseError(Unexpected error: ...)。这两个异常类型均定义在 exceptions.py 中可在业务代码中精确捕获知识库错误而不影响其他工具调用。7. 响应格式与来源映射机制7.1 标准化响应工具对外返回 JSON 字符串{ results: [ { content: Retrieved text content, content_type: text, source_type: S3, source_uri: s3://bucket/document.pdf, score: 0.95, metadata: { additional: metadata } } ], nextToken: pagination-token, guardrailAction: NONE }字段说明content/content_type检索片段文本及其类型默认textsource_type/source_uri数据源类型与定位地址见 7.2 的映射表score相关性分数仅当 API 返回时存在metadata知识库附加元数据仅当返回时存在此外_process_retrieval_result()还会把二进制片段映射为byte_content来自byteContent、结构化行映射为row_content来自row用于 SQL 等非文本数据源。7.2 八种数据源的 URI 映射_process_retrieval_result()内置了一张 Bedrock 位置类型 → 工具输出类型 → URI 取字段的映射表见 retriever_tool.py#L144-L153Bedrock 位置字段输出 source_typeURI 取值字段s3LocationS3uriconfluenceLocationConfluenceurlsalesforceLocationSalesforceurlsharePointLocationSharePointurlwebLocationWeburlcustomDocumentLocationCustomDocumentidkendraDocumentLocationKendraDocumenturisqlLocationSQLquery这意味着该工具天然覆盖 Bedrock 知识库支持的多种数据源Amazon S3、Confluence、Salesforce、SharePoint、网页、自定义文档位置、Amazon Kendra 与 SQL 数据库Agent 拿到的每条结果都带有可追溯的来源信息。8. 典型应用场景工具 README 归纳了五类落地场景均围绕让 Agent 的推理扎根于企业真实数据展开企业知识集成Agent 直接访问组织私有知识而不暴露敏感数据基于内部政策、流程与文档做决策领域专家知识无需微调模型即可让 Agent 接入法律、医疗、技术等垂直领域知识库复用 AWS 环境中已有的知识资产数据驱动决策以实际业务数据为回答依据减少幻觉可扩展的信息访问无需将数 TB 级知识嵌入模型按任务动态检索相关片段合规与治理Agent 的回答对齐已批准的内部文档且source_uri/metadata可形成可审计的信息来源记录配合 Guardrail 进一步控制访问边界。9. 小结BedrockKBRetrieverTool的实现非常聚焦一个query输入 Schema、五条构造参数、一次retrieve()调用、一套八源映射的结果标准化逻辑。它的工程价值在于把 Bedrock 知识库检索封装成 CrewAI 工具协议BaseTool下的普通成员——Agent 通过tools[kb_tool]即可挂载无需感知 boto3 细节而参数校验、错误包装、来源映射等健壮性逻辑保证了它在生产链路中可预测、可调试。相关源码索引工具实现retriever_tool.py异常定义exceptions.py模块文档README.md【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
