Amazon Bedrock Managed Knowledge Bases를 커넥터 대상으로 사용

Amazon Bedrock 관리형 지식 기반은 완전 관리형 검색 증강 생성(RAG)을 제공합니다. Amazon Bedrock은 벡터 스토어, 데이터 수집 및 검색 최적화를 처리하므로 프로비저닝하거나 운영할 검색 인프라가 없습니다. Amazon Bedrock AgentCore는 관리형 지식 기반을 네이티브 게이트웨이 커넥터로 노출합니다. 이를 AgentCore Gateway에 연결하면 에이전트가 빌드할 사용자 지정 검색 통합 없이 표준 모델 컨텍스트 프로토콜(MCP) 호출을 통해 이를 검색하고 쿼리합니다. 관리형 지식 기반을 생성하고 관리하는 방법에 대한 자세한 내용은 Amazon Bedrock 사용 설명서의 Amazon Bedrock용 지식 기반을 참조하세요.

커넥터는 두 개의 도구를 노출합니다. 첫 번째는 입니다AgenticRetrieveStream. 단일 조회 대신 검색 전략을 계획하고, 관리형 지식 기반에서 여러 검색 단계를 실행하고, 선택적으로 전체 문서로 확장하고, 지원 결과와 합성된 인용 기반 답변을 모두 스트리밍합니다.는 단일 하이브리드 검색을 Retrieve 수행하고 가장 관련성이 높은 구절을 반환합니다.

다음 섹션에서는 커넥터 작동 방식, 심층 에이전트 검색, 일반적인 사용 사례, 대상 설정 방법, 두 도구의 입력 및 응답 스키마를 안내합니다.

작동 방식

Amazon Bedrock AgentCore는 Amazon Bedrock 관리형 지식 기반에 내장된 커넥터를 제공합니다. 게이트웨이는 스키마 관리, 엔드포인트 확인 및 서비스 인증을 처리합니다. 커넥터는 에이전트가에서 검색하는 tools/list두 가지 도구를 노출합니다.

단일 Retrieve 호출은 다음 흐름을 따릅니다.

에이전트 검색 흐름은 에이전트 검색을 참조하세요.

에이전트 검색

AgenticRetrieveStream는 질문을 작업으로 처리합니다. 하나의 쿼리에 대해 Retrieve 실행되는 단일 하이브리드 검색 대신 검색 전략을 계획하고, 관리형 지식 기반에서 여러 검색 단계를 실행하고, 지원 결과와 합성된 인용 기반 응답을 스트리밍합니다.이 모든 것이 하나의 도구 호출로 이루어집니다. 합성된 답변은 기본적으로 반환됩니다. 결과만 반환false하도록를 generateResponse 로 설정합니다.

에이전트는 대화()를 통해 호출합니다messages. 각각 관리형 지식 기반을 가리키는 쿼리하는 리트리버는 에이전트가 제공하지 않고 대상의 관리자가 구성합니다. MCP를 통한 계획 및 검색 진행 스트림은 로notifications/message, 결과와 답변은 도구 결과에 반환됩니다.

에이전트 검색의 작동 방식에 대한 자세한 내용은 Amazon Bedrock 사용 설명서의 Amazon Bedrock용 지식 기반을 참조하세요.

요청 및 이벤트 스키마는 AgenticRetrieveStream 입력 스키마 및 AgenticRetrieveStream 응답 형식을 참조하세요.

사용 사례

관리형 지식 기반 설정

Python SDK 및 CLI를 사용한 설정 예제를 포함하여 Amazon Bedrock 관리형 지식 기반 커넥터 구성을 사용하여 게이트웨이 대상을 생성하는 방법에 대한 지침은 대상 구성 가이드의 관리형 지식 기반 설정을 참조하세요.

게이트웨이 서비스 역할 구성

게이트웨이에는 AgentCore 서비스가 사용자를 대신하여 관리형 지식 기반에서 검색 작업을 수행할 수 있는 서비스 역할이 필요합니다. 필요한 IAM 권한 및 정책 구성은 대상 구성 가이드의 게이트웨이 서비스 역할 구성을 참조하세요.

도구 호출

대상을 생성한 후 에이전트는를 사용하여 도구를 검색tools/list하고를 사용하여 호출합니다tools/call. 각 도구 이름에는 <target-name>_<tool-name>_AgenticRetrieveStream 또는 형식의 대상 이름이 접두사로 붙습니다managed-kb___Retrieve).

의 경우 AgenticRetrieveStream에이전트는 대화만 전달합니다. 리트리버는 관리자가 대상에 구성하므로 에이전트는 지식 기반 IDs를 보내지 않습니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "managed-kb___AgenticRetrieveStream",
    "arguments": {
      "messages": [
        { "role": "user", "content": { "text": "How do I configure a knowledge base target?" } }
      ]
    }
  }
}

Retrieve의 경우 관리형 지식 기반 식별자가 대상에 바인딩되므로 에이전트는 쿼리만 전달합니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "managed-kb___Retrieve",
    "arguments": {
      "retrievalQuery": { "text": "What is Amazon Bedrock AgentCore?" }
    }
  }
}

검색 파라미터를 에이전트에 노출한 경우(에이전트가 설정할 수 있는 파라미터 제어 참조) 에이전트는 호출 시 관리자가 구성한 기본값을 재정의할 수 있습니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "managed-kb___Retrieve",
    "arguments": {
      "retrievalQuery": { "text": "insurance benefits" },
      "retrievalConfiguration": {
        "managedSearchConfiguration": { "numberOfResults": 2 }
      }
    }
  }
}

AgenticRetrieveStream 입력 스키마

에서 반환되는 스키마는 에이전트가를 호출할 때 설정할 수 있는 필드 세트tools/list입니다AgenticRetrieveStream. 기본적으로 에이전트가 볼 수 있는 유일한 필드는 입니다messages. 쿼리할 리트리버와 모든 검색 구성은 대상에서 관리자가 설정합니다. 관리형 지식 기반 설정을 참조하세요. 에이전트에 더 많은 필드를 노출하려면 대상parameterOverrides에를 구성합니다. 에이전트가 설정할 수 있는 파라미터 제어를 참조하세요.

{
  "type": "object",
  "properties": {
    "messages": {
      "description": "The messages for the agentic retrieval conversation. Contains the user query and conversation history.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "description": "The role of the message sender (user or assistant).",
            "type": "string",
            "enum": ["user", "assistant"]
          },
          "content": {
            "description": "The content of the message.",
            "type": "object",
            "properties": {
              "text": {
                "description": "The text content of the message.",
                "type": "string"
              }
            }
          }
        },
        "required": ["content", "role"]
      }
    }
  },
  "required": ["messages"]
}

관리자 세트 필드 - retrievers, agenticRetrieveConfiguration (파운데이션 모델, 순위 조정, maxAgentIteration,를 통한 가드레일policyConfiguration) 및 generateResponse- 관리형 지식 기반 설정 및 구성 참조를 참조하세요.

AgenticRetrieveStream 응답 형식

AgenticRetrieveStream는 일련의 이벤트를 스트리밍합니다. MCP를 통해 추적 이벤트는 실시간 진행 상황을 notifications/message 위해 로 전달되고 검색 결과와 합성된 답변은 도구 결과에 전달됩니다. 스트림은 다음 이벤트 유형을 내보냅니다.

result 이벤트의 구조는 다음과 같습니다.

{
  "result": {
    "results": [
      {
        "content": {
          "text": "Amazon Bedrock AgentCore manages the storage, indexing, and retrieval infrastructure for a managed knowledge base...",
          "mimeType": "text/plain"
        },
        "sourceRetriever": { "identifier": "kb-retriever-1" },
        "metadata": { "x-amz-bedrock-kb-source-uri": "s3://example-bucket/docs/overview.pdf" }
      }
    ],
    "generatedResponse": {
      "answer": "A managed knowledge base lets Amazon Bedrock AgentCore handle the vector store, ingestion, and retrieval for you.",
      "citations": [
        {
          "startIndex": 0,
          "endIndex": 98,
          "references": [ { "..." : "references to supporting results" } ]
        }
      ]
    }
  }
}

입력 스키마 검색

에서 반환되는 스키마는 에이전트가를 호출할 때 설정할 수 있는 필드 세트tools/list입니다Retrieve. 기본적으로 에이전트가 볼 수 있는 유일한 필드는 입니다retrievalQuery.text. 관리형 지식 기반 식별자 및 모든 검색 설정은 대상에서 관리자가 설정합니다. numberOfResults 또는 메타데이터와 같은 검색 설정을 에이전트filter에 노출하려면 대상parameterOverrides에를 구성합니다. 에이전트가 설정할 수 있는 파라미터 제어를 참조하세요.

{
  "type": "object",
  "properties": {
    "retrievalQuery": {
      "description": "Contains the query to send the managed knowledge base.",
      "type": "object",
      "properties": {
        "text": {
          "description": "The text of the query made to the managed knowledge base.",
          "type": "string"
        }
      }
    }
  },
  "required": ["retrievalQuery"]
}

numberOfResults, 메타데이터 , filter, overrideSearchType순위 변경 및 멀티모달 이미지 쿼리와 같은 관리자 설정 및 재정의 가능한 필드는 구성 참조를 참조하세요.

응답 형식 검색

Retrieve 도구는 JSON-RPC 봉투에 래핑된 MCP tools/call 결과를 반환합니다. isError 및 content 필드는 내부에 result있으며 text 필드에는 직렬화된 retrievalResults페이로드가 포함되어 있습니다.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "{\"retrievalResults\":[{\"content\":{\"type\":\"TEXT\",\"text\":\"Amazon Bedrock AgentCore manages the storage, indexing, and retrieval infrastructure for a managed knowledge base...\"},\"location\":{\"type\":\"S3\",\"s3Location\":{\"uri\":\"s3://example-bucket/docs/overview.pdf\"}},\"score\":0.87,\"metadata\":{\"x-amz-bedrock-kb-source-uri\":\"s3://example-bucket/docs/overview.pdf\"}}]}"
      }
    ]
  }
}

의 각 항목은 다음과 같은 구조를 retrievalResults 갖습니다.

구성 참조

다음 필드는에서 관리자가 설정parameterValues하거나 대상을 생성할 parameterOverrides때를 사용하여 에이전트에 노출됩니다. 설정 위치는 관리형 지식 기반 설정 및 에이전트가 설정할 수 있는 파라미터 제어를 참조하세요.

AgenticRetrieveStream — agenticRetrieveConfiguration

Retrieve — managedSearchConfiguration

액세스 제어 필터링

관리형 지식 기반이 액세스 제어를 사용하여 사용자 또는 그룹별로 결과를 필터링하는 경우 호출 애플리케이션이 요청userContext과 함께를 전달해야 합니다. 게이트웨이는 이를 기반으로 액세스 제어 필터링을 적용하는 지식 기반에 userContext 전달됩니다. 게이트웨이는 호출자의 IAM 자격 증명userContext에서 채워지지 않으므로 애플리케이션이 명시적으로 제공해야 합니다.

이를 사용하려면:

{
  "arguments": {
    "retrievalQuery": { "text": "insurance benefits" },
    "userContext": {
      "userId": "user@example.com"
    }
  }
}