Domain 6 of 6 · Chapter 4 of 4

Operate agents with safe execution paths and robust error handling

Unlock the complete study guide.

Bundled into the existing Developing in Agentic AI Systems premium course — no separate purchase.

14-day money-back guarantee — no questions asked.

Included in this chapter:

  • Classify the failure before choosing a recovery
  • Match the hook event to the failure job
  • Retry the smallest failed unit, and bound every retry
  • Recover a broken MCP connection without replaying the call
  • Escalate through a channel that exists where the agent runs
  • Stop the agent outright, not only the current request
  • Treat a waiting gate as a job for a person, not an error
  • Check what happens when a policy hook itself fails
  • Keep attributable evidence that outlives the run
  • Roll back at the boundary where the change lives
  • Treat generated commands as untrusted at the execution boundary
  • Exam reasoning: choosing the safe recovery

Failure signals and the safe next move

Signal you seeWhat it tells youSafe next moveTempting but wrong
MCP JSON-RPC error for an unknown tool or malformed requestThe request itself was rejectedFix the request or the tool choiceTreating it as a tool result the model can argue with
MCP tool result with isError: trueThe tool ran and failed on API, validation, or business logicReturn the error to the model so it can correct its argumentsReconnecting as if the server were broken
gh pr create exits nonzero but prints a pull request URLSome attachments failed; the pull request existsInspect the result and continue with that pull requestRunning creation again and opening a duplicate
HTTP 404 on a request that carries MCP-Session-Id under the legacy 2025-11-25 Streamable HTTP transportThe server terminated that sessionSend a new InitializeRequest without the old session IDResending the expired ID with backoff
Stream closed after an event with a retry field (legacy 2025-11-25 Streamable HTTP transport)The response is still resumableWait the retry delay, then GET with Last-Event-IDReconnecting instantly or re-sending tools/call
REST rate-limit error with retry-afterYou must pause for the stated timeWait, then retry a bounded number of timesRetrying immediately or indefinitely
Workflows on a cloud-agent pull request are waitingThe default approval gate for a person with write accessReview the code and choose Approve and run workflowsRe-running the workflow as if it had failed
Artifact digest mismatch warningThe download does not match the uploaded digestInvestigate before trusting the evidenceAssuming the mismatch already failed the run automatically

Decision tree

A failure signal: which layer failed?Was the request itself rejectedwith a JSON-RPC error?YesFix the request or the tool choiceunknown tool or malformed requestNoDid the tool run and returna result with isError: true?YesReturn the error to the modelso it can correct its argumentsNoDid a resumable stream dropbefore the response finished?YesWait any retry delay, then resumeGET + Last-Event-ID; never re-send tools/call(legacy 2025-11-25 transport)NoDid a request carrying MCP-Session-Idget HTTP 404?YesStart a new sessionnew InitializeRequest (legacy 2025-11-25 transport)NoDid the request time outwhile you waited for it?YesCancel the request, stop waitingsend cancellation for that requestNoA command, job, or API call failed:could its side effect already exist?YesInspect state first, then act oncePR URL, run statusNoRetry only the failed part, bounded--failed, --job databaseId, retry-after, backoffUnsafe or blocked at any step: stop, then escalate through a channel that exists theredeny + interrupt in the CLI, gh run cancel, approval gates and required checks
Cheat sheet

Cheat sheet

  • Distinguish protocol errors from failures returned by a tool
  • Use errorOccurred for an agent-execution failure notification
  • Use postToolUseFailure to give the agent recovery guidance after a failed tool
  • Account for different failure behavior in command and HTTP preToolUse hooks
  • Check for a created pull request before retrying a partially failed creation command
  • Handle modern MCP version mismatches by retrying with a compatible version
  • Choose the failed-job rerun surface when an entire workflow replay is unnecessary
  • Use the job database identifier when retrying one workflow job
  • Enable debug logging on a workflow retry when the original evidence is insufficient
  • Bound tool waiting even when progress notifications continue
  • Resume a resumable response stream instead of blindly repeating the tool request
  • Start a new MCP session when the server rejects an expired session identifier
  • Respect the server's stream reconnection delay
  • Choose file rollback explicitly when rewinding a CLI session
  • Restore a VS Code checkpoint to return files and conversation to an earlier request boundary
  • Use Redo to recover changes undone by restoring a checkpoint
  • Editing an earlier request both reverts later changes and reruns the revised request
  • Use a revert pull request to propose rollback of a merged agent change
  • Recognize the default human approval gate before workflows run on cloud-agent code
  • Keep repository checks and branch protections in the agent's completion path
  • Choose an escalation mechanism that exists in the execution context
  • Stop the CLI agent explicitly when a denied operation requires escalation
  • Cancel a workflow run through the run-control surface
  • Use agent commit authorship and co-authorship to identify who initiated a change
  • A Verified agent commit proves who made it, not that the code is right
  • Follow the agent-authored commit's session link to inspect execution evidence
  • Upload workflow-produced traces and plans as artifacts for inspection and handoff
  • Treat an artifact digest mismatch as an integrity warning requiring investigation
  • Preserve cloud-hook evidence outside the ephemeral sandbox
  • Bound repeated rate-limit retries and increase the delay between attempts
  • Validate generated text for its execution context before a tool wrapper interprets it

Unlock with Premium — includes all practice exams and the complete study guide.

Also tested in

References

  1. Tools: error handling (Model Context Protocol specification 2025-11-25)
  2. Versioning (MCP specification 2026-07-28)
  3. gh pr create (GitHub CLI manual)
  4. Hooks reference (GitHub Copilot)
  5. Agent operations controls (Microsoft Learn training unit)
  6. gh run rerun (GitHub CLI manual)
  7. Re-running workflows and jobs (GitHub Actions)
  8. Enabling debug logging (GitHub Actions)
  9. Rate limits for the REST API
  10. Best practices for using the REST API
  11. Lifecycle: timeouts (MCP 2025-11-25)
  12. Cancellation (MCP specification)
  13. Transports: Streamable HTTP resumability and session management (MCP 2025-11-25)
  14. Using hooks with Copilot cloud agent
  15. gh run cancel (GitHub CLI manual)
  16. About commit signature verification
  17. Reviewing Copilot output
  18. Storing and sharing data from a workflow (GitHub Actions)
  19. Rolling back changes made during a Copilot CLI session
  20. GitHub Copilot CLI command reference
  21. Get an agent back on track (VS Code)
  22. Review and revert agent changes: chat checkpoints (VS Code)
  23. Reverting a pull request
  24. LLM05:2025 Improper Output Handling (OWASP GenAI Security Project)
  25. OS Command Injection Defense Cheat Sheet (OWASP)