Purpose: This document covers the block and tool system, which provides the integration framework for connecting workflows to external services and capabilities. Blocks are reusable workflow components that expose tools (functions) for AI agents to call. This page explains the registry architecture, block configuration, tool execution, and how blocks integrate with the execution engine.
Related pages:
The blocks and tools system follows a two-tier registry pattern: BlockConfig objects define workflow components with UI configuration (SubBlocks), while tool functions provide the executable capabilities that agents call at runtime.
The following diagram bridges the high-level workflow concepts to the specific TypeScript entities that define them.
Sources: apps/sim/blocks/registry.ts1-127 apps/sim/tools/registry.ts1-100 apps/sim/lib/oauth/oauth.ts57-60
The block registry is a centralized mapping of block types to their configurations. Each entry maps a string identifier to a BlockConfig object. The system supports hundreds of unique block types, from AI providers like AgentBlock to integrations like AirtableBlock or GitHubV2Block.
Key Registry Logic:
The registry handles versioning by appending suffixes like _v2 or _v3 to block types (e.g., MistralParseV3Block). The getLatestBlock function uses regex to find the highest version available for a base block name.
Sources: apps/sim/blocks/registry.ts1-150 apps/sim/blocks/registry.ts115-119
The tool registry exports a massive collection of individual tool functions. These tools are the actual executable logic that interacts with external APIs. There are over 200 integrated services represented.
Tool Categories:
| Category | Example Tools | Source File |
|---|---|---|
| CRM | apolloContactSearchTool, hubspotGetCompanyTool | apps/sim/tools/registry.ts64-89 |
| Storage | boxUploadFileTool, dropboxListFolderTool | apps/sim/tools/registry.ts172-182 |
| A2A | a2aSendMessageTool, a2aGetTaskTool | apps/sim/tools/registry.ts2-10 |
| SEO | ahrefsDomainRatingTool, ahrefsBacklinksTool | apps/sim/tools/registry.ts12-20 |
Sources: apps/sim/tools/registry.ts1-300 apps/docs/content/docs/en/tools/meta.json1-180
Tool execution is managed by the executeTool function, which handles credential resolution, parameter merging, and rate limiting.
injectHostedKeyIfNeeded apps/sim/tools/index.ts49-137recordUsage and checked against overage thresholds apps/sim/app/api/billing/update-cost/route.ts103-124validateUrlWithDNS and secureFetchWithPinnedIP apps/sim/tools/index.ts7-10Sources: apps/sim/tools/index.ts1-150 apps/sim/app/api/billing/update-cost/route.ts13-22
SubBlocks define the visual fields in the block configuration panel. They handle input types ranging from simple text to complex relational selectors.
visibility flags (e.g., user-only, llm-only).ToolInput component in the UI renders these based on the block's schema.Sources: apps/sim/app/api/wand/route.ts76-93 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:26-46
The system uses a hierarchical OAuth provider model. A "Base Provider" (like Google) can support multiple "Services" (like Gmail, Drive, Sheets), each with its own specific scopes.
This diagram shows how the system bridges OAuth configurations to the user's workspace credentials.
Key Components:
Sources: apps/sim/lib/oauth/oauth.ts57-210 apps/sim/lib/oauth/types.ts1-145
Each block is visually identified by an icon and has associated documentation generated for the integrated docs system.
apps/sim/components/icons.tsx (e.g., AgentIcon, ApiIcon, ConditionalIcon) apps/sim/components/icons.tsx24-98blockTypeToIconMap provides a lookup for the UI to render the correct SVG for a given block type apps/docs/components/ui/icon-mapping.ts185-310integrations.json file contains marketing and technical metadata for all external tools apps/sim/app/(landing)/integrations/data/integrations.json1-186Sources: apps/sim/components/icons.tsx1-125 apps/docs/components/ui/icon-mapping.ts184-310 apps/sim/app/(landing)/integrations/data/integrations.json1-186