createBedrockKBTool()

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

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+ 필요)