Tutorial API GPT-6 Sol: Construiește un agent de migrare a codului

Aici vom folosi GPT-6 Sol pentru a migra Northstar Checkout, un mic serviciu ficțional de checkout în Python, de la un adaptor local de plăți v1 la v2.

Mai exact, vom acoperi cum să:

• Faci primul apel la API-ul GPT-6 Sol și să citești câmpurile de utilizare

• Definești contractul de migrare înainte ca modelul să vadă repository-ul

• Oferi GPT-6 Sol instrumente restricționate pentru fișiere și teste, apoi faci accesul gradual cu allowed_tools

• Folosești GPT-6 Luna pentru triere și îl pui pe GPT-6 Sol să verifice lista scurtă

• Returnezi un plan de migrare structurat și îl verifici în raport cu fișierele deja citite de GPT-6 Sol

• Rulezi migrarea prin WebSocket și o ghidezi după ce încep editările

• Crești efortul de raționare după ce eșuează o probă de deployment independentă

• Calculezi costul înregistrat din utilizarea API-ului

Lucruri pe care le-am învățat pe parcurs

Patru constatări mi-au schimbat abordarea pentru următoarea versiune:

• Trecerea suitei de acceptanță n-a fost suficientă. Trimiterea aceleiași cereri de checkout către un alt server a expus totuși o excepție brută din adaptor.
• Creșterea efortului a avut un declanșator real. După ce a eșuat proba de deployment, GPT-6 Sol a găsit bugul în starea stocată de un proces și a reparat retry-urile între servere.
• O ghidare nu poate anula o editare, dar modelul poate. GPT-6 Sol deja redenumise un parametru public când a apărut noua cerință și a revenit asupra redenumirii.
• Lista scurtă a GPT-6 Luna a avut recall complet, dar economiile rămân neconcludente. GPT-6 Sol tot a căutat dincolo de ea înainte de planificare.

Ce este GPT-6 Sol?

GPT-6 Sol este nivelul intermediar al familiei GPT-6 de la OpenAI, iar ID-ul modelului în API este gpt-6-sol. Ghidul nostru pentru nivelurile de model GPT-6 acoperă lansarea și benchmark-urile. Ghidul pentru GPT-6 de la OpenAI plasează GPT-6 Astra pe primul loc, GPT-6 Sol la mijloc, iar GPT-6 Luna cu cel mai mic cost.

GPT-6 Sol are o fereastră de context de 1.050.000 de tokeni și returnează până la 128.000 de tokeni de ieșire. Efortul de raționare variază de la none până la max și implicit este medium. Chat Completions acceptă apelarea de funcții a GPT-6 Sol doar la none, așa că fiecare cerere de aici folosește Responses API.

Prețurile și suportul API determină cum trimite harness-ul fiecare cerere.

Cât costă API-ul GPT-6 Sol?

GPT-6 Sol costă 2 $ pe milion de tokeni de intrare și 10 $ pe milion de tokeni de ieșire pentru cereri de până la 272.000 de tokeni de intrare, conform paginii de prețuri OpenAI. Intrarea din cache costă 0,20 $ pe milion, iar scrierile în cache costă 2,50 $. Tarifele GPT-6 Luna pentru aceleași patru categorii sunt 0,10 $, 0,01 $, 0,125 $ și 0,50 $.

Peste 272.000 de tokeni de intrare, întreaga cerere este taxată la 2x pentru intrare și cache și 1,5x pentru ieșire. Nicio cerere din acest proiect nu s-a apropiat de aceste limite.

Ce funcții de API folosește acest tutorial?

Harness-ul, adică codul Python din jurul modelului, folosește aceste controale GPT-6:

• Steering la mijlocul rundei actualizează un răspuns în timp ce rulează

• configuration_update schimbă efortul de raționare fără a rescrie prefixul din cache

• allowed_tools setează submulțimea de instrumente apelabile pentru o cerere

• Structured Outputs definește câmpurile din plan și raport

Toate cele patru controale rămân în același lanț de răspunsuri al Responses API.

Ce vom construi cu API-ul GPT-6 Sol?

Vom construi un agent care mută Northstar Checkout de la Payments Adapter v1 la v2. Ambele adaptoare sunt substituenți locali pe care i-am scris pentru acest experiment, nu SDK-uri reale de plăți. Codul complet, fixturile și rularea înregistrată sunt în acest repository GitHub.

Repository-ul amestecă cod de plăți cu module fără legătură, așa că GPT-6 Sol trebuie să găsească singur fișierele afectate. V2 rupe patru contracte ale adaptorului:

• Crearea plății se mută de la client.charge(...) la client.payments.create(...)

• Dicționarele de rezultat devin obiecte tipizate cu sume de tip Money

• Cardurile refuzate întorc o stare în loc să arunce o excepție

• Webhook-urile își schimbă numele, plicul și antetul de semnătură

Căutarea-și-înlocuirea rezolvă redenumirea metodei. Nu rezolvă nicio schimbare de comportament.

Un ciclu de migrare, două modele GPT-6. Imagine de autor.

GPT-6 Sol primește specificația, arborele de fișiere și instrumente restricționate care devin apelabile în etape. Nu știe ce fișiere au nevoie de schimbări sau că o cerință se va schimba.

De ce e dificilă această migrare de API?

Două părți ale specificației sunt capcane. Niciuna nu este un bug introdus intenționat; ambele provin din comportamentul v2 întâlnind codul existent:

• Idempotency. v2 compară parametrii când vede un request_id repetat, dar checkout plasează un order_id nou în metadata la fiecare încercare, așa că un retry naiv este respins în loc să fie deduplicat.

• Totaluri de rambursare. Webhook-ul payment.refunded din v2 raportează totalul rambursat până acum, în timp ce handlerul vechi adună fiecare valoare cu +=.

Ambele trec de un verificator de tipuri. Le prinzi doar rulând cap-coadă checkout-ul și rambursările.

Schimbările de plăți traversează mai multe module Northstar. Imagine de autor.

Harta separă importurile directe ale adaptorului de modulele care depind de comportamentul plăților. Aceste legături indirecte sunt motivul pentru care contează o cheie de răspuns pentru întregul repository.

Cum vom testa migrarea?

O suită de acceptanță ținută deoparte, scrisă înainte de orice apel al modelului, decide rezultatul. GPT-6 Sol nu o vede niciodată; harness-ul o rulează cu pytest împotriva copiei migrate. Verifică faptul că:

• Checkout-ul reușește prin v2, iar un retry cu aceeași cheie de idempotency taxează o singură dată

• Un card refuzat ridică în continuare eroarea publică CheckoutDeclined

• O rambursare integrală, două rambursări parțiale și un webhook redelivrat lasă totalurile corecte

• CheckoutClient își păstrează neschimbate semnăturile metodelor

• Nu rămân referințe la v1, vendor/ și MIGRATION.md sunt neatinse, iar testele vizibile trec

Codul original trece deja de verificările pentru interfețe neschimbate și fișiere protejate; verificările rămase măsoară migrarea. O cheie de răspuns separată listează modificările necesare, dar doar harness-ul o citește.

Directorii acceptance/ și probes/ stau în afara repository-ului copiat expus ambelor modele. Cheia de răspuns trăiește sub acceptance/, deci nu poate intra în inputul GPT-6 Luna, arborele de fișiere sau vreun instrument de repository.

Poarta de citire poate returna căi din propriul plan al lui GPT-6 Sol. Rezultatul de acoperire față de cheia de răspuns este înregistrat doar pentru evaluare; nu trimite niciodată înapoi către GPT-6 Sol căi lipsă din ground truth.

O probă de deployment rulează după acea suită. Niciuna dintre verificări nu acceptă mesajul „gata” al modelului ca dovadă.

Cum configurezi API-ul GPT-6 Sol în Python

Ai nevoie de Python 3.10 sau mai nou și de o cheie API cu acces la ambele modele. Cerințele includ extra-ul realtime de care steering-ul are nevoie:

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

Pe macOS sau Linux, folosește source .venv/bin/activate și cp .env.example .env, apoi pune OPENAI_API_KEY=... în .env.

Dacă cheia ta deja funcționează cu Responses API, sari peste subsecțiunea următoare.

Fă primul tău apel la API-ul GPT-6 Sol

Cea mai mică cerere utilă confirmă cheia, ID-ul modelului și câmpurile de utilizare de care are nevoie secțiunea despre cost:

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)

Răspunsul raportează efortul medium, iar usage include cached_tokens și cache_write_tokens. Lasă deoparte temperature și top_p. Ambele returnează 400 ori de câte ori efortul nu este none.

Prima cerere GPT-6 Sol returnează utilizarea. Imagine de autor.

Cu ce efort de raționare ar trebui să începi?

Începe la medium, implicitul, și păstrează setarea la nivel de cerere acolo pe tot parcursul rundei. Majoritatea pașilor de migrare sunt citiri și editări mici. Proba de deployment de mai târziu oferă un motiv să crești efortul.

Cum adaugi instrumente sigure de repository unui agent de cod

Stratul de instrumente deține permisiunile agentului. GPT-6 Sol primește aceste instrumente de funcții cu strict: true:

• list_files și search_code localizează codul relevant

• read_file returnează un fișier din repository

• edit_file schimbă o singură apariție exactă

• run_tests execută o țintă pytest permisă

Schemele stricte verifică forma argumentelor, nu siguranța căii, astfel că Python impune limita de scriere:

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/")

Calea este rezolvată mai întâi, așa că ../ și căile absolute eșuează. edit_file înlocuiește o potrivire exactă, iar run_tests acceptă doar ținte sub tests/.

Harness-ul întoarce un apel blocat ca o ieșire de instrument ERROR:, iar bucla continuă. Ghidul nostru despre ingineria harness-ului pentru agenți explică de ce aceste verificări aparțin harness-ului, nu promptului.

Cum testezi limita de fișiere

Apelează fiecare instrument cu un input pe care trebuie să îl respingă:

• O cale care conține ..

• O cale absolută

• O scriere sub vendor/

• O țintă de test care conține o comandă de shell

Niciuna nu ar trebui să treacă. O editare care se potrivește în mai mult de un loc ar trebui să ceară mai mult context, iar păstrarea regulilor în funcții personalizate le pune într-un singur loc ușor de testat.

Cum folosești GPT-6 Luna pentru trierea repository-ului

Trierea repository-ului este o sarcină îngustă de clasificare: evaluează relevanța fiecărui fișier și citează referințe la v1. GPT-6 Luna primește această sarcină și nimic altceva, și rulează primul, înainte ca GPT-6 Sol să fi căutat ceva.

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

Inputul este specificația plus fiecare fișier Python de sub northstar/ și tests/. Orice este evaluat ca high sau medium intră pe lista scurtă pe care o primește GPT-6 Sol în pasul următor.

Cum verifici lista scurtă a GPT-6 Luna

Verifică lista scurtă în raport cu cheia de răspuns de mai devreme și uită-te întâi la recall. GPT-6 Luna a reținut fiecare fișier afectat și a adăugat câteva care nu necesitau schimbări.

GPT-6 Luna restrânge de la 56 la 16. Imagine de autor.

O listă scurtă e un indiciu, nu o limită.

Cum folosești allowed_tools pentru permisiuni în etape

allowed_tools este un mod de tool_choice care limitează ce instrumente poate apela modelul în timp ce lista completă rămâne la locul ei. Așa rămâne prima trecere a lui GPT-6 Sol doar în citire: lista completă este definită la fiecare cerere, dar doar listarea și căutarea sunt apelabile.

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,
)

Schimbarea lui tools între faze rescrie prefixul din cache. Ghidul pentru apelarea de funcții recomandă allowed_tools atunci când doar submulțimea apelabilă ar trebui să se schimbe.

De ce să pornești un agent de cod în mod doar-citire?

O trecere doar-citire separă diagnosticul de acțiune. GPT-6 Sol a primit lista scurtă de la GPT-6 Luna cu un simplu avertisment că ar putea fi greșită, iar căutările sale după importuri v1, apeluri charge și nume de webhook au scos la iveală fiecare fișier afectat de la sine.

A mers și dincolo de listă, marcând modelele de comenzi, store-ul de comenzi, serializer-ele și exportul de ledger ca dependențe în aval de verificat. Niciunul nu a necesitat schimbări până la urmă, dar citirea lor e modul în care afli asta. Aș păstra allowed_tools pentru orice agent care editează fișiere.

Cum folosești Structured Outputs pentru un plan de migrare

Un plan de migrare este locul în care agentul se angajează la fișiere specifice înainte să primească acces de scriere. Planificarea adaugă read_file, iar planul revine prin Structured Outputs cu instrumentele oprite:

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
)

Planul a acoperit fiecare schimbare necesară și a avertizat că un ID de comandă proaspăt ar schimba metadata v2 la retry. Acel avertisment revine mai târziu.

Cum verifici un plan de migrare structurat

Înainte de a acorda acces de scriere, harness-ul verifică structura, dovezile și acoperirea planului.

Trei verificări testează un singur plan de migrare. Imagine de autor.

Planul a trecut de fiecare poartă. A propus și redenumirea unui parametru public în client.py pentru a se potrivi cu denumirea din v2, lucru sugerat de secțiunea de curățare a specificației. Acea propunere devine testul pentru steering.

Cum construiești un agent de cod GPT-6 Sol cu Responses API

Un agent de cod GPT-6 Sol folosește o buclă de instrumente: așteaptă un răspuns, execută apelurile de funcții și returnează ieșirile. Ghidul nostru pentru OpenAI Responses API explică formatele pentru cereri și rezultate de instrumente. Această migrare păstrează bucla pe o singură conexiune WebSocket deoarece steering-ul are nevoie de ea.

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 păstrează modelul, instrucțiunile, instrumentele și efortul medium fixate pentru cache-ul de prompt. GPT-6 Sol a rulat testele vizibile pe măsură ce lucra, dar a scris și majoritatea testelor noi, deci acestea nu pot servi drept verificare independentă.

Cum funcționează steering-ul la mijlocul rundei în GPT-6 Sol?

Steering-ul la mijlocul rundei adaugă o instrucțiune unui răspuns care încă rulează, fără a-l anula. După response.created, trimiți response.steer pe aceeași conexiune cu ID-ul acelui răspuns, iar serverul aplică instrucțiunea într-un răspuns succesor.

Noua cerință a venit de la echipa de storefront: semnăturile CheckoutClient „trebuie să rămână exact cum sunt astăzi”, pentru că un alt serviciu le apelează. N-am vrut ca un timer să decidă când sosește aceasta, așa că harness-ul monitorizează repository-ul. După fiecare lot de apeluri de instrumente, compară semnăturile publice de pe disc cu originale, iar prima diferență armează steer-ul:

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"

Asta garantează că steer-ul aterizează după redenumirea pe care o contrazice, care este situația demnă de testat. Trimisa mai devreme, ar fi doar un prompt mai lung.

Serverul a raportat apoi ciclul de viață al steering-ului:

• response.steer.accepted a însemnat că actualizarea a fost pusă în coadă, nu aplicată

• response.incomplete a încheiat răspunsul original cu motivul steered

• Un response.created succesor a continuat cu noua cerință

Dacă răspunsul așteaptă un rezultat de la un instrument, serverul trimite response.steer.pending și ține steer-ul până când harness-ul îl întoarce. Continuă să răspunzi la apelurile de instrumente cât timp un steer este în așteptare.

Ce lasă steering-ul neschimbat?

Steering-ul schimbă ce face modelul în continuare. Ghidul OpenAI e direct în legătură cu restul: un steer nu rescrie ieșirea deja trimisă, nu anulează acțiuni anterioare și nu oprește instrumente care au început deja.

Când a sosit steer-ul, redenumirea era deja pe disc în client.py. GPT-6 Sol a revenit asupra ei, iar o verificare ținută deoparte a semnăturilor a confirmat mai târziu interfața finală.

O editare poate fi reversată. Un instrument care ar fi apelat deja un sistem extern n-ar lăsa nimic de inversat, așa că înregistrează starea repository-ului când sosește fiecare steer.

Poate GPT-6 Sol să migreze o bază de cod Python?

În acest repository, da, deși nu din prima. Prima migrare și-a îndeplinit contractul inițial, apoi proba de deployment a scos la iveală un caz lipsă.

Ce au arătat testele ținute deoparte?

Când GPT-6 Sol a raportat migrarea ca fiind completă, suita ținută deoparte a trecut fără rundă de reparare. Pentru rambursări, GPT-6 Sol a înlocuit adunarea cu o citire cumulativă care ignoră și webhook-urile livrate în altă ordine:

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

Pentru idempotency, GPT-6 Sol a păstrat un order_id nou la fiecare încercare și a adăugat un cache de cereri în store-ul de comenzi care răspunde cererilor repetate înainte să ajungă la v2. Acest cache trăiește în memoria procesului, ceea ce contează imediat.

Pot fi greșite Structured Outputs?

Da. Primul raport a numit un test de webhook actualizat un regres și a omis riscul retry-urilor între servere, deși planul numise acea capcană.

Structured Outputs validează schema, nu acele afirmații. Verifică câmpurile raportului în raport cu dovezile înregistrate și nu trata o listă de riscuri goală ca dovadă că nu mai există riscuri.

Ce au ratat testele de acceptanță?

Suita a ratat un retry direcționat către o altă instanță a aplicației. Am adăugat o probă de deployment cu doi clienți care împart același procesator de plăți, dar nu și memoria proceselor.

Proba a eșuat. Retry-ul pe a doua instanță a ridicat payments_adapter_v2.IdempotencyConflict, o excepție a adaptorului pe care storefront-ul nu trebuia să o vadă.

Doar un deployment cu mai mult de un proces expune acest eșec, care declanșează escaladarea efortului de raționare.

Cum schimbi efortul de raționare în mijlocul conversației

Un element de input configuration_update schimbă efortul de raționare pentru răspunsul următor și pentru toate cele de după, până când o altă actualizare îl înlocuiește. Efortul la nivel de cerere rămâne, deci prefixul din cache supraviețuiește. Când a eșuat proba, harness-ul a trimis această cerere, urmând ghidul de raționare:

Cereriile de migrare folosesc store=True, astfel că după închiderea WebSocket-ului harness-ul poate continua lanțul de răspunsuri stocat cu o cerere obișnuită la Responses API.

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 primește eșecul și forma deployment-ului, dar niciun indiciu despre remediere. DIAGNOSE_TOOLS permite citirea și testarea, nu editarea. Păstrarea instrumentelor și a text.format neschimbate conservă prefixul din cache.

Un detaliu al API-ului e deranjant: response.reasoning.effort raportează în continuare setarea la nivel de cerere după o actualizare. Harness-ul nu poate citi efortul activ din răspuns, așa că îl înregistrează singur când trimite actualizarea și etichetează fiecare răspuns ulterior cu el.

A funcționat repararea la efort high?

Da. GPT-6 Sol a urmărit eșecul până la store-ul local al celui de-al doilea server, apoi a urmărit ID-ul de comandă proaspăt în metadata plății. Procesatorul partajat a văzut parametri diferiți pentru același request_id.

Remedierea a făcut ID-ul comenzii o funcție de request ID, astfel încât fiecare server să calculeze același ID:

-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 a adăugat și un test vizibil pentru caz. Proba și suita de acceptanță au trecut, apoi un configuration_update a readus efortul la medium. Raportul final a descris corect eșecul real de data aceasta.

Aplicația proiectului în Streamlit redă rularea salvată fără a face apeluri API. Videoclipul trece de la prezentare generală la evenimentele de steering și apoi la rezultatele suita/probă.