GPT-6 Sol API-handledning: Bygg en agent för kodbasmigrering

Här använder vi GPT-6 Sol för att migrera Northstar Checkout, en liten fiktiv Python-betalningstjänst, från en lokal v1-betalningsadapter till v2.

Mer specifikt går vi igenom hur du:

• Gör ett första GPT-6 Sol API-anrop och läser dess användningsfält

• Definierar migrationskontraktet innan modellen ser koden i repot

• Ger GPT-6 Sol begränsade fil- och testverktyg, och fasar in åtkomst med allowed_tools

• Använder GPT-6 Luna för triage och låter GPT-6 Sol verifiera shortlist:en

• Returnerar en strukturerad migrationsplan och kontrollerar den mot filer som GPT-6 Sol redan har läst

• Kör migreringen över WebSocket och styr den efter att redigeringen har startat

• Ökar resonemangsinsatsen efter att en oberoende driftsättningskontroll misslyckas

• Beräknar den registrerade kostnaden från API-användning

Saker jag lärde mig på vägen

Fyra insikter ändrade hur jag skulle bygga nästa version:

• Att klara acceptanstesterna räckte inte. Att skicka samma checkout-begäran till en annan server exponerade fortfarande ett rått adapterundantag.
• Att höja insatsen hade en verklig trigger. Efter att driftsättningsproben misslyckades hittade GPT-6 Sol buggen i tillstånd lagrat av en process och reparerade omförsök över servrar.
• En styrsignal kan inte ångra en ändring, men modellen kan. GPT-6 Sol hade redan bytt namn på en publik parameter när det nya kravet kom, och den backade bytet.
• GPT-6 Lunas shortlist hade full recall, men besparingarna är ännu inte bevisade. GPT-6 Sol sökte ändå utanför den innan planering.

Vad är GPT-6 Sol?

GPT-6 Sol är mellannivån i OpenAIs GPT-6-familj, och dess API-modell-ID är gpt-6-sol. Vår guide till GPT-6-modellernas nivåer täcker lanseringen och benchmarktester. OpenAIs GPT-6-vägledning placerar GPT-6 Astra först, GPT-6 Sol i mitten och GPT-6 Luna lägst i kostnad.

GPT-6 Sol har ett kontextfönster på 1 050 000 token och returnerar upp till 128 000 utdata-token. Resonemangsinsatsen går från none till max och är som standard medium. Chat Completions stöder GPT-6 Sols funktionsanrop endast vid none, så varje begäran här använder Responses API.

Prissättning och API-stöd avgör hur harnessen skickar varje begäran.

Hur mycket kostar GPT-6 Sol API?

GPT-6 Sol kostar 2 USD per miljon indata-token och 10 USD per miljon utdata-token för begäranden upp till 272 000 indata-token, enligt OpenAIs prissida. Cachad indata kostar 0,20 USD per miljon, och cache-skrivningar kostar 2,50 USD. GPT-6 Lunas priser för samma fyra kategorier är 0,10, 0,01, 0,125 och 0,50 USD.

Över 272 000 indata-token debiteras hela begäran med 2x indata- och cacherates och 1,5x utdata-rate. Ingen begäran i det här projektet var i närheten.

Vilka API-funktioner använder den här handledningen?

Harnessen, alltså Python-koden runt modellen, använder dessa GPT-6-kontroller:

• Styrning mitt i turen uppdaterar ett svar medan det körs

• configuration_update ändrar resonemangsinsatsen utan att skriva om det cachade prefixet

• allowed_tools anger det anropbara delmängden för en begäran

• Structured Outputs sätter fälten i planen och rapporten

Alla fyra kontrollerna stannar i samma kedja av Responses API-svar.

Vad ska vi bygga med GPT-6 Sol API?

Vi bygger en agent som flyttar Northstar Checkout från Payments Adapter v1 till v2. Båda adaptrarna är lokala ersättare jag skrev för det här experimentet, inte riktiga betalnings-SDK:er. All källkod, fixtures och en inspelad körning finns i detta GitHub-repo.

Repon blandar betalningskod med orelaterade moduler, så GPT-6 Sol måste själv hitta vilka filer som berörs. V2 bryter fyra adapterkontrakt:

• Skapande av betalning flyttas från client.charge(...) till client.payments.create(...)

• Resultat-dictionaries blir typade objekt med Money-belopp

• Nekade kort returnerar ett tillstånd i stället för att kasta ett undantag

• Webhooks byter namn, kuvert och signaturheader

Sök-och-ersätt hanterar metodbytet. Det hanterar inga av beteendeförändringarna.

Ett migrationsvarv, två GPT-6-modeller. Bild: författaren.

GPT-6 Sol får specifikationen, filträdet och begränsade verktyg som blir anropbara i etapper. Den vet inte vilka filer som behöver ändras eller att ett krav kommer att ändras.

Varför är den här API-migreringen svår?

Två delar av specifikationen är fällor. Ingendera är en planterad bugg; båda uppstår när v2-beteende möter befintlig kod:

• Idempotens. v2 jämför parametrar när den ser ett upprepat request_id, men checkout lägger ett nytt order_id i metadata vid varje försök, så en naiv omförsökning blir avvisad i stället för deduplicerad.

• Återbetalningssummor. v2:s payment.refunded-webhook rapporterar den totala återbetalda summan hittills, medan den gamla hanteraren adderar varje värde med +=.

Båda överlever en typkontroll. Du fångar dem bara genom att köra checkout och återbetalningar från början till slut.

Betalningsändringar berör flera Northstar-moduler. Bild: författaren.

Kartan skiljer direkta adapter-importer från moduler som beror på betalningsbeteende. Dessa indirekta länkar är skälet till att en facitlista för hela repot spelar roll.

Hur kommer vi att testa migreringen?

En undanhållen acceptanssvit, skriven innan någon modellkörning, avgör resultatet. GPT-6 Sol ser den aldrig; harnessen kör den med pytest mot den migrerade kopian. Den kontrollerar att:

• Checkout lyckas genom v2, och ett omförsök med samma idempotensnyckel debiterar en gång

• Ett nekat kort höjer fortfarande det publika felet CheckoutDeclined

• En full återbetalning, två partiella och en omlevererad webhook lämnar alla korrekta totalsummor

• CheckoutClient-metodsignaturerna är oförändrade

• Inga v1-referenser återstår, vendor/ och MIGRATION.md är orörda, och de synliga testerna passerar

Originalkoden klarar redan kontroller för oförändrade gränssnitt och skyddade filer; de återstående kontrollerna mäter migreringen. Ett separat facit listar de nödvändiga ändringarna, men bara harnessen läser den.

Katalogerna acceptance/ och probes/ ligger utanför den kopierade repo-strukturen som exponeras för båda modellerna. Facitlistan ligger under acceptance/, så den kan inte komma in i GPT-6 Lunas indata, filträdet eller några repo-verktyg.

Läsgrinden kan returnera sökvägar från GPT-6 Sols egen plan. Resultatet från facittäckningen spelas in bara för utvärdering; det skickar aldrig saknade sanning-sökvägar tillbaka till GPT-6 Sol.

En driftsättningsprob körs efter den sviten. Ingen av kontrollerna accepterar modellens "klart"-meddelande som bevis.

Hur ställer man in GPT-6 Sol API i Python

Du behöver Python 3.10 eller nyare och en API-nyckel med åtkomst till båda modellerna. Kraven inkluderar realtime-extrat som styrning kräver:

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

På macOS eller Linux, använd source .venv/bin/activate och cp .env.example .env, och lägg sedan OPENAI_API_KEY=... i .env.

Om din nyckel redan fungerar med Responses API kan du hoppa över nästa delavsnitt.

Gör ditt första GPT-6 Sol API-anrop

Den minsta användbara begäran bekräftar nyckeln, modell-ID:t och användningsfälten som kostnadsavsnittet behöver:

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)

Svaret rapporterar medium-insats, och usage inkluderar cached_tokens och cache_write_tokens. Lämna ute temperature och top_p. Båda returnerar 400 när insatsen inte är none.

Första GPT-6 Sol-begäran returnerar användning. Bild: författaren.

Vilken resonemangsinsats ska du börja med?

Börja på medium, standardvärdet, och behåll begärandenivåns inställning där under hela körningen. De flesta migrationssteg är läsningar och små ändringar. Driftsättningsproben ger senare skäl att höja insatsen.

Hur man lägger till säkra repo-verktyg i en kodningsagent

Verktygslagret äger agentens behörigheter. GPT-6 Sol får dessa funktionsverktyg med strict: true:

• list_files och search_code hittar relevant kod

• read_file returnerar en fil i repot

• edit_file ändrar en exakt förekomst

• run_tests kör ett tillåtet pytest-mål

Strikta scheman kontrollerar argumentform, inte sökvägssäkerhet, så Python upprätthåller skrivgränsen:

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

Sökvägen löses först, så ../ och absoluta sökvägar misslyckas. edit_file ersätter en exakt matchning, och run_tests accepterar bara mål under tests/.

Harnessen returnerar ett blockerat anrop som en ERROR:-verktygsutdata, och loopen fortsätter. Vår guide till agent-harness-engineering förklarar varför dessa kontroller hör hemma i harnessen i stället för i prompten.

Hur man testar filgränsen

Anropa varje verktyg med en indata som det måste neka:

• En sökväg som innehåller ..

• En absolut sökväg

• En skrivning under vendor/

• Ett testmål som innehåller ett shell-kommando

Inget ska slinka igenom. En redigering som matchar mer än en plats ska be om mer kontext, och att behålla reglerna i anpassade funktioner samlar dem på ett testbart ställe.

Hur man använder GPT-6 Luna för repo-triage

Repo-triage är ett smalt klassificeringsjobb: betygsätt varje fils relevans och citera v1-referenser. GPT-6 Luna får detta jobb och inget annat, och den körs först, innan GPT-6 Sol har sökt något.

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

Indatan är specifikationen plus varje Python-fil under northstar/ och tests/. Allt som rankas high eller medium hamnar på shortlist:en som GPT-6 Sol får härnäst.

Hur man kontrollerar GPT-6 Lunas shortlist

Kontrollera shortlist:en mot facitlistan från tidigare, och titta först på recall. GPT-6 Luna behöll varje berörd fil och lade till några som inte krävde ändringar.

GPT-6 Luna snävar in från 56 till 16. Bild: författaren.

En shortlist är ett uppslag, inte en gräns.

Hur man använder allowed_tools för behörigheter i etapper

allowed_tools är ett tool_choice-läge som begränsar vilka verktyg modellen kan anropa medan den fullständiga verktygslistan ligger kvar. Det är så GPT-6 Sols första pass förblir skrivskyddat: hela listan är definierad vid varje begäran, men endast listning och sökning är anropbara.

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

Att ändra tools mellan faser skriver om det cachade prefixet. Guiden för funktionsanrop rekommenderar allowed_tools när endast den anropbara delmängden ska ändras.

Varför starta en kodningsagent i skrivskyddat läge?

Ett skrivskyddat pass separerar diagnos från åtgärd. GPT-6 Sol fick GPT-6 Lunas shortlist med en enkel varning om att den kunde vara fel, och dess sökningar efter v1-importer, charge-anrop och webhook-namn fångade alla berörda filer på egen hand.

Den gick också förbi listan, flaggade ordermodeller, orderlagret, serialiserare och huvudboks­export som nedströmsberoenden att kontrollera. Ingen av dem visade sig kräva ändringar, men att läsa dem är hur du tar reda på det. Jag skulle behålla allowed_tools för varje agent som redigerar filer.

Hur man använder Structured Outputs för en migrationsplan

En migrationsplan är där agenten binder sig till specifika filer innan den får skrivrättigheter. Planeringen lägger till read_file, och planen kommer tillbaka via Structured Outputs med verktygen avstängda:

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
)

Planen täckte varje nödvändig ändring och varnade för att ett nytt order-ID skulle ändra v2-metadata vid omförsök. Den varningen återkommer senare.

Hur man verifierar en strukturerad migrationsplan

Innan skrivrättigheter beviljas kontrollerar harnessen planens struktur, evidens och täckning.

Tre kontroller testar en migrationsplan. Bild: författaren.

Planen passerade varje grind. Den föreslog också att byta namn på en publik parameter i client.py för att matcha v2:s namngivning, vilket specifikationens städavsnitt föreslog. Det förslaget blir styrningstestet.

Hur man bygger en GPT-6 Sol-kodningsagent med Responses API

En GPT-6 Sol-kodningsagent använder en verktygsloop: vänta på ett svar, kör dess funktionsanrop och returnera utdata. Vår guide till OpenAI Responses API förklarar formatet för begäran och verktygsresultat. Den här migreringen behåller loopen på en WebSocket-anslutning eftersom styrning kräver det.

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 behåller modellen, instruktionerna, verktygen och medium-insats fast för prompt-cachning. GPT-6 Sol körde de synliga testerna medan den arbetade, men den skrev också de flesta nya testerna, så de kan inte fungera som en oberoende kontroll.

Hur fungerar styrning mitt i turen i GPT-6 Sol?

Styrning mitt i turen lägger till en instruktion i ett svar som fortfarande körs, utan att avbryta det. Efter response.created skickar du response.steer på samma anslutning med det svarets ID, och servern applicerar instruktionen i ett efterföljande svar.

Det nya kravet kom från butiksteamet: CheckoutClient-signaturerna "måste förbli exakt som de är idag", eftersom en annan tjänst anropar dem. Jag ville inte att en timer skulle avgöra när det kommer, så harnessen övervakar repot i stället. Efter varje batch av verktygsanrop jämför den de publika signaturerna på disk med originalen, och den första skillnaden armerar styrningen:

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"

Det garanterar att styrningen landar efter namnbytet den motsäger, vilket är situationen värd att testa. Skickad tidigare blir den bara en längre prompt.

Servern rapporterade sedan styrningens livscykel:

• response.steer.accepted betydde att uppdateringen var köad, inte tillämpad

• response.incomplete avslutade det ursprungliga svaret med orsaken steered

• Ett efterföljande response.created fortsatte med det nya kravet

Om svaret väntar på ett verktygsresultat skickar servern response.steer.pending och håller styrningen tills harnessen returnerar det. Fortsätt besvara verktygsanrop medan en styrning är väntande.

Vad lämnar styrning oförändrat?

Styrning ändrar vad modellen gör härnäst. OpenAIs guide är tydlig med resten: en styrning skriver inte om redan skickad utdata, ångrar inte tidigare åtgärder och avbryter inte verktyg som redan har startat.

När styrningen kom hade namnbytet redan skrivits till disk i client.py. GPT-6 Sol backade det, och en undanhållen signaturkontroll bekräftade senare det slutliga gränssnittet.

En redigering kan backas. Ett verktyg som redan hade anropat ett externt system skulle inte lämna något att backa, så spela in repots tillstånd när varje styrning anländer.

Kan GPT-6 Sol migrera en Python-kodbas?

I det här repot, ja, men inte i ett svep. Den första migreringen uppfyllde sitt ursprungliga kontrakt, sedan avslöjade driftsättningsproben ett saknat fall.

Vad visade de undanhållna testerna?

När GPT-6 Sol rapporterade att migreringen var klar, klarade den undanhållna sviten utan reparationsrunda. För återbetalningar ersatte GPT-6 Sol additionen med en kumulativ avläsning som också ignorerar webhooks i fel ordning:

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

För idempotens behöll GPT-6 Sol ett nytt order_id per försök och lade till en begärandecache i orderlagret som besvarar upprepade begäranden innan de når v2. Den cachen ligger i processminnet, vilket snart blir viktigt.

Kan Structured Outputs ha fel?

Ja. Den första rapporten kallade ett uppdaterat webhook-test en regression och utelämnade risken från omförsök över servrar, trots att planen hade nämnt den fällan.

Structured Outputs validerar schemat, inte dessa påståenden. Kontrollera rapportfält mot inspelad evidens, och betrakta inte en tom risklista som bevis på att ingen risk återstår.

Vad missade acceptanstesterna?

Sviten missade ett omförsök som dirigerades till en annan appinstans. Jag lade till en driftsättningsprob med två klienter som delar en betalningsprocessor men inte sitt processminne.

Proben misslyckades. Omförsöket på den andra instansen höjde payments_adapter_v2.IdempotencyConflict, ett adapterundantag som butiken aldrig var tänkt att se.

Bara en driftsättning med mer än en process blottlägger detta fel, vilket triggar eskaleringen av resonemanget.

Hur man ändrar resonemangsinsats mitt i konversationen

Ett configuration_update-indataobjekt ändrar resonemangsinsatsen för nästa svar och alla senare, tills en annan uppdatering ersätter den. Begärandenivåns insats förblir oförändrad, så det cachade prefixet överlever. När proben misslyckades skickade harnessen denna begäran, enligt resonemangsguiden:

Migreringsbegärandena använder store=True, så efter att WebSocket:en stängs kan harnessen fortsätta den sparade svarskedjan med en vanlig Responses API-begäran.

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 får felet och driftsättningsformen, men ingen vink om fixen. DIAGNOSE_TOOLS tillåter läsning och testning, inte redigering. Att behålla verktyg och text.format oförändrade bevarar det cachade prefixet.

En API-detalj är störande: response.reasoning.effort rapporterar fortfarande begärandenivåns inställning efter en uppdatering. Harnessen kan inte läsa tillbaka den aktiva insatsen från svaret, så den registrerar värdet själv när den skickar uppdateringen och taggar alla senare svar med det.

Fungerade reparationen vid high insats?

Ja. GPT-6 Sol spårade felet till den andra serverns lokala lager och följde sedan det nya order-ID:t in i betalningsmetadata. Den delade processorn såg olika parametrar för samma request_id.

Fixen gjorde order-ID:t till en funktion av request-ID:t, så varje server beräknar samma:

-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 lade också till ett synligt test för fallet. Proben och acceptanssviten passerade, sedan återställde en configuration_update insatsen till medium. Slutrapporten beskrev det verkliga felet korrekt denna gång.

Projektets Streamlit-app spelar upp den sparade körningen utan att göra API-anrop. Videon går från översikten till styrningshändelserna och sedan resultaten från acceptans och prob.