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:

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:

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

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

{
  "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

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

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.