> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# createBedrockKBTool()

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

## 使用範例

```typescript
import { createBedrockKBTool } from '@mastra/rag'

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

### 搭配 Agent

```typescript
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`。

```typescript
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 權限

```json
{
  "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 以上版本）