Agency and Orchestration Architecture · Lesson 1

Bounded agency and outcome contracts

8 min read

Lesson objectives

  • Design a defensible decision that can define a testable outcome and action boundary.

Work on Bounded agency and outcome contracts starts from a named business result: define a testable outcome and action boundary. For an assistant that triages service requests and proposes the next step, identify the unit of work, authorized identity, and intended effect. Establish a baseline for classification accuracy, resolution time, and escalation rate before introducing the selected agent. Treat confusing freedom to draft with authority to create side effects as a failure state, not wording to explain away. The lesson requires an inspectable outcome rather than activity volume or persuasive text. For Bounded agency and outcome contracts, this point is checked through classification accuracy, resolution time, and escalation rate.

Consider a request to cancel a subscription and refund the latest charge. The assistant may identify intent and propose a route, but it does not inherit authority to change the contract or move money. The outcome contract separates interpretation, recommendation, effect request, and effect execution. A server-side tool verifies employee identity, subscription state, policy, and operation key. If a timeout follows dispatch, the coordinator queries that key before retrying. Success therefore means correct classification and one authorized effect, not merely a fluent answer or a shorter handling time.

Write the outcome in observable terms: the request is placed in the right category, the next step is justified, and no financial or contractual change occurs except for the correct customer through an authorized service. “Help quickly” is not an outcome contract because it says nothing about correctness or authority. The tool payload should carry customer and subscription identifiers, the requested action, a state version, the acting principal, and one operation key. The model may draft the payload, but the service decides whether the action is eligible.

Suppose the human baseline classifies 180 of 200 requests correctly, resolves the median case in fourteen minutes, and escalates eighteen percent. The assisted flow reaches 188 correct classifications, ten minutes, and twelve percent escalation. Those figures still do not prove release readiness. If two of the twelve errors close the wrong subscription, a protective limit has failed despite the improved average. Compare the agent with a simpler structured form as well; if the form produces the same outcome with less risk, additional agency is not justified.

Now replay the cancellation twice after a network disconnect. The first call reached the subscription service, but its response was lost. The coordinator records an unknown outcome and queries the stable operation key. It finds that cancellation succeeded while the refund remained blocked because the reason was missing. The workflow records the partial result and asks for the missing fact instead of cancelling again. A second test uses an employee identity outside the permitted team and must fail before effect. These checks prove the contract outside the model: one effect, correct identity, current state, and an inspectable reason for stopping or continuing.

A second case changes a customer contact address rather than cancelling a subscription. The initial account record has version 7 and a verified address. The customer proposes a new address, but the request arrives from an unverified channel. The assistant can identify the requested change and explain verification; it cannot commit it. A trusted identity step produces a short-lived authorization for this customer and action. The change tool then compares version 7 and writes once with operation key A-391.

Test a missing postal field, a stale version after another employee changes the account, and two identical submissions. The missing field receives a validation error. The stale request receives a conflict and the coordinator rereads the current record before asking the customer to confirm the revised change. The duplicate returns the first committed result. A confirmation message is sent only after the account service proves the new address. This distinguishes a customer-facing sentence from the authoritative postcondition. The cancellation and address cases share a boundary principle but differ in consequence. An incorrect address may misroute correspondence and must be reversible; an incorrect refund may have a financial effect and separate approval. Write those differences into the outcome contract rather than declaring all agent actions equally safe. The learner’s decision is to permit drafting and structured requests in both cases while assigning effect eligibility to the owning service and higher scrutiny to irreversible changes.

An outcome contract separates four freedoms: interpreting text, proposing an option, invoking a tool, and causing an effect that is difficult to reverse. In service triage, an agent may propose category and priority, while closure requires evidence or accountable review according to impact. Define success as correct first-time resolution, add limits for wrongful closure and delay in critical classes, and compare against a simpler structured-request alternative. If the simpler design achieves the outcome with less risk, agency is not justified. A boundary review should classify every proposed action by reversibility and consequence. Drafting a reply is reversible; changing ownership, closing a case, or notifying a customer may not be. That classification determines whether the agent may act, must request approval, or may only recommend. Reviewers should challenge the boundary with a borderline case, because a design that handles only obvious high-impact actions often grants accidental authority through seemingly harmless status fields. The contract also needs an escalation path for incomplete evidence. Suppose a customer asks for a refund but the payment ledger has not synchronized the last charge. The assistant can acknowledge the request, gather the transaction reference, and put the case in pending_verification. It cannot infer that the charge occurred from the customer’s statement, nor infer that it did not occur from a delayed ledger. The decision owner and maximum wait belong in the workflow. If the ledger later confirms a charge, the refund service evaluates its policy at that time; if it proves no charge, the case receives an explanation without a monetary effect.

A review packet should make four questions easy to answer: what result was promised, which identity was authorized, which system owned the effect, and what observation proved the result? Walk through the cancelled subscription and contact-address examples with those questions. In both, an operation key protects against a repeated dispatch, but the postconditions differ. Cancellation requires the subscription state and any separate refund status. Address change requires the current contact field and confirmation of customer identity. This exercise teaches how to write a contract that a second engineer can test without relying on the agent’s own narrative of success.

Ask the learner to produce two test cases from each contract. One follows the happy path through a verified postcondition; the other changes a single decisive fact such as identity, state version, or refund eligibility. The expected tool response and customer message must be written separately. If the effect fails, a friendly message must not claim success. If the effect succeeds but the response is lost, a timeout message must not claim failure. This simple exercise exposes where product wording can contradict business truth, and it tests whether the system can explain its stopped state to a customer without leaking private implementation details.

Lesson summary

Apply Bounded agency and outcome contracts with explicit boundaries, measures, a safe stopped state, and reconsideration triggers.