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

# createBedrockKBTool()

그만큼`createBedrockKBTool()`함수는 Amazon Bedrock Knowledge Base에서 관련 문서를 검색하는 Tool을 생성합니다. 표준 검색으로 자동 대체하여 관리형 검색 구성과 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 리전입니다. 기본값은 AWS\_REGION 환경 변수 또는 us-east-1입니다.

**numberOfResults** (`number`): 반환할 최대 결과 수입니다. 기본값은 5입니다.

**useAgenticRetrieval** (`boolean`): 쿼리 분해와 관리형 재순위 지정이 필요한 복잡한 쿼리에 AgenticRetrieveStream을 사용합니다. 실패하면 표준 Retrieve로 대체됩니다. 기본값은 true입니다(USE\_AGENTIC\_RETRIEVAL=false 환경 변수로 비활성화).

**userId** (`string`): 문서 수준 액세스 제어에 사용할 기본 AWS 사용자 ID입니다. Mastra 요청 컨텍스트의 userId가 우선합니다.

## 입력 스키마

이 Tool은 Agent가 호출할 때 다음 입력을 허용합니다.

**queryText** (`string`): Knowledge Base에서 관련 문서를 찾기 위한 검색 쿼리입니다.

## 출력 스키마

이 Tool은 다음을 포함하는 개체를 반환합니다.

**results** (`BedrockKBResult[]`): 검색 결과 배열입니다. Bedrock에서 제공하는 경우 표준 검색에는 소스와 점수가 포함되지만 Agentic 검색에서는 해당 필드가 생략될 수 있습니다.

### BedrockKB결과

| 필드         | 유형                        | 설명                                                                                |
| ---------- | ------------------------- | --------------------------------------------------------------------------------- |
| `content`  | `string`                  | 검색된 구절의 텍스트 콘텐츠입니다.                                                               |
| `source`   | `string \| undefined`     | Bedrock에서 제공하는 소스 URI입니다. Agentic 검색은 결과 메타데이터에 `_source_uri`가 있을 때만 이 필드를 포함합니다. |
| `score`    | `number \| undefined`     | 표준 검색에서 반환된 관련성 점수입니다. Agent API는 결과 항목의 점수를 반환하지 않습니다.                           |
| `metadata` | `Record<string, unknown>` | 검색 결과의 추가 메타데이터입니다.                                                               |

## 검색 모드

### Agent 검색(기본값)

`useAgenticRetrieval`이 `true`(기본값)이면 Tool은 다음과 같은 `AgenticRetrieveStreamCommand`를 사용합니다.

- 복잡한 쿼리를 하위 쿼리로 분해합니다.
- 여러 패스에 걸쳐 검색
- 더 나은 결과를 위해 관리형 재순위 적용

Agent 검색이 실패하면(예: 이전 SDK, 권한) 자동으로 표준 관리형 검색으로 대체됩니다.

### 표준 관리 검색

`useAgenticRetrieval`이 `false`이면 Tool은 직접 단일 패스 검색을 위해 `managedSearchConfiguration`과 함께 `RetrieveCommand`를 사용합니다.

## 사용자 기반 접근 제어

Mastra 요청 컨텍스트에 `userId`를 설정하면 Bedrock `userContext.userId`로 전달됩니다. 이는 문서 수준 액세스 제어를 적용하는 Knowledge Base를 지원합니다. 요청 컨텍스트 값은 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+ 필요)