# Bases de conhecimento gerenciadas do Amazon Bedrock como destino do conector
<a name="gateway-target-connector-managed-kb"></a>

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](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) 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. `Retrieve`realiza uma única pesquisa híbrida e retorna as passagens mais relevantes.

**nota**  
Esse conector é compatível somente com as bases de conhecimento gerenciadas do Amazon Bedrock.

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.

**Topics**
+ [Como funciona](#gateway-target-connector-managed-kb-how-it-works)
+ [Recuperação agêntica](#gateway-target-connector-managed-kb-agentic-retrieval)
+ [Casos de uso](#gateway-target-connector-managed-kb-use-cases)
+ [Configurar uma base de conhecimento gerenciada](#gateway-target-connector-managed-kb-setup)
+ [Configurar a função do serviço de gateway](#gateway-target-connector-managed-kb-service-role)
+ [Invoque as ferramentas](#gateway-target-connector-managed-kb-invoke)
+ [AgenticRetrieveStream esquema de entrada](#gateway-target-connector-managed-kb-agentic-input-schema)
+ [AgenticRetrieveStream formato de resposta](#gateway-target-connector-managed-kb-agentic-response-format)
+ [Recuperar esquema de entrada](#gateway-target-connector-managed-kb-input-schema)
+ [Recuperar formato de resposta](#gateway-target-connector-managed-kb-response-format)
+ [Referência da configuração](#gateway-target-connector-managed-kb-config-reference)
+ [Filtragem de controle de acesso](#gateway-target-connector-managed-kb-access-control)

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

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`
+  `AgenticRetrieveStream`— uma recuperação agente de streaming em várias etapas que retorna resultados, eventos de rastreamento de planejamento e recuperação e uma resposta sintetizada com citações (retornadas por padrão; desabilitar com). `generateResponse: false`
+  `Retrieve`— uma única pesquisa híbrida que retorna as passagens mais relevantes com referências de origem.

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

1.  **Configuração do gateway** — Crie um gateway e adicione um alvo do Amazon Bedrock Managed Knowledge Bases, referenciando a base de conhecimento gerenciada que você deseja expor. O Gateway captura um instantâneo do esquema da ferramenta e provisiona a integração.

1.  **Descoberta de ferramentas** — Seu agente `tools/list` liga para o endpoint do Gateway e descobre a ferramenta de recuperação com seu esquema de entrada.

1.  **Invocação de recuperação** — Seu agente liga `tools/call` com uma consulta em linguagem natural. O Gateway se autentica no back-end e encaminha a solicitação para a base de conhecimento gerenciada, que executa uma pesquisa híbrida em todo o conteúdo ingerido.

1.  **Resultados** — A ferramenta retorna as passagens mais relevantes com referências de origem como JSON dentro do conteúdo do texto do resultado da ferramenta.

1.  **Resposta fundamentada** — Seu agente usa os resultados para compor uma resposta com fontes citadas.

Para o fluxo de recuperação agente, consulte Recuperação [agente](#gateway-target-connector-managed-kb-agentic-retrieval).

## Recuperação agêntica
<a name="gateway-target-connector-managed-kb-agentic-retrieval"></a>

 `AgenticRetrieveStream`trata 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 as`notifications/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](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) do *Amazon Bedrock*.

Para o esquema de solicitação e evento, consulte [esquema AgenticRetrieveStream de entrada e formato](#gateway-target-connector-managed-kb-agentic-input-schema) de [AgenticRetrieveStream resposta](#gateway-target-connector-managed-kb-agentic-response-format).

## Casos de uso
<a name="gateway-target-connector-managed-kb-use-cases"></a>
+  **Assistentes de conhecimento corporativo** — respostas de agentes terrestres em wikis internos, runbooks e documentos de políticas que foram inseridos em uma base de conhecimento gerenciada.
+  **Perguntas e respostas sobre documentos** — Responda a perguntas sobre grandes coleções de documentos sem criar ou operar um repositório de vetores.
+  **Multi-source RAG** — Consulte o conteúdo de várias fontes de dados combinadas em uma única base de conhecimento gerenciada em uma única chamada de recuperação.
+  **Multi-step planejamento** — Use `AgenticRetrieveStream` para responder perguntas ambíguas ou com várias partes que exigem planejamento e várias etapas de recuperação, retornando uma resposta sintetizada e baseada em citações em uma chamada.
+  **Tool-augmented agentes** — Combine a recuperação gerenciada da base de conhecimento com suas outras ferramentas do Gateway para que um agente possa pesquisar fatos fundamentados e realizar ações.

## Configurar uma base de conhecimento gerenciada
<a name="gateway-target-connector-managed-kb-setup"></a>

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](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup) no guia de configuração de destino.

## Configurar a função do serviço de gateway
<a name="gateway-target-connector-managed-kb-service-role"></a>

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](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-service-role) no guia de configuração de destino.

## Invoque as ferramentas
<a name="gateway-target-connector-managed-kb-invoke"></a>

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` ou`managed-kb___Retrieve`).

Pois`AgenticRetrieveStream`, 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?" } }
      ]
    }
  }
}
```

Pois`Retrieve`, 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](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)), 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
<a name="gateway-target-connector-managed-kb-agentic-input-schema"></a>

O esquema retornado por `tools/list` é o conjunto de campos que seu agente pode definir ao ligar`AgenticRetrieveStream`. 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](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup) uma base de conhecimento gerenciada. Para expor mais campos ao agente, configure `parameterOverrides` no destino — consulte [Controle quais parâmetros o agente pode definir](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 | Obrigatório | Description | 
| --- | --- | --- | --- | 
|  `messages`  | array | Sim | A conversa de recuperação do agente. Cada mensagem tem um `role` (`user`ou`assistant`) `content.text` e. | 

[Para os campos definidos pelo administrador —`retrievers`, `agenticRetrieveConfiguration` (modelo básico, `maxAgentIteration` reclassificação e proteção`policyConfiguration`) e `generateResponse` — consulte [Configurar uma base de conhecimento gerenciada e a referência de configuração](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup).](#gateway-target-connector-managed-kb-config-reference)

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

 `AgenticRetrieveStream`transmite 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:


| Event | Description | 
| --- | --- | 
|  `traceEvent`  | Uma etapa de planejamento ou recuperação, com um `step` (`Planning`,`Retrieval`, ou`FullDocumentExpansion`)`SpeculativeRetrieval`, um `status` (,`IN_PROGRESS`, ou`FAILED`)`SUCCEEDED`, um legível por humanos`message`, o `actions` realizado e qualquer ou. `warnings` `failures` | 
|  `responseEvent`  | Uma parte do texto de resposta gerado. Emitido por padrão; suprimido somente quando `generateResponse` está definido como. `false` | 
|  `result`  | A recuperação `results` e, a menos que `generateResponse` esteja definida como`false`, a final `generatedResponse` com a resposta e as citações. | 

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


| Campo | Tipo | Obrigatório | Description | 
| --- | --- | --- | --- | 
|  `results`  | array | Sim | Os resultados da recuperação. Cada item tem `content` (com `text` ou `byteContent` e a`mimeType`), o `sourceRetriever` que o produziu e opcional`metadata`. | 
|  `generatedResponse`  | objeto | Não | Presente por padrão. Omitido somente quando `generateResponse` está definido como. `false` Contém os intervalos de resposta sintetizados `answer` e `citations` que mapeiam (`startIndex`,`endIndex`) até os resultados de suporte. | 
|  `nextToken`  | string | Não | Um token para recuperar o próximo conjunto de resultados, se houver. | 

## Recuperar esquema de entrada
<a name="gateway-target-connector-managed-kb-input-schema"></a>

O esquema retornado por `tools/list` é o conjunto de campos que seu agente pode definir ao ligar`Retrieve`. 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](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters) 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"]
}
```


| Campo | Tipo | Obrigatório | Description | 
| --- | --- | --- | --- | 
|  `retrievalQuery`  | objeto | Sim | A consulta a ser enviada para a base de conhecimento gerenciada. | 
|  `retrievalQuery.text`  | string | Sim | O texto da consulta. | 

[Para os campos definidos pelo administrador e substituíveis — metadados`numberOfResults`, reclassificação e consultas de imagens `filter``overrideSearchType` multimodais — consulte a referência de configuração.](#gateway-target-connector-managed-kb-config-reference)

## Recuperar formato de resposta
<a name="gateway-target-connector-managed-kb-response-format"></a>

A `Retrieve` ferramenta retorna um `tools/call` resultado de MCP embrulhado em um JSON-RPC envelope. Os `content` campos `isError` e estão dentro`result`, 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:


| Campo | Tipo | Obrigatório | Description | 
| --- | --- | --- | --- | 
|  `content`  | objeto | Sim | O conteúdo do fragmento recuperado. Inclui um `type` (`TEXT`,`IMAGE`, `ROW``AUDIO`, ou`VIDEO`) e o conteúdo correspondente, como `text` para partes de texto. | 
|  `location`  | objeto | Não | A localização dos dados de origem. Inclui um `type` (`S3`,`WEB`,`CONFLUENCE`, `SHAREPOINT``CUSTOM`, etc.) e o objeto de localização correspondente, como`s3Location.uri`. | 
|  `score`  | número | Não | A relevância do resultado para a consulta. | 
|  `metadata`  | objeto | Não | Atributos de metadados e seus valores para o arquivo de origem na fonte de dados. | 

## Referência da configuração
<a name="gateway-target-connector-managed-kb-config-reference"></a>

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](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup) e [Controlar quais parâmetros o agente pode definir](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters).

 ** `AgenticRetrieveStream` — `agenticRetrieveConfiguration` ** 


| Campo | Valores válidos | Observações | 
| --- | --- | --- | 
|  `foundationModelType`  |  `MANAGED`, `CUSTOM`  |  `MANAGED`usa o modelo gerenciado por serviços (padrão). `CUSTOM`usa um ARN do modelo Bedrock que você fornece. | 
|  `rerankingModelType`  |  `MANAGED`, `CUSTOM`, `NONE`  |  `MANAGED`usa o reranker gerenciado pelo serviço (padrão). `CUSTOM`usa o seu. `NONE`desativa a reclassificação. | 
|  `foundationModelConfiguration.type`  |  `BEDROCK_FOUNDATION_MODEL`  | Exigido quando `foundationModelType` é`CUSTOM`. | 
|  `maxAgentIteration`  | integer | Limita o número de iterações de planejamento e recuperação. | 
|  `policyConfiguration.guardrailConfiguration`  |  `guardrailId`, `guardrailVersion`  | Anexa uma grade de proteção Amazon Bedrock. | 

 ** `Retrieve` — `managedSearchConfiguration` ** 


| Campo | Valores válidos | Observações | 
| --- | --- | --- | 
|  `numberOfResults`  | inteiro (1—100) | Número de partes de origem a serem recuperadas. | 
|  `overrideSearchType`  |  `HYBRID`, `SEMANTIC`  |  `HYBRID`combina pesquisa por palavra-chave e vetorial. `SEMANTIC`usa somente a pesquisa vetorial. | 
|  `rerankingModelType`  |  `MANAGED`, `CUSTOM`, `NONE`  | O mesmo que para`AgenticRetrieveStream`. | 
|  `rerankingConfiguration.type`  |  `BEDROCK_RERANKING_MODEL`  | Obrigatório ao usar a classificação personalizada. | 
|  `rerankingConfiguration.bedrockRerankingConfiguration.metadataConfiguration.selectionMode`  |  `SELECTIVE`, `ALL`  | Controla quais campos de metadados são passados para o reclassificador. | 
|  `filter`  |  `equals`, `notEquals`, `greaterThan`, `greaterThanOrEquals`, `lessThan`, `lessThanOrEquals`, `in`, `notIn`, `startsWith`, `listContains`, `stringContains`, `andAll`, `orAll`  | Filtro de metadados. Forneça exatamente um operador. | 

## Filtragem de controle de acesso
<a name="gateway-target-connector-managed-kb-access-control"></a>

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:

1. Exponha `$.userContext` ao agente configurando `parameterOverrides` no destino — consulte [Controle quais parâmetros o agente pode](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters) definir.

1. Faça com que o aplicativo de chamada (não o modelo) inclua `userContext` nos `tools/call` argumentos:

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