Custom Tool Creation

Relevant source files

• apps/sim/app/api/billing/update-cost/route.ts
• apps/sim/app/api/function/execute/route.test.ts
• apps/sim/app/api/function/execute/route.ts
• apps/sim/app/api/wand/route.ts
• apps/sim/app/api/workflows/[id]/log/route.ts
• apps/sim/executor/dag/construction/paths.ts
• apps/sim/executor/handlers/function/function-handler.test.ts
• apps/sim/executor/handlers/function/function-handler.ts
• apps/sim/executor/utils/output-filter.ts
• apps/sim/executor/utils/start-block.test.ts
• apps/sim/executor/utils/start-block.ts
• apps/sim/executor/variables/resolver.ts
• apps/sim/executor/variables/resolvers/block.test.ts
• apps/sim/executor/variables/resolvers/block.ts
• apps/sim/executor/variables/resolvers/reference.ts
• apps/sim/lib/billing/core/usage-log.ts
• apps/sim/lib/core/security/input-validation.server.ts
• apps/sim/lib/core/security/input-validation.test.ts
• apps/sim/lib/core/security/input-validation.ts
• apps/sim/lib/execution/isolated-vm-worker.cjs
• apps/sim/lib/guardrails/validate_regex.ts
• apps/sim/lib/logs/execution/logger.test.ts
• apps/sim/lib/logs/execution/logger.ts
• apps/sim/lib/logs/execution/logging-factory.ts
• apps/sim/lib/logs/execution/logging-session.ts
• apps/sim/lib/logs/types.ts
• apps/sim/lib/webhooks/rss-polling-service.ts
• apps/sim/tools/function/execute.test.ts
• apps/sim/tools/function/execute.ts
• apps/sim/tools/function/types.ts
• apps/sim/tools/hubspot/list_lists.ts
• apps/sim/tools/index.test.ts
• apps/sim/tools/index.ts
• apps/sim/tools/perplexity/chat.ts
• apps/sim/tools/types.ts

Custom tools enable users to extend Sim Studio's functionality by writing JavaScript or Python code that executes within workflows. These tools integrate seamlessly with AI agents, allowing LLMs to discover and invoke user-defined functions as needed during workflow execution.

Overview

Custom tools are user-defined functions that can be stored in the database or defined inline within a block. They consist of:

• JSON Schema: OpenAI-compatible function schema defining parameters and descriptions apps/sim/tools/index.ts24-28
• Implementation Code: JavaScript or Python code executed in an isolated environment apps/sim/app/api/function/execute/route.ts8-15
• Execution Strategy: Fast local execution for simple JavaScript or sandboxed E2B execution for Python/complex JS apps/sim/app/api/function/execute/route.ts4-7

Visualizing the Tool Creation Pipeline

The following diagram bridges the user-facing "Natural Language Space" where tools are defined to the "Code Entity Space" where they are executed.

Tool Execution Data Flow

Sources: apps/sim/tools/index.ts1-34 apps/sim/app/api/function/execute/route.ts1-21 apps/sim/executor/variables/resolvers/block.ts22-47

---

Code Execution Environment

Sim Studio provides a multi-tier execution environment for custom tools, prioritizing speed while maintaining security.

Isolated VM (IVM)

For standard JavaScript code without external imports, the system uses a high-performance isolated Node.js VM.

• Process Management: Managed via executeInIsolatedVM which handles local sandboxed execution apps/sim/app/api/function/execute/route.ts7
• Secure Fetch: Provides a wrapped fetch that validates URLs against SSRF patterns using validateUrlWithDNS and secureFetchWithPinnedIP apps/sim/tools/index.ts8-10
• Worker Communication: Communicates with the isolated-vm-worker.cjs to execute code in a separate process apps/sim/lib/execution/isolated-vm-worker.cjs1-4

E2B Sandboxing

For Python code or JavaScript code containing import statements, the system delegates to E2B (External 2 Business) sandboxes.

• Language Support: Automatically detects CodeLanguage.Python or CodeLanguage.JavaScript apps/sim/app/api/function/execute/route.ts8
• Import Extraction: Uses the TypeScript compiler API in extractJavaScriptImports to parse and extract imports from user code to determine if sandboxing is required apps/sim/app/api/function/execute/route.ts41-107

Sources: apps/sim/app/api/function/execute/route.ts6-15 apps/sim/tools/index.ts8-12 apps/sim/app/api/function/execute/route.ts41-107

---

Tool Definition and Schema

Custom tools are defined using the ToolConfig interface. When a user creates a "Function" block, it leverages the function_execute tool.

Parameter Definition

Parameters are defined with metadata that controls UI rendering and LLM visibility:

• Parameter Merging: Parameters are merged and validated via validateRequiredParametersAfterMerge before execution apps/sim/tools/index.ts33-34
• Output Schema: Block outputs are structured based on the OutputSchema defined for the tool apps/sim/executor/variables/resolvers/block.ts10-11

Reference Resolution

Code within custom tools can reference workflow state using specific syntaxes:

• {{VAR_NAME}}: Workflow variables and environment variables apps/sim/app/api/function/execute/route.ts13-15
• Block Outputs: Resolved via the BlockResolver which maps block names to their execution outputs apps/sim/executor/variables/resolvers/block.ts22-35

Variable Resolution Architecture

Sources: apps/sim/executor/variables/resolvers/block.ts22-76 apps/sim/app/api/function/execute/route.ts9-15 apps/sim/tools/index.ts33-34

---

Data Flow: Execution API

The /api/function/execute route serves as the central entry point for all custom code execution.

Step	Component	Action
1	checkInternalAuth	Validates the request via internal JWT or session apps/sim/app/api/function/execute/route.ts3
2	extractJavaScriptImports	Parses JS code to see if it requires E2B (external modules) apps/sim/app/api/function/execute/route.ts41
3	executeInIsolatedVM	Executes standard JS in pooled worker processes apps/sim/app/api/function/execute/route.ts7
4	executeInE2B	Executes Python or JS with imports in a secure remote sandbox apps/sim/app/api/function/execute/route.ts6
5	extractEnhancedError	Maps VM/Sandbox stack traces back to user-provided code line numbers apps/sim/app/api/function/execute/route.ts125-204

Sources: apps/sim/app/api/function/execute/route.ts1-204 apps/sim/tools/index.ts1-20

---

Security and Validation

To prevent VM escape and SSRF attacks, the system implements several layers of validation.

SSRF Protection

The secureFetchWithPinnedIP and validateUrlWithDNS functions ensure that code cannot access internal network resources or cloud metadata services apps/sim/tools/index.ts8-10

VM Hardening

• Context Stripping: Global objects like process, require, and module are explicitly set to undefined within the VM context to prevent access to the host system apps/sim/app/api/function/execute/route.test.ts82-85
• Constructor Blocking: Prevents escaping the sandbox via this.constructor.constructor patterns apps/sim/app/api/function/execute/route.test.ts72-76
• Rate Limiting: Hosted API keys used within tools are protected by getHostedKeyRateLimiter to prevent abuse apps/sim/tools/index.ts6-10

Sources: apps/sim/tools/index.ts8-10 apps/sim/app/api/function/execute/route.test.ts72-235 apps/sim/lib/execution/isolated-vm-worker.cjs146-200

---

Implementation Example: Hosted Key Injection

Custom tools can securely use platform-provided API keys without exposing them to the user code directly.

This logic ensures that tools like serper_search or perplexity_chat can function out-of-the-box while maintaining strict billing and quota controls apps/sim/tools/index.ts49-137

Sources: apps/sim/tools/index.ts49-137 apps/sim/tools/index.test.ts171-178