AnthropicClaude Certified Architect – Foundations2026-101.4 Implement multi-step workflows with enforcement and handoff patterns
Hand humans a case they can act on
Completed by the knowledge check
Learning objective
Produce structured human handoffs containing customer identifiers, findings, amounts, and recommended actions.
Core idea
A human support agent receiving an escalation might have no access to the conversation transcript. As the architect, you must make the handoff sufficient to identify the case, understand the established findings, distinguish a proposed refund from a completed one, and take the next permitted action.
A handoff is an operational record, not a shortened chat. Give it a defined structure and compile it from investigation results and trusted execution state. Claude can organize the record, but the application must check that its identifiers, monetary values, and action status match the case. A syntactically valid summary can still name the wrong customer or describe an unexecuted refund as complete.
See 1.4.3 for combining investigations and 1.4.2 for sensitive-operation gates. This Bite owns the transfer from that workflow to a person who needs the relevant evidence and decision without rereading the agent’s work.
How it works
Define the handoff contract
Design fields around the recipient’s next decision. The following are illustrative application fields, not an Anthropic-defined handoff schema:
| Field group | Information to preserve | Why the recipient needs it |
|---|---|---|
| Case identity | Case ID, customer ID, order or transaction ID, verification status | Locate the right record and see whether identity is established |
| Requested outcome | Each customer concern and requested remedy | Avoid resolving only the concern that triggered escalation |
| Findings | Established facts, supporting record references, root-cause assessment, unresolved questions | Distinguish evidence from an unsupported conclusion |
| Amounts | Currency, requested refund, eligible refund, executed refund | Avoid confusing a request, a policy calculation, and a payment |
| Next action | Recommended action, escalation reason, required approval, completed and blocked operations | Continue the workflow without repeating or bypassing steps |
Separate a confirmed cause from a hypothesis. “Carrier exception recorded for this shipment” is a finding. “The warehouse packed the order incorrectly” is not established by that record alone. If investigation cannot determine the root cause, make the uncertainty explicit and recommend the check needed to resolve it.
Money needs both an amount and a meaning. A single refund_amount field is ambiguous when the customer requested more than policy permits. For the example contract, use separate requested_refund_minor, eligible_refund_minor, and executed_refund_minor fields plus currency. The use of integer minor units is this application’s design choice. An unknown eligible amount is different from an established zero; represent that difference deliberately in the schema.
Choose structured response or tool submission
For a Messages API handoff-generation call, JSON outputs use output_config.format with type: "json_schema" and a schema. Define object properties, required fields, and additionalProperties: false according to the supported JSON Schema subset. Claude returns the structured record in a text content block, which your application parses and validates before handing it to the human-facing system.
JSON outputs are generally available on the Claude API for supported models; the structured-outputs page lists the supported model set. This lesson’s mechanism is scoped to the Claude API, rather than assuming every model or hosting integration supports it. The documented request uses output_config.format; beta headers are not required. The API’s deprecated output_format parameter is not the request field to copy.
If the workflow submits the record through a client tool, define an illustrative escalate_case tool with input_schema and strict: true. Strict tool use constrains the tool’s name and inputs to its schema; list every handoff field in the schema’s required array, and a strict call cannot omit one. The application still owns whether and how that tool executes. JSON outputs structure a response; strict tool use structures an invocation. Neither establishes that the customer ID or evidence is correct.
Keep the schema focused on a concise root-cause explanation and supporting findings. Do not request Claude’s private step-by-step reasoning as a handoff field. The structured-outputs documentation warns that a property asking for thinking can cause a reasoning_extraction refusal; ask for a short explanation instead.
Validate before releasing the record
Check stop_reason before treating structured output as a completed handoff. A refusal can take precedence over the schema even with an HTTP 200 response. Preserve that outcome rather than treating the content as a normal handoff. If stop_reason: "max_tokens" cuts the output, the documented remedy is to retry generation with a higher max_tokens; do not submit the truncated record.
Then check semantic consistency against trusted state. Customer and transaction IDs must refer to this case. Findings must agree with the investigation evidence. Amounts must agree with the request, policy result, and payment result respectively. A recommendation for supervisor approval must not be rewritten as approval already granted.
The submission handler can reject an inconsistent record and return a tool_result with is_error: true identifying what must be corrected. This uses the client-tool result mechanism from 1.1.2. If your application submits a parsed JSON response directly instead, perform the same validation before making that submission. Schema conformance is the structural check; the case service supplies the factual check.
A record reaches the human-facing system only after both its stop_reason and its consistency with trusted state are checked.
Key distinctions and trade-offs
A transcript preserves everything said, including speculation and repeated requests. A structured handoff preserves what the recipient needs to act. Useful concision comes from named fields and evidence-backed findings, not from omitting unresolved concerns. If the person lacks transcript access, “see conversation” is not an adequate root-cause assessment or recommendation.
A recommended action is separate from an execution result. “Approve an exception refund” tells the person what to decide. “Refund completed” asserts that a payment tool succeeded. Bind execution status to trusted tool outcomes rather than allowing the model to infer it from its own plan.
Required fields improve completeness, but they must permit honest uncertainty where the case is unresolved. For an unknown root cause, preserve the observed failure and the missing evidence. Do not make the schema require an invented cause merely to produce a fully populated object.
Architecture / decision scenario
A customer requests a $120 refund after a failed delivery and also asks to cancel renewal. The example service verifies the customer and confirms the carrier exception. Policy permits $80 without an exception, the $120 request is blocked pending supervisor approval, and subscription lookup fails. No refund has executed.
The agent compiles a structured handoff through output_config.format. It includes the case, customer, and order identifiers; the confirmed carrier finding with its record reference; the unresolved renewal concern; and the escalation reason. For USD, the example’s amount fields contain requested 12000, eligible 8000, and executed 0 minor units. The recommended actions are to decide the refund exception and investigate subscription state before canceling renewal.
The application verifies those fields against the lookup, policy, and execution records. A draft that reports an executed refund of 12000 fails semantic validation even if it matches the JSON schema. The accepted handoff lets the supervisor decide the exception without guessing which amount was requested or assuming the subscription concern was resolved. The existing sensitive-operation gates remain in force when work resumes.
Common exam traps
- Escalating with “please review the chat” when the recipient lacks transcript access.
- Providing a refund amount without currency or requested-versus-executed meaning.
- Presenting a plausible root cause as a confirmed finding.
- Assuming structured output guarantees factual accuracy or transaction authorization.
- Parsing every HTTP 200 as schema-compliant success despite
refusalormax_tokens. - Treating a recommendation to approve a refund as approval or completed payment.
What to remember
A human handoff must identify the case, preserve supported findings and unresolved concerns, distinguish monetary meanings, and recommend a concrete next action. Use JSON outputs or strict client-tool inputs for structure, then validate the record against trusted case state before releasing it.
Knowledge check
A support agent escalates a refund exception to a supervisor who has no access to the conversation transcript. Which handoff lets the supervisor act without repeating the investigation?
A customer requested a $120 refund. Policy permits $80 without a supervisor’s exception, and no refund has executed. The handoff schema holds one refund_amount field. How should the schema change?
The handoff generator requests JSON outputs through output_config.format. A response arrives with HTTP 200 and stop_reason: "max_tokens". What should the application do?
max_tokens before submittingmax_tokens can be incomplete and fail to match the schema, even with a 200 status, so stop_reason is checked before a record is treated as a handoff. The documented remedy is to retry with a higher max_tokens . A refusal is a different stop reason with its own handling, and a truncated record must not reach the human-facing system.A generated handoff conforms to its JSON schema and reports executed_refund_minor: 12000. The payment service shows no refund for the case. Which check catches this before the supervisor sees the record?
additionalProperties: falseescalate_case tool that submits the recordReferences
- Anthropic, Structured outputs
- Anthropic, Strict tool use
- Anthropic, Handle tool calls