Building Your First Flow

Flows is a visual automation builder that lets you create multi-step workflows by connecting components together on a drag-and-drop canvas. Each component performs a specific task: fetching data, processing it, calling an AI agent, sending an email, and you wire them together to build powerful automations without writing code.

What you can build with Flows:

• Content pipelines - Scrape a website, summarize it with AI, and email the result to your team
• Data processing - Call an API, extract fields, filter rows, and format the output
• AI-powered workflows - Chain agents with tools, knowledge bases, and conditional logic
• Automated notifications - Monitor data sources and trigger emails when conditions are met
• Knowledge management - Ingest documents into knowledge bases and retrieve them semantically

Understanding Data Types

Before building flows, it's important to understand the three data types that flow between components. Every connection carries one of these types, and components can only connect when their types are compatible.

Message

A Message is plain text, a string of characters. It's the simplest and most common data type.

"Hello, this is a message"

Where it comes from: Text Input, Agent responses, Prompt output, Mapping output, Calculator results
Where it goes: Agent input, Send Email fields, Text Output, any field that accepts text

Think of it as: A piece of text you could paste into a document.

Data

Data is a structured key-value object, similar to JSON. It holds named fields with values that can be strings, numbers, lists, or nested objects.

{
  "status_code": 200,
  "body": {
    "name": "John",
    "email": "john@example.com",
    "tags": ["customer", "premium"]
  },
  "headers": { "content-type": "application/json" }
}

Where it comes from: HTTP Request responses, Data Operations output, Agent data output
Where it goes: Data Operations (for extraction/transformation), Mapping (to format as text), Text Output

Think of it as: A structured record with labeled fields, like a JSON object or a Python dictionary.

Accessing nested values: Use dot notation in Data Operations, for example body.name, body.tags[0], headers.content-type.

DataFrame

A DataFrame is tabular data, rows and columns, like a spreadsheet or database table.

Where it comes from: Web Search results, URL/Browserless URL pages, DF Operations output
Where it goes: DF Operations (for filtering/sorting), Mapping (to format as text), HTML Parser, Text Output

Think of it as: A spreadsheet table where each row is a result and each column is a field.

Type Compatibility Rules

Some inputs accept multiple types. For example, Text Output accepts Message, Data, and DataFrame. The Mapping component accepts both Data and DataFrame and converts them to Message.

Can't connect? If a connection won't form between two components, it means the output type doesn't match the input type. Use Mapping to convert Data or DataFrame to Message, or Data Operations to transform Data structures.

Getting Started

Step 1: Add a Starter

Every flow begins with a Starter component. Open the sidebar, find the Starters category, and drag a component onto the canvas:

• Text Input - For entering text manually (simplest starter)
• Web Search - To search the web and get results as a table
• URL - To fetch content from web pages
• HTTP Request - To call an external API

Step 2: Add Processing or AI Components

Drag additional components to process your data. Common patterns:

• Mapping - Convert a DataFrame or Data into readable text
• Agent - Use AI to analyze, summarize, or generate content
• Data Operations - Extract specific fields from a Data object
• DF Operations - Filter, sort, or transform a DataFrame

Step 3: Connect Components

Hover over the output handle (right side circle) of one component. Click and drag to the input handle (left side circle) of another. A green highlight means the connection is valid.

Tip: If no highlight appears, the types don't match. Check the output type (Message, Data, or DataFrame) and make sure the target input accepts it.

Step 4: Configure Fields

Click on each component to see its fields. Required fields are marked with a red asterisk (*). Some fields have an info icon (i), hover over it for a tooltip explaining what the field does.

Fields with a left-side handle (colored circle) can receive data from other components instead of being filled manually. This is how you make dynamic flows.

Step 5: Add an Output

Every flow should end with an output to capture results:

• Text Output - Displays the final result in the flow canvas
• Send Email - Sends the result via email to recipients
• Add to Knowledge Base - Stores the result in a KB for future use

Step 6: Run the Flow

Click the Play button (▶) at the top of a component, or use the global Run button. Components execute in dependency order: starters first, then each downstream component as its inputs become available.

Watch the status indicator on each component: it shows a spinner while running, a green check on success, or a red X on failure with an error message.

Component Reference

Starters

Starters are the entry points of your flow. They provide the initial data that kicks off the pipeline. Every flow needs at least one starter.

Text Input

The simplest starter. Enter any text that downstream components will process: a question, a topic, a URL, or raw content.

Output: Message - The entered text, passed to the next component

When to use: When you want to manually provide input, a question for an Agent, a topic for Web Search, or any static text. This is the most common starting point for simple flows.

Web Search

Searches the web across multiple sources (Google, News, Scholar, YouTube, Reddit, and more) and returns structured results as a table.

Output: DataFrame - A table with columns: title, link, snippet, and (if Fetch Content is on) content

Common next steps:

• Connect to Mapping to format results as readable text, then to Agent for summarization
• Connect to DF Operations to filter results by keyword
• Connect to HTML Parser to extract specific elements from fetched content

Web Crawler

Fetches text content from one or more web pages. Can follow links on the page and crawl multiple levels deep within the same domain.

Output: DataFrame - A table with columns: url, content, success, error

URL vs Browserless URL: Use URL for simple, static pages (blogs, docs, news). If you get empty or incomplete results, the page likely needs JavaScript to render, switch to Browserless URL.

Web Scraper (Browserless URL)

Fetches web pages using a real headless browser, so it can handle JavaScript-rendered content and bot-protected sites (LinkedIn, Twitter/X, Amazon, etc.).

Output: DataFrame - A table with columns: url, title, content, success

When to use: For JavaScript-heavy sites (SPAs, dashboards), bot-protected pages, or when the regular URL component returns empty or incomplete content.

Webhook (HTTP Request)

Makes outbound HTTP requests to external APIs. Supports GET, POST, PUT, PATCH, DELETE methods with multiple authentication options.

Outputs:

• response (Data) - The full API response as a Data object with fields: status_code, body, headers, url
• status_code (Data) - Just the status code and a success boolean (hidden by default)

Common next steps: Connect the response output to Data Operations, then use "Select Keys" to extract body.results or any nested field.

Outputs

Output components are the endpoints of your flow. They capture the final result and either display it, send it somewhere, or store it.

Text Output

Displays the final result of your flow on the canvas. Accepts any data type and converts it to readable text. Use this during development to inspect what a component produces.

Output: Message - The text representation of whatever was connected

Send Email

Sends transactional emails to one or more recipients with HTML body support and optional call-to-action buttons.

Output: Message - A status report: which emails were sent successfully, which failed, and masked recipient addresses

Add to Knowledge Base

Uploads content into a TextCortex Knowledge Base so agents and the Retrieve component can search it later. Supports files, URLs, and raw text.

Outputs:

• status (Message) - Success or failure status
• file_id (Data) - The ID of the created file entry (hidden)
• kb_id (Data) - The Knowledge Base ID (hidden)

Data Sources

Retrieve from Knowledge Base

Performs a semantic search on a Knowledge Base and returns the most relevant document chunks. Unlike keyword search, semantic search understands meaning, searching "employee benefits" will find documents about "health insurance" and "PTO policy."

Outputs:

• retrieved_text (Message) - The matching document chunks formatted as numbered text, ready to feed into an Agent or Prompt
• results (Data) - Structured results with text, url, file_id, and score for each chunk (hidden)

Common pattern: Retrieve from KB → Prompt ("Based on this context: {retrieved_text}, answer: {question}") → Agent → Text Output

Agents

Agent

The most powerful component. Uses an AI language model to process text, analyze, summarize, generate, classify, translate, extract, or answer questions. Can be enhanced with tools (web search, calculator) and knowledge bases.

Outputs:

• text_output (Message) - The agent's text response, ready to pass to other components
• data_output (Data) - Structured response with metadata (model used, tokens consumed, etc.)

Tips:

• Start with "Blank Agent" for full control, or pick an existing agent to reuse its personality
• Combine with Prompt - Use a Prompt component to build the input dynamically with variables, then connect to the Agent
• Add Knowledge Bases to let the agent reference your company's documents instead of relying on general knowledge
• Enable Web Search when the agent needs current, real-time information beyond its training data

Prompts

Prompt

Creates dynamic text templates using {variable} syntax. Each {variable} automatically becomes a new input field on the component, so you can connect data from other components or fill them manually. This is the recommended way to build structured inputs for Agents.

Output: Message - The template with all variables replaced by their values

Example:

Template: "Write a {tone} email to {recipient} about {topic}. Keep it under {word_count} words."

This creates four input fields: tone, recipient, topic, and word_count. If you connect the topic field to a Web Search's output (via Mapping), the prompt dynamically includes search results.

When to use: Whenever you need to combine multiple pieces of data into a single text before sending it to an Agent. Much more flexible than typing everything into the Agent's input field.

Processing

DF Operations (DataFrame Operations)

Performs table operations on DataFrames, filter rows, sort columns, merge tables, and more. You can chain multiple DF Operations to build data transformation pipelines.

Available Operations:

Output: DataFrame - The transformed table

Example pipeline: Web Search → DF Operations (Filter by "contains: AI") → DF Operations (Head: 5) → Mapping → Agent

Data Operations

Performs operations on Data objects (JSON-like key-value structures). Essential for working with API responses from HTTP Request.

Available Operations:

Output: Data - The transformed data object

Example: HTTP Request returns { "data": { "users": [{"name": "John", "role": "admin"}] } } → Data Operations (Select Keys: data.users) → extracts just the users array.

Helpers

Calculator

Safely evaluates mathematical expressions. Use it for calculations within your flow, totals, percentages, conversions, and more.

Output: Data - The calculated numeric result

Current Date

Returns the current date and time, useful for timestamping, date-based logic, or including the date in generated content.

Output: Message - Formatted date and time string (for example, "2026-03-09 10:30:00 EST")

HTML Parser

Extracts specific elements from HTML content using CSS selectors. Perfect for scraping structured data from web pages.

Output: Message - All extracted values joined by the separator

Example pipeline:

1. URL (Format: HTML) → HTML Parser (selector: a.article-link, attribute: href) → Extracts all article URLs from a page
2. Browserless URL (Format: HTML) → HTML Parser (selector: span.price, attribute: text_content) → Extracts all prices from an e-commerce page

JSON Validator

Validates JSON data against a JSON Schema definition. Use it to ensure API responses or generated data match an expected structure before processing.

Outputs:

• validated_data (Message) - The validated JSON, pretty-printed for readability
• validation_result (Data) - Detailed validation report with valid, errors, and data

Mapping

Converts Data or DataFrame objects into formatted text using a template. This is the bridge between structured data and text-based components like Agents. Previously known as "Parser."

Output: Message - All rows/items formatted and joined by the separator

Field Picker - automatic field suggestions:

1. Connect a Data or DataFrame source to the Mapping component's input.
2. Run the upstream component to populate the field metadata.
3. Click the arrow icon (↓) next to the Template field. A dropdown appears listing all available field names.
4. Click a field name to insert it as a {field_name} placeholder at the cursor position.

This eliminates guesswork, you don't need to remember exact column names. Just run the upstream component and browse the available fields.

Note: The field picker only shows fields after the upstream component has been executed at least once. If no fields appear, run the upstream component first.

Example with DataFrame (from Web Search):

Template: "**{title}**\n{link}\n{snippet}"
Separator: "\n---\n"

Produces:

**AI in 2026**
https://example.com/1
Latest trends in artificial intelligence...
---
**Machine Learning Guide**
https://example.com/2
A comprehensive beginner's guide...

Example with Data (from HTTP Request):

Template: "User: {name} ({email})\nRole: {role}"

When to use: Always use Mapping between a DataFrame/Data source and an Agent. Agents work with text (Message), so Mapping converts your structured data into a format the Agent can understand.

Logic

If-Else

Evaluates a condition and routes data to one of two outputs: True or False. Use it to branch your flow based on text content, numbers, or patterns.

Outputs:

• true_result (Message) - Fires when the condition evaluates to true
• false_result (Message) - Fires when the condition evaluates to false

Example:

Input Text: (connected from Agent output)
Operator: contains
Match Text: "urgent"
→ True: Send Email (notify the team)
→ False: Text Output (log for review)

Example Workflows

1. Web Research Assistant

Goal: Search the web for a topic, summarize the findings with AI, and display the result.

Text Input → Web Search → Mapping → Agent → Text Output

1. Text Input - Enter: "Latest developments in quantum computing 2026"
2. Web Search - Mode: Web, Query: connected from Text Input, Max Results: 5, Fetch Content: Yes
3. Mapping - Template: **{title}**\n{link}\n{content}, Separator: \n---\n
4. Agent - Background: "You are a research analyst. Summarize the following articles into a concise briefing with key takeaways."
5. Text Output - Displays the AI-generated summary

2. Email Newsletter from Web Content

Goal: Scrape a news site, extract headlines, generate a newsletter, and email it.

URL → HTML Parser → Agent → Send Email

1. URL - URLs: https://news.example.com, Format: HTML
2. HTML Parser - CSS Selector: h2.headline a, Attribute: text_content
3. Agent - Background: "You are a newsletter editor. Write a professional email newsletter from these headlines. Include a brief intro and group by topic."
4. Send Email - To: team@company.com, Subject: "Daily News Digest", Body: connected from Agent

3. API Data Extraction Pipeline

Goal: Call an API, extract specific fields, filter results, and display them.

HTTP Request → Data Operations → Data Operations → Mapping → Text Output

1. HTTP Request - URL: https://api.example.com/products, Method: GET
2. Data Operations - Select Keys: body.products (extracts the products array)
3. Data Operations - Filter Values: key=category, operator=equals, value=electronics
4. Mapping - Template: {name} - ${price} ({category})
5. Text Output - Shows the filtered, formatted product list

4. Knowledge Base Q&A

Goal: Search your company's knowledge base and have an AI answer questions based on the results.

Text Input → Retrieve from KB ─┐
                                ├→ Prompt → Agent → Text Output
Text Input ────────────────────┘

1. Text Input - Enter: "What is our refund policy for enterprise customers?"
2. Retrieve from KB - Knowledge Base: "Company Policies", Query: connected from Text Input, Results: 5
3. Prompt - Template: Based on this context:\n\n{context}\n\nAnswer this question: {question}
4. Agent - Model: GPT-4o, Background: "Answer questions accurately based only on the provided context. If the context doesn't contain the answer, say so."
5. Text Output - Shows the AI's answer grounded in your company's documents

5. Conditional Email Alert

Goal: Have an AI classify incoming content and send an email only if it's urgent.

Text Input → Agent → If-Else → Send Email (True)
                             → Text Output (False)

1. Text Input - Enter the content to classify
2. Agent - Background: "Classify the following content as 'urgent' or 'routine'. Respond with only one word."
3. If-Else - Input Text: connected from Agent, Operator: equals, Match Text: urgent, Case Sensitive: No
4. True branch → Send Email - Subject: "URGENT: Action Required", Body: connected from Text Input
5. False branch → Text Output - Logs the content for review

Tips and Best Practices

Building Flows

1. Start simple, iterate. Begin with 2-3 components, run the flow to verify it works, then add more. Debugging a 10-component flow from scratch is much harder than building incrementally.
2. Always use Mapping before Agents. Agents expect text (Message), but many data sources output DataFrame or Data. The Mapping component bridges this gap by formatting structured data into readable text.
3. Use Prompt for complex Agent inputs. Instead of typing everything into the Agent's input field, use a Prompt component with {variables} to combine multiple data sources into a well-structured prompt.

Data Types

4. Check types when connections fail. If you can't connect two components, the output type (Message, Data, DataFrame) doesn't match the input type. The handle colors give you a visual cue, same color means compatible.
5. Use Data Operations for API responses. HTTP Request returns a Data object. Use Data Operations with "Select Keys" to extract the nested fields you need, for example body.results[0].name.
6. Use DF Operations for table data. Web Search, URL, and Browserless URL return DataFrames. Use DF Operations to filter, sort, or select columns before passing data downstream.

Performance

7. Limit results to what you need. Fetching 20 web search results with full content takes much longer than 5 results with just snippets. Start with fewer results and increase if needed.
8. Use URL before Browserless URL. The regular URL component is much faster. Only switch to Browserless URL when you get empty or incomplete results.

Debugging

9. Use Text Output to inspect data. Drop a Text Output after any component to see exactly what it produces. This is the fastest way to understand what data looks like at each step.
10. Check the status indicator. After running a flow, each component shows its status. Click on a failed component to see the error message, it usually tells you exactly what went wrong.