Runtime Tools

Runtime tools let you define tools directly in dispatch requests, without saving them to your account first. This is useful for dynamic tool configurations, testing, and multi-tenant applications.

When to Use Runtime Tools

Use Case	Description
Testing	Try tool configurations before saving
Dynamic configs	Tool URLs/params vary per request
User-provided	Users supply their own tool definitions
One-off tasks	Tools needed for a single execution

Basic Example

TypeScript SDK

1 import { FlowBuilder, RuntypeClient } from '@runtypelabs/sdk'
2 
3 const client = new RuntypeClient({
4   apiKey: process.env.RUNTYPE_API_KEY
5 })
6 
7 const result = await new FlowBuilder()
8   .createFlow({ name: 'Weather Agent' })
9   .prompt({
10     name: 'Agent',
11     model: 'gpt-4o',
12     userPrompt: 'What is the weather in Tokyo?',
13     tools: {
14       runtimeTools: [{
15         name: 'get_weather',
16         description: 'Get current weather for a city',
17         toolType: 'external',
18         parametersSchema: {
19           type: 'object',
20           properties: {
21             city: { type: 'string', description: 'City name' }
22           },
23           required: ['city']
24         },
25         config: {
26           url: 'https://api.weather.com/v1/current?city={{city}}',
27           method: 'GET',
28           headers: {
29             'Authorization': 'Bearer {{secrets.weather_key}}'
30           }
31         }
32       }]
33     }
34   })
35   .run(client, { streamResponse: true })

Python SDK

1 runtime_tool = {
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", "description": "City name"}
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.weather_key}}"
17         }
18     }
19 }
20 
21 for event in client.dispatch({
22     "flow": {
23         "steps": [{
24             "type": "prompt",
25             "config": {
26                 "model": "gpt-4o",
27                 "userPrompt": "What is the weather in Tokyo?",
28                 "tools": {
29                     "runtimeTools": [runtime_tool]
30                 }
31             }
32         }]
33     },
34     "secrets": {
35         "weather_key": os.environ["WEATHER_API_KEY"]
36     }
37 }):
38     print(event)

cURL

$ curl https://api.runtype.com/v1/dispatch \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "flow": {
>       "steps": [{
>         "type": "prompt",
>         "config": {
>           "model": "gpt-4o",
>           "userPrompt": "What is the weather in Tokyo?",
>           "tools": {
>             "runtimeTools": [{
>               "name": "get_weather",
>               "description": "Get current weather for a city",
>               "toolType": "external",
>               "parametersSchema": {
>                 "type": "object",
>                 "properties": {
>                   "city": {"type": "string"}
>                 },
>                 "required": ["city"]
>               },
>               "config": {
>                 "url": "https://api.weather.com/v1/current?city={{city}}",
>                 "method": "GET"
>               }
>             }]
>           }
>         }
>       }]
>     }
>   }'

Tool Types

Runtime tools support the same types as saved tools:

External Tools

Call any HTTP API:

1 {
2   name: 'fetch_user',
3   description: 'Fetch user details by ID',
4   toolType: 'external',
5   parametersSchema: {
6     type: 'object',
7     properties: {
8       userId: { type: 'string' }
9     },
10     required: ['userId']
11   },
12   config: {
13     url: 'https://api.example.com/users/{{userId}}',
14     method: 'GET',
15     headers: {
16       'Authorization': 'Bearer {{secrets.api_token}}'
17     }
18   }
19 }

Custom Tools (Code)

Execute JavaScript in a secure sandbox:

1 {
2   name: 'calculate_tax',
3   description: 'Calculate sales tax',
4   toolType: 'custom',
5   parametersSchema: {
6     type: 'object',
7     properties: {
8       amount: { type: 'number' },
9       rate: { type: 'number' }
10     },
11     required: ['amount', 'rate']
12   },
13   config: {
14     code: `
15       const tax = amount * (rate / 100);
16       return {
17         subtotal: amount,
18         tax: tax.toFixed(2),
19         total: (amount + tax).toFixed(2)
20       };
21     `,
22     timeout: 5000
23   }
24 }

Flow Tools

Execute another Runtype flow as a tool:

1 {
2   name: 'analyze_sentiment',
3   description: 'Run sentiment analysis on text',
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'
16   }
17 }

Passing Secrets

Use the secrets field for sensitive values:

1 const result = await client.dispatch({
2   flow: { ... },
3   secrets: {
4     api_token: process.env.EXTERNAL_API_KEY,
5     db_password: process.env.DB_PASSWORD
6   }
7 })

Reference in tool config: {{secrets.api_token}}

Secrets are never logged, stored, or returned in API responses.

Variable Substitution

Tool configurations support template variables:

Variable	Source
`{{paramName}}`	Tool call parameter
`{{secrets.keyName}}`	Dispatch secrets field
`{{_record.field}}`	Current record data
`{{_flow.id}}`	Flow metadata

Example:

1 config: {
2   url: 'https://api.example.com/{{_record.type}}/{{id}}',
3   headers: {
4     'Authorization': 'Bearer {{secrets.token}}',
5     'X-User-Id': '{{_user.id}}'
6   }
7 }

Combining with Saved Tools

Mix runtime tools with saved tools:

1 tools: {
2   // Saved tools by ID
3   toolIds: [
4     'tool_abc123',
5     'mcp:notion:create_page'
6   ],
7   // Runtime tools
8   runtimeTools: [
9     { name: 'dynamic_tool', ... }
10   ],
11   maxToolCalls: 10
12 }

SDK Helper Functions

The TypeScript SDK provides helper functions:

1 import { createExternalTool } from '@runtypelabs/sdk'
2 
3 const weatherTool = createExternalTool({
4   name: 'get_weather',
5   description: 'Get weather for a city',
6   parametersSchema: {
7     type: 'object',
8     properties: {
9       city: { type: 'string' }
10     }
11   },
12   url: 'https://api.weather.com/current?city={{city}}',
13   method: 'GET',
14   headers: {
15     'Authorization': 'Bearer {{secrets.key}}'
16   }
17 })
18 
19 // Use in flow
20 tools: { runtimeTools: [weatherTool] }

Limits

Limit	Value
Runtime tools per step	10
Total runtime tools per request	50
Custom tool timeout	30 seconds

API Format

The API uses camelCase for all field names:

1 {
2   "tools": {
3     "runtimeTools": [{
4       "name": "myTool",
5       "toolType": "external",
6       "parametersSchema": { ... },
7       "config": { ... }
8     }]
9   }
10 }

Best Practices

Save frequently-used tools

If you use the same runtime tool repeatedly, save it to your account via the API or dashboard for cleaner code.

Use lowercase headers

Use lowercase header names (e.g., authorization not Authorization) to avoid issues with automatic case conversion.

Test before production

Use runtime tools to test configurations, then save working tools for production use.

Validate schemas

Ensure parametersSchema is valid JSON Schema. Invalid schemas cause tool calls to fail.

Next Steps

Working with Tools

Complete tools overview

MCP Servers

Runtime MCP server configuration

Tools API

Tools endpoint reference

Building Flows

Create flows with tools

Runtime Tools

Runtime tools let you define tools directly in dispatch requests, without saving them to your account first. This is useful for dynamic tool configurations, testing, and multi-tenant applications.

When to Use Runtime Tools

Use Case	Description
Testing	Try tool configurations before saving
Dynamic configs	Tool URLs/params vary per request
User-provided	Users supply their own tool definitions
One-off tasks	Tools needed for a single execution

Basic Example

TypeScript SDK

1 import { FlowBuilder, RuntypeClient } from '@runtypelabs/sdk'
2 
3 const client = new RuntypeClient({
4   apiKey: process.env.RUNTYPE_API_KEY
5 })
6 
7 const result = await new FlowBuilder()
8   .createFlow({ name: 'Weather Agent' })
9   .prompt({
10     name: 'Agent',
11     model: 'gpt-4o',
12     userPrompt: 'What is the weather in Tokyo?',
13     tools: {
14       runtimeTools: [{
15         name: 'get_weather',
16         description: 'Get current weather for a city',
17         toolType: 'external',
18         parametersSchema: {
19           type: 'object',
20           properties: {
21             city: { type: 'string', description: 'City name' }
22           },
23           required: ['city']
24         },
25         config: {
26           url: 'https://api.weather.com/v1/current?city={{city}}',
27           method: 'GET',
28           headers: {
29             'Authorization': 'Bearer {{secrets.weather_key}}'
30           }
31         }
32       }]
33     }
34   })
35   .run(client, { streamResponse: true })

Python SDK

1 runtime_tool = {
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", "description": "City name"}
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.weather_key}}"
17         }
18     }
19 }
20 
21 for event in client.dispatch({
22     "flow": {
23         "steps": [{
24             "type": "prompt",
25             "config": {
26                 "model": "gpt-4o",
27                 "userPrompt": "What is the weather in Tokyo?",
28                 "tools": {
29                     "runtimeTools": [runtime_tool]
30                 }
31             }
32         }]
33     },
34     "secrets": {
35         "weather_key": os.environ["WEATHER_API_KEY"]
36     }
37 }):
38     print(event)

cURL

$ curl https://api.runtype.com/v1/dispatch \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "flow": {
>       "steps": [{
>         "type": "prompt",
>         "config": {
>           "model": "gpt-4o",
>           "userPrompt": "What is the weather in Tokyo?",
>           "tools": {
>             "runtimeTools": [{
>               "name": "get_weather",
>               "description": "Get current weather for a city",
>               "toolType": "external",
>               "parametersSchema": {
>                 "type": "object",
>                 "properties": {
>                   "city": {"type": "string"}
>                 },
>                 "required": ["city"]
>               },
>               "config": {
>                 "url": "https://api.weather.com/v1/current?city={{city}}",
>                 "method": "GET"
>               }
>             }]
>           }
>         }
>       }]
>     }
>   }'

Tool Types

Runtime tools support the same types as saved tools:

External Tools

Call any HTTP API:

1 {
2   name: 'fetch_user',
3   description: 'Fetch user details by ID',
4   toolType: 'external',
5   parametersSchema: {
6     type: 'object',
7     properties: {
8       userId: { type: 'string' }
9     },
10     required: ['userId']
11   },
12   config: {
13     url: 'https://api.example.com/users/{{userId}}',
14     method: 'GET',
15     headers: {
16       'Authorization': 'Bearer {{secrets.api_token}}'
17     }
18   }
19 }

Custom Tools (Code)

Execute JavaScript in a secure sandbox:

1 {
2   name: 'calculate_tax',
3   description: 'Calculate sales tax',
4   toolType: 'custom',
5   parametersSchema: {
6     type: 'object',
7     properties: {
8       amount: { type: 'number' },
9       rate: { type: 'number' }
10     },
11     required: ['amount', 'rate']
12   },
13   config: {
14     code: `
15       const tax = amount * (rate / 100);
16       return {
17         subtotal: amount,
18         tax: tax.toFixed(2),
19         total: (amount + tax).toFixed(2)
20       };
21     `,
22     timeout: 5000
23   }
24 }

Flow Tools

Execute another Runtype flow as a tool:

1 {
2   name: 'analyze_sentiment',
3   description: 'Run sentiment analysis on text',
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'
16   }
17 }

Passing Secrets

Use the secrets field for sensitive values:

1 const result = await client.dispatch({
2   flow: { ... },
3   secrets: {
4     api_token: process.env.EXTERNAL_API_KEY,
5     db_password: process.env.DB_PASSWORD
6   }
7 })

Reference in tool config: {{secrets.api_token}}

Secrets are never logged, stored, or returned in API responses.

Variable Substitution

Tool configurations support template variables:

Variable	Source
`{{paramName}}`	Tool call parameter
`{{secrets.keyName}}`	Dispatch secrets field
`{{_record.field}}`	Current record data
`{{_flow.id}}`	Flow metadata

Example:

1 config: {
2   url: 'https://api.example.com/{{_record.type}}/{{id}}',
3   headers: {
4     'Authorization': 'Bearer {{secrets.token}}',
5     'X-User-Id': '{{_user.id}}'
6   }
7 }

Combining with Saved Tools

Mix runtime tools with saved tools:

1 tools: {
2   // Saved tools by ID
3   toolIds: [
4     'tool_abc123',
5     'mcp:notion:create_page'
6   ],
7   // Runtime tools
8   runtimeTools: [
9     { name: 'dynamic_tool', ... }
10   ],
11   maxToolCalls: 10
12 }

SDK Helper Functions

The TypeScript SDK provides helper functions:

1 import { createExternalTool } from '@runtypelabs/sdk'
2 
3 const weatherTool = createExternalTool({
4   name: 'get_weather',
5   description: 'Get weather for a city',
6   parametersSchema: {
7     type: 'object',
8     properties: {
9       city: { type: 'string' }
10     }
11   },
12   url: 'https://api.weather.com/current?city={{city}}',
13   method: 'GET',
14   headers: {
15     'Authorization': 'Bearer {{secrets.key}}'
16   }
17 })
18 
19 // Use in flow
20 tools: { runtimeTools: [weatherTool] }

Limits

Limit	Value
Runtime tools per step	10
Total runtime tools per request	50
Custom tool timeout	30 seconds

API Format

The API uses camelCase for all field names:

1 {
2   "tools": {
3     "runtimeTools": [{
4       "name": "myTool",
5       "toolType": "external",
6       "parametersSchema": { ... },
7       "config": { ... }
8     }]
9   }
10 }

Best Practices

Save frequently-used tools

If you use the same runtime tool repeatedly, save it to your account via the API or dashboard for cleaner code.

Use lowercase headers

Use lowercase header names (e.g., authorization not Authorization) to avoid issues with automatic case conversion.

Test before production

Use runtime tools to test configurations, then save working tools for production use.

Validate schemas

Ensure parametersSchema is valid JSON Schema. Invalid schemas cause tool calls to fail.

Next Steps

Working with Tools

Complete tools overview

MCP Servers

Runtime MCP server configuration

Tools API

Tools endpoint reference

Building Flows

Create flows with tools

1	import { FlowBuilder, RuntypeClient } from '@runtypelabs/sdk'
2
3	const client = new RuntypeClient({
4	apiKey: process.env.RUNTYPE_API_KEY
5	})
6
7	const result = await new FlowBuilder()
8	.createFlow({ name: 'Weather Agent' })
9	.prompt({
10	name: 'Agent',
11	model: 'gpt-4o',
12	userPrompt: 'What is the weather in Tokyo?',
13	tools: {
14	runtimeTools: [{
15	name: 'get_weather',
16	description: 'Get current weather for a city',
17	toolType: 'external',
18	parametersSchema: {
19	type: 'object',
20	properties: {
21	city: { type: 'string', description: 'City name' }
22	},
23	required: ['city']
24	},
25	config: {
26	url: 'https://api.weather.com/v1/current?city={{city}}',
27	method: 'GET',
28	headers: {
29	'Authorization': 'Bearer {{secrets.weather_key}}'
30	}
31	}
32	}]
33	}
34	})
35	.run(client, { streamResponse: true })

1	runtime_tool = {
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", "description": "City name"}
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.weather_key}}"
17	}
18	}
19	}
20
21	for event in client.dispatch({
22	"flow": {
23	"steps": [{
24	"type": "prompt",
25	"config": {
26	"model": "gpt-4o",
27	"userPrompt": "What is the weather in Tokyo?",
28	"tools": {
29	"runtimeTools": [runtime_tool]
30	}
31	}
32	}]
33	},
34	"secrets": {
35	"weather_key": os.environ["WEATHER_API_KEY"]
36	}
37	}):
38	print(event)

$	curl https://api.runtype.com/v1/dispatch \
>	-H "Authorization: Bearer YOUR_API_KEY" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"flow": {
>	"steps": [{
>	"type": "prompt",
>	"config": {
>	"model": "gpt-4o",
>	"userPrompt": "What is the weather in Tokyo?",
>	"tools": {
>	"runtimeTools": [{
>	"name": "get_weather",
>	"description": "Get current weather for a city",
>	"toolType": "external",
>	"parametersSchema": {
>	"type": "object",
>	"properties": {
>	"city": {"type": "string"}
>	},
>	"required": ["city"]
>	},
>	"config": {
>	"url": "https://api.weather.com/v1/current?city={{city}}",
>	"method": "GET"
>	}
>	}]
>	}
>	}
>	}]
>	}
>	}'

1	{
2	name: 'fetch_user',
3	description: 'Fetch user details by ID',
4	toolType: 'external',
5	parametersSchema: {
6	type: 'object',
7	properties: {
8	userId: { type: 'string' }
9	},
10	required: ['userId']
11	},
12	config: {
13	url: 'https://api.example.com/users/{{userId}}',
14	method: 'GET',
15	headers: {
16	'Authorization': 'Bearer {{secrets.api_token}}'
17	}
18	}
19	}

1	{
2	name: 'calculate_tax',
3	description: 'Calculate sales tax',
4	toolType: 'custom',
5	parametersSchema: {
6	type: 'object',
7	properties: {
8	amount: { type: 'number' },
9	rate: { type: 'number' }
10	},
11	required: ['amount', 'rate']
12	},
13	config: {
14	code: `
15	const tax = amount * (rate / 100);
16	return {
17	subtotal: amount,
18	tax: tax.toFixed(2),
19	total: (amount + tax).toFixed(2)
20	};
21	`,
22	timeout: 5000
23	}
24	}

1	{
2	name: 'analyze_sentiment',
3	description: 'Run sentiment analysis on text',
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'
16	}
17	}

1	const result = await client.dispatch({
2	flow: { ... },
3	secrets: {
4	api_token: process.env.EXTERNAL_API_KEY,
5	db_password: process.env.DB_PASSWORD
6	}
7	})

1	config: {
2	url: 'https://api.example.com/{{_record.type}}/{{id}}',
3	headers: {
4	'Authorization': 'Bearer {{secrets.token}}',
5	'X-User-Id': '{{_user.id}}'
6	}
7	}

1	tools: {
2	// Saved tools by ID
3	toolIds: [
4	'tool_abc123',
5	'mcp:notion:create_page'
6	],
7	// Runtime tools
8	runtimeTools: [
9	{ name: 'dynamic_tool', ... }
10	],
11	maxToolCalls: 10
12	}

1	import { createExternalTool } from '@runtypelabs/sdk'
2
3	const weatherTool = createExternalTool({
4	name: 'get_weather',
5	description: 'Get weather for a city',
6	parametersSchema: {
7	type: 'object',
8	properties: {
9	city: { type: 'string' }
10	}
11	},
12	url: 'https://api.weather.com/current?city={{city}}',
13	method: 'GET',
14	headers: {
15	'Authorization': 'Bearer {{secrets.key}}'
16	}
17	})
18
19	// Use in flow
20	tools: { runtimeTools: [weatherTool] }

1	{
2	"tools": {
3	"runtimeTools": [{
4	"name": "myTool",
5	"toolType": "external",
6	"parametersSchema": { ... },
7	"config": { ... }
8	}]
9	}
10	}