べき等なツールと副作用
エージェントは再試行する可能性があります。2回呼び出しても二重請求や二重メール送信が起きないようツールを設計します。
「べき等なツールと副作用」はCoddyKit上の無料AI Agentsレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはAI Agents学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Agentsコースには全4レッスンが含まれています。
冪等性が重要な理由
エージェントのループでは、リトライが発生する可能性があります。ツールがメールを送信したりクレジットカードに課金したりする場合、リトライするとアクションが重複します。冪等性があれば、Xがすでに実行されているときに「もう一度Xを実行する」ことが何もしない処理になります。
冪等性とは
操作をN回呼び出したときの効果が、1回だけ呼び出したときと同じであれば、その操作は冪等です。例：
- 「ユーザーのステータスをactiveに設定する」— 冪等です（activeに再設定しても何も起こりません）
- 「カウンターを1増やす」— 冪等ではありません（呼び出すたびにさらに1増えます）
冪等性キー
冪等でない操作（決済やメール送信など）には、冪等性キーを使用します。
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
)意図からキーを生成
(tool_name, arguments, run_id)のハッシュを使用すると、同一のリトライで同じキーを再利用できます。
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'))
副作用の一覧を作成
どのツールに副作用があるかを一覧にします。
- SENDによるメール／SMSの送信
- CHARGE／refund
- データベース行のCREATE／DELETE
- 状態を変更する外部APIへのPOST
読み取り専用のツールは本質的に冪等です。書き込みに注目します。
副作用のあるツールをラップ
ツールの実装に冪等性レイヤーを追加します。
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'}実行前に確認する
影響の大きいアクションには、確認ステップを追加します。
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))
2フェーズのツール
ツールを「draft」フェーズと「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))補償アクション
副作用を避けられない場合は、「undo」ツールを定義します。
def refund_payment(payment_id):
return stripe.Refund.create(payment=payment_id)
# Now an erroneous create_payment can be undone.監査ログ
副作用のあるすべてのツールで、実行者、引数、実行時刻、結果を必ずログに記録します。後から検索できる構造化ログを使用します。
実行ごとの副作用予算
安全策として、1回の実行で発生できる副作用の数に上限を設けます。
if state.side_effect_count >= 5:
return {'error': 'Side-effect budget exhausted for this run.'}ドライランモード
開発中に役立ちます。ツールが実行するはずの内容をログに記録しますが、実際には実行しません。
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)
定義
ツールにおいて「冪等」とは何を意味しますか。
まとめ
副作用を特定します。冪等性キーを使用します。2フェーズのツールと補償アクションを構築します。すべてを監査します。開発時にはドライランを使用します。
よくある質問
「べき等なツールと副作用」レッスンは無料ですか？
はい。「べき等なツールと副作用」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Agentsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Agentsコースには全4レッスンが含まれています。
「べき等なツールと副作用」で何を学びますか？
エージェントは再試行する可能性があります。2回呼び出しても二重請求や二重メール送信が起きないようツールを設計します。 ブラウザで直接実行するハンズオンコードでAI Agentsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
AI Agentsを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのAI Agentsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「べき等なツールと副作用」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このAI Agentsレッスンでコードを書いて実行できますか？
はい。すべてのAI Agentsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。