AI Agents · 课时

幂等工具与副作用

Q: 「幂等工具与副作用」这节课中我会学到什么？

智能体可能会重试——请设计工具，使调用两次不会造成重复扣费或重复发送邮件。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

智能体可能会重试——请设计工具，使调用两次不会造成重复扣费或重复发送邮件。

幂等工具与副作用 是 CoddyKit 上的免费 AI Agents 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

幂等性为何重要

代理循环可能会重试。如果工具发送电子邮件或扣除信用卡费用，重试会重复执行操作。幂等性使“再次执行 X”在 X 已经发生时变成空操作。

什么是幂等性

如果某个操作调用 N 次产生的效果与调用一次相同，那么该操作就是幂等的。示例：

“将用户状态设置为 active”——幂等（再次设置为 active 不会产生任何变化）
“将计数器增加 1”——NOT 幂等（每次调用都会再增加 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
    )

根据意图生成键

使用（工具名称、参数、运行 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 / 退款
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))

两阶段工具

将工具拆分为“草稿”和“提交”两个阶段：

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

补偿操作

如果无法避免副作用，请定义一个“撤销”工具：

def refund_payment(payment_id):
    return stripe.Refund.create(payment=payment_id)
# Now an erroneous create_payment can be undone.

审计日志

每个具有副作用的工具 MUST 记录：触发者、参数、时间和结果。请使用以后可以查询的结构化日志。

每次运行的副作用预算

限制每次运行产生的副作用，作为安全保障：

if state.side_effect_count >= 5:
    return {'error': 'Side-effect budget exhausted for this run.'}

试运行模式

在开发过程中非常有用：工具记录它们 WOULD 执行的操作，但实际上不执行：

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)

定义

对于工具来说，“幂等”是什么意思？

回顾

识别副作用。使用幂等键。构建两阶段工具和补偿操作。审计所有操作。在开发环境中使用试运行。

常见问题解答

「幂等工具与副作用」课时是免费的吗？

是的 — 「幂等工具与副作用」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「幂等工具与副作用」这节课中我会学到什么？

智能体可能会重试——请设计工具，使调用两次不会造成重复扣费或重复发送邮件。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「幂等工具与副作用」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents