> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow Editor & Workflows

> Build visual multi-step workflows with the drag-and-drop Flow Editor — connect agents, tools, conditions, and teams into automated pipelines.

# Flow Editor & Workflows

The **Flow Editor** is a visual drag-and-drop canvas for building multi-step agent workflows. Instead of configuring a single agent, you design a graph of interconnected nodes — agents, tools, conditions, and teams — that execute in sequence or in parallel.

## When to Use Workflows

Use the Flow Editor when:

* **Your process has multiple steps** — e.g., qualify a lead, then enrich data, then send an email
* **You need branching logic** — Route different outcomes to different paths
* **You want team coordination** — Multiple agents collaborating on a task
* **You need tool chaining** — One tool's output feeds into another
* **You require human approval gates** — Pause workflow for human review

For simple single-agent use cases (answer questions, make calls), the standard agent configuration is sufficient.

## Concepts

### Nodes

A **node** is a single step in your workflow. Each node has a type and configuration:

| Node Type     | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| **Agent**     | An AI agent that processes input and generates a response                  |
| **Tool**      | Executes a specific tool (search, email, API call, etc.)                   |
| **Condition** | If/else branching based on the previous step's output                      |
| **Team**      | A group of agents working together (coordinate, route, collaborate, tasks) |
| **Start**     | The entry point of the workflow                                            |
| **End**       | The termination point                                                      |

### Edges

**Edges** connect nodes and define the flow of data between them. Each edge carries the output of the previous node as input to the next.

### Variables

**Variables** are dynamic values that can be referenced throughout the workflow. Types include:

| Type              | Description               |
| ----------------- | ------------------------- |
| `string`          | Text values               |
| `number`          | Numeric values            |
| `boolean`         | True/false flags          |
| `array`           | Lists of values           |
| `object`          | Structured data           |
| `python_function` | Custom Python expressions |

Variables can be scoped to:

* **Flow-level** — Available to all nodes
* **Session-level** — Persist across sessions for the same user

## Building a Workflow

### From the Dashboard

1. Navigate to your agent's page and click the **Flow** tab.
2. The Flow Editor canvas opens with a **Start** node.
3. Click **+** to add nodes to the canvas.
4. Drag edges between nodes to connect them.
5. Click a node to configure it (model, tools, instructions, etc.).
6. Click **Deploy** when ready.

### Node Configuration

Each node has its own settings panel:

**Agent Node:**

* Model selection (Claude, GPT-4, Gemini, etc.)
* System instructions
* Temperature and max tokens
* Assigned tools
* Knowledge sources

**Tool Node:**

* Tool type (search, email, API call, etc.)
* Tool-specific parameters
* API keys and credentials

**Condition Node (If/Else):**

* Multiple branches with natural language conditions
* LLM-evaluated conditions (the AI reads the previous output and decides which branch to take)
* Default/fallback branch

**Team Node:**

* Team mode: `coordinate`, `route`, `collaborate`, or `tasks`
* Member agents
* Leader instructions
* Max iterations

### Partial Execution (Debugging)

You can run a workflow up to a specific node for debugging:

1. Right-click on a node in the canvas.
2. Select **Run to here**.
3. The workflow executes from Start up to the selected node and shows intermediate results.

This is useful for testing individual steps without running the entire pipeline.

## AI Flow Scaffolding

Don't want to build from scratch? Use the AI to generate a complete flow:

1. In the Flow Editor, click **Generate with AI**.
2. Describe your workflow in natural language.
3. The AI generates a complete graph with nodes, edges, and configurations.
4. Review and customize as needed.

### Via the API

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/scaffold-flow \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead Pipeline",
    "description": "Qualify inbound leads by asking questions, then score and route to sales or nurture"
  }'
```

### Response

```json theme={null}
{
  "graph": {
    "nodes": [
      { "id": "start_1", "type": "start", "data": {} },
      { "id": "agent_qualify", "type": "agent", "data": { "instructions": "..." } },
      { "id": "condition_score", "type": "condition", "data": { "branches": [...] } },
      { "id": "agent_sales", "type": "agent", "data": { "instructions": "..." } },
      { "id": "agent_nurture", "type": "agent", "data": { "instructions": "..." } }
    ],
    "edges": [
      { "source": "start_1", "target": "agent_qualify" },
      { "source": "agent_qualify", "target": "condition_score" },
      { "source": "condition_score", "target": "agent_sales", "label": "Hot lead" },
      { "source": "condition_score", "target": "agent_nurture", "label": "Cold lead" }
    ]
  },
  "suggested_queries": ["I want to learn about your product", "Can I get a demo?"]
}
```

## Graph Execution

When a user sends a message to a workflow-based agent:

1. The message enters at the **Start** node.
2. Each node processes the message in sequence.
3. At **Condition** nodes, the AI evaluates which branch to follow.
4. At **Team** nodes, member agents collaborate according to the team mode.
5. The final node's output is returned to the user.
6. If an **Approval** gate is configured, execution pauses until a human approves.

### Streaming

Workflow execution supports streaming responses. Each node's output is streamed as it completes, so the user sees progressive results.

### Session State

Variables and context persist across messages within a session. This means:

* The agent remembers previous conversation turns
* Variables set in earlier steps are available in later steps
* Session-scoped variables persist across separate conversations

## Via the API

### Execute a Graph

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/graph/execute \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "message": "I want to book an appointment",
    "session_id": "session_xyz",
    "stream": true
  }'
```

### Validate a Graph

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/graph/validate \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "graph": { "nodes": [...], "edges": [...] }
  }'
```

## Best Practices

* **Keep workflows linear for voice agents** — Complex branching can cause latency in phone conversations.
* **Use descriptive node names** — Makes the canvas easier to understand.
* **Test each node individually** — Use partial execution before running the full flow.
* **Set max iterations on teams** — Prevents infinite loops in collaborative modes.
* **Use conditions for routing** — Instead of one big agent, route to specialized agents.
* **Add approval gates for sensitive actions** — Require human confirmation before sending emails, processing payments, etc.