Tools

Runtime tools

Runtime tools are tool definitions passed inline with a dispatch API request, without saving them to the platform first. They support the same execution types as saved tools.

When to use runtime tools

  • SDK-driven workflows that need dynamic tool definitions
  • Temporary tools that do not need to persist in the database
  • Testing tool configurations before saving them
  • Self-referential tools (e.g., an Agent calling the Runtype API itself)

Tool types

Runtime tools support five types:

External

Call any HTTP API. Configure the URL, method, headers, and body with {{parameter}} template variables.

1{
2  "name": "get_weather",
3  "description": "Get current weather for a city",
4  "toolType": "external",
5  "parametersSchema": {
6    "type": "object",
7    "properties": {
8      "city": { "type": "string" }
9    },
10    "required": ["city"]
11  },
12  "config": {
13    "url": "https://api.weather.com/v1/current?city={{city}}",
14    "method": "GET",
15    "headers": {
16      "authorization": "Bearer {{secrets.api_key}}"
17    }
18  }
19}

Custom

Execute sandboxed JavaScript, TypeScript, or Python code.

1{
2  "name": "calculate_discount",
3  "description": "Calculate discount percentage",
4  "toolType": "custom",
5  "parametersSchema": {
6    "type": "object",
7    "properties": {
8      "price": { "type": "number" },
9      "discount": { "type": "number" }
10    },
11    "required": ["price", "discount"]
12  },
13  "config": {
14    "code": "return { discounted_price: price * (1 - discount / 100) }",
15    "timeout": 5000,
16    "language": "javascript"
17  }
18}

Flow

Execute another saved Runtype Flow as a tool.

1{
2  "name": "analyze_sentiment",
3  "description": "Run sentiment analysis flow",
4  "toolType": "flow",
5  "parametersSchema": {
6    "type": "object",
7    "properties": {
8      "text": { "type": "string" }
9    },
10    "required": ["text"]
11  },
12  "config": {
13    "flowId": "flow_abc123",
14    "parameterMapping": { "input_text": "text" },
15    "outputMapping": "sentiment_result"
16  }
17}

Subagent

Spawn a focused child agent with its own context window and a restricted tool subset. The child runs in isolation — it cannot see the parent’s conversation — and only its final result returns to the parent. This keeps the parent’s context clean for a narrow sub-task that may take several tool calls.

Subagents come in three forms:

  • Saved — point at an existing agent by agentId. The saved agent is org-scoped and ownership-checked.
  • Inline — define the child agent’s shape directly in the tool’s agent field, with no saved agent. Set exactly one of agentId or agent.
  • Dynamic — let the parent agent decide at runtime what to delegate. See dynamic subagents below.
1{
2  "name": "research_topic",
3  "description": "Spawn a research subagent",
4  "toolType": "subagent",
5  "parametersSchema": {
6    "type": "object",
7    "properties": {
8      "task": { "type": "string" }
9    },
10    "required": ["task"]
11  },
12  "config": {
13    "agentId": "agent_abc123",
14    "allowedTools": ["builtin:exa", "builtin:firecrawl"],
15    "maxTurns": 5,
16    "outputFormat": "text"
17  }
18}

allowedTools is required and is intersected with the parent’s available tools, so the child can never use a tool the parent itself lacks (no privilege escalation). Use wildcards like mcp:* or builtin:*, or an empty array [] for a model-only child.

FieldDefaultDescription
agentId—Saved agent to run as the child. Set this or agent, not both.
agent—Inline agent definition (runtime export shape).
allowedToolsrequiredTool IDs the child may use. Subset of the parent’s tools.
maxTurns5Maximum agent-loop iterations for the child.
maxCostparent’s remaining budgetSpend cap for the child; its cost rolls up into the parent.
timeoutMs300000 (5 min)Time limit for the whole child run.
outputFormattextHow the result returns: text, json, or last_message.
inheritMessagesfalseWhen true, the parent’s current messages seed the child’s context.
taskTemplate—Template the child’s first user message from the parent’s tool-call parameters (e.g. {{topic}}).

Dynamic subagents (spawn_subagent)

Instead of pre-defining a child, you can let an agent spin off focused subagents on its own. Add a subagentConfig to the agent’s tools configuration and Runtype adds a built-in spawn_subagent tool that the model can call, choosing the task, the tools to grant, and an optional system prompt at runtime.

1{
2  "subagentConfig": {
3    "toolPool": ["builtin:exa", "mcp:linear:*"],
4    "defaultMaxTurns": 5,
5    "maxTurnsLimit": 10,
6    "maxSpawnsPerRun": 5,
7    "allowNesting": false
8  }
9}
FieldDefaultDescription
toolPoolrequiredTools the parent may grant to spawned subagents. Subset of the parent’s tools.
defaultMaxTurns5Default turn cap per spawned subagent.
maxTurnsLimit10Hard ceiling the model cannot exceed.
maxSpawnsPerRun5Maximum subagents per parent run.
defaultModelparent’s modelModel used for spawned subagents.
allowNestingfalseWhether a subagent may itself spawn subagents.
defaultTimeoutMs300000 (5 min)Default time limit per spawned subagent.

The model grants only tools from toolPool, and that pool is itself a subset of the parent’s resolved tools — the same no-escalation rule applies. By default subagents cannot spawn their own subagents.

Local

Local tools run on the calling client, not on Runtype. When the model calls one, the run pauses and surfaces the tool call to your SDK client (the dashboard, CLI, or Persona widget), which executes it out-of-band and resumes the run with the result. Runtype never resolves a local tool server-side. Use them for actions only the client can perform — prompting the end user, reading local state, or anything that must happen in the caller’s environment.

1{
2  "name": "ask_user",
3  "description": "Ask the end user a clarifying question",
4  "toolType": "local",
5  "parametersSchema": {
6    "type": "object",
7    "properties": {
8      "question": { "type": "string" }
9    },
10    "required": ["question"]
11  }
12}

Passing runtime tools in a dispatch request

Include runtime tools in the tools.runtimeTools array on a prompt step:

1{
2  "flow": {
3    "name": "My Assistant",
4    "steps": [
5      {
6        "id": "step-1",
7        "type": "prompt",
8        "name": "Assistant",
9        "order": 1,
10        "enabled": true,
11        "config": {
12          "model": "gpt-5.4-mini",
13          "systemPrompt": "You are a helpful assistant.",
14          "tools": {
15            "runtimeTools": [
16              {
17                "name": "search_web",
18                "description": "Search the web",
19                "toolType": "external",
20                "parametersSchema": {
21                  "type": "object",
22                  "properties": {
23                    "query": { "type": "string" }
24                  },
25                  "required": ["query"]
26                },
27                "config": {
28                  "url": "https://api.search.com/search?q={{query}}",
29                  "method": "GET"
30                }
31              }
32            ]
33          }
34        }
35      }
36    ]
37  },
38  "options": {
39    "streamResponse": true,
40    "flowMode": "virtual"
41  }
42}

Runtime tools can be combined with saved tools and built-in tools in the same step:

1{
2  "tools": {
3    "toolIds": ["tool_abc123", "builtin:exa"],
4    "runtimeTools": [
5      { "name": "my_runtime_tool", "..." : "..." }
6    ]
7  }
8}

Secrets

Runtime tools can reference credentials passed in the secrets field of the dispatch request. Secrets are never logged or returned in responses.

1{
2  "secrets": {
3    "api_key": "your-api-key"
4  }
5}

Reference them in tool configs with {{secrets.key_name}}.

Limits

LimitValue
Max runtime tools per request50 (across all steps)
Timeout (custom code tools)30 seconds

Next steps