As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Bases de conhecimento gerenciadas da Amazon Bedrock como alvo de conectores

As bases de conhecimento gerenciadas da Amazon Bedrock fornecem geração aumentada de recuperação (RAG) totalmente gerenciada: a 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 a necessidade de criar uma integração de recuperação personalizada. 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, opcionalmente se expande para documentos completos e retorna tanto os resultados de apoio quanto 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 de agentes em profundidade, os casos de uso comuns, como configurar um alvo e os esquemas de entrada e resposta para ambas as ferramentas.

Como funciona

O Amazon Bedrock AgentCore fornece um conector integrado às bases de conhecimento gerenciadas do Amazon Bedrock. O Gateway gerencia o gerenciamento de esquemas, a resolução de terminais e a 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 de agentes, consulte Recuperação de agentes.

Recuperação de agentes

AgenticRetrieveStreamtrata uma pergunta como uma tarefa: em vez da única pesquisa híbrida que 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 transmite de volta os resultados de suporte e uma resposta sintetizada e baseada em citações — tudo em uma chamada de ferramenta. A resposta sintetizada é retornada por padrão; definida como generateResponse 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 MCPnotifications/message, e os resultados e a resposta são retornados no resultado da ferramenta.

Para saber mais sobre como a recuperação agente 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 do alvo.

Configurar a função de 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 de IAM e a configuração de políticas necessárias, 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 as ferramentas tools/list e liga para elas. tools/call Cada nome de ferramenta é prefixado com o nome do alvo, no formato managed-kb___Retrieve (<target-name>_<tool-name>_AgenticRetrieveStreamou).

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 os 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 pelo agente é. messages Os recuperadores a serem consultados e toda a configuração 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, reclassificação e barreiraspolicyConfiguration) e generateResponse — consulte Configurar uma base de conhecimento gerenciada e referência de configuração. maxAgentIteration Referência da 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 entregues 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 pelo agente é. retrievalQuery.text O identificador da base de conhecimento gerenciada e todas as configurações de recuperação são definidos pelo administrador no destino. Para expor configurações de recuperação, como numberOfResults ou 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 configurados pelo administrador e substituíveis — metadadosnumberOfResults, reclassificação e consultas de imagens filter overrideSearchType multimodais — consulte Referência de configuração. Referência da 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 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:

Referência da configuração

Os campos a seguir são definidos pelo administrador ou expostos ao parameterOverrides agente quando você cria o alvo. 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 resultados por usuário ou grupo, o aplicativo chamador 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 é userContext preenchido a partir da identidade IAM do chamador — seu aplicativo deve fornecê-lo explicitamente.

Para usá-lo:

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