# Basi di conoscenza gestite da Amazon Bedrock come destinazione del connettore
<a name="gateway-target-connector-managed-kb"></a>

Amazon Bedrock Managed Knowledge Bases fornisce una generazione di recupero aumentata (RAG) completamente gestita: Amazon Bedrock gestisce l'archiviazione vettoriale, l'inserimento dei dati e l'ottimizzazione del recupero, quindi non esiste un'infrastruttura di recupero da fornire o gestire. Amazon Bedrock AgentCore offre una knowledge base gestita come connettore gateway nativo: lo colleghi al AgentCore gateway e i tuoi agenti lo scoprono e lo interrogano con chiamate standard Model Context Protocol (MCP), senza alcuna integrazione di recupero personalizzata da creare. Per informazioni dettagliate sulla creazione e la gestione di una knowledge base gestita, consulta [Knowledge base per Amazon Bedrock nella *Amazon Bedrock User Guide*](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html).

Il connettore espone due strumenti. Il primo è`AgenticRetrieveStream`. Invece di una singola ricerca, pianifica una strategia di recupero, esegue più fasi di recupero nelle knowledge base gestite, facoltativamente si espande a documenti completi e trasmette sia i risultati di supporto che una risposta sintetizzata e supportata da citazioni. `Retrieve`esegue una singola ricerca ibrida e restituisce i passaggi più pertinenti.

**Nota**  
Questo connettore è supportato solo per Amazon Bedrock Managed Knowledge Base.

Le sezioni seguenti illustrano il funzionamento del connettore, il recupero degli agenti in modo approfondito, i casi d'uso comuni, come impostare un target e gli schemi di input e risposta per entrambi gli strumenti.

**Topics**
+ [Come funziona](#gateway-target-connector-managed-kb-how-it-works)
+ [Recupero agentico](#gateway-target-connector-managed-kb-agentic-retrieval)
+ [Casi d’uso](#gateway-target-connector-managed-kb-use-cases)
+ [Configura una knowledge base gestita](#gateway-target-connector-managed-kb-setup)
+ [Configura il ruolo del servizio Gateway](#gateway-target-connector-managed-kb-service-role)
+ [Invoca gli strumenti](#gateway-target-connector-managed-kb-invoke)
+ [AgenticRetrieveStream schema di input](#gateway-target-connector-managed-kb-agentic-input-schema)
+ [AgenticRetrieveStream formato di risposta](#gateway-target-connector-managed-kb-agentic-response-format)
+ [Recupera lo schema di input](#gateway-target-connector-managed-kb-input-schema)
+ [Recupera il formato di risposta](#gateway-target-connector-managed-kb-response-format)
+ [Informazioni di riferimento sulla configurazione](#gateway-target-connector-managed-kb-config-reference)
+ [Filtraggio per il controllo degli accessi](#gateway-target-connector-managed-kb-access-control)

## Come funziona
<a name="gateway-target-connector-managed-kb-how-it-works"></a>

Amazon Bedrock AgentCore fornisce un connettore integrato per Amazon Bedrock Managed Knowledge Base. Il Gateway gestisce la gestione degli schemi, la risoluzione degli endpoint e l'autenticazione del servizio. Il connettore espone due strumenti, che l'agente scopre con: `tools/list`
+  `AgenticRetrieveStream`— un recupero agentico in streaming in più fasi che restituisce risultati, eventi di tracciamento della pianificazione e del recupero e una risposta sintetizzata con citazioni (restituita per impostazione predefinita; disabilita con). `generateResponse: false`
+  `Retrieve`— una singola ricerca ibrida che restituisce i passaggi più pertinenti con riferimenti alle fonti.

Una singola `Retrieve` invocazione segue questo flusso:

1.  **Configurazione del gateway**: crea un gateway e aggiungi un obiettivo Amazon Bedrock Managed Knowledge Bases, facendo riferimento alla knowledge base gestita che desideri esporre. Il Gateway crea un'istantanea dello schema dello strumento e fornisce l'integrazione.

1.  **Individuazione degli strumenti**: l'agente richiama `tools/list` l'endpoint Gateway e scopre lo strumento di recupero con il relativo schema di input.

1.  Richiamo di **recupero: l'agente chiama con una** query in linguaggio naturale. `tools/call` Il Gateway esegue l'autenticazione nel backend e indirizza la richiesta alla knowledge base gestita, che esegue la ricerca ibrida tra i contenuti acquisiti.

1.  **Risultati**: lo strumento restituisce i passaggi più pertinenti con riferimenti alla fonte in formato JSON all'interno del contenuto testuale del risultato dello strumento.

1.  **Risposta fondata**: il tuo agente utilizza i risultati per comporre una risposta con fonti citate.

[Per il flusso di recupero agentico, vedi Agentic retrieval.](#gateway-target-connector-managed-kb-agentic-retrieval)

## Recupero agentico
<a name="gateway-target-connector-managed-kb-agentic-retrieval"></a>

 `AgenticRetrieveStream`considera una domanda come un'attività: anziché eseguire una singola ricerca ibrida per una sola query, pianifica una strategia di recupero, `Retrieve` esegue più fasi di recupero nelle knowledge base gestite e restituisce i risultati di supporto e una risposta sintetizzata e supportata da citazioni, il tutto in un'unica operazione. La risposta sintetizzata viene restituita per impostazione predefinita; è impostata per restituire solo risultati. `generateResponse` `false`

Il tuo agente la richiama con una conversazione (). `messages` I retriever interrogati, ognuno dei quali punta a una knowledge base gestita, sono configurati dall'amministratore sulla destinazione e non forniti dall'agente. I flussi di avanzamento della pianificazione e del recupero su MCP vengono visualizzati come risultato dello strumento e i risultati e la `notifications/message` risposta vengono restituiti nel risultato dello strumento.

*Per ulteriori informazioni su come funziona l'agentic retrieval, consulta [le Knowledge base per Amazon Bedrock nella Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) User Guide.*

[[Per lo schema delle richieste e degli eventi, consulta AgenticRetrieveStream lo schema di input e il formato di risposta. AgenticRetrieveStream ](#gateway-target-connector-managed-kb-agentic-response-format)](#gateway-target-connector-managed-kb-agentic-input-schema)

## Casi d’uso
<a name="gateway-target-connector-managed-kb-use-cases"></a>
+  **Enterprise Knowledge Assistant**: risposte degli agenti di base nei wiki interni, nei runbook e nei documenti relativi alle policy che sono stati inseriti in una knowledge base gestita.
+  Domande **e risposte sui documenti: rispondi** alle domande su raccolte di documenti di grandi dimensioni senza creare o gestire un archivio vettoriale.
+  **Multi-source RAG**: interrogazioni su contenuti provenienti da più fonti di dati combinati in un'unica base di conoscenza gestita in un'unica chiamata di recupero.
+  **Multi-step pianificazione**: consente di rispondere `AgenticRetrieveStream` a domande articolate in più parti o ambigue che richiedono una pianificazione e diverse fasi di recupero, restituendo una risposta sintetizzata e supportata da citazioni in un'unica chiamata.
+  **Tool-augmented agenti**: combina il recupero gestito della knowledge base con gli altri strumenti di Gateway in modo che un agente possa sia cercare fatti fondati che intraprendere azioni.

## Configura una knowledge base gestita
<a name="gateway-target-connector-managed-kb-setup"></a>

Per istruzioni su come creare un Gateway Target con la configurazione del connettore Amazon Bedrock Managed Knowledge Bases, inclusi esempi di configurazione utilizzando Python SDK e CLI[, consulta Configurare una knowledge base gestita](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup) nella guida alla configurazione di Target.

## Configura il ruolo del servizio Gateway
<a name="gateway-target-connector-managed-kb-service-role"></a>

Il Gateway necessita di un ruolo di AgentCore servizio che gli consenta di eseguire azioni di recupero sulla Knowledge Base gestita per conto dell'utente. Per le autorizzazioni IAM richieste e la configurazione delle policy, consulta [Configurare il ruolo del servizio Gateway](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-service-role) nella guida alla configurazione di Target.

## Invoca gli strumenti
<a name="gateway-target-connector-managed-kb-invoke"></a>

Dopo aver creato l'obiettivo, il tuo agente scopre gli strumenti con `tools/list` cui li chiama. `tools/call` Il nome di ogni strumento è preceduto dal nome della destinazione, nel formato `<target-name>_<tool-name>_AgenticRetrieveStream` o`managed-kb___Retrieve`).

Perché `AgenticRetrieveStream` il tuo agente trasmette solo la conversazione. I retriever sono configurati sulla destinazione dall'amministratore, quindi l'agente non invia gli ID della knowledge base:

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

Infatti`Retrieve`, l'identificatore della knowledge base gestita è associato alla destinazione, quindi l'agente trasmette solo la query:

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

Se hai esposto i parametri di recupero all'agente (vedi [Controlla i parametri che l'agente può impostare), l'agente può](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters) sovrascrivere le impostazioni predefinite configurate dall'amministratore al momento della chiamata:

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

## AgenticRetrieveStream schema di input
<a name="gateway-target-connector-managed-kb-agentic-input-schema"></a>

Lo schema restituito `tools/list` è l'insieme di campi che l'agente può impostare quando chiama`AgenticRetrieveStream`. Per impostazione predefinita, l'unico campo visibile all'agente è. `messages` [I retriever da interrogare e tutte le configurazioni di recupero sono impostati dall'amministratore sulla destinazione. Vedi Configurare una knowledge base gestita.](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup) [Per esporre più campi all'agente, configuralo `parameterOverrides` sulla destinazione: vedi Controlla i parametri che l'agente può impostare.](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)

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


| Campo | Tipo | Campo obbligatorio | Description | 
| --- | --- | --- | --- | 
|  `messages`  | array | Sì | La conversazione sul recupero dell'agente. Ogni messaggio ha un `role` (`user`o) e. `assistant` `content.text` | 

[Per i campi impostati dall'amministratore `agenticRetrieveConfiguration` (modello di base`retrievers`, reranking e guardrails through`policyConfiguration`) e `generateResponse` — consulta [Configurazione di una knowledge base gestita e riferimenti alla configurazione](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup). `maxAgentIteration`](#gateway-target-connector-managed-kb-config-reference)

## AgenticRetrieveStream formato di risposta
<a name="gateway-target-connector-managed-kb-agentic-response-format"></a>

 `AgenticRetrieveStream`trasmette una sequenza di eventi. Tramite MCP, gli eventi di traccia vengono forniti in base all'avanzamento in tempo reale, mentre `notifications/message` i risultati del recupero e la risposta sintetizzata vengono forniti nel risultato dello strumento. Lo stream emette i seguenti tipi di eventi:


| Event | Description | 
| --- | --- | 
|  `traceEvent`  | Una fase di pianificazione o recupero, con un `step` (,`Planning`,, o) `Retrieval``SpeculativeRetrieval`, un `status` (, o`FullDocumentExpansion`) `IN_PROGRESS``SUCCEEDED`, un elemento leggibile dall'uomo`message`, l'`actions`esecuzione e qualsiasi o`FAILED`. `warnings` `failures` | 
|  `responseEvent`  | Una parte del testo di risposta generato. Emesso per impostazione predefinita; soppresso solo quando `generateResponse` è impostato su. `false` | 
|  `result`  | Il recupero `results` e, a meno che non `generateResponse` sia impostato su`false`, il finale `generatedResponse` con la risposta e le citazioni. | 

Un `result` evento ha la seguente struttura:

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


| Campo | Tipo | Campo obbligatorio | Description | 
| --- | --- | --- | --- | 
|  `results`  | array | Sì | I risultati del recupero. Ogni articolo ha `content` (con `text` o `byteContent` e a`mimeType`), il nome `sourceRetriever` che lo ha prodotto e facoltativo. `metadata` | 
|  `generatedResponse`  | oggetto | No | Presente per impostazione predefinita. Omessa solo quando `generateResponse` è impostata su. `false` Contiene la risposta sintetizzata `answer` e `citations` quella cartografica estendono (`startIndex`,`endIndex`) ai risultati di supporto. | 
|  `nextToken`  | stringa | No | Un token per recuperare l'eventuale set di risultati successivo. | 

## Recupera lo schema di input
<a name="gateway-target-connector-managed-kb-input-schema"></a>

Lo schema restituito `tools/list` è l'insieme di campi che l'agente può impostare quando chiama`Retrieve`. Per impostazione predefinita, l'unico campo visibile all'agente è. `retrievalQuery.text` L'identificatore della Knowledge Base gestita e tutte le impostazioni di recupero sono impostate dall'amministratore sulla destinazione. [Per esporre le impostazioni di recupero, ad esempio `numberOfResults` o i metadati, `filter` all'agente, configuratele `parameterOverrides` sulla destinazione. Consultate Controllare i parametri che l'agente può impostare.](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)

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


| Campo | Tipo | Campo obbligatorio | Description | 
| --- | --- | --- | --- | 
|  `retrievalQuery`  | oggetto | Sì | La query da inviare alla knowledge base gestita. | 
|  `retrievalQuery.text`  | stringa | Sì | Il testo dell'interrogazione. | 

[Per i campi impostati dall'amministratore e sovrascrivibili`numberOfResults`, ovvero i metadati, la riclassificazione e le interrogazioni sulle immagini multimodali `filter``overrideSearchType`, consulta la guida di riferimento alla configurazione.](#gateway-target-connector-managed-kb-config-reference)

## Recupera il formato di risposta
<a name="gateway-target-connector-managed-kb-response-format"></a>

Lo `Retrieve` strumento restituisce un `tools/call` risultato MCP racchiuso in una busta. JSON-RPC I `content` campi `isError` e si trovano all'interno e `result` il `text` campo contiene il payload serializzato: `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\"}}]}"
      }
    ]
  }
}
```

Ogni elemento `retrievalResults` ha la seguente struttura:


| Campo | Tipo | Campo obbligatorio | Description | 
| --- | --- | --- | --- | 
|  `content`  | oggetto | Sì | Il contenuto del blocco recuperato. Include un `type` (`TEXT`,`IMAGE`, `ROW``AUDIO`, o`VIDEO`) e il contenuto corrispondente, ad esempio `text` per i blocchi di testo. | 
|  `location`  | oggetto | No | La posizione dei dati di origine. Include un `type` (`S3``WEB`,`CONFLUENCE`,`SHAREPOINT`,`CUSTOM`, ecc.) e l'oggetto di posizione corrispondente, ad esempio`s3Location.uri`. | 
|  `score`  | numero | No | La rilevanza del risultato rispetto alla query. | 
|  `metadata`  | oggetto | No | Attributi dei metadati e relativi valori per il file di origine nell'origine dati. | 

## Informazioni di riferimento sulla configurazione
<a name="gateway-target-connector-managed-kb-config-reference"></a>

I seguenti campi vengono impostati dall'amministratore o esposti all'agente durante `parameterOverrides` la creazione della destinazione. `parameterValues` Per dove impostarli, consulta [Configurare una knowledge base gestita](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup) e [Controllare i parametri che l'agente può impostare](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters).

 ** `AgenticRetrieveStream` — `agenticRetrieveConfiguration` ** 


| Campo | Valori validi | Note | 
| --- | --- | --- | 
|  `foundationModelType`  |  `MANAGED`, `CUSTOM`  |  `MANAGED`utilizza il modello gestito dai servizi (impostazione predefinita). `CUSTOM`utilizza un ARN modello Bedrock fornito dall'utente. | 
|  `rerankingModelType`  |  `MANAGED`, `CUSTOM`, `NONE`  |  `MANAGED`utilizza il reranker gestito dal servizio (impostazione predefinita). `CUSTOM`usa il tuo. `NONE`disabilita la riclassificazione. | 
|  `foundationModelConfiguration.type`  |  `BEDROCK_FOUNDATION_MODEL`  | Richiesto quando è. `foundationModelType` `CUSTOM` | 
|  `maxAgentIteration`  | intero | Limita il numero di iterazioni di pianificazione e recupero. | 
|  `policyConfiguration.guardrailConfiguration`  |  `guardrailId`, `guardrailVersion`  | Collega un parapetto Amazon Bedrock. | 

 ** `Retrieve` — `managedSearchConfiguration` ** 


| Campo | Valori validi | Note | 
| --- | --- | --- | 
|  `numberOfResults`  | numero intero (1—100) | Numero di blocchi di origine da recuperare. | 
|  `overrideSearchType`  |  `HYBRID`, `SEMANTIC`  |  `HYBRID`combina la ricerca per parole chiave e quella vettoriale. `SEMANTIC`utilizza solo la ricerca vettoriale. | 
|  `rerankingModelType`  |  `MANAGED`, `CUSTOM`, `NONE`  | Uguale a. `AgenticRetrieveStream` | 
|  `rerankingConfiguration.type`  |  `BEDROCK_RERANKING_MODEL`  | Obbligatorio quando si utilizza una nuova classificazione personalizzata. | 
|  `rerankingConfiguration.bedrockRerankingConfiguration.metadataConfiguration.selectionMode`  |  `SELECTIVE`, `ALL`  | Controlla quali campi di metadati vengono passati al reranker. | 
|  `filter`  |  `equals`, `notEquals`, `greaterThan`, `greaterThanOrEquals`, `lessThan`, `lessThanOrEquals`, `in`, `notIn`, `startsWith`, `listContains`, `stringContains`, `andAll`, `orAll`  | Filtro per i metadati. Fornisci esattamente un operatore. | 

## Filtraggio per il controllo degli accessi
<a name="gateway-target-connector-managed-kb-access-control"></a>

Se la knowledge base gestita utilizza il controllo degli accessi per filtrare i risultati per utente o gruppo, l'applicazione chiamante deve passare `userContext` insieme alla richiesta. Il Gateway `userContext` passa alla knowledge base, che applica il filtro di controllo degli accessi basato su di esso. Il gateway non viene compilato `userContext` in base all'identità IAM del chiamante: l'applicazione deve fornirla in modo esplicito.

Per utilizzarlo:

1. Esporre `$.userContext` all'agente effettuando la configurazione `parameterOverrides` sulla destinazione: vedi [Controlla i parametri che l'agente può](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters) impostare.

1. Fate in modo che l'applicazione chiamante (non il modello) includa `userContext` negli `tools/call` argomenti:

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