Skip to content

KnowledgeBaseAdminService

Runtime-agnostic service for managing Vertex AI Agent Builder data stores, documents, and canonical ground-truth files in S3 or GCS.

Import

import {
  KnowledgeBaseAdminService,
  KnowledgeBaseAdminServiceConfig,
} from "@modernpath/agent-framework";

Configuration

KnowledgeBaseAdminServiceConfig

Property Type Required Default Description
defaultStore string No — Full resource name of the default Vertex AI data store
canonicalS3 CanonicalS3Config No — S3 / MinIO settings for canonical ground-truth storage
canonicalGcs CanonicalGcsConfig No — GCS settings for canonical ground-truth storage
s3KeyPrefix string No "" Prefix prepended to all S3 object keys
gcsKeyPrefix string No "" Prefix prepended to all GCS object paths

CanonicalS3Config

Property Type Required Default Description
endpoint string Yes — S3-compatible endpoint URL
region string Yes — AWS region
bucket string Yes — Bucket name
forcePathStyle boolean No false Use path-style addressing (required for MinIO)
accessKeyId string Yes — AWS access key ID
secretAccessKey string Yes — AWS secret access key

CanonicalGcsConfig

Property Type Required Default Description
bucket string Yes — GCS bucket name

Constructor

const admin = new KnowledgeBaseAdminService(config: KnowledgeBaseAdminServiceConfig);

Methods

listStores()

Lists all Vertex AI Agent Builder data stores in the configured project/location.

const result = await admin.listStores();
// result.stores: KnowledgeBaseStoreInfo[]
// result.defaultStore: string | undefined
// result.canonicalSourceType: GroundTruthSourceType | undefined

Returns: { stores: KnowledgeBaseStoreInfo[], defaultStore?: string, canonicalSourceType?: GroundTruthSourceType }

createStore(displayName)

Creates a new data store.

const store = await admin.createStore("Customer Manuals");
Parameter Type Description
displayName string Human-readable name for the store

Returns: KnowledgeBaseStoreInfo

deleteStore(storeName)

Deletes a data store by its full resource name.

await admin.deleteStore(store.name);
Parameter Type Description
storeName string Full resource name of the store

Returns: void

listDocuments(storeName)

Lists all documents in a store with enriched metadata, including ground-truth download URLs when canonical storage is configured.

const docs = await admin.listDocuments(store.name);
// docs: KnowledgeBaseDocumentInfo[]
Parameter Type Description
storeName string Full resource name of the store

Returns: KnowledgeBaseDocumentInfo[]

uploadDocument(storeName, filename, mimeType, bytes)

Uploads a document to the data store. When canonical storage (S3/GCS) is configured, the original file is also stored there as ground truth.

await admin.uploadDocument(
  store.name,
  "manual.pdf",
  "application/pdf",
  pdfBuffer,
);
Parameter Type Description
storeName string Full resource name of the store
filename string Document filename
mimeType string MIME type of the document
bytes Buffer Document content

Returns: void

deleteDocument(storeName, docName, options?)

Deletes a document from the data store and optionally its ground-truth copy.

await admin.deleteDocument(store.name, doc.name, {
  deleteGroundTruth: true,
});
Parameter Type Description
storeName string Full resource name of the store
docName string Full resource name of the document
options.deleteGroundTruth boolean Also delete from canonical storage (default: false)

Returns: void

getGroundTruthDownloadUrl(storeName, docName)

Returns a pre-signed download URL for the ground-truth copy of a document.

const url = await admin.getGroundTruthDownloadUrl(store.name, doc.name);
Parameter Type Description
storeName string Full resource name of the store
docName string Full resource name of the document

Returns: string — Pre-signed URL

downloadGroundTruthBytes(storeName, docName)

Downloads the raw bytes of the ground-truth document from S3 or GCS.

const buffer = await admin.downloadGroundTruthBytes(store.name, doc.name);
Parameter Type Description
storeName string Full resource name of the store
docName string Full resource name of the document

Returns: Buffer

Type References

KnowledgeBaseStoreInfo

interface KnowledgeBaseStoreInfo {
  name: string;           // Full resource name
  displayName: string;    // Human-readable name
  documentCount: number;  // Number of documents
  sizeBytes: number;      // Total size in bytes
  createdAt: string;      // ISO 8601 timestamp
  isDefault: boolean;     // Whether this is the default store
}

KnowledgeBaseDocumentInfo

interface KnowledgeBaseDocumentInfo {
  name: string;                      // Full resource name
  displayName: string;               // Human-readable name
  mimeType: string;                  // MIME type
  sizeBytes: number;                 // Size in bytes
  createdAt: string;                 // ISO 8601 timestamp
  groundTruth: boolean;              // Has canonical copy
  groundTruthDownloadUrl?: string;   // Pre-signed URL (when available)
  metadata?: Record<string, string>; // Frontmatter metadata
}

GroundTruthSourceType

type GroundTruthSourceType = "s3" | "sharepoint" | string;

Serverless Handlers

The framework also provides pre-built HTTP handlers for exposing the admin service as serverless endpoints:

import { createKnowledgeBaseAdminHandlers } from "@modernpath/agent-framework";

const handlers = createKnowledgeBaseAdminHandlers({
  adminService: admin,
});

// handlers.listStores(event)
// handlers.createStore(event)
// handlers.deleteStore(event)
// handlers.listDocuments(event)
// handlers.uploadJson(event)
// handlers.deleteDocument(event)
// handlers.groundTruthRedirect(event)

See Handler Factories for details on wiring these into your serverless entrypoint.