Structured Output for Cap Exceeded: A Schema for Refusals

Define one schema per task family and reuse it for both the success and the cap case. The difference between the two is the status field, not the shape. That way the orchestrator has a single parser and a single validator.

{
  "status": "capped",
  "reason_code": "TOKEN_CAP",
  "partial_result": { "sections": ["intro", "pricing"], "claims": 14 },
  "schema_ok": true,
  "coverage": {
    "items_expected": 40,
    "items_completed": 28,
    "unit": "sections",
    "fraction": 0.70
  },
  "steps": {
    "completed": ["outline", "sections 1-28", "claim extraction"],
    "remaining": ["sections 29-40", "dedupe", "final validation"]
  },
  "retry_hint": {
    "suggested_action": "SPLIT",
    "suggested_scope": "sections 29-40",
    "budget_multiplier": 1.0,
    "notes": "remaining work is independent per section"
  }
}

Field by field:

Keep the reason_code set closed. Six values cover most production caps: TOKEN_CAP, TIME_CAP, TOOL_CALL_CAP, CONTEXT_OVERFLOW, DEPENDENCY_FAILED (an upstream tool or API failed), and SCOPE_TOO_BROAD (the subagent concluded the task should be decomposed rather than attempted). Closed sets matter because they let you write an exhaustive decision table and let a validator reject unknown values. JSON Schema enums exist for exactly this, and schema validation is the contract that describes required fields, types and constraints before the data exists Agenta's structured output guide.

Provider-native structured output features enforce a JSON schema at generation time, while function calling has the model name the function and fill parameters in a validated format Agenta's guide to structured outputs and function calling. Use them, but do not stop there. A schema constrains shape, not truth, and provider behavior around refusals, truncation and fallback still matters TrueFoundry's structured outputs writeup.

One practical wrinkle: if your runtime only offers schema enforcement on the whole response and you also want free text in partial_result, ask for the envelope as a tool call and keep any narrative in a string field. That pattern is common enough that developers ask about forcing correct tool-call JSON while leaving the rest of the message free this OpenAI community thread.

Validation on receipt, in order:

1. Parse the envelope. Reject on parse failure and mark the subagent run as a contract failure.
2. Validate against the envelope schema. Unknown reason_code values fail here.
3. If schema_ok is true, validate partial_result against the task schema. If validation fails, downgrade schema_ok to false and treat the partial result as absent.
4. Check that coverage fractions are arithmetically consistent (completed never exceeds expected).
5. Route violations to retry, repair or escalation logic, never straight to the user MLflow.

Grammar-constrained decoding can nearly eliminate syntax errors, yet structural and semantic errors persist, as an empirical study of structured output control found Song et al. on arXiv. That is the reason step 3 exists: the model can produce valid JSON that is not a valid answer to your task.

This is the part most teams get wrong. They branch on coverage alone and treat every partial result as retryable. The reason_code is what tells you whether more budget helps. A TOKEN_CAP at high coverage is a different problem from a SCOPE_TOO_BROAD at low coverage.

Two numbers make the table concrete. In Anthropic's multi-agent research setup, subagents running in separate context windows let the system spread reasoning in a way a single agent could not, and the orchestrated system outperformed a single agent by a wide margin on internal research evaluations, as summarized by ByteByteGo. The gain comes from decomposition, which is exactly the action the table prefers when coverage is low or the context overflows. Meanwhile, multi-agent orchestration adds latency at every handoff and requires explicit state management between components, which is why Microsoft advises using the lowest complexity that reliably meets requirements Microsoft's Azure Architecture Center. A cap envelope is state management in its cheapest form: it is a message, not a new agent.

The rule in one sentence: coverage decides whether to resume or split, and reason_code decides whether more budget could possibly help. If the reason is not a budget cause, spend nothing.

Suppose a subagent is asked to extract 40 structured product records from a document corpus, with a token cap of 60,000, a wall-clock cap of 10 minutes, and a tool-call cap of 100.

Run 1 returns TOKEN_CAP with coverage 0.35 (14 of 40 records) and an empty remaining-work list beyond "the rest of the corpus." Under the table, 0.35 is below 0.8, so the orchestrator does not buy a bigger budget. It splits: four workers, each assigned 10 records. Cost of the decision: one envelope validation and one planning call.

Run 2: three workers return ok, one returns TIME_CAP at coverage 0.60 (6 of 10 records) because a source was slow. The four remaining records sit in steps.remaining, so the orchestrator resumes that one worker with a narrower scope of exactly those four records rather than re-running all ten. Rough saving: it re-does four records instead of ten, a 60 percent reduction in that worker's repeated work.

Run 3: one record returns DEPENDENCY_FAILED because the source document is unreachable. The orchestrator escalates to a human queue with the partial result attached, since no amount of retry budget fixes a missing source.

Without the envelope, the same run most likely produces an apology and a partial dump. The orchestrator either retries everything (paying for work that already succeeded) or discards everything (losing 28 records' worth of output). The envelope's value is not elegance, it is measured in avoided re-computation. Note also that coordination has its own price: a three-agent pipeline consumed roughly 29,000 tokens versus 10,000 for an equivalent single-agent approach, per Beam AI's production patterns writeup. A split is a tool to use when coverage is low, not a default.

The subagent sees the failure from the inside, so it often knows whether the remaining work is parallelizable, whether a source was flaky, or whether the scope was simply too wide. Capture that in retry_hint, then treat it as advisory. Three rules keep it honest:

• Bound the vocabulary. suggested_action takes values from the same table actions: RESUME, SPLIT, NARROW, ESCALATE, FAIL. If the subagent proposes RESUME on a CONTEXT_OVERFLOW, the orchestrator's table overrules it, because fresh context is the documented reason recursive decomposition helps, as Gandhi et al. describe.
• Ignore proposed budgets. Let the orchestrator, not the worker, own the multiplier. A worker that asks for ten times its budget is asking you to spend money on its own optimism.
• Log the disagreement. When the hint and the decision table differ, record both. Over a few weeks those mismatches tell you which reason_codes your table gets wrong, which is cheaper than tuning prompts.

Keep schema violations as contract failures and send them to a repair path, the same way you would treat any malformed handoff MLflow. And correlate traces across the orchestrator and its workers, since a cap event is only debuggable if you can see the budget at the moment it fired; practical guidance on agent observability and failure handling covers the trace side of this the JetBrains single versus multi-agent guide.

Worked against real traffic, the envelope also gives you a migration path. Start with a single agent and one cap, wrap it in the envelope, and add reason codes only when you observe the failure. Microsoft's guidance to use the lowest level of complexity that meets requirements applies to your error taxonomy as much as to your architecture Microsoft.

If you are running several subagents behind one orchestrator and want one key for text, image and embedding models, Quanta Inference (https://quantaintelligence.ai/inference) keeps the routing and billing side to one interface while your code owns the envelope contract.