Ад інжынеріі запитоў да агентных робочых практык: стварэнне інтелігентных систем на

Наступныя прытамкі восстанавляюць практычны маршрут, які праходзіць па шляху «Ад інжынерыі запроса да агентных рабочых практык: стварэнне інтелігентных систем на Dataproc Serverless, частка 1». Акцэнт ставіцца на контракты, перакананняя та мескі для коду, які можна легка заменіць, а не на мотывацыйныя аспекты. Калі працуеце над стадзіяй аглявання, спачатку запісайце контракт: неабяжлівыя даннэ, сігнал успеху та тое, што выканаецца у разе частковага нявыпалення. Такі список перакананняя дапамагае заліцьварыць пазнейшыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок нявыпалецца, прычына нявыпалення павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцужок задач.

Агляванне серыі

Этап аналізу серыі працюе наякраща, калі яго розглядаць як меркаваемую плошчу. Запісаце адна ідеальная версія, адзін прыклад неудачы і запіс працэў па адвярненню змян пры расшырэнні масштаба. Разглядзеце этап як кантракт межа вхіднымі дадзеннямі і паверыжанымі выходнымі рэзультатамі. Даце назвы артыфактам, задаце критэрыя успеху і не падзельвайцеся на частковыя рэшынкі без адзначэння. Задаце бюджет токенав на кожны раунд і на кожную сесію. Інструменты-агенты агрэсывна расширваюць контекст; строгі ліміты не дазволяюць дэмам ператварыцца на неспакоўныя рахункі.

Частка 1: Усуненне працоўных труднасцей разработчыкаў Spark — автаматызацыя жыцёвага циклу Git, SBT і хмарнага сховішча

Этап часткі 1 «Адзёрванне Spark» працюе наяўней, калі яго розглядаць як вимерную паверхню. Зафіксавайце адна «золатая» транскрыпцыю, адин прыклад неудачы і запіс пра вярненне да пачатковага стану, перш чым расширваць масштабы. Запісвайце часы выконання і кост токенав або запытаў па боку функцыйнальных рэзультатаў. Відразлівае паказанне костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмавайнога режыма ў спяльныя сераўы. Задаце бюджет токенав на кожны раунд і на кожную сесію. Інструменты-агенты агрэсывна расширваюць контекст; строгі ліміты не дазволяюць дэмам ператварыцца на неспакойныя рахункі.

Введэнне: Агонія внутранняго цыклу ў інжынерыі Spark

Увядзенне: «Аганія стэйджа» працуе наўзярэдзе, калі яе спрыяваць як мерымае паверхне. Зберагчыце адны ідеальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштабы. Зберагчыце настройкі параду ўнутры коду прыемлівання. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функцый должны знаходзіцца ў аднам месцы, куды аператары можаць адрабоўваць контроль, не чытаючы весь ланцуг. Задаўце ліміты бюджету на кожны раунд і кожную сесію. Інструменты-агенты агрэсывна расширваюць контекст; жорсткія ліміты не дазволяюць дэмам ператварыцца на неспакоўлівыя рахункі. Увядзенне: «Аганія стэйджа» працуе наўзярэдзе, калі яе спрыяваць як мерымае паверхне. Зберагчыце адны ідеальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштабы. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі які-небудзь крок не выйшае, неудача должна вказваць на адну адпаведальнасць, а не на заплутаны ланцуг задач.

Архітектура: Раз'єднання процеса створення та завантажэння для агентнага викорыстоўвання

Для раз'єднання процеса створэння та наступнага етапу ў архітектуре неабходна прадзефінаваць вхідныя даны, адпаведальную особу за кожны крок і критэрыя завершэння пры зміне коду. Аперацыйныя системы должны магчымае перзапускати крок з вядомай точкі контролю, не прабуючы спадарожваць схованы стан. Цей етап трэба розглядаць як кантракт між вхіднымі данымі та перакананымі выходнымі рэзультатамі. Назваць артыфакты, прадзефінаваць пераканання на успех і не прабываць прыйматы часткова завершаную роботу без паведамлення. Калі наступным крокам є код або вызов інструменту, лепш выкарыстоўваць структураваныя выходныя даны з перакананням схемы, чым вільная проза.

Пасляпасовая рэалізацыя

У стадії параграфовайго адаптавання неабяжна ўзначыць вхідныя даны, адпаведальнага за кожны крок і критэрыі завершэння пры змяне коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не прабуючы спадарожваць схованы стан. Запісвайце час выконання і вартасць токена або запыту праза функцыйнальныя рэзултаты. Відразлівае паказанне вартасцей запобегае неспадзяваным рахункам, калі процес пераходзіць з дэмовай среды ў спяльнаваныя сераўеры. Калі наступны крок — це код або вызов інструмента, лепш выкарыстоўваць структураваныя выходныя даны з перакананнем схэмы, чым вольныя тэкстовыя апісанні.

1. Абавязковае выкарыстоўванне Java 11 і адкрыцье параметраў будовы (artifact_builder.py)

Для стадіі 1 «Выпэўненне Java 11» неабходна прадзефінаваць вхідныя даны, адпаведальную за шаг і крэтыніяты для завершэння пры змены коду. Аператары должны магчымае перзапускать шаг з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба знаходзіць за межамі коду прыемленае. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функцияў должны быць у аднам месца, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг задач. Калі наступны шаг — це код або вызов інструмента, лепш выкарыстоўваць структураваныя выходныя даны з перакананнем схэмы, чым вольныя тэкстовыя апісанні. Для стадіі 1 «Выпэўненне Java 11» неабходна прадзефінаваць вхідныя даны, адпаведальную за шаг і крэтыніяты для завершэння пры змены коду. Аператары должны магчымае перзапускать шаг з вядомай точкі контролю, не падозрываючы прыхованы стан. Лепш выкарыстоўваць маленькія, тэставаныя елементы, чым велікія скрыпты. Калі шаг не выйшоў, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцуг задач.

import os
import subprocess
import logging

class ArtifactBuilder:
    """Builds Scala JAR artifacts from Git repositories using SBT."""

    def __init__(self, repo_url: str, branch: str = "main"):
        self.repo_url = repo_url
        self.branch = branch

    def clone_repo(self, dest_dir: str):
        """Clone the given Git repository to the destination directory."""
        logging.info(f"Cloning {self.repo_url} (branch={self.branch}) into {dest_dir}")
        subprocess.run(["git", "clone", "-b", self.branch, self.repo_url, dest_dir], check=True)

    def find_build_dir(self, root_dir: str) -> str:
        """Recursively search for SBT build file."""
        for dirpath, _, filenames in os.walk(root_dir):
            if "build.sbt" in filenames:
                logging.info(f"Detected SBT build file in {dirpath}")
                return dirpath
        raise FileNotFoundError(f"No build.sbt file found in {root_dir}")

    def check_java_installed(self):
        """Ensure Java 11 is available and active in environment."""
        env = os.environ.copy()
        env["JAVA_HOME"] = "/opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk/Contents/Home"
        env["PATH"] = f"/opt/homebrew/opt/openjdk@11/bin:{env.get('PATH', '')}"

        result = subprocess.run(
            ["java", "-version"],
            check=True,
            env=env,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )
        output = result.stdout + result.stderr
        if "version" in output:
            version_str = output.split("version")[1].split()[0].strip('"')
            major_version = int(version_str.split(".")[0])
            if major_version != 11:
                raise EnvironmentError(f"Java 11 required, but detected Java {major_version}")
        logging.info("Java 11 verified successfully.")

    def build_artifact(self, repo_dir: str) -> str:
        """Compile and assemble fat JAR."""
        build_dir = self.find_build_dir(repo_dir)
        self.check_java_installed()

        env = os.environ.copy()
        env["JAVA_HOME"] = "/opt/homebrew/opt/openjdk@11/libexec/openjdk.jdk/Contents/Home"
        env["PATH"] = f"/opt/homebrew/opt/openjdk@11/bin:{env.get('PATH', '')}"

        logging.info("Running: sbt clean compile assembly...")
        subprocess.run(["sbt", "clean", "compile", "assembly"], cwd=build_dir, env=env, check=True)

        target_dir = os.path.join(build_dir, "target")
        return self._find_file(target_dir, ".jar")

    def _find_file(self, directory: str, extension: str) -> str:
        for root, _, files in os.walk(directory):
            for f in files:
                if f.endswith(extension):
                    return os.path.join(root, f)
        raise FileNotFoundError(f"No {extension} file found in {directory}")

2. Надзяйна публікацыя у хмарным сховішчы (uploader.py)

Калі працюеце над 2-м этапам надзяйнай публікацыі у хмарным сховішчы, спачатку запісайце угоду: неабяжлівыя даннэ, сигнал успеху і тое, што выходзіць у разе частковага невыпання. Такі список пераконтроўкаў дапамагае заліцьваты змяны ў кодзе. Спрыймайце гэты этап як угоду межа даннемі і перакананымі выходамі. Дайце назву элементам, задаце перакананні успеху і не прабывайце адбыць частковае завершэння без паведамлення. Зберагачыце у кэшы стабільныя інструкцыі системы і схемы інструментаў. Перадзесланне ідэнтычных прамаўляючых частак — частая прычына зусіль.

from google.cloud import storage
import logging
import os

class ArtifactUploader:
    """Handles secure upload of artifacts to Google Cloud Storage."""

    def __init__(self):
        self.client = storage.Client()

    def upload_to_gcs(self, bucket_name: str, artifact_path: str, dest_path: str):
        if not os.path.exists(artifact_path):
            raise FileNotFoundError(f"Artifact not found: {artifact_path}")

        logging.info(f"Uploading {artifact_path} → gs://{bucket_name}/{dest_path}")
        bucket = self.client.bucket(bucket_name)
        blob = bucket.blob(dest_path)
        blob.upload_from_filename(artifact_path)
        logging.info("Upload to GCS completed successfully.")

3. Оркестрацыя на бакэндзе і кліентскі абгортк (run_build_and_upload.py)

Калі працуеце над 3 стадзямі Backend Orchestration CLI, спачатку запісайце контракт: неабяжлівыя даны, сигнал успеху і тое, што выходзіць пад частковыя неудачы. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Запісвайце час выканання і кост токена або запыту пад функцыйнальнымі рэзултатамі. Відразы коста з самага пачатку запобегае неспакоўным рахункам, калі працэс пераходзіць з дэмовай среды ў спяльныя сераўеры. Зберагайце у кэшы стабільныя інструкцыі системы і схемы інструментаў. Перадзял у тое ж самае прамэру ёсць частым выклікам зайвых витрачэнняў.

# Executed autonomously in the background by the Agent's backend tool:
python3 artifact_pipeline/run_build_and_upload.py \
  --repo "https://github.com/<username>/demo-pipeline.git" \
  --branch main \
  --bucket "demo-spark-sandbox-bucket" \
  --dest "spark-jobs/spark-serverless-job_test.jar" \
  --cleanup

Візуалізацыя процесу стварэння у дзейнасці

Калі працюеце над стадзіяй «Візуалізацыя пайплайна будовы», спачатку запісаце кантракт: неабяжлівыя вхідныя даны, сігнал успеху і тое, што выканаецца у разе частковага нявыполнення. Такі список пераканальвае ў тым, каб пазнейшыя змены коду былі чыстымі. Зберагаеце настройкі праза код аплікацыі. Файлы сераўнавання, хранільнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаюць адбавіць аудыт без неабяжлівага чытання всей структуры. Кэшавайце стабільныя інструкцыі системы і схемы інструментаў. Перадача ідэнтычных даных знову є частым выклікам витрачання ресурсаў.

1. Перакананне хмарнага сховішча

Калі працюеце над 1-ым этапам адзначэння чыстоты хмарнага сховішча, спачатку запісайце угоду: неабяжлівыя данні, сігнал успеху і тое, што выканаецца у разе частковага нявыполнення. Такі список пераканаецца у тым, што пазнейшыя змены коду будуць чыстымі. Документавайце як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў ёсць часткай продукту, а не пазнейшым дапрацоўкам. Зберагайце у кэшы стабільныя інструкцыі системы і схемы інструментаў. Перасылка ідэнтычных паведамленняў ёсць частым выкліком для ресурсаў.

2. Жыцёвы цикл выканання агента ў Streamlit

Калі працуеце з стадзіяй 2 «Выкананне агента», спачатку запісайце умовы дагавору: неабяжлівыя даны, сігнал успеху і тое, што выходзіць пад частковыя неудачы. Такі список контроля дапамагае заліцварыць пазнейшыя змены ў кодзе. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, неудача должна вказваць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг задач. Зберагаеце у кэшы стабільныя інструкцыі системы і схемы інструментаў. Перадзесланне ідэнтычных даных — частая прычына зайвых витрацоў.

Эфектывае расляганне памылак і діагностика на практыцы

Калі працюеце над стадзіяй «Дыягнастыка жывучага адрабатавання з бягамі», спачатку запісайце контракт: неабяжныя вхідныя даны, сігнал успеху і тое, што выходзіць пад частковым бягам. Такі список пераканае ў тым, што пазнейшыя змены коду будуць чыстымі. Спрыймайце гэтую стадзію як контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы элементам, задаце правіла пераканання успеху і не падзволяйце частковам завершэнням без адпаведных падтверджэнняў. Зберагаюце у кешы стабільныя інструкцыі системы і схемы інструментаў. Перадача ідэнтычных прамуслов ёсць частым выклікам зношэння ресурсаў.

Сценарый 1: Автанація ў Git і бягі пад час клонавання

Калі працюеце над стадзіяй аутэнтыкацыі Git у Сцэнарыі 1, спачатку запісайце контракт: неабяжлівыя даннэ, сігнал успеху і тое, што выходзіць пад частыя неудачы. Такі список пераканаець у тым, што пазнейшыя змены коду будуць чыстымі. Запісвайце час выканання і кост токена або запыту пад функцыйнальнымі рэзултатамі. Відразы відомасці коста з’являецца неспакоўныя рахункі, калі працэс пераходзіць з дамоўкі ў спяльныя сэрвісы. Зберагаеце у кешы стабільныя інструкцыі системы і схемы інструментаў. Перадзял у тое ж самае прамэру ёсць частым выклікам затрат.

Сцэнарыя 2: Час выканання пайплайну і адыі ў сэрвісе

Калі працуеце над стадзіяй «Scenario 2 Pipeline Runtime», спачатку запісайце умовы вярбунка: неабяжлівыя данні, сигнал працэйскага успеху і тое, што выканаецца пад частковай нявыполненасці. Такі список дапамагае залічыць пазнейшыя змены ў кодзе.

Галоўныя выводы з часткі 1

Ключовыя моменты стадіі частковай роботы даюць найкращыя результаты, калі яе спрыяваць як меравальную плошчу. Запісаўце адна «золатая» транскрыпцыю, адин прыклад неудачы і прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Спрыявайце гэтую стадію як даговор межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаце критэрыя успеху і не падпісвайцеся на тыхое часткова завершэнне задання. Задзейце бюджет на токены за кожны раунд і за кожную сесію. Інструменты-агенты агрэсывна расширваюць контекст; строгі ліміты не дазволяюць дэмам ператварыцца на неспакоўныя рахункі.

Заключэнне

Этап заключэння працюе наяўней, калі яго спрыяваць як мерыемую плошчу. Запісаўце адна ідеальная версія рэзультата, адин прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расширваць масштабы. Запісвайце час выканання і кост токеноў або запытаў па боку функцыйнаых рэзультатаў. Відразлівае паказанне костаў з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмавай версіі у спяльныя среды. Задаўце бюджет на токены на кожны раунд і на кожную сесію. Інструменты-агенты агрэсывна расширваюць контекст; строгі ліміты не дазволяюць дэмавай версіям ператварыцца на неспакойныя рахункі.

Справы і далейшая літэратура (Частка 1)

Этап «Справакі, дадатковая література» працюе найэфективней, калі яго спрыяваць як до меры. Зберагчыце адны ідеальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштабы. Храніце настройкі параду ад коду прыемліка. Файлы серавэра, базы секретных даных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адрабоўваць аудыт, не чытаючы весь структураны код. Устанавіце ліміты на колькість токеноў за раунд і за сесію. Інструменты-агенты агрэсывна расширваюць контекст; жорсткія ліміты не дазволяюць дэмам ператварыцца на неспакоўлівыя рахункі. Этап «Справакі, дадатковая література» працюе найэфективней, калі яго спрыяваць як до меры. Зберагчыце адны ідеальны прыклад, адзін кейс неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць масштабы. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі які-небудзь крок не выйшае, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцоўкі задач.

Чэрніця аператыўных дзеянняў

У стадії перагляду канцэларыі аперацыйяў неабходна практычна вызначыць вхідныя даны, адпаведальнага за крок і крэтырыя завершэння пры зміне коду. Аперацыйныя працавнікі должны магчымае запускаць крок з вядомай точкі контролю, не спрабоўваючы здогадвацца пра схованы стан.

Неабходна адзначыць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія перакрыцця і обробка некоректных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней.

Калі наступны крок — це код або вызов інструмента, лепш выкарыстоўваць структураваныя выходны даны з перакрычэнням схемы, чым вольнае пісьменне выказванне.

Заставляйце точкі контролю пасля дорогіх крокаў. Система вярнення не должна занова ставіць плату за той самы вызов LLM, калі працавнік перапрыбуе пазнейшы вузел.

Фіксуйце версіі залежнасцяў і запішыце хэш адобраза, які выканаў дэманстрацыю. Возможнасць перадарабаткі важлівейшая, чым камунітэтныя знання.

Запісвайце часы выконання а таксу калечака або запиту праз функцыянальныя рэзультаты. Відразлівая візуабільнасць таксы з’яўляецца перашкодай неспакою па часе, калі маршрут пераходзіць з дэмавайнага режыма ў спакульную среду.

Перш чым пераводзіць стэк у продакшн, заморозьце версіі, зафіксавайце «золаты» транскрыпты для критычных маршрутаў і паказваце крокі для атрыбуцыі. У спакульных средах неабходны ліміты швыдкасці, перакананні ў прыналежнасці та чысты власнік для ротацыі секрэтных даных. Лепш выбраць простую надзею на надзейнасць, чым хітрыя експерыментальныя дэманстрацыі.

Прыметка для 671e92168610: не кладзіце ключы прадастаўцаў у репазітарый, задаце верхнюю межу калечака на адную сесію і зберагачыце транскрыпты праз фіксатары адлікавання, каб пазнейшыя замены модэляў заставаліся пораўнанымі.