createBedrockKBTool()

createBedrockKBTool() 函數會建立一個 Tool，從 Amazon Bedrock Knowledge Base 擷取相關文件。它同時支援受管理搜尋配置及代理式擷取（查詢分解和受管理重新排序），並可自動回退至標準擷取。

使用範例

import { createBedrockKBTool } from '@mastra/rag'

const kbTool = createBedrockKBTool({
  knowledgeBaseId: 'YOUR_KB_ID',
  region: 'us-west-2',
  numberOfResults: 5,
  useAgenticRetrieval: true,
})

配合 Agent 使用

import { Agent } from '@mastra/core/agent'
import { createBedrockKBTool } from '@mastra/rag'

const kbTool = createBedrockKBTool({
  knowledgeBaseId: 'YOUR_KB_ID',
})

const agent = new Agent({
  name: 'KnowledgeAssistant',
  instructions: 'Use the knowledge base tool to answer questions.',
  model: myModel,
  tools: { kb: kbTool },
})

參數

knowledgeBaseId:

string

要查詢的 Amazon Bedrock Knowledge Base ID。

region?:

string

Knowledge Base 部署所在的 AWS 區域。預設為 AWS_REGION 環境變數或 us-east-1。

numberOfResults?:

number

傳回結果的數目上限。預設為 5。

useAgenticRetrieval?:

boolean

針對需要查詢分解和受管理重新排序的複雜查詢使用 AgenticRetrieveStream。失敗時會回退至標準 Retrieve。預設為 true（可透過 USE_AGENTIC_RETRIEVAL=false 環境變數停用）。

userId?:

string

用於文件層級存取控制的預設 AWS 使用者 ID。Mastra 請求 context 中的 userId 優先。

輸入 Schema

由 Agent 呼叫時，此 Tool 接受以下輸入：

queryText:

string

用於在 Knowledge Base 中尋找相關文件的搜尋查詢。

輸出 Schema

此 Tool 傳回包含以下內容的物件：

results:

BedrockKBResult[]

擷取結果陣列。當 Bedrock 提供來源和分數時，標準擷取會包含這些資料；代理式擷取則可能省略這些欄位。

BedrockKBResult

欄位	類型	說明
content	string	所擷取段落的文字內容。
source	string | undefined	Bedrock 有提供時的來源 URI。只有當結果 metadata 包含 _source_uri 時，代理式擷取才會包含此欄位。
score	number | undefined	標準擷取傳回的相關性分數。代理式 API 不會為結果項目傳回分數。
metadata	Record<string, unknown>	擷取結果的其他 metadata。

擷取模式

代理式擷取（預設）

當 useAgenticRetrieval 為 true（預設值）時，此 Tool 會使用 AgenticRetrieveStreamCommand，它會：

• 將複雜查詢分解為子查詢
• 分多輪擷取資料
• 套用受管理重新排序，以改善結果

如果代理式擷取失敗（例如 SDK 較舊或權限不足），它會自動回退至標準受管理擷取。

標準受管理擷取

當 useAgenticRetrieval 為 false 時，此 Tool 會使用配備 managedSearchConfiguration 的 RetrieveCommand 直接執行單輪擷取。

以使用者為基礎的存取控制

在 Mastra 請求 context 中設定 userId，即可將其作為 Bedrock userContext.userId 轉送。這可支援強制執行文件層級存取控制的 Knowledge Base。請求 context 的值會覆寫此 Tool 上配置的預設 userId。

import { RequestContext } from '@mastra/core/request-context'

const requestContext = new RequestContext()
requestContext.set('userId', 'user-123')

await agent.generate('Find my private documents', { requestContext })

所需 IAM 權限

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:Retrieve", "bedrock:AgenticRetrieveStream"],
      "Resource": "arn:aws:bedrock:*:*:knowledge-base/*"
    }
  ]
}

SDK 要求

• @aws-sdk/client-bedrock-agent-runtime >= 3.1000（AgenticRetrieveStreamCommand 需要 ~3.1000+）