Atomic Transactions

Tool calls and state writes wrapped in ACID semantics. Failures rollback. Retries are deterministic.

Problem

Agents execute multi-step workflows: call a search tool, invoke an LLM, write results to a database. If the LLM times out after the tool runs, retry logic executes the tool again, causing duplicate API calls, double charges, or inconsistent state. There is no atomic boundary.

Neusnap Approach

Neusnap wraps workflows in a transaction. Tool calls and state writes are staged in a buffer. The LLM runs. If everything succeeds, the transaction commits atomically. If any step fails, the buffer is discarded and retries start from a clean slate. Tool results are cached so retries do not re-execute tools.

Example

import { Neusnap } from "@neusnap/sdk";

const neusnap = new Neusnap({ apiKey: process.env.NEUSNAP_API_KEY });

// Atomic transaction
const result = await neusnap.transaction(async (tx) => {
  // Tool call (cached on retry)
  const searchResults = await tx.tool("search", {
    query: "AI agent frameworks",
  });

  // LLM invocation with routing
  const summary = await tx.llm({
    model: "auto", // Token triage
    prompt: `Summarize these results: ${searchResults}`,
  });

  // State write (buffered until commit)
  await tx.writeState("lastSummary", summary);
  await tx.writeState("timestamp", Date.now());

  return summary;
});

// Automatic commit on success, rollback on failure
console.log(result);

Handling Partial Failures

Neusnap guarantees that partial failures do not corrupt state. If the LLM times out, tool results remain cached but state writes never reach the database. Retries see the cached tool output and proceed from there, ensuring exactly-once semantics for side effects.

Failure Scenarios

What's Guaranteed