Web edition 001 · October 30, 2026
An AI assistant can produce a convincing plan and still be the wrong component to authorize a refund, change a customer record, or deploy a service. For an architecture review, separate three questions: what may this system do, how will we know what happened, and how will we recover when the outcome is uncertain?
This first Brief offers a practical review framework. The recommendations below are design guidance for discussion; the linked sources explain the underlying retry contracts.
1. Permission: make the boundary executableStart with one business action. Define who may request it, the resources it may affect, and the limits that apply. In a hypothetical refund assistant, these might include the customer account, the original payment, the remaining refundable amount, and an approval threshold.
Enforce those rules in a service that validates every tool request using the current user's permissions and current business state. Instructions in a prompt are useful context; they should not be the mechanism that grants authority. Keep credentials outside the model's output, and expose narrow operations with validated inputs.
If an approval is required, bind it to the specific proposed action and its parameters. Changing the amount or destination should require a fresh decision. Your review question is concrete: can a persuasive but unauthorized tool call pass this boundary?
2. Evidence: record decisions you can reconstructChoose an operation ID before execution. Link it to the request, the policy decision, the approval if required, the tool invocation, and the provider's result. Record the relevant model, prompt-template, and policy versions so an investigation can identify what was running.
Evidence does not require collecting everything. Decide which fields are necessary, redact secrets and unnecessary personal data, restrict access, and define retention. Store observable inputs, decisions, and outcomes. A model's explanation is a statement to evaluate, not proof that an external action succeeded.
Use this test: could another engineer reconstruct the sequence from the operation record without rerunning the agent or asking the original developer?
3. Recovery: design for an unknown outcomeA timeout means the caller stopped waiting. It does not establish whether the remote system performed the action. Represent that uncertainty explicitly rather than immediately marking the operation failed.
The Amazon Builders' Library explains caller-provided request identifiers as a way to distinguish retries from new intent. For a retry of the same approved operation, preserve its identity and parameters, subject to the provider's actual contract.
That contract matters. Stripe's API v1 documentation says a repeated idempotency key can return the saved response, including a server error; a key reused after pruning can start a new request. An idempotency key is therefore not an unlimited recovery guarantee. Read the contract for the API version you use.
Give one component ownership of bounded retries. Use a deadline, backoff, and jitter; AWS describes how retries can amplify load. When the outcome remains unclear, reconcile against provider records or route the case for review. Do not let the agent invent a new operation identity merely to get past an error.
Try it in your next design reviewPick one action and write four lines: the permission boundary, the evidence record, the recovery owner, and the condition that requires human review. Then simulate a lost response after the remote action succeeds. Explain why your design avoids a second business action while preserving a path to resolution.
Use the Agent Action Review worksheet to capture your reasoning. Continue with Architecture Challenge 001, or explore the system design book for the broader learning path.
Web edition 001 · October 30, 2026
An AI assistant can produce a convincing plan and still be the wrong component to authorize a refund, change a customer record, or deploy a service. For an architecture review, separate three questions: what may this system do, how will we know what happened, and how will we recover when the outcome is uncertain?
This first Brief offers a practical review framework. The recommendations below are design guidance for discussion; the linked sources explain the underlying retry contracts.
1. Permission: make the boundary executableStart with one business action. Define who may request it, the resources it may affect, and the limits that apply. In a hypothetical refund assistant, these might include the customer account, the original payment, the remaining refundable amount, and an approval threshold.
Enforce those rules in a service that validates every tool request using the current user's permissions and current business state. Instructions in a prompt are useful context; they should not be the mechanism that grants authority. Keep credentials outside the model's output, and expose narrow operations with validated inputs.
If an approval is required, bind it to the specific proposed action and its parameters. Changing the amount or destination should require a fresh decision. Your review question is concrete: can a persuasive but unauthorized tool call pass this boundary?
2. Evidence: record decisions you can reconstructChoose an operation ID before execution. Link it to the request, the policy decision, the approval if required, the tool invocation, and the provider's result. Record the relevant model, prompt-template, and policy versions so an investigation can identify what was running.
Evidence does not require collecting everything. Decide which fields are necessary, redact secrets and unnecessary personal data, restrict access, and define retention. Store observable inputs, decisions, and outcomes. A model's explanation is a statement to evaluate, not proof that an external action succeeded.
Use this test: could another engineer reconstruct the sequence from the operation record without rerunning the agent or asking the original developer?
3. Recovery: design for an unknown outcomeA timeout means the caller stopped waiting. It does not establish whether the remote system performed the action. Represent that uncertainty explicitly rather than immediately marking the operation failed.
The Amazon Builders' Library explains caller-provided request identifiers as a way to distinguish retries from new intent. For a retry of the same approved operation, preserve its identity and parameters, subject to the provider's actual contract.
That contract matters. Stripe's API v1 documentation says a repeated idempotency key can return the saved response, including a server error; a key reused after pruning can start a new request. An idempotency key is therefore not an unlimited recovery guarantee. Read the contract for the API version you use.
Give one component ownership of bounded retries. Use a deadline, backoff, and jitter; AWS describes how retries can amplify load. When the outcome remains unclear, reconcile against provider records or route the case for review. Do not let the agent invent a new operation identity merely to get past an error.
Try it in your next design reviewPick one action and write four lines: the permission boundary, the evidence record, the recovery owner, and the condition that requires human review. Then simulate a lost response after the remote action succeeds. Explain why your design avoids a second business action while preserving a path to resolution.
Use the Agent Action Review worksheet to capture your reasoning. Continue with Architecture Challenge 001, or explore the system design book for the broader learning path.