liveBook · Manning

Commit identity

As explained in Designing AI Agents

An identifier assigned by a runtime to recognize repeated requests for the same state-changing business operation.

A commit identity is a runtime-issued identifier that lets retries refer to the same state-changing business operation. The runtime reuses it for that operation rather than letting the model invent a new identifier for each attempt. This prevents a model-chosen identifier from turning a retry into an apparently new operation. section 6.3.3 section 6.1.2

The identity is part of an action contract, alongside the intended effect, target, state version, request digest, and acceptance labels. The digest binds the selected tool and effect to the admitted arguments, so the same identity cannot silently acquire a different meaning. Execution attempts remain separate: an attempt can fail, be rejected, or have an uncertain external outcome. section 6.1.2

Listing 6.7 Admission checks for one selected tool call
class AdmissionError(ValueError):
    pass
 
 
@dataclass(frozen=True)
class AdmittedCall:
    spec: ToolSpec
    contract: ActionContract
    arguments_json: str
    provenance: tuple[tuple[str, str], ...]
    state_read_at: datetime | None
 
    def arguments(self) -> dict[str, Any]:
        return json.loads(self.arguments_json)
 
 
class CommitStore:
    def __init__(self) -> None:
        self._digests: dict[str, str] = {}
        self._lock = Lock()
 
    def reserve(self, commit_id: str, digest: str) -> str:
        with self._lock:  #A
            current = self._digests.get(commit_id)
            if current is None:
                self._digests[commit_id] = digest
                return "new"
            if current != digest:  #B
                raise AdmissionError("commit identity changed arguments")
            return "repeat"
 
    def release(self, commit_id: str, digest: str) -> None:
        with self._lock:
            if self._digests.get(commit_id) == digest:
                del self._digests[commit_id]
 
    def digest_for(self, commit_id: str) -> str | None:
        with self._lock:
            return self._digests.get(commit_id)
 
 
def canonical_arguments(
    arguments: Mapping[str, Any],
) -> str:
    try:
        document = json.dumps(
            dict(arguments),
            allow_nan=False,
            separators=(",", ":"),
            sort_keys=True,
        )
    except (TypeError, ValueError) as error:
        raise AdmissionError("arguments must be JSON values") from error
    return document
 
 
def request_digest(spec: ToolSpec, arguments_json: str) -> str:
    request = json.dumps(
        {
            "tool": spec.name,
            "effect": spec.effect,
            "arguments": json.loads(arguments_json),
        },
        separators=(",", ":"),
        sort_keys=True,
    )
    return sha256(request.encode("utf-8")).hexdigest()
 
 
def admit(
    registry: ToolRegistry,
    intent: ToolIntent,
    context: DispatchContext,
) -> AdmittedCall:
    eligible = {item.name: item for item in registry.eligible(context)}
    spec = eligible.get(intent.tool_name)  #C
    if spec is None:
        raise AdmissionError("tool is not eligible in this context")
 
    document = canonical_arguments(intent.arguments)
    digest = request_digest(spec, document)
    arguments = json.loads(document)  #D
    try:
        spec.validate_arguments(arguments)
    except (TypeError, ValueError) as error:
        raise AdmissionError("tool arguments are invalid") from error
 
    provenance: list[tuple[str, str]] = []
    for name in spec.protected_args:  #E
        trusted = context.trusted_values.get(name)
        if trusted is None or arguments.get(name) != trusted.value:
            raise AdmissionError(f"{name} is not runtime-bound")
        if not trusted.source_ref or not trusted.state_version:
            raise AdmissionError(
                f"trusted evidence is incomplete for {name}"
            )
        provenance.append((name, trusted.source_ref))
 
    state = (
        context.trusted_values.get(spec.state_arg)
        if spec.state_arg is not None
        else None
    )
    if spec.state_arg is not None and state is None:
        raise AdmissionError("trusted state basis is missing")
    if spec.max_state_age_seconds is not None:  #F
        if state is None:
            raise AdmissionError("fresh state is required")
        if state.read_at.utcoffset() is None:
            raise AdmissionError("state timestamp needs a timezone")
        if context.now.utcoffset() is None:
            raise AdmissionError("runtime timestamp needs a timezone")
        age = (context.now - state.read_at).total_seconds()
        if age < 0 or age > spec.max_state_age_seconds:
            raise AdmissionError("state snapshot is stale")
 
    if spec.mutates_state and not context.commit_id:
        raise AdmissionError("commit identity is required")
 
    target = str(arguments.get(spec.target_arg, "unknown"))
    contract = ActionContract(
        effect=spec.effect,
        target=target,
        state_version=(state.state_version if state else "not-required"),
        commit_id=context.commit_id or "read-only",
        request_digest=digest,
        acceptance_labels=spec.acceptance_labels,
    )
    return AdmittedCall(
        spec=spec,
        contract=contract,
        arguments_json=document,
        provenance=tuple(provenance),
        state_read_at=(state.read_at if state else None),
    )

The commit store reserves an identity against a digest, recognizes a matching repeat, and rejects a repeat with changed arguments. section 6.3.3

A payroll retry

A payroll transfer may use the right tool and valid arguments yet still create an unauthorized second payment. The runtime resolves the protected employee and amount from the approved payroll record and reuses the operation’s commit identity. A pre-check ties the contract to the reserved digest; a post-check accepts only a settled receipt matching the commit, employee, amount, and payroll version. section 6.3.3 section 6.1.2 section 6.5.4

If an external outcome is unknown, query by commit identity rather than replaying blindly. Commit checks work within one identity: detecting a second payment under a different identity also requires authorization and reconciliation across the business operation. In production, reserve commits in a durable store and verify effects against authoritative systems. section 6.5.4

Commit identity is one control in an execution boundary, not proof that an action was authorized or completed. Admission must remain on the only execution path available to the agent; otherwise, a direct runner or alternate API path can bypass the dispatcher. Acceptance depends on independent evidence of the effect. section 6.3.3 section 6.9

How Designing AI Agents covers it

How deep it goes
Works through identity reservation, digest matching, and receipt checks, while calling for durable storage and authoritative verification in production.
Examples
Uses a payroll transfer and a settled provider receipt to illustrate duplicate-payment risk and effect verification.
What you can do after
Evaluate whether a retry refers to the same operation and when an uncertain outcome requires a query rather than blind replay.
How it connects
Links action contracts and tool dispatch with authorization, preconditions, postconditions, and reconciliation.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Agents. The section links point to the parts of the book it draws on.