createBedrockKBTool()

createBedrockKBTool() 函式會建立一個 Tool，從 Amazon Bedrock Knowledge Base 擷取相關文件。此函式同時支援受管搜尋設定與 Agent 式擷取（查詢分解與受管重新排序），並會在失敗時自動退回標準擷取。

使用範例

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 region。預設使用 AWS_REGION 環境變數或 us-east-1。

numberOfResults?:

number

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

useAgenticRetrieval?:

boolean

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

userId?:

string

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

輸入 schema

Agent 呼叫此 Tool 時可傳入下列輸入：

queryText:

string

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

輸出 schema

此 Tool 會回傳具有下列欄位的物件：

results:

BedrockKBResult[]

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

BedrockKBResult

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

擷取模式

Agent 式擷取（預設）

當 useAgenticRetrieval 為 true（預設值）時，此 Tool 會使用 AgenticRetrieveStreamCommand，其功能包括：

• 將複雜查詢分解為子查詢
• 透過多個階段進行擷取
• 套用受管重新排序以取得更好的結果

若 Agent 式擷取失敗（例如 SDK 版本較舊或權限不足），系統會自動退回標準受管擷取。

標準受管擷取

當 useAgenticRetrieval 為 false 時，此 Tool 會搭配 managedSearchConfiguration 使用 RetrieveCommand，直接進行單階段擷取。

使用者存取控制

在 Mastra request context 中設定 userId，即可將它轉送為 Bedrock userContext.userId。這項功能支援強制執行文件層級存取控制的 Knowledge Base。Request 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 以上版本）