Idempotenta verktyg och sidoeffekter
En agent kan göra om ett anrop – utforma verktygen så att två anrop inte leder till dubbel debitering eller dubbla e-postmeddelanden.
Idempotenta verktyg och sidoeffekter är en gratis lektion i AI-agenter på CoddyKit. Detta är lektion 1 av 4. Ni kan läsa hela lektionen gratis nedan och sedan öva praktiskt i webbläsaren med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt. Den ingår i lärvägen för AI-agenter, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i AI-agenter innehåller totalt 4 lektioner.
Varför idempotens är viktigt
En agentloop kan försöka igen. Om ett verktyg skickar ett e-postmeddelande eller debiterar ett kreditkort leder ett nytt försök till att åtgärden utförs två gånger. Idempotens gör att "gör X igen" blir en no-op när X redan har hänt.
Vad är idempotens?
En operation är idempotent om N anrop ger samma effekt som ett enda anrop. Exempel:
- "Ställ in användarens status på aktiv" — idempotent (att ställa in den på aktiv igen gör ingenting)
- "Öka räknaren med 1" — INTE idempotent (varje anrop lägger till ytterligare 1)
Idempotensnycklar
För icke-idempotenta operationer (betalningar, e-post) använder du idempotensnycklar:
import uuid
def create_payment(amount, idempotency_key):
# Stripe accepts this header — returns the existing payment if key was used
return stripe.Charge.create(
amount=amount,
currency='usd',
source=token,
idempotency_key=idempotency_key
)Generera nycklar från avsikten
Använd en hash av (tool_name, arguments, run_id) så att identiska omförsök använder samma nyckel:
import hashlib, json
def intent_key(tool_name, args, run_id):
payload = json.dumps([tool_name, args, run_id], sort_keys=True)
return hashlib.sha256(payload.encode()).hexdigest()
print(intent_key('transfer_money', {'to': 'acc2', 'amount': 100}, 'run-1'))
Inventering av sidoeffekter
Lista vilka verktyg som har sidoeffekter:
- SEND e-post / SMS
- CHARGE / refund
- CREATE / DELETE databasrader
- POST till externa API:er som ändrar tillstånd
Verktyg som bara läser är automatiskt idempotenta. Fokusera på skrivningarna.
Omslut verktyg med sidoeffekter
Lägg till ett idempotenslager i verktygets implementation:
def send_email(to, subject, body, run_id):
key = intent_key('send_email', {'to': to, 'subject': subject, 'body': body}, run_id)
if redis.set(f'sent:{key}', 1, nx=True, ex=86400):
smtp.send(to, subject, body)
return {'sent': True}
return {'sent': False, 'reason': 'already-sent'}Bekräfta innan åtgärden utförs
För åtgärder med stora konsekvenser lägger du till ett bekräftelsesteg:
def transfer_money(from_acc, to_acc, amount, confirmed=False):
if not confirmed:
return {'pending': True, 'msg': 'Call again with confirmed=True to proceed.'}
return {'pending': False, 'msg': f'Transferred {amount} from {from_acc} to {to_acc}.'}
print(transfer_money('acc1', 'acc2', 100))
print(transfer_money('acc1', 'acc2', 100, confirmed=True))
Tvåfasverktyg
Dela upp verktyg i faserna "draft" och "commit":
def draft_email(to, subject, body):
draft_id = save_draft(to, subject, body)
return {'draft_id': draft_id, 'preview': body[:200]}
def send_draft(draft_id):
return smtp.send(load_draft(draft_id))Kompenserande åtgärder
Om du inte kan undvika en sidoeffekt definierar du ett "undo"-verktyg:
def refund_payment(payment_id):
return stripe.Refund.create(payment=payment_id)
# Now an erroneous create_payment can be undone.Granskningsloggar
Varje verktyg med sidoeffekter MÅSTE logga: vem som utlöste det, vilka argument som användes, när det skedde och resultatet. Använd strukturerade loggar som du kan söka i senare.
Budget för sidoeffekter per körning
Begränsa antalet sidoeffekter per körning som ett extra skyddsnät:
if state.side_effect_count >= 5:
return {'error': 'Side-effect budget exhausted for this run.'}Dry-run-läge
Användbart under utveckling: verktyg loggar vad de SKULLE göra, men utför det inte i verkligheten:
import os
os.environ['DRY_RUN'] = '1'
DRY_RUN = os.getenv('DRY_RUN') == '1'
def send_email(to, subject, body):
if DRY_RUN:
print(f'would send email to {to}')
return {'sent': False, 'dry_run': True}
print(f'sending email to {to}')
return {'sent': True, 'dry_run': False}
result = send_email('user@example.com', 'Hi', 'Hello there')
print(result)
Definition
Vad innebär "idempotent" för ett verktyg?
Sammanfattning
Identifiera sidoeffekter. Använd idempotensnycklar. Bygg tvåfasverktyg och kompenserande åtgärder. Granska allt. Använd dry-run i utvecklingsmiljön.
Lär dig AI-agenter med en AI-lärare – gratis
Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.
- Kurser
- 60
- Lektioner
- 239
Vanliga frågor
Är lektionen ”Idempotenta verktyg och sidoeffekter” gratis?
Ja – hela texten till ”Idempotenta verktyg och sidoeffekter” kan läsas gratis här på webben. Om Ni vill öva interaktivt med en inbyggd kodredigerare och en AI-handledare som är tillgänglig dygnet runt och låsa upp resten av kursen i AI-agenter, kan Ni uppgradera till CoddyKit PRO. Kursen i AI-agenter innehåller totalt 4 lektioner.
Vad lär jag mig i ”Idempotenta verktyg och sidoeffekter”?
En agent kan göra om ett anrop – utforma verktygen så att två anrop inte leder till dubbel debitering eller dubbla e-postmeddelanden. Ni övar på AI-agenter med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.
Behöver jag någon erfarenhet för att börja lära mig AI-agenter?
Du behöver inga förkunskaper. Utbildningen i AI-agenter på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 1 av 4.
Hur lång tid tar lektionen ”Idempotenta verktyg och sidoeffekter”?
De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.
Kan jag skriva och köra kod i den här AI-agenter-lektionen?
Ja. Varje AI-agenter-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.
Alla lektioner i den här kursen
- Idempotenta verktyg och sidoeffekter
- Omförsök med exponentiell backoff
- Tidsgränser och circuit breakers
- Validera verktygsutdata (Pydantic)