Pi Durable: agents veilig hervatten na een herstart

Pi Durable kan een agent helpen om na een heruitrol het werk te hervatten. Maar een opgeslagen gespreksgeschiedenis voorkomt niet dat de agent dezelfde factuur twee keer verstuurt.

Herstel vraagt om meer dan een opgeslagen gespreksgeschiedenis

Stel: een agent is al 40 minuten bezig met een onderhoudstaak. Hij heeft een repository onderzocht, een plan vastgelegd en een uitrol gestart wanneer zijn container wordt vervangen. De gespreksgeschiedenis laat misschien zien wat de agent van plan was, maar voor herstel moet ook duidelijk zijn welk werk is afgerond, welke statuswijzigingen zijn vastgelegd en of die uitrol daadwerkelijk heeft plaatsgevonden.

Pi Durable biedt hiervoor persistente opslag en uitvoeringsmechanismen. De library verscheen tegelijk met Pi 1.0 en is gemaakt door de ontwikkelaars van de Pi coding agent, die nu onder Earendil valt. U bouwt er een applicatie omheen, met afzonderlijke bouwstenen voor de gespreksgeschiedenis, de applicatiestatus en onafgerond werk:

Een commit kan gespreksitems, Document-wijzigingen, nieuwe Tasks en Submission-updates samen vastleggen. Zo treft het herstelproces geen vastgelegde beslissing aan zonder de bijbehorende wijziging in de applicatiestatus. Die garantie houdt op bij de opslaggrens: een databasecommit en het afleveren van een externe e-mail kunnen hiermee niet als één ondeelbare bewerking worden uitgevoerd.

Zet versies vast en neem herstel op in de opstartprocedure

Begin met de pakketten uit de officiële repository:

bashCopy
npm install --save-exact @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord

De optie --save-exact legt de exacte versies van directe afhankelijkheden vast. Neem zowel package.json als uw lockfile op in versiebeheer: Pi Durable is experimenteel en de API kan veranderen. Gebruik de actuele voorbeelden uit de repository voor de volledige applicatie; ga niet gokken welke argumenten constructors verwachten.

De opstartprocedure moet deze stappen doorlopen:

1. Open SQLite-opslag met openNodeSqliteStorage('./agent.sqlite'), geïmporteerd uit @earendil-works/pi-durable/storage/sqlite/node.
2. Geef die opslag door aan Harness.open.
3. Roep bij elke start harness.resume aan voordat u nieuwe invoer accepteert.
4. Dien nieuwe invoer in via root.submit.
5. Bewaar de identiteit van de Submission, zodat aanroepers deze na een herstart kunnen terugvinden en op het resultaat kunnen wachten.

Na een herstart moet de applicatie opgeslagen werk hervatten, niet het oorspronkelijke verzoek als een nieuwe taak indienen.

Geef bij een triage-agent die op webhooks reageert een stabiele requestId, zoals job-42, mee met de indiening. Volgens de documentatie en voorbeelden van Pi Durable levert een nieuwe poging met datzelfde ID de bestaande Submission op. Gebruik waar mogelijk de stabiele identificatie van het binnenkomende event. Als u voor elke afleverpoging een nieuwe identificatie genereert, werkt deduplicatie niet.

Classificeer elke tool voordat u de prompt schrijft

Een beheeragent heeft verschillende herstelregels nodig voor tools die configuratie uitlezen, de uitrolstatus controleren of een uitrol starten.

Met defineTool maakt Pi Durable de veiligheid van herhaling tot een expliciete keuze. Een onderbroken tool die als veilig is gemarkeerd, kan opnieuw worden uitgevoerd. Bij een ongemarkeerde tool meldt de harness de onderbreking aan het model, zoals beschreven in de officiële aankondiging.

Dat is een verstandige standaard. Een proces kan wegvallen nadat een externe dienst een verzoek heeft geaccepteerd, maar voordat de agent het resultaat vastlegt. De uitkomst is dan onzeker.

Een idempotentiesleutel is een stabiele identificatie waarmee een dienst herhaalde verzoeken voor dezelfde bewerking kan herkennen. Houd die identificatie bij elke nieuwe poging gelijk.

Een Document kan voltooide acties en externe bewerkings-ID's bijhouden. Toch blijft er een kwetsbaar moment tussen het slagen van een externe actie en het lokaal vastleggen van de voltooiing. Voor herstel is een manier nodig om de uitkomst bij de aanbieder op te vragen of die onzekerheid anders weg te nemen.

Kies voor een beheeragent bij voorkeur een workflow die een uitrol start, het externe bewerkings-ID bewaart en de status afzonderlijk controleert. Is door een onderbreking niet bekend of de uitrol is gestart? Vereis dan verificatie of goedkeuring voordat de agent het opnieuw probeert.

SQLite is de standaard, maar opslag heeft een eigenaar nodig

Een container die ./agent.sqlite naar zijn tijdelijke bestandssysteem schrijft, verliest zijn persistente status zodra dat bestandssysteem verdwijnt. Zet het bestand op een persistent volume voordat u herstel gaat testen.

De officiële repository beveelt SQLite aan voor agents die langdurig draaien. Kies alleen een andere backend als daar een concrete eis voor is; een embedded database is niet per definitie te beperkt.

JSONL slaat één JSON-record per regel op. Dat leesbare formaat is handig, maar doordat de geschiedenis in het geheugen blijft, is het geen goede standaardkeuze voor een agent die onbeperkt blijft groeien. De library biedt ook een kleine opslaginterface, conformiteitstests en benchmarks voor eigen implementaties. Die helpen om een adapter te valideren; ze maken een beoogde Postgres- of key-value-backend niet automatisch productierijp.

Leg de regels voor de uitrol expliciet vast:

• Wijs voor elke opslaginstantie precies één proces als eigenaar aan.
• Laat andere clients via dat proces werken.
• Bewaar het SQLite-bestand op persistente schijf en maak er back-ups van als database.
• Plaats het niet op een netwerkshare waar meerdere machines naar schrijven.
• Wijs bij horizontale schaling aparte opslag toe per agent of tenant.

Pi Durable start het proces niet zelf opnieuw. Op een Linux-server is systemd met Restart=always een eenvoudige keuze; gebruik in containers een herstartbeleid en een aangekoppeld persistent volume. SQLite zorgt dat de databasegegevens bewaard blijven. Elk vervangend proces moet nog steeds harness.resume aanroepen.

Breid de agent uit zonder operationele risico's te verhullen

Een coding agent die 's nachts doorwerkt, is een logische eerste toepassing. De officiële repository bevat daar al een klein voorbeeld van. Volg voor een gestructureerde planningsstatus het voorbeeld van de vakantieplanner en bewaar de voortgang in Documents.

De ingebouwde mogelijkheden en uitbreidingspunten voorzien in verschillende behoeften:

CodingTools, uit @earendil-works/pi-durable/tools, biedt tools voor lezen, schrijven, bewerken en bash. NodeExecutionEnv, uit @earendil-works/pi-durable/env/node, voert ze lokaal uit. De rechten van die tools zijn dus de rechten die u aan uw agent verleent.

Voor een gesprek over systeembeheer kan thread.configure({ tools: { remove: [deploy] } }) de toegang tot een uitroltool intrekken. Leg goedkeuringscontroles en auditregistratie vast in een toolwrapper. Vertrouw er niet op dat een prompt het beleid blijft bewaken.

Uitbreidingen kunnen tools, hooks, promptonderdelen via section, wrappers via wrapTool en aangepaste taken via defineTask toevoegen. Het gedocumenteerde patroon registry.install(await loadExtension('./ops.ts')) ondersteunt het laden van nieuwe uitbreidingscode terwijl de agent draait. Maar ook wijzigingen tijdens runtime verdienen hersteltests.

Het officiële voorbeeld voor contextcompactie gebruikt reserveTokens: 16384 en backgroundTokens: 32768. Compactie bepaalt wat in de context van het model terechtkomt, zonder de persistent opgeslagen geschiedenis weg te gooien.

Er zijn geen ingebouwde subagents. De voorbeelden laten zien hoe u er een als tool implementeert, waarbij api.createTask en api.waitForTask onderliggende taken ondersteunen.

Bewijs dat crashherstel werkt voordat u de agent zelfstandig laat werken

Test een onderbreking van een uitrol nadat de externe dienst het verzoek heeft geaccepteerd, maar voordat de agent het resultaat opslaat. Dat is een betere test voor duurzaam herstel dan een inactief proces stoppen en controleren of de berichten weer verschijnen.

De officiële voorbeelden in packages/durable/test/examples zijn het beste startpunt: ze volgen de API nauwkeuriger dan een blogpost kan. Test daarmee uw gekozen workflow en voeg vervolgens storingen toe rond de externe effecten ervan.

Pi Durable past bij langdurige programmeertaken, gestructureerde planners, triage op basis van webhooks en beheerworkflows met expliciete herstelregels. Gebruik het niet voor eenmalige scripts, stateless chat of een team dat dit kwartaal een stabiele API nodig heeft.

U blijft zelf verantwoordelijk voor modeltoegangsgegevens, tools, de gebruikersinterface, back-ups en opschoning van de opslag, procesbewaking en beveiliging tegen ongewenste externe acties. De documentatie beschrijft ook hoe u de opslag aanpast voor Bun of een Cloudflare Durable Object; die integraties vereisen configuratie.

Implementatiechecklist

• Installeer met --save-exact en neem daarna package.json en het lockfile op in versiebeheer.
• Bepaal voor elke tool of herhaling veilig is of dat onderbrekingen apart moeten worden afgehandeld, voordat u onbeheerde uitvoering inschakelt.
• Dien hetzelfde webhookevent twee keer in met dezelfde requestId en controleer of dit de bestaande Submission oplevert.
• Herstart het proces tijdens een modelbeurt en een toolaanroep; controleer of harness.resume het werk vanuit de persistente database hervat.
• Onderbreek één externe schrijfbewerking nadat deze is geaccepteerd en controleer vervolgens of het herstelproces de uitkomst vaststelt zonder de bewerking blind te herhalen.

Nuttige bronnen

• Officiële Pi-website - De Pi-agent en het project.
• Aankondiging van Pi Durable - Ontwerp, toepassingsgebied en experimentele status.
• Officiële Pi-repository - De README van Pi Durable en voorbeelden in packages/durable/test/examples.
• SQLite - De database achter de aanbevolen opslagbackend.
• systemd - Procesbewaking onder Linux.

Waar het op neerkomt

Pi Durable maakt het mogelijk om onderbroken werk te hervatten, maar de afspraken rond uw tools bepalen of dat veilig gebeurt. Begin met één agent met een afgebakende taak, persistente SQLite-opslag en een gerichte crashtest rond de meest risicovolle externe actie. Geef de agent pas meer autonomie als die test een verklaarbaar resultaat oplevert.