Design a bounded incident investigator

Pattern 01 companion: Python example · Behavioral tests · Example license

Choose the responsibility before the model

An incident-response assistant receives a report that checkout is slow. Its job is to collect approved observations and prepare a reviewable account, not restart checkout or declare the incident resolved. That narrow responsibility is an architectural decision. A single agent can choose whether to inspect a latency fixture or an availability fixture, while the surrounding program decides which observations are permitted and when work must stop. The useful freedom is choosing the next question; production authority remains elsewhere.

Anthropic distinguishes predefined workflows from agents whose models choose their process and tool use, and recommends adding complexity only when it earns its cost. Source: foundational pattern distinction. That source is conceptual background, not a current SDK recipe. The implementation here is an original deterministic teaching harness. Its callable adapter is the seam where a real model could later propose actions.

Architecture and request sequence

Component diagram for Design a bounded incident investigator — Original reference architecture by Sandeep Belgavi. Arrows show the responsibilities and transitions described below.

Request sequence for Design a bounded incident investigator — Illustrative sequence for this design; failure and recovery variants are explained in the article.

Specify the task and observation contract

Use an incident identifier, an allowed service set, a bounded observation inventory, and a maximum decision count as the request contract. The model does not manufacture the inventory. An operator or authenticated upstream service provides it after authorization. An observation contains a stable locator, capture time, service identity, and measured value. A response contains an explicit terminal status and the observations actually consulted. In the small companion program, the inventory is an in-memory dictionary and each successful read produces an event with its step number and reference.

Define what the terminal status means before naming it complete. Here complete means the bounded collection exercise finished after reading at least one approved item. It does not mean the service recovered, the proposed diagnosis is correct, or the customer impact ended. Those stronger outcomes need separate measurements. This modest semantic contract prevents a convenient label from quietly becoming an operational guarantee.

Keep the decision loop smaller than its policy

The proposed loop has four operations: request a decision, validate its shape, authorize its action, and record the result. It accepts read and finish. A proposed restart is rejected even if the argument looks plausible. A repeated read of the same fixture ends the demonstration rather than letting the agent spin. The decision count is charged before another proposal can be requested. These rules belong to the harness, so a persuasive tool response cannot rewrite them.

A production adapter adds another boundary: it must parse model output into the same constrained decision type. Parsing success is not authorization. An allowed tool name can still name a forbidden service or an observation outside the incident window. Keep identity and scope validation after parsing. The loop should report invalid output separately from denied authority; one suggests adapter repair, while the other may indicate an inappropriate request or an attempted escape.

Budget capacity in decisions and occupied time

Consider an illustrative service admitting ten incident investigations per minute, each with at most three model decisions. That creates a ceiling of thirty decisions per minute before retries, but does not bound concurrent connections. If each decision stalls for twenty seconds, occupied workers can accumulate even though the decision ceiling looks small. Define a separate admission limit, per-call deadline, overall deadline and cancellation policy. The teaching program implements only a decision ceiling because its adapter is immediate local code.

Choose a smaller ceiling when escalation is cheap and uncertainty is high. Choose a larger ceiling only when added observations measurably improve diagnosis. Measure decisions used by successful cases and by exhausted cases separately. Averages hide looping failures. The cost model should charge input and output usage at the adapter boundary and include observation transport, storage and reviewer time. A budget breach must preserve collected evidence rather than discard the whole investigation.

Decide when a single agent is the wrong fit

A single agent is attractive when one compact context can hold the task, the available observations and their relationships. It reduces handoff surfaces and makes ownership clear. It becomes awkward when independent specialties require different access scopes, when long evidence streams crowd out the task contract, or when a fixed procedure must be followed every time. In those cases, deterministic workflow or specialist routing can make the contract easier to inspect.

Do not split an investigator merely to obtain several personalities. First identify a concrete boundary: independent data access, separately testable expertise, or genuinely concurrent work. Conversely, do not grant one general investigator every production credential to avoid writing interfaces. The architecture should express the minimum authority required for the current incident. The next pattern examines a fixed workflow where a model supplies a classification while code controls every stage.

Sources and scope

The foundational reference supports the workflow-versus-agent distinction. All incident contracts, capacity numbers and proposed policies in this article are original educational designs by Sandeep Belgavi. The Evals collection supplies prerequisite measurement concepts. No provider, production service or cloud deployment was exercised. Model capabilities and framework APIs can change; the companion example targets Python 3.11 or later without depending on either.