AI-agenter · Lektion

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.

Lektion 1 av 414 steg

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.

Gratis att börja

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

  1. Idempotenta verktyg och sidoeffekter
  2. Omförsök med exponentiell backoff
  3. Tidsgränser och circuit breakers
  4. Validera verktygsutdata (Pydantic)
← Tillbaka till AI-agenter