Require exact human approval before agent actions

Application background

A support assistant suggests giving a customer a $5 credit for a particular ticket. That suggestion appears for a human reviewer to inspect. Only after the reviewer approves the exact action should a separate executor contact the payment provider.

An approval is not general permission to do whatever the assistant later suggests. If the amount changes to $50, the target changes or the approval becomes too old, the original click no longer authorizes the operation.

The proposed action the reviewer sees

This is an illustrative proposal record, not the complete stored schema of the supplied workflow:

{"proposal_id":"p-7","version":1,"ticket_id":"T7","action":"credit","amount_minor":500,"currency":"USD"}

500 is five dollars expressed in cents. The approval must identify this proposal version and these effectful fields. Changing amount_minor to 5000 changes the proposed action to fifty dollars and requires new approval.

The executor is the component allowed to perform the external action. It must verify the saved approval and current facts before using provider credentials.

Your assignment

Deliver: Extend the supplied proposal and approval workflow with a reviewer interface. Handle changed parameters, expired approvals and uncertain provider outcomes before connecting real actions.

Required behavior: Proposal, approval and execution are separate durable states. Approval identifies the exact target and the same consistently represented parameters that execution will use. Different amounts or targets need different approval. The executor rechecks permission, expiry and operation identity before performing an external effect.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/ai-systems/demo.py agent

Supplied code: AI workflow implementation, starting at demo.py. These are local workflows with fixture providers and temporary storage. They do not include the user interface or connect to the AWS services in the diagram.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

[
  {
    "request": {
      "action": "order.put",
… (more output follows)

Set up your implementation workspace

Create work/02-approval-desk/ in your checkout (or use a separate repository). Copy examples/ai-systems/ there so you can change the workflow and its storage/provider boundaries together. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Run the proposal-to-execution reference

Execute the agent demo, inspect the immutable proposal and approval receipt, and identify the executor boundary in the retained implementation. The supplied demo shows approval and duplicate execution handling. Add changed-parameter and expired-approval cases as explicit next implementation steps before connecting a real provider.

2. Build the reviewer interface

Show target, amount, currency and effect in plain language. Keep approval attached to a proposal version/hash. Editing any effectful parameter creates a new proposal. The UI cannot silently reuse a previous click.

3. Add a restricted executor

Give it only the approved action types and provider credentials. Revalidate current reviewer/subject authority, expiry and source facts. Persist a stable provider key before the call and classify timeout as unknown rather than definitely not executed.

4. Reconcile external outcomes

Query or safely retry under the provider’s actual idempotency contract. Preserve attempt history and show pending repair to the operator. A model-generated explanation is not evidence that a credit happened.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

The durable approval ledger and restricted executor enforce authority. A queue moves approved work but does not make stale or changed proposals valid.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Turn an approved batch into individually accountable effects

Approval of ten credits must not become permission for an eleventh. A crash after credit three also must not cause credits one through three to be submitted with new identities.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Hash the complete approved item set, per-item amounts, currencies and aggregate limits. Persist a batch record and a stable provider operation ID for every item. Execute only items covered by a still-valid approval and recheck limits before each effect. Keep confirmed, unknown and not-started states separately. An uncertain item is reconciled with its original provider before automatic continuation or retry. A reviewer sees partial completion rather than one misleading batch-failed label.

Walk through the result. Approve three credits of $5. Confirm item 1, lose the response for item 2 and stop before item 3. Restart and recover item 2 by its original identity. Add a fourth item and show rejection because the plan hash changed. Deliver the batch approval and three-item outcome ledger.

Approve a batch of credits. Bind approval to the complete item set and per-item limits, then report partial execution and repair without turning one approval into an unlimited batch capability.

if proposal["status"] == "COMMITTED":
    return proposal  # The prior receipt is the retry result.
if now >= proposal["expires_at"]:
    raise Invalid("proposal expired")

python3.12 examples/ai-systems/demo.py agent