Tool Design Execution

On Runtype

• Read the platform guides first. get_platform_documentation(topic="operational-design") covers retries, idempotency, and choosing an execution mode. topic="limits" lists every time budget, and topic="subagent-delegation" covers detached subagents.

• Tool time limits. An external (HTTP) tool call is capped at 30 s. A custom tool defined inline in a dispatch request is rejected when its config.timeout is above 30000 ms. The Timeout (ms) field on a saved custom tool accepts up to 300000 ms. An MCP server timeout can be up to 300000 ms, but a call that holds the original request open is clamped to 30 s.

• Run budgets. A flow step gets 5 minutes by default and a flow 15 minutes. options.stepTimeoutMs goes up to 10 minutes and options.flowTimeoutMs up to 15 minutes. For a flow started with async: true (Prefer: respond-async over REST), both go up to 30 minutes. An execute-agent step gets only 30 s unless you raise its config.timeout, and that value is nested inside the step budget. One agent turn gets 5 minutes, or 30 minutes on durable execution, and config.durability.maxBudgetMs raises it up to 24 hours.

• Async job shape inside an agent. Use a subagent tool with config.execution.mode: "detached". The call returns a subagent_run handle (runId, status). notify sets what happens on completion: none only stores the result, and narrate (the default) posts a completion status into the parent conversation. narrate needs a saved parent agent and a conversationId. react (start a new parent turn) is rejected today, so use narrate or none. Bound the run with maxBudgetMs (up to 24 hours) and noProgressBudgetMs (a silence timeout that resets on progress). Runtype adds get_subagent_run, list_subagent_runs, and cancel_subagent_run automatically, so you do not write status or cancel tools. With narrate, completion arrives in the conversation, so the agent must not poll get_subagent_run in a loop. The dynamic spawn_subagent tool can run detached when config.tools.subagentConfig.executionModes includes "detached".

• Async job shape from outside. Start a flow or agent with run_flow, dispatch, or execute_agent with async: true, then poll get_execution_status with the returned execution id. After a timeout, poll instead of starting the run again. When a saved agent runs on durable execution, send an Idempotency-Key header on POST /v1/agents/{id}/execute or dispatch so a repeated request does not start a second run. The header is ignored on other runs.

• A flow tool is not async. The agent waits for the nested flow and gets its result, so the flow must finish inside the tool's budget.

• Waiting on an external job inside a flow. Use a wait-until step with poll: { http, intervalMs, maxAttempts, success }. The flow pauses without holding a connection. On durable execution Runtype caps the attempts at 1,000, so raise intervalMs for a longer wait. Keep the worst-case wait under 30 days, or the flow is rejected when you save it. Set continueOnTimeout: true when a timeout must not fail the flow.

• Idempotent records. Use upsert-record with recordType and a recordName built from a stable id that the caller supplies. A repeated call updates the same record instead of adding a duplicate.

• Isolate side effects. Put each side-effecting step (send-email, upsert-record, an api-call that changes data) in its own step, never in a step that can retry. A retry re-runs the failed step, and a resume after wait-until, crawl, or an approval pause re-enters the flow. For an external POST, pass the provider's idempotency key and check status after an ambiguous timeout before you retry.

• Platform retries. A tool-call step never retries a timeout, and it retries a tool that reports failure only when you set onError: "retry" or maxRetries (backoff up to 5 s between attempts). A step's errorHandling.fallbacks can also hold { "type": "retry", "delay": 2000 }. Turn either on only for a tool that is safe to retry.

• Compensation in flows. Context steps take errorHandling: { "onError": "fail" | "continue" | "fallback", "fallbacks": [...] }. fail stops the flow, continue substitutes defaultValue, and fallback runs the fallbacks chain in order. A chain entry is a retry, a step, or a flow, so a compensating step or flow can be the undo path:

  {
    "errorHandling": {
      "onError": "fallback",
      "fallbacks": [
        { "type": "flow", "flowId": "flow_refund_order", "inputs": { "orderId": "{{orderId}}" } }
      ]
    }
  }

  A tool-call step uses its own config.onError (default fail) instead. For the defaults when errorHandling is unset, see tool-design-errors. Flows have no cross-step transaction, so order the steps so the irreversible one runs last.

• Confirmation gate. List command tools that are not safe to retry in config.tools.approval.require. The approval timeout defaults to 300000 ms. An approval authorizes the action but does not make a retry safe. See tool-design-security for the full approval contract.

• Timeout errors from a tool reach the model as the tool's error. Name the async alternative in the tool description so the agent knows where to go.