AgentKit Studio
Runtimes and deployment

Degradation and retry

How resource bindings, MCP sessions, and model calls recover from failure — and which recovery paths are proposals rather than shipped behaviour.

A failed resource recovery is a policy choice, not a fatal error. One flaky MCP server must not take the whole Agent down, so the default behaviour is "degrade and keep going"; a deployment that would rather refuse a turn than run with fewer tools can opt into strict mode.

How this page is written

Every section is labelled. Shipped claims point at a line in src/**. Proposal sections describe design intent with no implementation in the current code — do not integrate against them.

The two strategies (shipped)

StrategyHow to enableBehaviourSource
Default: degradeNothing to configureA binding that failed to recover is left out of the tool set; the rest of the conversation and the model continuesrc/providers/dsh-runtime-plugin.mjs:219-233
Strict: refuseAGENTKIT_STRICT_RESOURCES=1Preset assembly fails outright and every turn is rejectedsrc/host/bootstrap.mjs:135

The strict switch accepts 1, true, yes or on, case-insensitively; anything else counts as off (src/host/bootstrap.mjs:135).

# Local Studio: process environment variable
AGENTKIT_STRICT_RESOURCES=1

# Cloud Agent: the same key under Advanced.EnvironmentVariables

Under strict mode the error code is always STUDIO_PRESET_RESOURCES_UNAVAILABLE, and message carries the resource detail in the form MCP/Tool <id>(<code>) or Skill <id>(<code>) (src/providers/dsh-runtime-plugin.mjs:224-233).

Reprobe schedule after degradation (shipped)

Degradation is not permanent. The Host re-probes at 30 seconds → 2 minutes → 10 minutes from the moment of degradation:

ItemValueSource
Checkpoints[30000, 120000, 600000] mssrc/agent-preset-admission.mjs:26
SemanticsOffsets from degradation; each timer waits only the gap to the previous checkpoint:246
Strict modeNever re-probes — it never degrades, so it needs no recovery path:240, :279
RecoveryLogs a console.info and swaps the placeholder for a ready registration:277-280
Scope teardownTimers are unref()ed so they never block process exit:252

The probe only exists after a degradation

A re-probe requires a placeholder carrying resourcesUnavailable in the registry. If the preset never degraded, this entire path never starts (src/agent-preset-admission.mjs:241-242).

MCP connection recovery (shipped)

BehaviourDetailSource
Single-flight connectConcurrent first connects share one promise; a generation counter stops a stale connection from overwriting a new onesrc/local-resource-adapters.mjs:191-225
Credential fingerprint isolationThe cache key hashes endpoint, transport, command, environment and sorted headers:181-185
Session expiry replays onceOn a definite session failure, retire the old connection, rebuild, and retry at most once:274-296
Tool errors are not retriedMCP_TOOL_FAILED is an application result, not a transport failure, and propagates:290-291
Writes are never auto-retriedAn unconfirmed memory write throws MEMORY_RESPONSE_UNKNOWN and asks you to verify:26
Retry classificationretryClass is pre_dispatch, session_expired or transport_ambiguous:282, :296-297

retryClass means: pre_dispatch never left the process, session_expired was rebuilt after a dead session, and transport_ambiguous was interrupted with unknown side effects — the last one must never be replayed blindly.

Observability (shipped)

Every real resource adapter call appends one durable, content-free studio/resource-check event:

FieldTypeMeaning
kindskill | skill-space | knowledge-base | memory-instanceResource kind
resourceIdstringMatches ^[A-Za-z0-9_.:-]{1,200}$
actionload | search | recall | writeAction
statussucceeded | failedOutcome
durationMs / hitCount / definitionCountnon-negative integer (optional)Quantities
acceptedboolean (optional)Whether it was accepted
codeupper-case code (optional)Matches ^[A-Z][A-Z0-9_]{0,100}$

Source: src/resource-checks.mjs:1-27. Anything outside that allowlist is dropped — this event never leaks query text or returned content.

Error classification (shipped)

CodeTriggerRetryable
MCP_CONNECT_FAILEDConnection failedYes (next probe)
MCP_AUTH_FAILEDHTTP 401No, update credentials
MCP_PERMISSION_DENIEDHTTP 403No, fix permissions
MCP_ENDPOINT_NOT_FOUNDHTTP 404No, check the endpoint
MCP_TLS_FAILEDCertificate verification failedNo
MCP_SESSION_EXPIREDSession expiredYes, replayed once automatically
MCP_TOOL_DISCOVERY_FAILEDTool catalogue fetch failedYes
MCP_TOOL_FAILEDTool returned an errorNo (application result)
MCP_CREDENTIAL_MISSINGA declared header has no credentialNo, configure it in Host settings
MCP_JSON_CODEC_UNAVAILABLEClient lacks the exact JSON parser contractNo
MCP_AUTHORITY_INVALID / MCP_AUTHORITY_STALEInvocation authority failed or went staleNo
MEMORY_RESPONSE_UNKNOWNMemory service did not confirmNo, verify by hand

Source: src/local-resource-adapters.mjs:95-126, :26, :65.

Proposals (not implemented)

None of the following exists in the code today

These are design intentions with no implementation, configuration key or API. Do not integrate against them and do not record them as accepted.

ProposalIntended shapeCurrent state
Manual retry entry pointA "retry this call" action on the resource status pageOnly automatic re-probes exist; there is no AGENTKIT_MCP_RETRY-style switch
Idempotency identityEvery resource call carries an IdempotencyKey so replay cannot duplicate side effectsOnly deployment, build and evaluation paths carry one; resource calls do not
Single absolute deadlineOne deadline per turn instead of per-layer timersToday budgets are layered: Codex idle/stream, 15-minute frozen runtime, 60-second MCP tool
safe-read recoveryRead-only tools may be replayed when side effects are uncertainreadOnly: false and concurrentSafe: false are hard-coded — unknown external effects never earn safe-read (src/providers/native-dsh-tools.mjs:952-954)
Resource events as first-class UI actionsResource check events drive page actionsThe event ships, but the UI only displays it

Never mask unknown side effects with a retry

When retryClass is transport_ambiguous, the remote side may already have executed. The correct response is to reconcile — read the current state back — not to send the call again. That constraint already holds before any of the proposals land.

Relationship to the transport layer (shipped)

Host-side fetch is pinned to Undici rather than Node's native fetch: on Node 22 the native path fails with UND_ERR_INVALID_ARG: invalid content-length header once the first web_fetch installs the legacy dispatcher. Resource RPC, model discovery, MCP transports and the Host-created model handler therefore share one implementation (src/http-fetch.mjs:1-5).

On this page