Tutorial API GPT-6 Sol: Bangun Agen Migrasi Codebase

Di sini, kita akan menggunakan GPT-6 Sol untuk memigrasikan Northstar Checkout, layanan checkout Python fiksi berukuran kecil, dari adapter pembayaran lokal v1 ke v2.

Secara lebih spesifik, kita akan membahas cara:

• Melakukan panggilan API GPT-6 Sol pertama dan membaca field penggunaan

• Mendefinisikan kontrak migrasi sebelum model melihat repositori

• Memberi GPT-6 Sol alat berkas dan pengujian yang dibatasi, lalu menahap akses dengan allowed_tools

• Menggunakan GPT-6 Luna untuk triase dan membuat GPT-6 Sol memverifikasi shortlist

• Mengembalikan rencana migrasi terstruktur dan memeriksanya terhadap berkas yang sudah dibaca GPT-6 Sol

• Menjalankan migrasi melalui WebSocket dan mengarahkannya setelah pengeditan dimulai

• Menaikkan upaya penalaran setelah uji penerapan independen gagal

• Menghitung biaya yang tercatat dari penggunaan API

Hal-Hal yang Saya Pelajari Sepanjang Proses

Empat temuan mengubah cara saya membangun versi berikutnya:

• Lolos acceptance suite saja tidak cukup. Mengirim permintaan checkout yang sama ke server berbeda tetap menampakkan pengecualian adapter mentah.
• Peningkatan upaya memiliki pemicu nyata. Setelah uji penerapan gagal, GPT-6 Sol menemukan bug pada state yang disimpan oleh satu proses dan memperbaiki retry lintas server.
• Sebuah steer tidak bisa membatalkan edit, tetapi model bisa. GPT-6 Sol sudah mengganti nama parameter publik ketika persyaratan baru datang, dan ia membalikkan penggantian nama itu.
• Shortlist GPT-6 Luna memiliki recall penuh, tetapi penghematannya belum terbukti. GPT-6 Sol tetap mencari di luar shortlist sebelum merencanakan.

Apa Itu GPT-6 Sol?

GPT-6 Sol adalah tier menengah dari keluarga GPT-6 OpenAI, dan ID model API-nya adalah gpt-6-sol. Panduan kami tentang tier model GPT-6 membahas peluncuran dan benchmark. Panduan GPT-6 dari OpenAI menempatkan GPT-6 Astra di urutan pertama, GPT-6 Sol di tengah, dan GPT-6 Luna dengan biaya terendah.

GPT-6 Sol memiliki jendela konteks 1.050.000 token dan mengembalikan hingga 128.000 token keluaran. Upaya penalaran berjalan dari none hingga max dan default ke medium. Chat Completions mendukung pemanggilan fungsi GPT-6 Sol hanya pada none, sehingga setiap permintaan di sini menggunakan Responses API.

Harga dan dukungan API menentukan bagaimana harness mengirim tiap permintaan.

Berapa biaya API GPT-6 Sol?

GPT-6 Sol dikenai biaya $2 per satu juta token input dan $10 per satu juta token output untuk permintaan hingga 272.000 token input, menurut halaman harga OpenAI. Input yang di-cache dikenai $0,20 per satu juta, dan penulisan cache $2,50. Tarif GPT-6 Luna untuk empat kategori yang sama adalah $0,10, $0,01, $0,125, dan $0,50.

Di atas 272.000 token input, seluruh permintaan ditagihkan 2x tarif input dan cache serta 1,5x tarif output. Tidak ada permintaan dalam proyek ini yang mendekati batas tersebut.

Fitur API mana yang digunakan tutorial ini?

Harness, yaitu kode Python di sekitar model, menggunakan kendali GPT-6 berikut:

• Steering di tengah giliran memperbarui respons saat sedang berjalan

• configuration_update mengubah upaya penalaran tanpa menulis ulang prefiks yang di-cache

• allowed_tools menetapkan subset alat yang dapat dipanggil untuk suatu permintaan

• Structured Outputs menetapkan field dalam rencana dan laporan

Keempat kendali ini tetap berada dalam rantai respons Responses API yang sama.

Apa yang Akan Kita Bangun dengan API GPT-6 Sol?

Kita akan membangun agen yang memindahkan Northstar Checkout dari Payments Adapter v1 ke v2. Keduanya adalah pengganti lokal yang saya tulis untuk eksperimen ini, bukan SDK pembayaran nyata. Kode lengkap, fixture, dan rekaman run ada di repositori GitHub ini.

Repositori mencampurkan kode pembayaran dengan modul yang tidak terkait, jadi GPT-6 Sol harus menemukan berkas yang terdampak sendiri. V2 mematahkan empat kontrak adapter:

• Pembuatan pembayaran berpindah dari client.charge(...) ke client.payments.create(...)

• Kamus hasil menjadi objek bertipe dengan jumlah Money

• Kartu yang ditolak mengembalikan state alih-alih melempar pengecualian

• Webhook mengubah nama, amplop, dan header tandatangan

Cari-dan-ganti menangani penggantian nama metode. Itu tidak menangani perubahan perilaku mana pun.

Satu loop migrasi, dua model GPT-6. Gambar oleh Penulis.

GPT-6 Sol mendapatkan spesifikasi, pohon berkas, dan alat terbatas yang dapat dipanggil secara bertahap. Ia tidak tahu berkas mana yang perlu diubah atau bahwa persyaratan akan berubah.

Mengapa migrasi API ini sulit?

Dua bagian spesifikasi adalah jebakan. Keduanya bukan bug yang ditanam; keduanya muncul dari perilaku v2 yang bertemu dengan kode yang ada:

• Idempoten. v2 membandingkan parameter saat melihat request_id yang diulang, namun checkout menempatkan order_id baru di metadata pada setiap percobaan, sehingga retry naif ditolak alih-alih dideduplikasi.

• Total refund. Webhook payment.refunded pada v2 melaporkan total yang telah direfund sejauh ini, sementara handler lama menambahkan setiap nilai dengan +=.

Keduanya lolos pemeriksa tipe. Anda hanya menangkapnya dengan menjalankan checkout dan refund secara end-to-end.

Perubahan pembayaran melintasi beberapa modul Northstar. Gambar oleh Penulis.

Peta memisahkan impor adapter langsung dari modul yang bergantung pada perilaku pembayaran. Keterkaitan tak langsung itulah alasan jawaban kunci untuk seluruh repositori menjadi penting.

Bagaimana kita akan menguji migrasi?

Acceptance suite yang ditahan, ditulis sebelum panggilan model apa pun, menentukan hasilnya. GPT-6 Sol tidak pernah melihatnya; harness menjalankannya dengan pytest terhadap salinan yang telah dimigrasikan. Ia memeriksa bahwa:

• Checkout berhasil melalui v2, dan retry dengan kunci idempoten yang sama hanya menagih sekali

• Kartu yang ditolak masih memunculkan error publik CheckoutDeclined

• Satu refund penuh, dua refund parsial, dan webhook yang dikirim ulang semuanya menghasilkan total yang benar

• CheckoutClient tidak berubah tanda tangan metodenya

• Tidak ada referensi v1 yang tersisa, vendor/ dan MIGRATION.md tidak tersentuh, dan pengujian yang terlihat lolos

Kode asli sudah lolos pemeriksaan untuk antarmuka yang tidak berubah dan berkas yang dilindungi; pemeriksaan yang tersisa mengukur migrasi. Kunci jawaban terpisah mencantumkan perubahan yang diperlukan, namun hanya harness yang membacanya.

Direktori acceptance/ dan probes/ berada di luar repositori yang disalin yang diekspos ke kedua model. Kunci jawaban berada di bawah acceptance/, sehingga tidak dapat masuk ke input GPT-6 Luna, pohon berkas, atau alat repositori mana pun.

Gerbang baca dapat mengembalikan path dari rencana GPT-6 Sol sendiri. Hasil cakupan kunci jawaban dicatat hanya untuk evaluasi; ia tidak pernah mengirim path bukti dasar yang hilang kembali ke GPT-6 Sol.

Uji penerapan dijalankan setelah suite itu. Tidak ada pemeriksaan yang menerima pesan "done" dari model sebagai bukti.

Cara Menyiapkan API GPT-6 Sol di Python

Anda memerlukan Python 3.10 atau lebih baru dan kunci API dengan akses ke kedua model. Persyaratan mencakup realtime extra yang dibutuhkan steering:

git clone https://github.com/KhalidAbdelaty/gpt-6-sol-api.git
cd gpt-6-sol-api
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

Di macOS atau Linux, gunakan source .venv/bin/activate dan cp .env.example .env, lalu letakkan OPENAI_API_KEY=... di .env.

Jika kunci Anda sudah berfungsi dengan Responses API, lewati subbagian berikutnya.

Lakukan panggilan API GPT-6 Sol pertama Anda

Permintaan terkecil yang berguna mengonfirmasi kunci, ID model, dan field penggunaan yang diperlukan bagian biaya:

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()
response = client.responses.create(
    model="gpt-6-sol",
    input="In one sentence, why is a breaking API migration harder than renaming a function?",
)
print(response.reasoning.effort, response.output_text)
print(response.usage)

Respons melaporkan upaya medium, dan usage menyertakan cached_tokens dan cache_write_tokens. Abaikan temperature dan top_p. Keduanya mengembalikan 400 kapan pun upaya tidak none.

Permintaan GPT-6 Sol pertama mengembalikan usage. Gambar oleh Penulis.

Upaya penalaran mana yang harus Anda mulai?

Mulai pada medium, defaultnya, dan pertahankan pengaturan tingkat permintaan tersebut sepanjang run. Sebagian besar giliran migrasi adalah baca dan edit kecil. Uji penerapan nanti memberi alasan untuk menaikkan upaya.

Cara Menambahkan Alat Repositori Aman ke Agen Kode

Lapisan alat memiliki hak akses agen. GPT-6 Sol mendapatkan alat fungsi berikut dengan strict: true:

• list_files dan search_code menemukan kode yang relevan

• read_file mengembalikan satu berkas repositori

• edit_file mengubah satu kemunculan persis

• run_tests menjalankan target pytest yang diizinkan

Skema ketat memeriksa bentuk argumen, bukan keamanan path, sehingga Python menegakkan batas tulis:

READ_ONLY = ("vendor/", "MIGRATION.md", "conftest.py")

if write:
    if rel_posix.startswith(READ_ONLY) or rel_posix in READ_ONLY:
        raise ToolError(f"{rel_posix} is read-only")  # the spec and both adapters
    if not rel_posix.startswith(("northstar/", "tests/")) or not rel_posix.endswith(".py"):
        raise ToolError("writes are limited to Python files under northstar/ and tests/")

Path diselesaikan terlebih dahulu, sehingga ../ dan path absolut gagal. edit_file menggantikan satu kecocokan persis, dan run_tests hanya menerima target di bawah tests/.

Harness mengembalikan panggilan yang diblokir sebagai keluaran alat ERROR:, dan loop tetap berjalan. Panduan rekayasa agent harness kami menjelaskan mengapa pemeriksaan ini berada di harness, bukan di prompt.

Cara menguji batasan berkas

Panggil setiap alat dengan input yang harus ditolak:

• Path yang berisi ..

• Path absolut

• Penulisan di bawah vendor/

• Target pengujian yang berisi perintah shell

Tidak ada yang boleh lolos. Edit yang cocok di lebih dari satu lokasi harus meminta konteks lebih lanjut, dan menyimpan aturan dalam fungsi kustom menempatkannya di satu tempat yang dapat diuji.

Cara Menggunakan GPT-6 Luna untuk Triase Repositori

Triase repositori adalah tugas klasifikasi sempit: menilai relevansi setiap berkas dan mengutip referensi v1. GPT-6 Luna mendapatkan tugas ini dan tidak ada yang lain, dan dijalankan lebih dulu, sebelum GPT-6 Sol mencari apa pun.

class FileVerdict(BaseModel):
    path: str
    relevance: Literal["high", "medium", "low", "none"]
    legacy_references: list[str]

triage = client.responses.parse(model="gpt-6-luna", input=spec_and_all_files,
                                text_format=TriageResult)  # a list of FileVerdict

Inputnya adalah spesifikasi plus setiap berkas Python di bawah northstar/ dan tests/. Apa pun yang diberi nilai high atau medium masuk daftar pendek yang diterima GPT-6 Sol berikutnya.

Cara memeriksa shortlist GPT-6 Luna

Periksa daftar pendek terhadap kunci jawaban sebelumnya, dan lihat recall terlebih dahulu. GPT-6 Luna mempertahankan setiap berkas yang terkena dampak dan menambahkan beberapa yang tidak perlu diubah.

GPT-6 Luna mempersempit 56 menjadi 16. Gambar oleh Penulis.

Shortlist adalah petunjuk, bukan batas.

Cara Menggunakan allowed_tools untuk Perizinan Bertahap

allowed_tools adalah mode tool_choice yang membatasi alat mana yang dapat dipanggil model sementara daftar alat penuh tetap ada. Begitulah cara lompatan pertama GPT-6 Sol tetap read-only: daftar penuh didefinisikan pada setiap permintaan, tetapi hanya listing dan pencarian yang dapat dipanggil.

def allowed(names):
    return {"type": "allowed_tools", "mode": "auto",
            "tools": [{"type": "function", "name": n} for n in names]}

response = client.responses.create(
    model="gpt-6-sol", instructions=INSTRUCTIONS, tools=TOOLS,  # full list, every time
    tool_choice=allowed(["list_files", "search_code"]),
    reasoning={"effort": "medium"}, input=inspect_prompt, store=True,
)

Mengubah tools antar fase menulis ulang prefiks yang di-cache. Panduan pemanggilan fungsi merekomendasikan allowed_tools ketika hanya subset yang dapat dipanggil yang berubah.

Mengapa memulai agen kode dalam mode read-only?

Lintasan read-only memisahkan diagnosis dari tindakan. GPT-6 Sol mendapatkan shortlist GPT-6 Luna dengan peringatan biasa bahwa itu bisa salah, dan pencariannya untuk impor v1, pemanggilan charge, dan nama webhook menampilkan setiap berkas yang terdampak secara mandiri.

Ia juga melampaui daftar, menandai model order, penyimpanan order, serializer, dan ekspor buku besar sebagai dependensi hilir untuk diperiksa. Tidak ada yang akhirnya perlu diubah, tetapi membaca merekalah cara Anda mengetahuinya. Saya akan tetap menggunakan allowed_tools untuk agen apa pun yang mengedit berkas.

Cara Menggunakan Structured Outputs untuk Rencana Migrasi

Rencana migrasi adalah tempat agen berkomitmen pada berkas tertentu sebelum mendapat akses tulis. Perencanaan menambahkan read_file, dan rencana kembali melalui Structured Outputs dengan alat dimatikan:

plan = client.responses.parse(
    model="gpt-6-sol", instructions=INSTRUCTIONS, tools=TOOLS, tool_choice="none",
    reasoning={"effort": "medium"}, previous_response_id=last_id,
    input=PLAN_REQUEST, text_format=MigrationPlan,  # files, evidence, risks
)

Rencana mencakup setiap perubahan yang diperlukan dan memperingatkan bahwa order ID baru akan mengubah metadata v2 pada retry. Peringatan itu kembali nanti.

Cara memverifikasi rencana migrasi terstruktur

Sebelum memberikan akses tulis, harness memeriksa struktur, bukti, dan cakupan rencana.

Tiga pemeriksaan menguji satu rencana migrasi. Gambar oleh Penulis.

Rencana melewati setiap gerbang. Ia juga mengusulkan penggantian nama parameter publik client.py agar sesuai dengan penamaan v2, yang disarankan bagian pembersihan spesifikasi. Usulan itu menjadi uji steering.

Cara Membangun Agen Kode GPT-6 Sol dengan Responses API

Agen kode GPT-6 Sol menggunakan loop alat: tunggu respons, jalankan panggilan fungsinya, dan kembalikan keluarannya. Panduan OpenAI Responses API kami menjelaskan format permintaan dan hasil alat. Migrasi ini menjaga loop pada satu koneksi WebSocket karena steering membutuhkannya.

with client.responses.connect() as conn:
    conn.response.create(**base, previous_response_id=plan_id, input=[start_message])
    for event in conn:
        if event.type == "response.incomplete":
            reason = getattr(event.response.incomplete_details, "reason", None)
            if reason == "steered":
                continue  # keep reading for the automatic successor
            raise RuntimeError(reason or "response incomplete")
        if event.type != "response.completed":
            continue
        calls = [i for i in event.response.output if i.type == "function_call"]
        if not calls:
            break  # GPT-6 Sol says it's done here; the held-out tests decide whether it is
        outputs = [{"type": "function_call_output", "call_id": c.call_id,
                    "output": tools.run(c.name, c.arguments)} for c in calls]
        conn.response.create(**base, previous_response_id=event.response.id,
                             input=outputs)

base menjaga model, instruksi, alat, dan upaya medium tetap tetap untuk caching prompt. GPT-6 Sol menjalankan pengujian yang terlihat saat bekerja, tetapi ia juga menulis sebagian besar pengujian baru, jadi pengujian itu tidak bisa menjadi pemeriksaan independen.

Bagaimana Cara Kerja Steering di Tengah Giliran di GPT-6 Sol?

Steering di tengah giliran menambahkan instruksi ke respons yang masih berjalan, tanpa membatalkannya. Setelah response.created, Anda mengirim response.steer pada koneksi yang sama dengan ID respons tersebut, dan server menerapkan instruksi dalam respons penerus.

Persyaratan baru datang dari tim storefront: tanda tangan CheckoutClient "harus tetap persis seperti sekarang," karena layanan lain memanggilnya. Saya tidak ingin pengatur waktu yang menentukan kapan itu tiba, jadi harness mengawasi repositori sebagai gantinya. Setelah setiap batch panggilan alat, ia membandingkan tanda tangan publik di disk dengan aslinya, dan perbedaan pertama menyiagakan steer:

if steer_state == "idle" and signature_changes(repo):  # CheckoutClient, compared with ast
    steer_state = "armed"

if event.type == "response.created" and steer_state == "armed":
    conn.response.steer(previous_response_id=event.response.id, input=STEER_TEXT)
    steer_state = "sent"

Itu memastikan steer mendarat setelah penggantian nama yang ia sanggah, yang merupakan situasi yang layak diuji. Jika dikirim lebih awal, itu hanya prompt yang lebih panjang.

Server kemudian melaporkan siklus hidup steering:

• response.steer.accepted berarti pembaruan diantrikan, belum diterapkan

• response.incomplete mengakhiri respons asli dengan alasan steered

• Sebuah response.created penerus melanjutkan dengan persyaratan baru

Jika respons menunggu hasil alat, server mengirim response.steer.pending dan menahan steer sampai harness mengembalikannya. Terus jawab panggilan alat saat steer tertunda.

Apa yang tidak diubah oleh steering?

Steering mengubah apa yang dilakukan model selanjutnya. Panduan OpenAI jelas tentang sisanya: steer tidak menulis ulang keluaran yang sudah dikirim, tidak membatalkan tindakan sebelumnya, atau membatalkan alat yang sudah dimulai.

Saat steer tiba, penggantian nama sudah ada di disk di client.py. GPT-6 Sol membatalkannya, dan pemeriksaan tanda tangan yang ditahan kemudian mengonfirmasi antarmuka akhir.

Edit dapat dibatalkan. Alat yang sudah memanggil sistem eksternal tidak akan menyisakan apa pun untuk dibatalkan, jadi rekam state repositori saat setiap steer tiba.

Bisakah GPT-6 Sol Memigrasikan Codebase Python?

Di repositori ini, bisa, meski tidak dalam satu lintasan. Migrasi pertama memenuhi kontrak aslinya, lalu uji penerapan menyingkap kasus yang hilang.

Apa yang ditunjukkan pengujian yang ditahan?

Ketika GPT-6 Sol melaporkan migrasi selesai, acceptance suite lolos tanpa putaran perbaikan. Untuk refund, GPT-6 Sol mengganti penjumlahan dengan pembacaan kumulatif yang juga mengabaikan webhook tidak berurutan:

-        order.refunded_cents += data["amount_refunded"]
+        order.refunded_cents = max(order.refunded_cents, refunded["cents"])

Untuk idempoten, GPT-6 Sol mempertahankan order_id baru per percobaan dan menambahkan cache permintaan di penyimpanan order yang menjawab permintaan berulang sebelum mencapai v2. Cache itu berada di memori proses, yang penting sebentar lagi.

Bisakah Structured Outputs salah?

Bisa. Laporan pertama menyebut pengujian webhook yang diperbarui sebagai regresi dan mengabaikan risiko dari retry lintas server, meski rencana telah menyebut jebakan itu.

Structured Outputs hanya memvalidasi skema, bukan klaim tersebut. Periksa field laporan terhadap bukti yang direkam, dan jangan perlakukan daftar risiko kosong sebagai bukti bahwa tidak ada risiko yang tersisa.

Apa yang terlewat oleh acceptance tests?

Suite melewatkan retry yang diarahkan ke instance aplikasi lain. Saya menambahkan uji penerapan dengan dua klien yang berbagi satu prosesor pembayaran tetapi tidak berbagi memori proses.

Uji tersebut gagal. Retry pada instance kedua memunculkan payments_adapter_v2.IdempotencyConflict, pengecualian adapter yang memang tidak untuk dilihat storefront.

Hanya penerapan dengan lebih dari satu proses yang menyingkap kegagalan ini, yang memicu eskalasi penalaran.

Cara Mengubah Upaya Penalaran di Tengah Percakapan

Item input configuration_update mengubah upaya penalaran untuk respons berikutnya dan setiap respons sesudahnya, hingga pembaruan lain menggantikannya. Upaya tingkat permintaan tetap, sehingga prefiks yang di-cache bertahan. Saat uji penerapan gagal, harness mengirim permintaan ini, mengikuti panduan penalaran:

Permintaan migrasi menggunakan store=True, sehingga setelah WebSocket ditutup harness dapat melanjutkan rantai respons tersimpan dengan permintaan Responses API biasa.

response = client.responses.create(
    model="gpt-6-sol", reasoning={"effort": "medium"},  # unchanged, so the prefix survives
    instructions=INSTRUCTIONS, tools=TOOLS, tool_choice=allowed(DIAGNOSE_TOOLS),
    previous_response_id=last_id,
    input=[{"type": "configuration_update", "reasoning": {"effort": "high"}},
           {"role": "user", "content": probe_failure + DIAGNOSE_FIRST}],
)
active_effort = "high"  # the harness records it; the response won't

GPT-6 Sol menerima kegagalan dan bentuk penerapan, tetapi tanpa petunjuk tentang perbaikannya. DIAGNOSE_TOOLS mengizinkan membaca dan menguji, bukan mengedit. Menjaga alat dan text.format tidak berubah mempertahankan prefiks yang di-cache.

Satu detail API cukup mengganggu: response.reasoning.effort tetap melaporkan pengaturan tingkat permintaan setelah pembaruan. Harness tidak bisa membaca upaya aktif kembali dari respons, jadi ia mencatat nilainya sendiri saat mengirim pembaruan dan menandai setiap respons berikutnya dengannya.

Apakah perbaikan pada upaya high berhasil?

Berhasil. GPT-6 Sol menelusuri kegagalan ke penyimpanan lokal server kedua, lalu mengikuti order ID baru ke metadata pembayaran. Prosesor bersama melihat parameter berbeda untuk request_id yang sama.

Perbaikannya menjadikan order ID sebagai fungsi dari request ID, sehingga setiap server menghitung yang sama:

-def new_order_id() -> str:
+def new_order_id(request_id: str | None = None) -> str:
+    if request_id:
+        stable = uuid.uuid5(uuid.NAMESPACE_URL, f"northstar.checkout.order:{request_id}")
+        return f"ord_{stable.hex[:12]}"
     return f"ord_{uuid.uuid4().hex[:12]}"

GPT-6 Sol juga menambahkan pengujian yang terlihat untuk kasus tersebut. Uji penerapan dan acceptance suite lolos, lalu sebuah configuration_update mengembalikan upaya ke medium. Laporan akhir menggambarkan kegagalan nyata secara akurat kali ini.

Aplikasi Streamlit proyek memutar ulang run yang disimpan tanpa melakukan panggilan API. Videonya bergerak dari ringkasan ke peristiwa steering lalu ke hasil acceptance dan uji penerapan.