Repository navigation
Unified error handling across the agent - #55
Conversation
There was a problem hiding this comment.
ℹ️ One low-impact edge case inline.
Reviewed changes This review covers the unified error-handling changes across the agent runtime, model/provider adapters, tools, skills, tests, and documentation.
- Error outcomes:
TerminalError,AgentTerminalError, and retryable errors now have consistent behavior across hooks, tools, nested agents, forks, journaled steps, and RPC. - Model recovery: Rejections and recoverable response problems become provisional model feedback; provider retry behavior, output limits, and usage accounting are updated.
- Validation and fallbacks: Tool batches and skill definitions receive stricter validation, invalid external skills are skipped, and compaction/depth-limit fallbacks are adjusted.
- Coverage and documentation: The PR adds error-path and RPC tests and updates examples and the Restate Agents references.
Important
This run used your free trial credits ($9.28 of $10 left) on GPT Luna, a fast, lightweight model. Connect a provider → to run the model you choose.
gpt-6-luna (free trial credits) | 𝕏
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes This incremental review covers the follow-up changes since the prior Pullfrog review.
- Skill validation: Reserved a skill name only after that skill passes validation, allowing a later valid entry to survive an invalid duplicate.
- Guardrail errors: Added
GuardrailErroras aToolError, classifying policy failures and rejections with guardrail-specific codes. - Progress reporting: Added
error-noteevents and forwarded sub-agent and fork progress through their parent tool calls. - Model retries: Changed the default attempt limit for journaled and AI SDK model calls to three attempts.
Important
This run used your free trial credits ($9.22 of $10 left) on GPT Luna, a fast, lightweight model. Connect a provider → to run the model you choose.
gpt-6-luna (free trial credits) | 𝕏

Unified error handling across the agent
Before this change, the code that caught an error decided what it meant. The same
TerminalErrorbecame atool_failedresult in a tool, aguardrail_failedresult inbeforeTool, and failed the whole run inbeforeStep. To predict whether an error stopped the agent, you had to know which code would catch it.Now the error's type decides the outcome, wherever the run throws it: in a tool, an
asyncTool, a handler a tool calls, a sub-agent, a fork, a guardrail, or a hook.TerminalError, includingToolErrorAgentTerminalErrorA
TerminalErrorgoes to the model because that lets tools compose without wrapping each other's errors, and lets the model react to a failure, for example by trying another approach after a timeout.AgentTerminalErrorstops the run from anywhere, so stopping never depends on where the error is caught. No configuration option changes what an error means.Cancellation is the exception to the first row. Restate's
CancelledErroris aTerminalError, but it propagates from every location and never reaches the model.Keep the meaning across journaled steps and RPC
A journaled step or an RPC rebuilds every failure as a plain
TerminalError. The message, status code and metadata survive, but the class does not.AgentTerminalErrorandToolErrortherefore store their meaning in the error's metadata (agentlib.kindandagentlib.code), and the run reads it from there.isAgentTerminal(error)performs the same check for handler code that receives errors over RPC.Error metadata requires Restate 1.6 or later. An integration test verifies that the metadata arrives intact over an RPC, both directly and through an intermediate handler.
What the model receives
A failed tool call is recorded as
{status: "error", code, message}, with theToolError's code ortool_failed. A rejection by a guardrail or an approver is recorded with statusdenied. The other calls in the batch keep running, so a failed call costs no extra step.A
TerminalErrorfrom anywhere else in the run reaches the model as a note, a user message from the runtime before the model's next call:{"source": "agent-runtime", "type": "error", "origin": "beforeStep", "code": "pii_detected", "message": "Remove the account number."}Notes are provisional: the model sees them for the rest of the run, but they are never saved to the conversation or returned in
result.messages.TerminalErroris thrownbeforeTool,afterTool, the tool'sbeforeandafter, approvals, and anything the tool callsbeforeRun, thrown or returned as a rejectioninstructionsfunction, orbeforeStepthrown or returned as a rejectionmaxOutputCharsafterRun, for a completed answerbeforeSteeringafterRunfor a stopped or interrupted result, the model call itself, loading or saving the conversation, listing skills, or theonProgresshandlerBreaking changes
Guardrails and hooks
TerminalErrorin a hook reaches the model. Thrown inbeforeRun, theinstructionsfunction,beforeStep, orafterRunfor a completed answer, it becomes a note instead of failing the run. InbeforeSteering, it rejects the steering message. To stop the run, throwAgentTerminalError.beforeRunorbeforeStepreturnsfalseor a reason, the model receives the reason with codedenied, instead of the run failing with aGuardrailError. A rejected input stays in the history, followed by the note. WhenafterRunrejects a completed answer, the model gets its answer back with the reason and another step, so write reasons the model can act on. Lesson 08 now does this.afterRunrejection of a stopped or interrupted result still fails the run, because no model step can follow. It now throws aToolErrorwith codedeniedinstead of aGuardrailError.guardrail_failedcode is removed. ATerminalErrorfrombeforeToolorafterToolis recorded astool_failed, or with theToolError's code, like a failure anywhere else in the tool call.Error classes
ToolErrornow extendsTerminalError. A remote handler can throw it without Restate retrying the child invocation, and its code reaches the calling agent's model. Its string code moved fromcodetotoolCode, becausecodeis the numeric status everyTerminalErrorhas. Readerror.toolCodewhere you readerror.codefrom aToolError.GuardrailError,AgentLimitErrorandModelProtocolErrorare removed.RunFailedErrorremains as a deprecated alias ofAgentTerminalError.Model calls
journaledModelandaiModelno longer default to three attempts, so a failing model call follows the invocation's retry policy, which pauses the invocation by default. InaiModel, a failure that retrying can't fix, such as a missing API key or a rejected request, pauses the invocation at once. Whenretry.maxAttemptsorretry.maxDurationis set, the call fails the run once its attempts run out, and an unfixable failure fails it immediately. Setretry.maxAttemptsin handlers whose callers wait for a response, such as chat handlers.usage.Mistakes in code are retryable
A terminal error would permanently fail an invocation that a deploy could fix. The SDK now throws a
TypeErrororRangeErrorfor these mistakes, so Restate retries the invocation until a fix is deployed:beforeStepmessages, or an empty replacement message;afterRunoutput that fails the output schema or exceedsmaxOutputChars;maxOutputChars.Two definition mistakes now fail when the code runs, usually at service startup:
skills()throws aTypeErrorfor a skill with an invalid name, an empty description or a duplicate name.agent()throws for invalid tool names and background handoff tools.Other changes
maxToolDepthfails alone with codedepth_limit, and the run continues. Before, it failed the run with anAgentLimitError.skills()no longer fails the run on an invalid skill. The run skips a skill with an invalid name, an empty description or a duplicate name, and logs a warning. Of two skills with the same name, it keeps the first, andloadreceives that one.AgentTerminalErrorwitherrorCode: 413is not a context overflow. Before, the run compacted the conversation and called the model again, and in a sub-agent the parent receivedtool_failed. This also applied toRunFailedErroron main.Forks
This branch is rebased on the fork tool from #54, and forks follow the same rules:
fork_limit,fork_nestedandfork_unavailable, areToolErrors, so the model receives them as tool results.AgentTerminalErrorin a fork fails the run it was started from.beforeRunandafterRun.Documentation
references/error-handling.mdin therestate-agentsskill explains the three outcomes, what the model receives from each location, error codes, RPC behavior, cancellation, and what a failed run keeps.SKILL.mdand the tools, guardrails, and models references link to it.CONTEXT.md, the other skill references and lesson 08 describe the new behavior.Testing
pnpm build: compile, lint, format and typecheck pass.pnpm test: 337 tests pass. The newerrors.test.tscovers each location above,AgentTerminalErrorfrom every site, anAgentTerminalErrorinside anasyncToolon replay, from a sub-agent and from a fork, anAgentTerminalErrorwith code 413, cancellation from every site, aTimeoutErrorin a tool, and depth limits.skills.test.tscoversskills()rejecting invalid and duplicate skills, and a custom source's duplicate loading the listed skill.pnpm test:integration: 72 tests pass, including error metadata over an RPC and a remote handler'sAgentTerminalErrorandToolErrorreaching an agent, directly and through a relay.🤖 Generated with Claude Code