Letting an Agent Change the World Safely

Notebook Summary

Hand-copyable revision sheet. Fully derivable from the detailed notes below.

Detailed Study Notes

A support agent runs read-only for three months, handling 10,000 tickets a day. Flawless. One sprint, the team gives it a single new power: issue partial refunds through the payment gateway when a billing error is confirmed. It deploys Tuesday morning. By Thursday afternoon the billing team spots something odd — 47 customers received double refunds over the last 48 hours, roughly $23,000 gone. No attacker. No bug in the refund logic. The agent behaved exactly as designed. What it lacked was the engineering discipline that writing to the world demands.

That is this whole lesson. We will build up the controls on a deliberately low-stakes write — creating a GitHub issue — then see how the same patterns harden the operations that can actually hurt you.

2.1 · A read costs time; a write costs consequences

An operation is idempotent when doing it many times leaves the system in exactly the same state as doing it once. Reads are idempotent by nature: ask for a customer's balance five times and you get the same number five times, and nothing in the world changed. Writes usually are not: submit the same refund five times and you have debited — or credited — five times.

In HTTP terms, GET is idempotent and POST is not. This asymmetry decides how a failure hurts you.

2.2 · The stuttering agent: write amplification

Write amplification is when an agent fires the same write more times than intended. It is worth being precise about what it is not: not a wrong decision (a logic bug), not a malformed request (an integration bug). The agent made the right call and formed the request correctly — the execution layer simply lacked the control to stop a duplicate from firing. The nickname is the stuttering agent: it repeats itself not from malice or error, but because it never heard confirmation that the first attempt landed.

Here is the exact chain, because every link matters. LLM agents are unusually exposed to this: an inference step in a production loop already takes seconds, and the external write API adds its own latency — seconds under normal load, longer at peak (think a sale day when everyone is checking out at once).

1. The agent decides to create a GitHub issue (engineering escalation).
2. GitHub is under peak load; the real response takes 6 seconds.
3. The LangGraph tool node has a default 5-second timeout. It sees silence and returns a timeout message to the agent.
4. The agent's working memory is its message history. It reads "attempt → timeout" and cannot tell a genuine failure from a slow success. It reasons: "that failed, try again."
5. It calls the tool again with identical arguments. Both GitHub calls complete. Two identical issues now exist.

The cruel part: the agent only ever sees the second success and reports one issue URL to the user. The first issue is a ghost — sitting in the repo with no owner, no reference from the application, no log of its existence, so the normal workflow will never close it.

Three things conspire, and you have to fix all three — defence in depth. Fixing one or two is not enough for production.

2.3 · Not every write carries the same risk

Match the controls to how hard the write is to undo. Applying maximum controls to every write wastes effort on the harmless ones and, worse, tempts you to under-protect the dangerous ones. The discipline is a risk-proportionate taxonomy: classify each write by reversibility, then apply the minimum controls that make that tier production-safe.

2.4 · Zero trust: the model never touches a credential

Give the LLM exactly the information it needs to make a correct tool decision, and nothing else. In practice that is an absolute rule: the model never sees API keys, tokens, or secrets of any kind. Split the concerns cleanly — the semantic arguments (issue title, body, repository label) are the model's domain; the authentication (who is allowed to perform this) is the Python runtime's domain. These two never cross.

So the credential is read from the environment at module load time, never passed as a function argument and never in the tool's signature.

import os

# Read ONCE, at import time. If it's missing, the service fails to
# start — the deploy pipeline catches it, not a user at 2am.
GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
if not GITHUB_TOKEN:
    raise RuntimeError("GITHUB_TOKEN is not set; refusing to start.")

# The token is captured here in the runtime's scope. It is NEVER a
# parameter of the tool the LLM calls, so it can never appear in a
# tool-call argument, a trace, or a checkpoint.

2.5 · A production write tool has five parts

Every serious write tool is built from the same five pieces, each doing a distinct job: the @tool decorator, a docstring, a Pydantic argument schema, a function body with runtime credential injection, and a structured return value.

The docstring is not developer documentation — it is the tool's specification for the model, so it must carry three things: what the tool does (imperative), when to call it, and the exact shape of the return value on success and on failure. The Pydantic schema earns its place two ways: it type-validates arguments before the API is ever touched (a malformed key is rejected with a clear error, not a failed API call), and its field descriptions are what the model reads while filling the arguments in.

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

class CreateIssueArgs(BaseModel):
    title: str = Field(description="Short, specific issue title.")
    body: str = Field(description="Structured description of the technical problem.")
    idempotency_key: str = Field(
        description="32-char hex uniquely identifying THIS logical request."
    )

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

    Call this ONLY when the knowledge base returned no resolution for a
    confirmed technical issue needing engineering. Do NOT call it for
    billing questions, account questions, or fraud reports.

    On success returns: success, issue_number, issue_url, repository,
    created_at, idempotency_key.
    On failure returns: success=False, error_type, message.
    """
    ...  # body uses the module-level GITHUB_TOKEN; see 2.4

Finally, bind each agent only to the tools it is authorised to use — tool scope isolation. The triage agent classifies tickets and has no business creating issues; the fraud agent has no business querying the bug tracker; the synthesizer has no tools at all.

2.6 · The idempotency key

An idempotency key is a unique, deterministic identifier for one logical operation, sent to the API alongside the write. The API stores the key 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 is the whole mechanism — and note it is something we design, not a magic LLM behaviour.

To be correct, a key must satisfy two properties at once:

LangGraph hands you a natural base: the thread_id. It is unique per conversation (uniqueness across threads) and stable for every call within that thread (determinism on retry). When one thread might legitimately create several issues — a complex ticket touching multiple components — fold the operation's content into the key too.

import hashlib

def generate_idempotency_key(thread_id: str, title: str, body: str) -> str:
    """Same inputs -> same key (deterministic). Different content ->
    different key (unique per logical op). A retry reproduces it exactly."""
    raw = f"{thread_id}|{title}|{body}"
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()

The anti-patterns all fail one of the two properties — learn to spot them on sight in review.

# WRONG — non-deterministic; a retry never matches the original
key = str(uuid.uuid4())                 # random every call
key = datetime.now().isoformat()        # different every millisecond

# RIGHT — deterministic hash of the logical operation's content
key = generate_idempotency_key(thread_id, title, body)

2.7 · Two lines of defence, not one

The internal state guard and the server-side idempotency key defend against different failures, so you keep both. They look redundant; they are complementary.

def github_tool_node(state: dict) -> dict:
    draft = state.get("github_draft")
    if not draft:
        return {"github_issue_url": ""}          # nothing to do

    # 1st line of defence: has this thread already produced the issue?
    for f in state.get("findings", []):
        if f.get("agent_finding_type") == "github_issue_created":
            return {"github_issue_url": f["issue_url"]}   # reuse, don't refire

    key = generate_idempotency_key(THREAD_ID, draft["title"], draft["body"])
    return create_github_issue.invoke({**draft, "idempotency_key": key})

2.8 · The void problem: a write must hand something back

A write that returns only "success" throws its own output into a void. A bare 200 tells the agent the mutation happened but nothing about what was created, where to find it, or how to reference it later. The problem bites hardest for operations that create addressable resources — things with an id and a URL a user could open.

If the tool returns "issue created successfully" and stops, that information is gone: the user can't navigate to the issue, the synthesizer can't cite it in the final answer, the audit log can't record which issue was created, and on a re-attempt the system can't even detect the issue already exists.

return {
    "success": True,
    "issue_number": issue.number,          # int, unique in the repo
    "issue_url": issue.html_url,            # full URL the user can open
    "repository": "owner/repo",             # confirms where it landed
    "created_at": issue.created_at.isoformat(),   # ISO 8601, audit timeline
    "idempotency_key": idempotency_key,     # ties response to THIS op
}

[!] The session framed this as "five fields" (the resource metadata) and then added success on top — so the return dict actually carries six. Memorise all six.

2.9 · Errors: know which ones to retry

A production write tool must sort failures into "retry" and "don't retry," because getting it wrong is catastrophic. Retry a transient blip and you recover; retry an authentication failure and you spin an infinite loop against a wall.

try:
    issue = repo.create_issue(title=title, body=body)
except GithubException as e:
    if e.status in (401, 403):
        return {"success": False, "error_type": "authentication_failure",
                "message": "Token invalid or lacks permission.", "retry": False}
    if e.status == 404:
        return {"success": False, "error_type": "not_found",
                "message": f"Repository {REPO} not found.", "retry": False}
    if e.status == 422:
        return {"success": False, "error_type": "validation_error",
                "message": str(e.data), "retry": True}   # fix field, retry
    return {"success": False, "error_type": "server_error",
            "message": "Transient failure.", "retry": True}   # 5xx / timeout

A good degraded response has four parts:

1. Acknowledge the technical issue can't be resolved immediately.
2. Still deliver the full technical diagnosis the analysis agent produced — that work shouldn't be lost just because escalation is briefly unavailable.
3. Say plainly that automatic escalation was attempted and is temporarily unavailable.
4. Give the user a concrete next action (contact support directly, quote the ticket's thread ID, ask for engineering escalation).

Findings and the confidence = 1.0 rule

Both outcomes are written into the graph's shared state as a finding, and each carries confidence: 1.0.

# success
{"agent_finding_type": "github_issue_created",
 "issue_number": 412, "issue_url": "...", "repository": "owner/repo",
 "created_at": "2026-09-01T...", "idempotency_key": "...", "confidence": 1.0}

# failure
{"agent_finding_type": "github_issue_error",
 "error_type": "network_error", "message": "...", "confidence": 1.0}

2.10 · The whole pipeline

Every ticket flows through the same graph. Personally-identifying data is masked up front; only technical tickets ever reach the write tool, and only high/critical findings populate a draft.

Interview & practice questions

Key takeaways

1. Reads are idempotent and cost time; writes are not and cost consequences. Treat the distinction as a correctness and liability problem.
2. Write amplification comes from correct calls firing twice, not from bugs — the "stuttering agent." Fix the retry, the duplication-awareness, and the state-check together.
3. Set the tool timeout above the API's max response time plus a buffer; timing out early and retrying is what creates duplicates.
4. Scale controls with irreversibility across three tiers; a Tier 3 write needs a hard approval node in the graph.
5. The model never sees a credential. Inject it at module load, keep it out of every argument and log.
6. An idempotency key must be unique per logical op and deterministic — a content hash, never a UUID or timestamp.
7. Keep both defences: an internal state guard for retries, a server-side key for concurrency.
8. Return structured metadata, not a bare success, and sort errors into retry / don't-retry. Degrade so the user always has a next step.

Microexercises

Attempt each before opening the walkthrough. Runnable in your head or a scratch file.

3.1 · Build the idempotency key

import hashlib

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

assert make_key("t1", "A", "B") == make_key("t1", "A", "B")   # deterministic
assert make_key("t1", "A", "B") != make_key("t1", "A", "C")   # content-sensitive

3.2 · Diagnose the double write

import uuid

def github_node(state):
    draft = state["github_draft"]
    key = str(uuid.uuid4())            # "unique" key per call
    return create_github_issue.invoke(
        {**draft, "idempotency_key": key}
    )

def github_node(state):
    draft = state["github_draft"]

    # 1st line: already created on this thread? reuse it.
    for f in state.get("findings", []):
        if f.get("agent_finding_type") == "github_issue_created":
            return {"github_issue_url": f["issue_url"]}

    # deterministic key -> retry reproduces it -> server dedupes
    key = make_key(state["thread_id"], draft["title"], draft["body"])
    return create_github_issue.invoke({**draft, "idempotency_key": key})

3.3 · Diagnose the infinite loop

def create_with_retry(draft, key, attempts=5):
    for _ in range(attempts):
        try:
            return repo.create_issue(draft["title"], draft["body"])
        except GithubException:
            continue          # something failed, just try again
    return {"success": False}

NO_RETRY = {401, 403, 404}

def create_with_retry(draft, key, attempts=5):
    for _ in range(attempts):
        try:
            return repo.create_issue(draft["title"], draft["body"])
        except GithubException as e:
            if e.status in NO_RETRY:
                return {"success": False, "error_type": "auth_or_config",
                        "message": f"HTTP {e.status}: fix token/repo, not a retry."}
            # transient (5xx/timeout): fall through and retry with backoff
    return {"success": False, "error_type": "exhausted", "message": "Gave up."}