Bases de conhecimento gerenciadas do Amazon Bedrock como destino do conector

As bases de conhecimento gerenciadas do Amazon Bedrock fornecem geração aumentada de recuperação (RAG) totalmente gerenciada: o Amazon Bedrock gerencia o armazenamento vetorial, a ingestão de dados e a otimização da recuperação, portanto, não há infraestrutura de recuperação para você provisionar ou operar. O Amazon Bedrock AgentCore expõe uma base de conhecimento gerenciada como um conector de gateway nativo — você a conecta ao seu AgentCore gateway e seus agentes a descobrem e consultam com chamadas padrão do Model Context Protocol (MCP), sem nenhuma integração de recuperação personalizada para criar. Para obter detalhes sobre como criar e gerenciar uma base de conhecimento gerenciada, consulte Bases de conhecimento do Amazon Bedrock no Guia do usuário do Amazon Bedrock.

O conector expõe duas ferramentas. O primeiro éAgenticRetrieveStream. Em vez de uma única pesquisa, ele planeja uma estratégia de recuperação, executa várias etapas de recuperação em suas bases de conhecimento gerenciadas, se expande opcionalmente para documentos completos e retorna os resultados de suporte e uma resposta sintetizada baseada em citações. Retrieverealiza uma única pesquisa híbrida e retorna as passagens mais relevantes.

As seções a seguir explicam como o conector funciona, a recuperação agente em profundidade, os casos de uso comuns, como configurar um destino e os esquemas de entrada e resposta de ambas as ferramentas.

Como funciona

O Amazon Bedrock AgentCore fornece um conector integrado às bases de conhecimento gerenciadas do Amazon Bedrock. O Gateway lida com gerenciamento de esquemas, resolução de endpoints e autenticação de serviços. O conector expõe duas ferramentas, que seu agente descobre com: tools/list

Uma única Retrieve invocação segue esse fluxo:

Para o fluxo de recuperação agente, consulte Recuperação agente.

Recuperação agêntica

AgenticRetrieveStreamtrata uma pergunta como uma tarefa: em vez de uma única pesquisa híbrida Retrieve executada para uma consulta, ela planeja uma estratégia de recuperação, executa várias etapas de recuperação em suas bases de conhecimento gerenciadas e retransmite os resultados de suporte e uma resposta sintetizada baseada em citações — tudo em uma chamada de ferramenta. A resposta sintetizada é retornada por padrão; generateResponse defina como false para retornar somente resultados.

Seu agente o invoca com uma conversa ()messages. Os recuperadores que ele consulta — cada um apontando para uma base de conhecimento gerenciada — são configurados pelo administrador no destino, não fornecidos pelo agente. O progresso do planejamento e da recuperação flui pelo MCP asnotifications/message, e os resultados e a resposta são retornados no resultado da ferramenta.

Para saber mais sobre como a recuperação de agentes funciona, consulte Bases de conhecimento do Amazon Bedrock no Guia do usuário do Amazon Bedrock.

Para o esquema de solicitação e evento, consulte esquema AgenticRetrieveStream de entrada e formato de AgenticRetrieveStream resposta.

Casos de uso

Configurar uma base de conhecimento gerenciada

Para obter instruções sobre como criar um Gateway Target com a configuração do conector Amazon Bedrock Managed Knowledge Bases, incluindo exemplos de configuração usando o SDK e a CLI do Python, consulte Configurar uma base de conhecimento gerenciada no guia de configuração de destino.

Configurar a função do serviço de gateway

O Gateway precisa de uma função de serviço que permita que o AgentCore serviço execute ações de recuperação na base de conhecimento gerenciada em seu nome. Para obter as permissões e a configuração de políticas necessárias do IAM, consulte Configurar a função de serviço do Gateway no guia de configuração de destino.

Invoque as ferramentas

Depois de criar o alvo, seu agente descobre tools/list e liga para as tools/call ferramentas. Cada nome de ferramenta é prefixado com o nome do alvo, no formato <target-name>_<tool-name>_AgenticRetrieveStream oumanaged-kb___Retrieve).

PoisAgenticRetrieveStream, seu agente passa apenas a conversa. Os recuperadores são configurados no destino pelo administrador, portanto, o agente não envia IDs da base de conhecimento:

{
  "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?" } }
      ]
    }
  }
}

PoisRetrieve, o identificador da base de conhecimento gerenciada está vinculado ao destino, então seu agente passa somente a consulta:

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

Se você expôs parâmetros de recuperação ao agente (consulte Controlar quais parâmetros o agente pode definir), o agente pode substituir os padrões configurados pelo administrador no momento da chamada:

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

AgenticRetrieveStream esquema de entrada

O esquema retornado por tools/list é o conjunto de campos que seu agente pode definir ao ligarAgenticRetrieveStream. Por padrão, o único campo visível para o agente é. messages Os recuperadores a serem consultados e todas as configurações de recuperação são definidos pelo administrador no destino — consulte Configurar uma base de conhecimento gerenciada. Para expor mais campos ao agente, configure parameterOverrides no destino — consulte Controle quais parâmetros o agente pode definir.

{
  "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"]
}

Para os campos definidos pelo administrador —retrievers, agenticRetrieveConfiguration (modelo básico, maxAgentIteration reclassificação e proteçãopolicyConfiguration) e generateResponse — consulte Configurar uma base de conhecimento gerenciada e a referência de configuração.

AgenticRetrieveStream formato de resposta

AgenticRetrieveStreamtransmite uma sequência de eventos. No MCP, os eventos de rastreamento são fornecidos conforme notifications/message o progresso em tempo real, e os resultados da recuperação e a resposta sintetizada são fornecidos no resultado da ferramenta. O stream emite os seguintes tipos de eventos:

Um result evento tem a seguinte estrutura:

{
  "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" } ]
        }
      ]
    }
  }
}

Recuperar esquema de entrada

O esquema retornado por tools/list é o conjunto de campos que seu agente pode definir ao ligarRetrieve. Por padrão, o único campo visível para o agente é. retrievalQuery.text O identificador da base de conhecimento gerenciada e todas as configurações de recuperação são definidas pelo administrador no destino. Para expor configurações de recuperação, como numberOfResults metadados, filter ao agente, configure parameterOverrides no destino — consulte Controle quais parâmetros o agente pode definir.

{
  "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"]
}

Para os campos definidos pelo administrador e substituíveis — metadadosnumberOfResults, reclassificação e consultas de imagens filteroverrideSearchType multimodais — consulte a referência de configuração.

Recuperar formato de resposta

A Retrieve ferramenta retorna um tools/call resultado de MCP embrulhado em um JSON-RPC envelope. Os content campos isError e estão dentroresult, e o text campo contém a retrievalResults carga serializada:

{
  "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\"}}]}"
      }
    ]
  }
}

Cada item retrievalResults tem a seguinte estrutura:

Referência da configuração

Os campos a seguir são definidos pelo administrador ou expostos ao agente com ele parameterOverrides quando você cria o destino. parameterValues Para saber onde configurá-los, consulte Configurar uma base de conhecimento gerenciada e Controlar quais parâmetros o agente pode definir.

AgenticRetrieveStream — agenticRetrieveConfiguration

Retrieve — managedSearchConfiguration

Filtragem de controle de acesso

Se sua base de conhecimento gerenciada usa controle de acesso para filtrar os resultados por usuário ou grupo, o aplicativo de chamada deve passar um userContext com a solicitação. O Gateway userContext passa para a base de conhecimento, que aplica a filtragem de controle de acesso com base nela. O Gateway não é preenchido a userContext partir da identidade do IAM do chamador — seu aplicativo deve fornecê-lo explicitamente.

Para usá-lo:

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