{
  "id": 10415837,
  "title": "Designing Idempotent Side-Effect Contracts for AI Agents",
  "url": "https://urgent.news/2026/09/28/designing-idempotent-side-effect-contracts-for-ai-agents",
  "topic": "ai",
  "section": "AI",
  "published": "2026-09-28T09:00:20.000Z",
  "source": {
    "name": "HackerNoon",
    "slug": "hackernoon",
    "url": "https://hackernoon.com/designing-idempotent-side-effect-contracts-for-ai-agents?source=rss"
  },
  "original_language": "en",
  "account": "When an AI agent uses a payment provider, it sends a refund request. If the response is lost during a network timeout, the runtime retries the request. The agent's trace shows that both refund attempts succeed, but the customer ends up with two refunds. This example shows a common issue in distributed systems - how to distinguish an unsuccessful response from an unsuccessful effect.\n\nTo address this problem, the runtime needs a tool contract that clearly defines the behavior of a tool. The contract specifies whether the tool is read-only, an idempotent write, a deduplicated write, or a non-repeatable write. This distinction matters when an agent can change the world, such as sending a message, creating a ticket, issuing a credit, booking a trip, deleting a record, or triggering a deployment.\n\nDevelopers often describe a tool with an input and output schema, but this schema only validates the shape of the data, not the behavior. The tool contract should focus on the intended business effect, not just the response status code. The Model Context Protocol includes tool annotations like readOnlyHint, destructiveHint, and idempotentHint, but these are just untrusted hints, not security or correctness guarantees.\n\nA runtime still needs to enforce its own policy about retry behavior. The key is to define the side-effect contract as part of the tool definition, rather than scattering it across prompts and catch blocks. By doing this, we can create a more reliable and predictable tool behavior.",
  "summary": "A timed-out agent tool may already have changed the world. Design explicit side-effect contracts, idempotency, reconciliation, and safe recovery.",
  "key_points": [],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}