From 18cee3dd7d56a7ec2eb5d034cce04290560334c7 Mon Sep 17 00:00:00 2001 From: William Chen Date: Fri, 5 Jun 2026 18:16:12 -0700 Subject: [PATCH] docs: reorganize into topic/ontology IA with a builder-first rewrite Restructure the English docs from internal product categories into a topic-based information architecture, and rewrite the conceptual pages to install a mental model first rather than enumerate features. Structure & navigation - Reorder the sidebar to follow how someone builds: Get Started -> Workflows -> Tables -> Files -> Knowledge Bases -> Logs -> Building agents -> Mothership -> Workspaces -> Platform -> Reference. - Demote the generated blocks/tools/triggers catalogs to a Reference section at the bottom. - Break up the monolithic execution/ folder into deployment/ and logs-debugging/; collapse connections/* and variables/* into single pages under workflows/. - Rename capabilities/ to building-agents/; relabel the integration catalog as "Integrations". Remove deprecated copilot and form deployment. Redirects added in next.config.ts for every moved URL. Conceptual rewrites - Workflows core (index, how-it-runs, data-flow, connections, variables): one mental model, one running example, terser prose. - New building-agents overview distinguishes an agent (a workflow you build) from an Agent block (one reasoning step), plus a "choosing what to use" guide. - Concept-trim passes on Knowledge Base, Tables, Blocks, Triggers overviews; new task pages for KB, Tables, and Files. - New code-verified Alerts page. Infrastructure - pageType frontmatter (concept/guide/reference) + badge render. - WorkflowPreview / OutputBundle components to embed real, app-styled workflow diagrams (adds framer-motion + reactflow to apps/docs). Co-Authored-By: Claude Opus 4.8 (1M context) --- apps/docs/app/[lang]/[[...slug]]/page.tsx | 6 +- apps/docs/components/page-type-badge.tsx | 44 ++ .../workflow-preview/block-icons.tsx | 85 +++ .../components/workflow-preview/examples.ts | 182 ++++++ .../docs/components/workflow-preview/index.ts | 13 + .../workflow-preview/output-bundle.tsx | 83 +++ .../workflow-preview/preview-block-node.tsx | 162 +++++ .../workflow-preview/workflow-data.ts | 114 ++++ .../workflow-preview/workflow-preview.tsx | 176 +++++ apps/docs/content/docs/en/blocks/index.mdx | 163 ++--- .../docs/en/building-agents/choosing.mdx | 73 +++ .../content/docs/en/building-agents/index.mdx | 72 +++ .../content/docs/en/connections/basics.mdx | 60 -- .../docs/en/connections/data-structure.mdx | 198 ------ .../content/docs/en/connections/index.mdx | 52 -- .../content/docs/en/connections/meta.json | 3 - .../docs/content/docs/en/connections/tags.mdx | 121 ---- apps/docs/content/docs/en/copilot/index.mdx | 59 -- .../content/docs/en/{execution => }/costs.mdx | 6 +- .../api-deployment.mdx => deployment/api.mdx} | 4 +- .../en/{execution => deployment}/chat.mdx | 2 +- .../docs/content/docs/en/deployment/index.mdx | 84 +++ .../mcp.mdx} | 2 +- .../docs/content/docs/en/deployment/meta.json | 4 + apps/docs/content/docs/en/execution/api.mdx | 606 ------------------ .../docs/content/docs/en/execution/basics.mdx | 109 ---- apps/docs/content/docs/en/execution/form.mdx | 136 ---- apps/docs/content/docs/en/execution/index.mdx | 170 ----- apps/docs/content/docs/en/execution/meta.json | 3 - .../docs/content/docs/en/files/generating.mdx | 68 ++ apps/docs/content/docs/en/files/index.mdx | 25 + .../files.mdx => files/passing-files.mdx} | 9 +- .../docs/en/files/using-in-workflows.mdx | 109 ++++ .../content/docs/en/getting-started/index.mdx | 4 +- apps/docs/content/docs/en/index.mdx | 6 +- .../content/docs/en/integrations/meta.json | 2 +- .../content/docs/en/introduction/index.mdx | 121 ++-- .../docs/en/keyboard-shortcuts/index.mdx | 84 ++- .../en/knowledgebase/chunking-strategies.mdx | 43 +- .../en/knowledgebase/debugging-retrieval.mdx | 95 +++ .../content/docs/en/knowledgebase/index.mdx | 143 +---- .../content/docs/en/knowledgebase/meta.json | 9 +- .../content/docs/en/knowledgebase/tags.mdx | 2 +- .../en/knowledgebase/using-in-workflows.mdx | 85 +++ .../content/docs/en/logs-debugging/alerts.mdx | 108 ++++ .../content/docs/en/logs-debugging/index.mdx | 91 +++ .../{execution => logs-debugging}/logging.mdx | 6 +- apps/docs/content/docs/en/mcp/index.mdx | 2 +- apps/docs/content/docs/en/meta.json | 77 ++- .../docs/content/docs/en/mothership/files.mdx | 2 +- .../docs/content/docs/en/mothership/index.mdx | 2 +- .../content/docs/en/mothership/knowledge.mdx | 2 +- .../docs/content/docs/en/mothership/tasks.mdx | 2 +- .../content/docs/en/mothership/workflows.mdx | 2 +- .../en/permissions/roles-and-permissions.mdx | 2 +- apps/docs/content/docs/en/skills/index.mdx | 2 +- apps/docs/content/docs/en/tables/index.mdx | 173 +---- .../docs/en/tables/using-in-workflows.mdx | 130 ++++ .../docs/en/tables/workflow-columns.mdx | 108 ++++ apps/docs/content/docs/en/tools/meta.json | 4 +- apps/docs/content/docs/en/triggers/index.mdx | 100 +-- apps/docs/content/docs/en/triggers/start.mdx | 9 +- apps/docs/content/docs/en/variables/index.mdx | 90 --- apps/docs/content/docs/en/variables/meta.json | 5 - .../docs/en/variables/workflow-variables.mdx | 164 ----- .../content/docs/en/workflows/connections.mdx | 158 +++++ .../content/docs/en/workflows/data-flow.mdx | 71 ++ .../content/docs/en/workflows/how-it-runs.mdx | 52 ++ apps/docs/content/docs/en/workflows/index.mdx | 83 +++ .../content/docs/en/workflows/variables.mdx | 110 ++++ .../docs/en/workspaces/fundamentals.mdx | 87 +++ .../docs/en/workspaces/organization.mdx | 78 +++ apps/docs/lib/source.ts | 4 + apps/docs/next.config.ts | 32 + apps/docs/package.json | 4 +- apps/docs/source.config.ts | 12 +- bun.lock | 2 + 77 files changed, 2969 insertions(+), 2402 deletions(-) create mode 100644 apps/docs/components/page-type-badge.tsx create mode 100644 apps/docs/components/workflow-preview/block-icons.tsx create mode 100644 apps/docs/components/workflow-preview/examples.ts create mode 100644 apps/docs/components/workflow-preview/index.ts create mode 100644 apps/docs/components/workflow-preview/output-bundle.tsx create mode 100644 apps/docs/components/workflow-preview/preview-block-node.tsx create mode 100644 apps/docs/components/workflow-preview/workflow-data.ts create mode 100644 apps/docs/components/workflow-preview/workflow-preview.tsx create mode 100644 apps/docs/content/docs/en/building-agents/choosing.mdx create mode 100644 apps/docs/content/docs/en/building-agents/index.mdx delete mode 100644 apps/docs/content/docs/en/connections/basics.mdx delete mode 100644 apps/docs/content/docs/en/connections/data-structure.mdx delete mode 100644 apps/docs/content/docs/en/connections/index.mdx delete mode 100644 apps/docs/content/docs/en/connections/meta.json delete mode 100644 apps/docs/content/docs/en/connections/tags.mdx delete mode 100644 apps/docs/content/docs/en/copilot/index.mdx rename apps/docs/content/docs/en/{execution => }/costs.mdx (99%) rename apps/docs/content/docs/en/{execution/api-deployment.mdx => deployment/api.mdx} (99%) rename apps/docs/content/docs/en/{execution => deployment}/chat.mdx (99%) create mode 100644 apps/docs/content/docs/en/deployment/index.mdx rename apps/docs/content/docs/en/{mcp/deploy-workflows.mdx => deployment/mcp.mdx} (99%) create mode 100644 apps/docs/content/docs/en/deployment/meta.json delete mode 100644 apps/docs/content/docs/en/execution/api.mdx delete mode 100644 apps/docs/content/docs/en/execution/basics.mdx delete mode 100644 apps/docs/content/docs/en/execution/form.mdx delete mode 100644 apps/docs/content/docs/en/execution/index.mdx delete mode 100644 apps/docs/content/docs/en/execution/meta.json create mode 100644 apps/docs/content/docs/en/files/generating.mdx create mode 100644 apps/docs/content/docs/en/files/index.mdx rename apps/docs/content/docs/en/{execution/files.mdx => files/passing-files.mdx} (97%) create mode 100644 apps/docs/content/docs/en/files/using-in-workflows.mdx create mode 100644 apps/docs/content/docs/en/knowledgebase/debugging-retrieval.mdx create mode 100644 apps/docs/content/docs/en/knowledgebase/using-in-workflows.mdx create mode 100644 apps/docs/content/docs/en/logs-debugging/alerts.mdx create mode 100644 apps/docs/content/docs/en/logs-debugging/index.mdx rename apps/docs/content/docs/en/{execution => logs-debugging}/logging.mdx (95%) create mode 100644 apps/docs/content/docs/en/tables/using-in-workflows.mdx create mode 100644 apps/docs/content/docs/en/tables/workflow-columns.mdx delete mode 100644 apps/docs/content/docs/en/variables/index.mdx delete mode 100644 apps/docs/content/docs/en/variables/meta.json delete mode 100644 apps/docs/content/docs/en/variables/workflow-variables.mdx create mode 100644 apps/docs/content/docs/en/workflows/connections.mdx create mode 100644 apps/docs/content/docs/en/workflows/data-flow.mdx create mode 100644 apps/docs/content/docs/en/workflows/how-it-runs.mdx create mode 100644 apps/docs/content/docs/en/workflows/index.mdx create mode 100644 apps/docs/content/docs/en/workflows/variables.mdx create mode 100644 apps/docs/content/docs/en/workspaces/fundamentals.mdx create mode 100644 apps/docs/content/docs/en/workspaces/organization.mdx diff --git a/apps/docs/app/[lang]/[[...slug]]/page.tsx b/apps/docs/app/[lang]/[[...slug]]/page.tsx index 6fb69448f8b..eaae5fe1c57 100644 --- a/apps/docs/app/[lang]/[[...slug]]/page.tsx +++ b/apps/docs/app/[lang]/[[...slug]]/page.tsx @@ -5,11 +5,12 @@ import type { ApiPageProps } from 'fumadocs-openapi/ui' import { createAPIPage } from 'fumadocs-openapi/ui' import { Pre } from 'fumadocs-ui/components/codeblock' import defaultMdxComponents from 'fumadocs-ui/mdx' -import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page' +import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/page' import { notFound } from 'next/navigation' import { PageFooter } from '@/components/docs-layout/page-footer' import { PageNavigationArrows } from '@/components/docs-layout/page-navigation-arrows' import { LLMCopyButton } from '@/components/page-actions' +import { PageTypeBadge } from '@/components/page-type-badge' import { StructuredData } from '@/components/structured-data' import { CodeBlock } from '@/components/ui/code-block' import { Heading } from '@/components/ui/heading' @@ -173,7 +174,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l {data.title} - {data.description} @@ -222,8 +222,8 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l + {data.pageType && } {data.title} - {data.description} + +interface PageTypeBadgeProps { + type: DocsPageType + className?: string +} + +/** + * Small label that tells the reader which Diátaxis mode a page is — learning, + * task, lookup, or understanding. Rendered only when a page declares `type`. + */ +export function PageTypeBadge({ type, className }: PageTypeBadgeProps) { + const config = CONFIG[type] + if (!config) return null + + return ( + + {config.label} + + ) +} diff --git a/apps/docs/components/workflow-preview/block-icons.tsx b/apps/docs/components/workflow-preview/block-icons.tsx new file mode 100644 index 00000000000..3379d1f4202 --- /dev/null +++ b/apps/docs/components/workflow-preview/block-icons.tsx @@ -0,0 +1,85 @@ +import type { SVGProps } from 'react' +import { + Code2, + CornerDownRight, + Database, + GitBranch, + Globe, + Repeat, + Split, + Table, +} from 'lucide-react' + +/** + * The two Sim-specific block glyphs we need, ported verbatim from + * `apps/sim/components/icons.tsx` so the preview matches the real builder. + * Other block types fall back to lucide-react stand-ins for now. + */ +export function StartIcon(props: SVGProps) { + return ( + + + + ) +} + +export function AgentIcon(props: SVGProps) { + return ( + + + + + + ) +} + +/** Block type → glyph. Sim glyphs where it matters; lucide stand-ins elsewhere. */ +export const BLOCK_ICONS: Record> = { + starter: StartIcon, + start_trigger: StartIcon, + agent: AgentIcon, + response: CornerDownRight, + function: Code2, + condition: Split, + router: GitBranch, + loop: Repeat, + api: Globe, + knowledge_base: Database, + knowledge: Database, + table: Table, +} diff --git a/apps/docs/components/workflow-preview/examples.ts b/apps/docs/components/workflow-preview/examples.ts new file mode 100644 index 00000000000..a8f28baa47b --- /dev/null +++ b/apps/docs/components/workflow-preview/examples.ts @@ -0,0 +1,182 @@ +import type { PreviewWorkflow } from '@/components/workflow-preview/workflow-data' + +/** + * The running example used across the Workflows overview: a workflow that takes + * an incoming customer message, classifies its category and urgency, and returns + * the result. Colors match the real Start / Agent / Response blocks. + */ +export const CLASSIFY_WORKFLOW: PreviewWorkflow = { + id: 'classify-message', + name: 'Classify customer message', + blocks: [ + { + id: 'start', + name: 'Start', + type: 'start_trigger', + bgColor: '#34B5FF', + position: { x: 0, y: 0 }, + hideTargetHandle: true, + rows: [{ title: 'Input', value: 'Customer message' }], + }, + { + id: 'agent', + name: 'Agent', + type: 'agent', + bgColor: '#6f3dfa', + position: { x: 340, y: 0 }, + hideSourceHandle: true, + rows: [ + { title: 'Model', value: 'gpt-4o' }, + { title: 'Prompt', value: 'Classify ' }, + ], + }, + ], + edges: [{ id: 'start-agent', source: 'start', target: 'agent' }], +} + +/** + * A three-block chain used on the Data flow page: the message is classified, then + * a reply is drafted from that classification. Shows values moving forward along + * the chain (Reply reads Classify's output; Classify reads the Start input). + */ +export const CLASSIFY_REPLY_WORKFLOW: PreviewWorkflow = { + id: 'classify-reply', + name: 'Classify and reply', + blocks: [ + { + id: 'start', + name: 'Start', + type: 'start_trigger', + bgColor: '#34B5FF', + position: { x: 0, y: 0 }, + hideTargetHandle: true, + rows: [{ title: 'Input', value: 'Customer message' }], + }, + { + id: 'classify', + name: 'Classify', + type: 'agent', + bgColor: '#6f3dfa', + position: { x: 330, y: 0 }, + rows: [ + { title: 'Model', value: 'gpt-4o' }, + { title: 'Prompt', value: 'Classify ' }, + ], + }, + { + id: 'reply', + name: 'Reply', + type: 'agent', + bgColor: '#6f3dfa', + position: { x: 660, y: 0 }, + hideSourceHandle: true, + rows: [ + { title: 'Model', value: 'gpt-4o' }, + { title: 'Prompt', value: 'Draft a reply for ' }, + ], + }, + ], + edges: [ + { id: 'start-classify', source: 'start', target: 'classify' }, + { id: 'classify-reply', source: 'classify', target: 'reply' }, + ], +} + +/** + * A support workflow used on the "Using a knowledge base" page: a question is + * searched against a knowledge base, and an Agent answers from the matches. + */ +export const SUPPORT_KB_WORKFLOW: PreviewWorkflow = { + id: 'support-kb', + name: 'Answer from docs', + blocks: [ + { + id: 'start', + name: 'Start', + type: 'start_trigger', + bgColor: '#34B5FF', + position: { x: 0, y: 0 }, + hideTargetHandle: true, + rows: [{ title: 'Input', value: 'Customer question' }], + }, + { + id: 'knowledge', + name: 'Knowledge', + type: 'knowledge', + bgColor: '#00B0B0', + position: { x: 330, y: 0 }, + rows: [ + { title: 'Operation', value: 'Search' }, + { title: 'Query', value: '' }, + ], + }, + { + id: 'agent', + name: 'Agent', + type: 'agent', + bgColor: '#6f3dfa', + position: { x: 660, y: 0 }, + hideSourceHandle: true, + rows: [ + { title: 'Model', value: 'gpt-4o' }, + { title: 'Prompt', value: 'Answer from ' }, + ], + }, + ], + edges: [ + { id: 'start-knowledge', source: 'start', target: 'knowledge' }, + { id: 'knowledge-agent', source: 'knowledge', target: 'agent' }, + ], +} + +/** + * The lead-enrichment chain from the "Using tables in workflows" page: query + * unprocessed rows, classify each with an Agent, write the result back. The + * first Table block is named "Table 1" to match the `` references + * in the prose. + */ +export const TABLE_ENRICH_WORKFLOW: PreviewWorkflow = { + id: 'table-enrich', + name: 'Enrich leads', + blocks: [ + { + id: 'table1', + name: 'Table 1', + type: 'table', + bgColor: '#10B981', + position: { x: 0, y: 0 }, + hideTargetHandle: true, + rows: [ + { title: 'Operation', value: 'Query Rows' }, + { title: 'Filter', value: 'status = unprocessed' }, + ], + }, + { + id: 'classify', + name: 'Classify', + type: 'agent', + bgColor: '#6f3dfa', + position: { x: 330, y: 0 }, + rows: [ + { title: 'Model', value: 'gpt-4o' }, + { title: 'Prompt', value: 'Classify each lead' }, + ], + }, + { + id: 'table2', + name: 'Table 2', + type: 'table', + bgColor: '#10B981', + position: { x: 660, y: 0 }, + hideSourceHandle: true, + rows: [ + { title: 'Operation', value: 'Update Rows' }, + { title: 'Set', value: 'status = qualified' }, + ], + }, + ], + edges: [ + { id: 'table1-classify', source: 'table1', target: 'classify' }, + { id: 'classify-table2', source: 'classify', target: 'table2' }, + ], +} diff --git a/apps/docs/components/workflow-preview/index.ts b/apps/docs/components/workflow-preview/index.ts new file mode 100644 index 00000000000..00dd6c0d7bc --- /dev/null +++ b/apps/docs/components/workflow-preview/index.ts @@ -0,0 +1,13 @@ +export { + CLASSIFY_REPLY_WORKFLOW, + CLASSIFY_WORKFLOW, + SUPPORT_KB_WORKFLOW, + TABLE_ENRICH_WORKFLOW, +} from '@/components/workflow-preview/examples' +export { OutputBundle } from '@/components/workflow-preview/output-bundle' +export type { + PreviewBlock, + PreviewTool, + PreviewWorkflow, +} from '@/components/workflow-preview/workflow-data' +export { WorkflowPreview } from '@/components/workflow-preview/workflow-preview' diff --git a/apps/docs/components/workflow-preview/output-bundle.tsx b/apps/docs/components/workflow-preview/output-bundle.tsx new file mode 100644 index 00000000000..84791a2c86f --- /dev/null +++ b/apps/docs/components/workflow-preview/output-bundle.tsx @@ -0,0 +1,83 @@ +'use client' + +import { BLOCK_ICONS } from '@/components/workflow-preview/block-icons' + +interface OutputValue { + key: string + value: string + /** Emphasize this row as the one being read by the tag below. */ + highlight?: boolean +} + +interface OutputBundleProps { + /** The block's name (unique within the workflow), e.g. "classify". */ + blockName: string + blockType?: string + blockColor?: string + values: OutputValue[] + /** A `blockName.key` reference to annotate beneath the card. */ + read?: string +} + +/** + * Teaches what a block's "output" is: a bundle of named values remembered under + * the block's name for the run, read by key with a `` tag. + */ +export function OutputBundle({ + blockName, + blockType = 'agent', + blockColor = '#6f3dfa', + values, + read, +}: OutputBundleProps) { + const Icon = BLOCK_ICONS[blockType] + const [tagBlock, tagKey] = read ? read.split('.') : [] + + return ( +
+
+
+
+ {Icon && } +
+ {blockName} + output · remembered this run +
+
+ {values.map((v) => ( +
+ + {v.key} + + {v.value} +
+ ))} +
+
+ + {read && tagBlock && tagKey && ( +
+
Read one value by name:
+
+ < + {tagBlock} + . + {tagKey} + > +
+
+ ↑ block name + ↑ value to read +
+
+ )} +
+ ) +} diff --git a/apps/docs/components/workflow-preview/preview-block-node.tsx b/apps/docs/components/workflow-preview/preview-block-node.tsx new file mode 100644 index 00000000000..b211398716e --- /dev/null +++ b/apps/docs/components/workflow-preview/preview-block-node.tsx @@ -0,0 +1,162 @@ +'use client' + +import { memo } from 'react' +import { domAnimation, LazyMotion, m } from 'framer-motion' +import { Handle, type NodeProps, Position } from 'reactflow' +import { BLOCK_ICONS } from '@/components/workflow-preview/block-icons' +import { + BLOCK_STAGGER, + EASE_OUT, + type PreviewTool, +} from '@/components/workflow-preview/workflow-data' + +interface PreviewBlockData { + name: string + blockType: string + bgColor: string + rows: Array<{ title: string; value: string }> + tools?: PreviewTool[] + hideTargetHandle?: boolean + hideSourceHandle?: boolean + index?: number + animate?: boolean + isHighlighted?: boolean + isDimmed?: boolean +} + +/** + * Handle styling matching the real WorkflowBlock handles. + * --workflow-edge in dark mode: #454545 + */ +const HANDLE_BASE = '!z-[10] !border-none !bg-[#454545]' +const HANDLE_LEFT = `${HANDLE_BASE} !left-[-8px] !h-5 !w-[7px] !rounded-r-none !rounded-l-[2px]` +const HANDLE_RIGHT = `${HANDLE_BASE} !right-[-8px] !h-5 !w-[7px] !rounded-l-none !rounded-r-[2px]` + +/** + * Static preview block node matching the real WorkflowBlock styling. + * Renders a header (icon + name), sub-block rows, and tool chips. + * + * Dark-theme colors mirror the app canvas: + * surface #232323, border #3d3d3d, text #e6e6e6 / #b3b3b3. + */ +export const PreviewBlockNode = memo(function PreviewBlockNode({ + data, +}: NodeProps) { + const { + name, + blockType, + bgColor, + rows, + tools, + hideTargetHandle, + hideSourceHandle, + index = 0, + animate = false, + isHighlighted = false, + isDimmed = false, + } = data + const Icon = BLOCK_ICONS[blockType] + const delay = animate ? index * BLOCK_STAGGER : 0 + const hasContent = rows.length > 0 || (tools && tools.length > 0) + + return ( + + +
+ {isHighlighted && ( +
+ )} + {!hideTargetHandle && ( + + )} + +
+
+
+ {Icon && } +
+ {name} +
+
+ + {hasContent && ( +
+ {rows.map((row) => ( +
+ + {row.title} + + {row.value && ( + + {row.value} + + )} +
+ ))} + + {tools && tools.length > 0 && ( +
+ + Tools + +
+ {tools.map((tool) => { + const ToolIcon = BLOCK_ICONS[tool.type] + return ( +
+
+ {ToolIcon && } +
+ + {tool.name} + +
+ ) + })} +
+
+ )} +
+ )} + + {!hideSourceHandle && ( + + )} +
+ + + ) +}) diff --git a/apps/docs/components/workflow-preview/workflow-data.ts b/apps/docs/components/workflow-preview/workflow-data.ts new file mode 100644 index 00000000000..c1209479ced --- /dev/null +++ b/apps/docs/components/workflow-preview/workflow-data.ts @@ -0,0 +1,114 @@ +import { type Edge, type Node, Position } from 'reactflow' + +/** + * Tool entry displayed as a chip on a block (e.g. an Agent's attached tools). + */ +export interface PreviewTool { + name: string + type: string + bgColor: string +} + +/** + * A single block in a preview workflow. Presentational shape — authored by hand + * for docs diagrams, not the app's full serialized block state. + */ +export interface PreviewBlock { + id: string + name: string + type: string + bgColor: string + rows: Array<{ title: string; value: string }> + tools?: PreviewTool[] + position: { x: number; y: number } + hideTargetHandle?: boolean + hideSourceHandle?: boolean +} + +/** + * A workflow rendered as a read-only, app-styled diagram in the docs. + */ +export interface PreviewWorkflow { + id: string + name: string + blocks: PreviewBlock[] + edges: Array<{ id: string; source: string; target: string }> +} + +export const BLOCK_STAGGER = 0.12 +export const EASE_OUT: [number, number, number, number] = [0.16, 1, 0.3, 1] + +const EDGE_STYLE = { stroke: '#454545', strokeWidth: 1.5 } as const +const EDGE_STYLE_HIGHLIGHT = { stroke: '#33b4ff', strokeWidth: 2.5 } as const + +/** Optional emphasis: light one block or one edge and dim everything else. */ +export interface HighlightOptions { + highlightBlock?: string + highlightEdge?: string +} + +/** + * Converts a {@link PreviewWorkflow} to React Flow nodes and edges. + * + * @param workflow - The workflow definition + * @param animate - When true, node/edge data carries stagger metadata + * @param highlight - Optional block/edge to emphasize (dims the rest) + */ +export function toReactFlowElements( + workflow: PreviewWorkflow, + animate = false, + highlight: HighlightOptions = {} +): { nodes: Node[]; edges: Edge[] } { + const { highlightBlock, highlightEdge } = highlight + const hasHighlight = Boolean(highlightBlock || highlightEdge) + const blockIndexMap = new Map(workflow.blocks.map((b, i) => [b.id, i])) + + const nodes: Node[] = workflow.blocks.map((block, index) => ({ + id: block.id, + type: 'previewBlock', + position: block.position, + data: { + name: block.name, + blockType: block.type, + bgColor: block.bgColor, + rows: block.rows, + tools: block.tools, + hideTargetHandle: block.hideTargetHandle, + hideSourceHandle: block.hideSourceHandle, + index, + animate, + isHighlighted: highlightBlock === block.id, + isDimmed: hasHighlight && highlightBlock !== block.id, + }, + draggable: true, + selectable: false, + connectable: false, + sourcePosition: Position.Right, + targetPosition: Position.Left, + })) + + const edges: Edge[] = workflow.edges.map((e) => { + const sourceIndex = blockIndexMap.get(e.source) ?? 0 + const isEdgeHighlight = highlightEdge === e.id + const dimmed = hasHighlight && !isEdgeHighlight + return { + id: e.id, + source: e.source, + target: e.target, + type: 'previewEdge', + animated: false, + style: { + ...(isEdgeHighlight ? EDGE_STYLE_HIGHLIGHT : EDGE_STYLE), + opacity: dimmed ? 0.35 : 1, + }, + sourceHandle: 'source', + targetHandle: 'target', + data: { + animate, + delay: animate ? sourceIndex * BLOCK_STAGGER + BLOCK_STAGGER : 0, + }, + } + }) + + return { nodes, edges } +} diff --git a/apps/docs/components/workflow-preview/workflow-preview.tsx b/apps/docs/components/workflow-preview/workflow-preview.tsx new file mode 100644 index 00000000000..6a58dba2305 --- /dev/null +++ b/apps/docs/components/workflow-preview/workflow-preview.tsx @@ -0,0 +1,176 @@ +'use client' + +import { useCallback, useMemo, useState } from 'react' +import { domAnimation, LazyMotion, m } from 'framer-motion' +import ReactFlow, { + applyEdgeChanges, + applyNodeChanges, + Background, + BackgroundVariant, + type Edge, + type EdgeProps, + type EdgeTypes, + getSmoothStepPath, + type Node, + type NodeTypes, + type OnEdgesChange, + type OnNodesChange, + ReactFlowProvider, +} from 'reactflow' +import 'reactflow/dist/style.css' +import { PreviewBlockNode } from '@/components/workflow-preview/preview-block-node' +import { + EASE_OUT, + type PreviewWorkflow, + toReactFlowElements, +} from '@/components/workflow-preview/workflow-data' + +interface WorkflowPreviewProps { + workflow: PreviewWorkflow + /** Canvas height in px. Default 260. */ + height?: number + animate?: boolean + /** Emphasize one block by id, dimming the rest. */ + highlightBlock?: string + /** Emphasize one edge by id, dimming the rest. */ + highlightEdge?: string +} + +/** Smooth-step edge, matching the app's connection styling. */ +function PreviewEdge({ + id, + sourceX, + sourceY, + targetX, + targetY, + sourcePosition, + targetPosition, + style, + data, +}: EdgeProps) { + const [edgePath] = getSmoothStepPath({ + sourceX, + sourceY, + targetX, + targetY, + sourcePosition, + targetPosition, + }) + + if (data?.animate) { + return ( + + ) + } + + return ( + + ) +} + +const NODE_TYPES: NodeTypes = { previewBlock: PreviewBlockNode } +const EDGE_TYPES: EdgeTypes = { previewEdge: PreviewEdge } +const PRO_OPTIONS = { hideAttribution: true } +const FIT_VIEW_OPTIONS = { padding: 0.25, maxZoom: 1 } as const + +function PreviewFlow({ + workflow, + animate = false, + highlightBlock, + highlightEdge, +}: WorkflowPreviewProps) { + const { nodes: initialNodes, edges: initialEdges } = useMemo( + () => toReactFlowElements(workflow, animate, { highlightBlock, highlightEdge }), + [workflow, animate, highlightBlock, highlightEdge] + ) + + const [nodes, setNodes] = useState(initialNodes) + const [edges, setEdges] = useState(initialEdges) + + const onNodesChange: OnNodesChange = useCallback( + (changes) => setNodes((nds) => applyNodeChanges(changes, nds)), + [] + ) + const onEdgesChange: OnEdgesChange = useCallback( + (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)), + [] + ) + + return ( + + + + ) +} + +/** + * Read-only, app-styled workflow diagram for docs pages. Renders a + * {@link PreviewWorkflow} with ReactFlow — draggable, non-editable, no app runtime. + * + * @example + * + */ +export function WorkflowPreview({ + workflow, + height = 260, + animate = false, + highlightBlock, + highlightEdge, +}: WorkflowPreviewProps) { + return ( + +
+ + + +
+ + ) +} diff --git a/apps/docs/content/docs/en/blocks/index.mdx b/apps/docs/content/docs/en/blocks/index.mdx index 5e91e36e700..118c11a8065 100644 --- a/apps/docs/content/docs/en/blocks/index.mdx +++ b/apps/docs/content/docs/en/blocks/index.mdx @@ -1,150 +1,69 @@ --- -title: Overview -description: The building components of your AI workflows +title: Blocks +description: The steps a workflow is built from, and the kinds of blocks you connect together. +pageType: concept --- import { Card, Cards } from 'fumadocs-ui/components/card' -import { Step, Steps } from 'fumadocs-ui/components/steps' -import { Tab, Tabs } from 'fumadocs-ui/components/tabs' import { Video } from '@/components/ui/video' import { FAQ } from '@/components/ui/faq' -Blocks are the building components you connect together to create AI workflows. Think of them as specialized modules that each handle a specific task—from chatting with AI models to making API calls or processing data. +A **block** is one step in a workflow. Each block does a single thing: an [Agent](/blocks/agent) reasons with a model, a [Function](/blocks/function) runs code, a [Condition](/blocks/condition) branches. You build a workflow by placing blocks and connecting them, and the [connections](/workflows/connections) decide the order they run in. -
+A block takes inputs (the fields you configure, including [references](/workflows/data-flow) to earlier outputs), does its work, and produces an output the blocks after it can read. + +
-## Core Block Types - -Sim provides essential block types that handle the core functions of AI workflows: - -### Processing Blocks -- **[Agent](/blocks/agent)** - Chat with AI models (OpenAI, Anthropic, Google, local models) -- **[Function](/blocks/function)** - Run custom JavaScript/TypeScript code -- **[API](/blocks/api)** - Connect to external services via HTTP requests +## Core blocks -### Logic Blocks -- **[Condition](/blocks/condition)** - Branch workflow paths based on boolean expressions -- **[Router](/blocks/router)** - Use AI to intelligently route requests to different paths -- **[Evaluator](/blocks/evaluator)** - Score and assess content quality using AI +The general-purpose blocks every workflow is built from. -### Control Flow Blocks -- **[Variables](/blocks/variables)** - Set and manage workflow-scoped variables -- **[Wait](/blocks/wait)** - Pause workflow execution for a specified time delay -- **[Human in the Loop](/blocks/human-in-the-loop)** - Pause for human approval and feedback before continuing +**Do work** -### Output Blocks -- **[Response](/blocks/response)** - Format and return final results from your workflow +- [Agent](/blocks/agent) reasons with a model, calls tools, and returns text or structured output. +- [Function](/blocks/function) runs a snippet of JavaScript or TypeScript. +- [API](/blocks/api) calls an external service over HTTP. +- [Workflow](/blocks/workflow) runs another workflow as a single step. -## How Blocks Work +**Direct the flow** -Each block has three main components: +- [Condition](/blocks/condition) branches on an explicit rule. +- [Router](/blocks/router) lets a model choose which path to take. +- [Loop](/blocks/loop) repeats its inner blocks over a list or a count. +- [Parallel](/blocks/parallel) runs its inner blocks for many items at once. -**Inputs**: Data coming into the block from other blocks or user input -**Configuration**: Settings that control how the block behaves -**Outputs**: Data the block produces for other blocks to use +**Shape the run** - - - Receive Input: Block receives data from connected blocks or user input - - - Process: Block processes the input according to its configuration - - - Output Results: Block produces output data for the next blocks in the workflow - - +- [Response](/blocks/response) returns a result from a deployed API or chat. +- [Variables](/blocks/variables) sets or updates a workflow [variable](/workflows/variables). +- [Evaluator](/blocks/evaluator) scores an output with a model. +- [Guardrails](/blocks/guardrails) checks an output against rules before it continues. +- [Wait](/blocks/wait) pauses for a set time. +- [Human in the loop](/blocks/human-in-the-loop) pauses for a person to approve or edit. -## Connecting Blocks +## Integrations and triggers -You create workflows by connecting blocks together. The output of one block becomes the input of another: +Two larger families of blocks do more specific jobs: -- **Drag to connect**: Drag from an output port to an input port -- **Multiple connections**: One output can connect to multiple inputs -- **Branching paths**: Some blocks can route to different paths based on conditions - -
-
+- **[Integrations](/tools)** connect to an external service, like Gmail, Slack, Notion, or a database, with hundreds available. An agent can also call them as tools. +- **[Triggers](/triggers)** are the blocks that start a workflow, like the Start trigger, a webhook, or a schedule. -## Common Patterns - -### Sequential Processing -Connect blocks in a chain where each block processes the output of the previous one: -``` -User Input → Agent → Function → Response -``` - -### Conditional Branching -Use Condition or Router blocks to create different paths: -``` -User Input → Router → Agent A (for questions) - → Agent B (for commands) -``` - -### Quality Control -Use Evaluator blocks to assess and filter outputs: -``` -Agent → Evaluator → Condition → Response (if good) - → Agent (retry if bad) -``` - -## Block Configuration - -Each block type has specific configuration options: - -**All Blocks**: -- Input/output connections -- Error handling behavior -- Execution timeout settings - -**AI Blocks** (Agent, Router, Evaluator): -- Model selection (OpenAI, Anthropic, Google, local) -- API keys and authentication -- Temperature and other model parameters -- System prompts and instructions - -**Logic Blocks** (Condition, Function): -- Custom expressions or code -- Variable references -- Execution environment settings - -**Integration Blocks** (API, Response): -- Endpoint configuration -- Headers and authentication -- Request/response formatting +## Next - - Connect to AI models and create intelligent responses - - - Run custom code to process and transform data - - - Integrate with external services and APIs - - - Create branching logic based on data evaluation - - - Pause for human approval and feedback before continuing - - - Set and manage workflow-scoped variables - - - Pause workflow execution for specified time delays - + + + + diff --git a/apps/docs/content/docs/en/building-agents/choosing.mdx b/apps/docs/content/docs/en/building-agents/choosing.mdx new file mode 100644 index 00000000000..27790da5f2f --- /dev/null +++ b/apps/docs/content/docs/en/building-agents/choosing.mdx @@ -0,0 +1,73 @@ +--- +title: Choosing what to use +description: Pick between a deterministic block, an agent tool, a custom tool, an MCP server, a workflow-as-tool, and a skill. +pageType: concept +--- + +import { Callout } from 'fumadocs-ui/components/callout' +import { Card, Cards } from 'fumadocs-ui/components/card' + +When you build an agent, several features overlap: a deterministic block and an agent tool can run the same integration, and a custom tool, an MCP tool, and a workflow-as-tool can all give an agent the same action. This page lays out the differences so you pick the right one. They vary along three lines: whether the action is **deterministic** (always runs) or **model-decided** (an agent chooses), whether it lives in one workflow or is **reusable** across your workspace, and whether it comes from Sim or an **external** provider. + +The running example is a workflow that scores inbound sales leads. It reads a new lead, enriches it, decides on a score, logs the result, and notifies the team. Each option below builds part of it. + +{/* VISUAL: decision tree. Always happens? → deterministic block. Else agent chooses? → agent tool. Reuse across workspace? → custom tool. External toolset? → MCP. Whole workflow? → workflow-as-tool. Reusable instructions? → skill. */} + +## Deterministic block + +A **block** is a single step that runs at a fixed point on the path, with no model deciding whether to. It always runs when the workflow reaches it. Use one when the action must happen every time: an API call, a data transform, a branch. + +In the lead scorer, a [Google Sheets](/tools) block always appends the scored lead to a tracking sheet, and a [Function](/blocks/function) block always reshapes the enrichment response into the fields the next step expects. There is no judgment call. The work is guaranteed. + +Most steps in a workflow are blocks. Reach for the kinds below only when you want a model to decide, or you want to reuse something. + +## Agent tool + +An **agent tool** is an action you hand to an [Agent](/blocks/agent) block. The agent reads the task and decides whether and when to call it. The same catalog of [integrations](/tools) that exist as standalone blocks can also be attached to an agent as tools. + +In the lead scorer, the Agent has a Search tool and a Send Email tool. For a lead with a thin profile it runs Search to gather context; for a strong lead it calls Send Email. A thin, obvious lead might trigger neither. The agent chooses per run. + +Each tool carries a `usageControl` setting. **Auto** lets the model decide (the default). **Force** makes the agent call the tool every run, for actions that should never be skipped, like always logging the decision. **None** removes the tool from that agent. + + +A block and an agent tool can be the same underlying integration. The difference is who decides. A block runs because the path reached it. An agent tool runs because the agent chose it. + + +## Custom tool + +A **custom tool** is a tool you define once with an object schema and a snippet of JavaScript or Python, then reuse across your workspace. It needs no external account. Use one when you have logic that several agents or workflows would otherwise duplicate. + +In the lead scorer, a `normalizeCompanyDomain` custom tool cleans a raw website into a canonical domain. The same tool serves the lead scorer, a deduplication workflow, and a reporting agent. Define it in the workspace, then pick it from any Agent block's tool list. + +## MCP server + +**MCP** (Model Context Protocol) is a standard for connecting an external tool provider. Connect an [MCP server](/mcp) and its tools appear in the agent's tool list as a set. Use it to bring in a complete toolset that Sim does not provide natively, rather than wiring each action by hand. + +In the lead scorer, your CRM vendor ships an MCP server. After you connect it once, the agent can read accounts and update records through the vendor's own tools. The difference from a custom tool is who maintains it: a custom tool is code you wrote, while an MCP server is a toolbox someone else maintains. + +## Workflow-as-tool + +A **workflow-as-tool** runs a whole workflow as one step. The [Workflow](/blocks/workflow) block selects a child workflow and maps values to its [Start](/triggers/start) trigger, then returns `success`, `result`, and `error`. Use it to keep a large system modular: build a procedure once, call it from many parents. + +In the lead scorer, enrichment is its own workflow with five steps. The parent uses a Workflow block to call it and reads the enriched lead from `result`, instead of inlining those five steps. So one workflow can call another, much the way a function calls another function. + +## Skill + +A **skill** is reusable instructions, a written playbook an agent can follow. Each skill has a short name and description that are always visible to the agent, plus a longer body the agent loads only when it decides the skill applies. Use one to capture how something should be done, separate from the tools that do it. + +In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers. The agent sees the skill's name and description on every run, and when a lead is ambiguous it loads the full rubric and applies it. The distinction is simple: a tool is an action the agent takes, and a skill is guidance the agent reads. Manage skills in your [workspace](/skills). + +{/* VISUAL: comparison grid. Rows: block / agent tool / custom tool / MCP / workflow-as-tool / skill. Columns: Who decides (path / agent) · Where it lives (workflow / workspace / external) · How you author it (drag-drop / code / protocol / instructions). */} + +## Putting it together + +The lead scorer uses six kinds at once: blocks for the steps that must always run, agent tools for the calls the model should weigh, a custom tool for shared logic, an MCP server for the CRM, a workflow-as-tool for enrichment, and a skill for the scoring rules. In general, start with a block, then move to an agent tool when a model should decide. Reach for the rest only when you need reuse, an external toolset, a sub-workflow, or written guidance. + +## Next + + + + + + + diff --git a/apps/docs/content/docs/en/building-agents/index.mdx b/apps/docs/content/docs/en/building-agents/index.mdx new file mode 100644 index 00000000000..17568a80ae5 --- /dev/null +++ b/apps/docs/content/docs/en/building-agents/index.mdx @@ -0,0 +1,72 @@ +--- +title: Overview +description: An agent is a workflow that reasons and acts, built around Agent blocks and the features you give them. +pageType: concept +--- + +import { Callout } from 'fumadocs-ui/components/callout' +import { Card, Cards } from 'fumadocs-ui/components/card' + +An **agent** is a [workflow](/workflows) that reasons and acts on its own. It reads an input, decides what to do, and carries it out, calling tools and using your data along the way. You build a custom agent in Sim by composing a workflow whose thinking runs through one or more [Agent blocks](/blocks/agent). + +An **Agent block** is the reasoning step inside that workflow: a model reads the values available to it, decides, and returns a result that later blocks read by reference. A simple agent is a single Agent block; a larger one wires several together with other blocks. The Agent block is where the model thinks; the rest of the workflow is what it acts on and through. + +{/* VISUAL: a small agent-workflow. Start → Agent block (model + a tool) → Response, with the Agent block highlighted as the reasoning core of the agent. */} + +The example throughout is an agent that scores inbound sales leads. + +## The Agent block + +You set up the reasoning step by giving the Agent block a **model** and a **prompt**. The model is the LLM that powers it; you pick one from the available providers, and the default is `claude-sonnet-4-6`. The prompt is a system message that defines who the agent is and how it should behave, plus a user message that carries the input, usually a reference like ``. + +When it runs, the Agent block reasons, calls any tools it needs, and stores its result under its own name. By default that result is free text in `content`, read by a later block as ``, alongside run details like the model used, token counts, tool calls, and cost. Every setting and output field is in the [Agent block reference](/blocks/agent). + +## What you give an agent + +On its own, an Agent block can only reason and write text. You extend it so it can act, follow your rules, use your data, remember, and return results other blocks can rely on. Each feature maps to something you'd want an agent to do. + +### Take an action: tools + +To let an agent do something in the world, give it **tools**. A tool is an action the agent can call, like sending an email, searching the web, updating a CRM record, or running another workflow. You attach tools to the Agent block, and the agent decides which to call for the task in front of it. In the lead scorer, the agent has a search tool to gather context on a thin profile and an email tool to reach out to a strong lead. + +Tools come from a few places: + +- **[Integrations](/tools)** are the catalog of external services: Gmail, Slack, Airtable, Linear, and hundreds more. +- **[Custom tools](/tools/custom-tools)** are tools you define once with a schema and a snippet of code, then reuse. +- **[MCP tools](/mcp)** come from an external provider you connect through the Model Context Protocol. +- **[Workflow-as-tool](/workflows)** makes another workflow callable, so the agent runs a whole procedure as one step. + + +The same integration can run two ways. As a [block](/blocks) it runs because the path reached it. As an agent tool it runs because the agent chose it. Each agent tool has a usage control: **Auto** lets the model decide (the default), **Force** calls it on every run, and **None** removes it. + + +### Follow a procedure: skills + +To give an agent instructions it can follow, write a [skill](/skills). A skill is a reusable playbook with a short name and description the agent always sees, plus a longer body it loads only when the skill applies. In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers, and the agent reads the full rubric only when a lead is ambiguous. A tool is an action the agent takes; a skill is guidance it reads. + +### Use your documents: knowledge + +To let an agent answer from your own content, connect a [knowledge base](/knowledgebase). The agent searches it and grounds its answers in what it finds, instead of relying only on the model's general training. Give the lead scorer a knowledge base of past deals and it can compare a new lead against ones you've closed before. + +### Remember across runs: memory + +To let an agent reuse information from one run to the next, give it [memory](/tools/memory), which stores and recalls values keyed to a conversation. Without it, each run starts fresh; with it, an agent in a chat carries what was said earlier into later messages. + +### Return a usable result: structured output + +To make an agent's result something later blocks can act on, give it a **structured output**: a typed object you define instead of free text. In the lead scorer, the agent returns `{ score, tier, reason }`, and a later [Condition](/blocks/condition) block reads `` to branch. See [how blocks pass data](/workflows/data-flow) for reading fields. + +## Choosing what to use + +Start with one Agent block and a prompt, then add only what the task needs: a tool when the agent should act, a skill when it needs written guidance, a knowledge base when it should answer from your documents, memory when it should remember, and a structured output when a later block has to read its result. + + + +## Next + + + + + + + diff --git a/apps/docs/content/docs/en/connections/basics.mdx b/apps/docs/content/docs/en/connections/basics.mdx deleted file mode 100644 index 839b4058faa..00000000000 --- a/apps/docs/content/docs/en/connections/basics.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Basics ---- - -import { Callout } from 'fumadocs-ui/components/callout' -import { Step, Steps } from 'fumadocs-ui/components/steps' -import { Video } from '@/components/ui/video' -import { FAQ } from '@/components/ui/faq' - -## How Connections Work - -Connections are the pathways that allow data to flow between blocks in your workflow. In Sim, connections define how information passes from one block to another, enabling data flow throughout your workflow. - - - Each connection represents a directed relationship where data flows from a source block's output - to a destination block's input. - - -### Creating Connections - - - - Select Source Block: Click on the output port of the block you want to connect - from - - - Draw Connection: Drag to the input port of the destination block - - - Confirm Connection: Release to create the connection - - - -
-
- -### Connection Flow - -The flow of data through connections follows these principles: - -1. **Directional Flow**: Data always flows from outputs to inputs -2. **Execution Order**: Blocks execute in order based on their connections -3. **Data Transformation**: Data may be transformed as it passes between blocks -4. **Conditional Paths**: Some blocks (like Router and Condition) can direct flow to different paths - - - Deleting a connection will immediately stop data flow between the blocks. Make sure this is - intended before removing connections. - - - - diff --git a/apps/docs/content/docs/en/connections/data-structure.mdx b/apps/docs/content/docs/en/connections/data-structure.mdx deleted file mode 100644 index 2c112b781df..00000000000 --- a/apps/docs/content/docs/en/connections/data-structure.mdx +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Data Structure ---- - -import { Callout } from 'fumadocs-ui/components/callout' -import { Tab, Tabs } from 'fumadocs-ui/components/tabs' -import { FAQ } from '@/components/ui/faq' - -When you connect blocks, understanding the data structure of different block outputs is important because the output data structure from the source block determines what values are available in the destination block. Each block type produces a specific output structure that you can reference in downstream blocks. - - - Understanding these data structures is essential for effectively using connection tags and - accessing the right data in your workflows. - - -## Block Output Structures - -Different block types produce different output structures. Here's what you can expect from each block type: - - - - ```json - { - "content": "The generated text response", - "model": "gpt-4o", - "tokens": { - "prompt": 120, - "completion": 85, - "total": 205 - }, - "toolCalls": [...], - "cost": [...], - "usage": [...] - } - ``` - - ### Agent Block Output Fields - - - **content**: The main text response generated by the agent - - **model**: The AI model used (e.g., "gpt-4o", "claude-3-opus") - - **tokens**: Token usage statistics - - **prompt**: Number of tokens in the prompt - - **completion**: Number of tokens in the completion - - **total**: Total tokens used - - **toolCalls**: Array of tool calls made by the agent (if any) - - **cost**: Array of cost objects for each tool call (if any) - - **usage**: Token usage statistics for the entire response - - - - ```json - { - "data": "Response data", - "status": 200, - "headers": { - "content-type": "application/json", - "cache-control": "no-cache" - } - } - ``` - - ### API Block Output Fields - - - **data**: The response data from the API (can be any type) - - **status**: HTTP status code of the response - - **headers**: HTTP headers returned by the API - - - - ```json - { - "result": "Function return value", - "stdout": "Console output", - } - ``` - - ### Function Block Output Fields - - - **result**: The return value of the function (can be any type) - - **stdout**: Console output captured during function execution - - - - ```json - { - "content": "Evaluation summary", - "model": "gpt-5", - "tokens": { - "prompt": 120, - "completion": 85, - "total": 205 - }, - "metric1": 8.5, - "metric2": 7.2, - "metric3": 9.0 - } - ``` - - ### Evaluator Block Output Fields - - - **content**: Summary of the evaluation - - **model**: The AI model used for evaluation - - **tokens**: Token usage statistics - - **[metricName]**: Score for each metric defined in the evaluator (dynamic fields) - - - - ```json - { - "conditionResult": true, - "selectedPath": { - "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1", - "blockType": "agent", - "blockTitle": "Follow-up Agent" - }, - "selectedOption": "condition-1" - } - ``` - - ### Condition Block Output Fields - - - **conditionResult**: Boolean result of the condition evaluation - - **selectedPath**: Information about the selected path - - **blockId**: ID of the next block in the selected path - - **blockType**: Type of the next block - - **blockTitle**: Title of the next block - - **selectedOption**: ID of the selected condition - - - - ```json - { - "content": "Routing decision", - "model": "gpt-4o", - "tokens": { - "prompt": 120, - "completion": 85, - "total": 205 - }, - "selectedPath": { - "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1", - "blockType": "agent", - "blockTitle": "Customer Service Agent" - } - } - ``` - - ### Router Block Output Fields - - - **content**: The routing decision text - - **model**: The AI model used for routing - - **tokens**: Token usage statistics - - **selectedPath**: Information about the selected path - - **blockId**: ID of the selected destination block - - **blockType**: Type of the selected block - - **blockTitle**: Title of the selected block - - - - -## Custom Output Structures - -Some blocks may produce custom output structures based on their configuration: - -1. **Agent Blocks with Response Format**: When using a response format in an Agent block, the output structure will match the defined schema instead of the standard structure. - -2. **Function Blocks**: The `result` field can contain any data structure returned by your function code. - -3. **API Blocks**: The `data` field will contain whatever the API returns, which could be any valid JSON structure. - - - Always check the actual output structure of your blocks during development to ensure you're - referencing the correct fields in your connections. - - -## Nested Data Structures - -Many block outputs contain nested data structures. You can access these using dot notation in connection tags: - -``` - -``` - -For example: - -- `` - Access the total tokens from an Agent block -- `` - Access the ID of the first result from an API response -- `` - Access a nested field in a Function block's result - - navigates into the data field, then into the results array at index 0, and retrieves the id property." }, -]} /> - diff --git a/apps/docs/content/docs/en/connections/index.mdx b/apps/docs/content/docs/en/connections/index.mdx deleted file mode 100644 index db12a79780c..00000000000 --- a/apps/docs/content/docs/en/connections/index.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Overview -description: Connect your blocks to one another. ---- - -import { Callout } from 'fumadocs-ui/components/callout' -import { Card, Cards } from 'fumadocs-ui/components/card' -import { ConnectIcon } from '@/components/icons' -import { Video } from '@/components/ui/video' -import { FAQ } from '@/components/ui/faq' - -Connections are the pathways that allow data to flow between blocks in your workflow. They define how information is passed from one block to another, enabling you to create sophisticated, multi-step processes. - - - Properly configured connections are essential for creating effective workflows. They determine how - data moves through your system and how blocks interact with each other. - - -
-
- -## Connection Types - -Sim supports different types of connections that enable various workflow patterns: - - - - Learn how connections work and how to create them in your workflows - - - Understand how to use connection tags to reference data between blocks - - - Explore the output data structures of different block types - - - Learn techniques for accessing and manipulating connected data - - - Follow recommended patterns for effective connection management - - - -, which the variable resolver replaces with the actual data at execution time." }, - { question: "Can a block receive input from multiple upstream blocks?", answer: "Yes. A block waits until all of its incoming connections have been fulfilled before it executes. The engine tracks incoming edges for each node and only marks a block as ready when every upstream dependency has completed. You can reference outputs from any connected block using their respective connection tags." }, - { question: "What happens if an upstream block fails?", answer: "If a block errors, the engine activates the error edge (if one exists) and deactivates the normal output edge. Downstream blocks on the success path will not execute. You can connect an error handle to a separate block to build fallback or recovery logic." }, - { question: "Do connections support conditional branching?", answer: "Yes. Router and Condition blocks produce a selected route or option that determines which outgoing edge is activated. Only the blocks on the chosen path will execute. Edges on unselected paths are deactivated and their entire downstream subgraph is skipped." }, - { question: "Can blocks in parallel branches share data with each other?", answer: "Blocks within the same parallel branch cannot directly reference blocks in a sibling branch because branches execute independently. However, once all branches complete and the parallel block exits, downstream blocks can access the aggregated results from all branches." }, - { question: "How are connection tags formatted?", answer: "Connection tags use angle-bracket syntax: . For nested data you can chain dot notation, such as . The resolver walks the object path at execution time and substitutes the resolved value into your input field." }, -]} /> diff --git a/apps/docs/content/docs/en/connections/meta.json b/apps/docs/content/docs/en/connections/meta.json deleted file mode 100644 index a120e6e0300..00000000000 --- a/apps/docs/content/docs/en/connections/meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "pages": ["index", "basics", "data-structure", "tags"] -} diff --git a/apps/docs/content/docs/en/connections/tags.mdx b/apps/docs/content/docs/en/connections/tags.mdx deleted file mode 100644 index 6daf9384dde..00000000000 --- a/apps/docs/content/docs/en/connections/tags.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Tags ---- - -import { Callout } from 'fumadocs-ui/components/callout' -import { Video } from '@/components/ui/video' -import { FAQ } from '@/components/ui/faq' - -Connection tags are visual representations of the data available from connected blocks, providing an easy way to reference data between blocks and outputs from previous blocks in your workflow. - -
-
- -### What Are Connection Tags? - -Connection tags are interactive elements that appear when blocks are connected. They represent the data that can flow from one block to another and allow you to: - -- Visualize available data from source blocks -- Reference specific data fields in destination blocks -- Create dynamic data flows between blocks - - - Connection tags make it easy to see what data is available from previous blocks and use it in your - current block without having to remember complex data structures. - - -## Using Connection Tags - -There are two primary ways to use connection tags in your workflows: - -
-
-

Drag and Drop

-
- Click on a connection tag and drag it into input fields of destination blocks. A dropdown will - appear showing available values. -
-
    -
  1. Hover over a connection tag to see available data
    2. -
  2. Click and drag the tag to an input field
    3. -
  3. Select the specific data field from the dropdown
    4. -
  4. The reference is inserted automatically
    5. -
-
- -
-

Angle Bracket Syntax

-
- Type <> in input fields to see a dropdown of available connection values - from previous blocks. -
-
    -
  1. Click in any input field where you want to use connected data
    2. -
  2. - Type <> to trigger the connection dropdown -
    3. -
  3. Browse and select the data you want to reference
    4. -
  4. Continue typing or select from the dropdown to complete the reference
    5. -
-
-
- -## Tag Syntax - -Connection tags use a simple syntax to reference data: - -``` - -``` - -Where: - -- `blockName` is the name of the source block -- `path.to.data` is the path to the specific data field - -For example: - -- `` - References the content field from a block with ID "agent1" -- `` - References the name of the first user in the users array from the data field of a block with ID "api2" - -## Dynamic Tag References - -Connection tags are evaluated at runtime, which means: - -1. They always reference the most current data -2. They can be used in expressions and combined with static text -3. They can be nested within other data structures - -### Examples - -```javascript -// Reference in text -"The user's name is " - -// Reference in JSON -{ - "userName": "", - "orderTotal": -} - -// Reference in code -const greeting = "Hello, !"; -const total = * 1.1; // Add 10% tax -``` - - - When using connection tags in numeric contexts, make sure the referenced data is actually a number - to avoid type conversion issues. - - - is matched against resolvers in order: loop references, parallel references, workflow variables, environment variables, and finally block output references. The first resolver that recognizes the reference handles it." }, - { question: "Does the block name in a tag reference need to match exactly?", answer: "Block names are normalized by converting to lowercase and removing spaces before matching. So and resolve to the same block. However, the field path after the block name (e.g., content, data.users) is case-sensitive." }, - { question: "Can I reference environment variables in tag syntax?", answer: "Yes, but environment variables use double-brace syntax instead of angle brackets: {{MY_VAR}}. These are resolved by a dedicated environment variable resolver during execution." }, - { question: "What happens if I reference a block that did not execute on the current path?", answer: "If the referenced block exists in the workflow but did not produce output (for example, it was on an unselected condition branch), the reference resolves to an empty value. In most blocks this becomes an empty string; in Function blocks it becomes null." }, - { question: "Can I access array elements inside a tag reference?", answer: "Yes. Use bracket notation for array indices within the dot path, for example . The resolver supports multiple levels of array indexing like items[0][1] as well." }, - { question: "How are tag values formatted inside Function blocks versus other blocks?", answer: "In Function blocks, resolved values are formatted as code literals (strings are quoted, objects are JSON, null stays as null) so they can be used directly in JavaScript or Python code. In other block types, objects are JSON-stringified and primitives are converted to plain strings." }, - { question: "Can I mix static text with tag references?", answer: "Yes. You can embed tag references anywhere in a text string, such as \"Hello, ! Your order total is .\" The resolver replaces each tag in place while leaving the surrounding text intact." }, -]} /> - diff --git a/apps/docs/content/docs/en/copilot/index.mdx b/apps/docs/content/docs/en/copilot/index.mdx deleted file mode 100644 index f30f3da691f..00000000000 --- a/apps/docs/content/docs/en/copilot/index.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Copilot -description: Your per-workflow AI assistant for building and editing workflows. ---- - -import { Callout } from 'fumadocs-ui/components/callout' -import { Image } from '@/components/ui/image' -import { Video } from '@/components/ui/video' -import { FAQ } from '@/components/ui/faq' - -Copilot is the AI assistant built into every workflow editor. It is scoped to the workflow you have open — it reads the current structure, makes changes directly, and saves checkpoints so you can revert if needed. - -For workspace-wide tasks (managing multiple workflows, running research, working with tables, scheduling jobs), use [Mothership](/mothership). - - - Copilot is a Sim-managed service. For self-hosted deployments, go to [sim.ai](https://sim.ai) → Settings → Copilot, generate a Copilot API key, then set `COPILOT_API_KEY` in your self-hosted environment. - - -