Teaching an agent to spend money safely

Notebook summary

The whole lesson, compressed for copying by hand. Every point below is unpacked in the Detailed Notes.

Detailed study notes

A support system runs flawlessly for three months. It reads customer records, searches a knowledge base, classifies tickets — ten thousand a day, every action read-only, never a wrong move. Then one sprint adds a single capability: the agent can now issue partial refunds through the payment API when it confirms a billing error. It ships Tuesday. By Thursday the billing team notices forty-seven customers were refunded twice, roughly twenty-three thousand dollars gone, over forty-eight hours. No attacker. No bug in the refund logic. The agent did exactly what it was designed to do. What it lacked was the discipline that write access quietly demands — and that discipline is the whole of this lesson.

2.1Reading is free. Writing has consequences.

A read can be repeated harmlessly; a write cannot. This is the asymmetry every write-capable agent is built on. Everything you have wired up so far — pulling a record from Mongo, running a text-to-SQL query, classifying a ticket — is a read. Reads are idempotent: run one five times and you get the same answer five times and the system on the other end is untouched. That is a plain-English way of saying an operation you can safely repeat.

Writes break that promise. The formal test: an operation is idempotent only if executing it N times leaves exactly the same system state as executing it once. An HTTP GET passes — five identical GETs, same data, no change. An HTTP POST fails — five identical POSTs typically create five records, charge five times, send five notifications.

2.2Write amplification and the stuttering agent

Write amplification is when an agent fires the same write more times than it meant to — with no logic bug and no malformed call. The decision was right and the request was well-formed; the execution layer simply lacked the control to stop a duplicate. The behavioral name for the agent doing this is the stuttering agent: it repeats itself not from malice but because it never heard a clear confirmation that the first attempt was received.

Here is the precise causal chain, because you'll want to recognize it on sight. The agent decides an engineering escalation is needed and calls create_github_issue. GitHub is under peak load, so the API takes 6 seconds. The LangGraph tool node is configured with a 5-second timeout. At 5s it gives up and returns a timeout message to the agent. The agent's working memory is just its message history, and that history now reads "attempt, then timeout" — indistinguishable from a genuine failure. It reasons, "my call failed, I should retry," and fires the identical call again. Both calls eventually succeed. Two identical issues exist. The agent only ever saw the second success, reports one issue, and the first sits in the repo as a ghost: no owner, no reference from the app, invisible to the normal resolution flow.

Three factors must all be controlled — fixing one or two is not enough for production safety:

2.3Idempotency keys — the shield

An idempotency key is a unique, deterministic name for one logical write, sent alongside the request so the API can recognize a repeat. The external API stores the key together with the result of processing it. If a later request arrives carrying the same key, the API returns the stored result instead of doing the work again. That single mechanism is what turns "fired twice" into "fired once, acknowledged twice."

To be correct the key must satisfy two properties at the same time:

LangGraph hands you a natural base for this: the thread_id, which is unique per conversation and stable across retries within it. That satisfies both properties — until a single thread legitimately needs several issues (one complex ticket touching multiple components). So the key must also encode the content of the specific operation, not just the thread. The standard recipe hashes all three together:

import hashlib

def generate_idempotency_key(thread_id: str, title: str, body: str) -> str:
    """Deterministic key for one logical write.
    Same inputs -> same key (retries collapse); different op -> different key."""
    payload = f"{thread_id}:{title}:{body}".encode("utf-8")
    return hashlib.sha256(payload).hexdigest()

2.4Not every write is equally dangerous

Classify each write by how reversible it is, then spend controls in proportion. A system that slaps maximum controls on everything wastes effort on cheap operations and, worse, tends to under-protect the expensive ones. The fix is a risk-proportionate taxonomy with three tiers and escalating requirements.

2.5Zero-trust: the model never touches the keys

Give the LLM exactly what it needs to decide the call, and nothing else — never credentials. The semantic arguments (issue title, body, repo label, the idempotency key) are the model's domain. The authentication that says who is allowed to perform the operation is the Python runtime's domain. These two concerns must never cross.

Why non-negotiable: an LLM's inputs and outputs are logged everywhere. A single tool call lands in the LangChain callback trace, the LangSmith run tree, the persisted checkpoint state, and the provider's own request logs. A token passing through those tool arguments has been written to at least four storage systems, any of which could leak it. A key that passes through an LLM call is a compromised key — not immediately, but inevitably.

import os

# Injected by the runtime at MODULE LOAD, never passed through the LLM.
GITHUB_TOKEN = os.getenv("GITHUB_ACCESS_TOKEN")
if not GITHUB_TOKEN:
    # Fail at startup / in CI, not on a user's ticket at 3am.
    raise RuntimeError("GITHUB_ACCESS_TOKEN not set; refusing to start.")

2.6Anatomy of a production write tool

A production-grade write tool has five parts, each doing one job. This is the same tool-calling pattern you already know, tightened for a write. The parts: the @tool decorator, the docstring, the Pydantic argument schema, the function body with runtime credential injection, and the structured return value.

The docstring is not developer documentation — it is the specification the LLM reads to decide whether and how to call the tool. For a write tool it must carry three things: what the tool does in imperative form, when to call it, and the exact return format on success and failure. The Pydantic schema earns its place two ways: it validates argument types before the API call fires (a malformed key is rejected up front), and its per-field descriptions are what the LLM reads while constructing the values.

from langchain_core.tools import tool
from pydantic import BaseModel, Field

class CreateIssueArgs(BaseModel):
    title: str = Field(description="Short imperative summary of the bug.")
    body: str = Field(description="Structured technical description of the issue.")
    idempotency_key: str = Field(
        description="32+ char hex string uniquely identifying this request."
    )

@tool(args_schema=CreateIssueArgs)
def create_github_issue(title: str, body: str, idempotency_key: str) -> str:
    """Create a GitHub issue in the engineering bug-tracker repository.

    Call ONLY when knowledge-base search returned no applicable resolution
    for a confirmed technical issue needing engineering intervention.
    Do NOT call for billing questions, account questions, or fraud reports.

    On success return JSON with: issue_number, issue_url, repository,
    created_at, idempotency_key, success=true.
    On failure return JSON with: success=false, error_type, message.
    """
    ...  # body follows in 2.7

2.7The void problem — writes must return metadata

A write that returns only "success" throws its result into a void. The operation happened, the system mutated, but the agent, the synthesizer, and any downstream consumer learn nothing about what was created, where to find it, or how to reference it. This bites hardest for operations that create addressable resources — things with an id and a URL a user could open. GitHub assigned an issue number and a full URL; if the tool returns "issue created successfully," that information is discarded before it can be used. The user can't navigate to it, the synthesizer can't cite it, the audit log can't record which issue, and a later attempt can't detect it already exists.

from github import Github, GithubException
import os, json

def create_github_issue(title, body, idempotency_key):
    try:
        repo = Github(GITHUB_TOKEN).get_repo(os.getenv("GITHUB_REPO"))
        issue = repo.create_issue(title=title, body=body)
        return json.dumps({                       # structured metadata, no void
            "success": True,
            "issue_number": issue.number,
            "issue_url": issue.html_url,
            "repository": repo.full_name,
            "created_at": issue.created_at.isoformat(),
            "idempotency_key": idempotency_key,
        })
    except GithubException as e:
        transient = e.status in (500, 502, 503)   # retryable vs permanent
        return json.dumps({
            "success": False,
            "error_type": "transient" if transient else "permanent",
            "status": e.status,
            "message": str(e.data),
        })

2.8Error handling and graceful degradation

A write tool must sort failures into "retry" and "don't," and always leave the user with something useful. External APIs fail in kinds: some are transient (a brief server overload that clears in seconds), some are permanent (an auth failure that needs a config change), and some are in between (a validation error the agent can fix and re-send). Treating them alike is how you get an infinite loop — retrying a 401 forever will only produce another 401.

Graceful degradation is the guarantee that when the write fails, the user still gets a useful response — not that failures are hidden. A support system that crashes or dumps a raw error when GitHub is briefly down has failed its user twice: once because the issue wasn't created, and again because they got no idea what happened or what to do. The correct degraded response for a failed issue creation has four parts:

2.9Two guards, and the confidence marker

The internal state guard and the server-side idempotency key are complementary, not redundant — they defend different failures. The guard checks the agent's own prior findings before it even constructs a retry, so it stops the stuttering failure (a deliberate retry after reading a timeout) and saves the network round-trip entirely. The server key stops concurrent double-fires — two calls reaching GitHub at once, e.g. under parallel execution — that a local guard would miss. First line of defense and last line of defense.

2.10Interview & practice Q&A

2.11Key takeaways

• Reads are idempotent and consequence-free; writes are not, and their damage scales with how many times they fire.
• Write amplification comes from correct components combining badly — the classic trigger is a tool timeout set below the API's response time.
• Fix it with a deterministic idempotency key (SHA-256(thread_id:title:body)), never a timestamp or UUID.
• Spend controls in proportion to irreversibility: T1 key+return+log, T2 adds human confirm, T3 adds a hard approval graph node and signing.
• The LLM handles semantic args only; credentials are injected by the runtime at module load and validated there.
• Return structured metadata — never let a write vanish into the void.
• Separate transient from permanent errors, degrade gracefully in four moves, and layer an internal guard with a server key.

Microexercises

Reading proves you recognize the pattern. These prove you can build it. Attempt each before opening the walkthrough.

3.1Diagnose it — the write that fires twice

import uuid
from langchain_core.tools import tool

TOOL_TIMEOUT = 3  # seconds

@tool
def create_github_issue(title: str, body: str) -> str:
    key = str(uuid.uuid4())          # "idempotency" key
    return github_api.create_issue(title, body, idempotency_key=key,
                                   timeout=TOOL_TIMEOUT)

import hashlib
from langchain_core.tools import tool

TOOL_TIMEOUT = 10  # > p99 (5s) + buffer

@tool
def create_github_issue(title: str, body: str, thread_id: str) -> str:
    # deterministic: a retry recomputes the identical key
    key = hashlib.sha256(f"{thread_id}:{title}:{body}".encode()).hexdigest()
    return github_api.create_issue(title, body, idempotency_key=key,
                                   timeout=TOOL_TIMEOUT)

3.2Build it — the key and the guard

import hashlib

def generate_idempotency_key(thread_id: str, title: str, body: str) -> str:
    payload = f"{thread_id}:{title}:{body}".encode("utf-8")
    return hashlib.sha256(payload).hexdigest()

def guard(state: dict, key: str) -> str | None:
    for f in state.get("findings", []):
        if f.get("success") and f.get("idempotency_key") == key:
            return f["issue_url"]        # reuse; do NOT call the API
    return None

# usage inside the agent, before firing the tool
key = generate_idempotency_key(thread_id, title, body)
existing = guard(state, key)
if existing:
    return f"Issue already exists: {existing}"
# else: fall through to create_github_issue(title, body, key)