agent-platform-rag-engine-management

Agent Platform RAG Engine Management — это навык для работы с корпусами и файлами Agent Platform RAG Engine через официальный Python SDK. Он покрывает четыре связанные операции: перечисление корпусов и файлов, получение сведений о конкретном корпусе, retrieval-запрос за релевантными контекстами и генерацию ответа, grounded на найденном корпусе. Такой набор полезен, когда документы уже организованы в RAG Engine и агенту нужно сначала понять доступные ресурсы, затем извлечь контекст и только после этого сформировать ответ. Навык не предназначен для обычных SQL или Spanner-запросов, Google Workspace RAG и других продуктов RAG, включая gRAG. Ключевое правило реализации — использовать Python SDK vertexai для операций RAG Engine, а не сырые REST-вызовы или MCP-инструменты. Для начала требуется настроить Google Cloud authentication: выполнить вход через gcloud и включить Application Default Credentials. В исходных инструкциях также предложены отдельное виртуальное окружение Python и пакеты google-cloud-aiplatform и google-genai. Вызовы используют project, region и идентификатор корпуса; из них строится ресурсное имя вида projects/.../locations/.../ragCorpora/.... Если эти параметры неизвестны, рабочий порядок начинается с discovery, а не с угадывания имени ресурса. Для discovery доступны list_corpora и list_files. SDK умеет автоматически проходить страницы при преобразовании результата в список; для больших наборов показан и ручной pager с page_size и next_page_token. У корпуса можно прочитать resource name и display name, а у файла — display name, resource name и описание. Расширение имени файла помогает отличить PDF и обычный текст, но само по себе не заменяет проверку фактического содержимого. Этот этап удобен перед retrieval: он позволяет убедиться, что выбран именно нужный корпус и что в нём есть ожидаемые документы. Операция retrieval_query принимает список корпусов, текст запроса и параметр similarity_top_k. В ответе навык предлагает пройти по contexts и вывести текст каждого контекста вместе с source_uri. Это даёт агенту проверяемую основу для последующей работы: результат можно связать с конкретным источником, а число возвращаемых фрагментов ограничить параметром top-k. Для grounded generation используется клиент google.genai с enterprise=True, project и location. В инструмент передаётся VertexRagStore с ресурсом корпуса; в примере также указаны top_k и порог vector similarity threshold. Инструкции разделяют действия по уровню подтверждения. Списки корпусов и файлов, получение корпуса и retrieval_query являются read-only и могут выполняться сразу. Генерация через client.models.generate_content тоже не меняет документы, но потребляет вычислительные ресурсы, поэтому перед её запуском нужен отдельный интерактивный запрос подтверждения с точными параметрами: корпусом, моделью и текстом запроса. Это важное ограничение для автоматизации: нельзя молча подставлять произвольные project, region, corpus ID или вопрос. Навык подходит для контролируемой работы с grounded-контекстом, но не заменяет настройку IAM, ADC, квот и проверку содержимого источников; эти внешние условия должны быть готовы до запуска SDK-кода.