Skip to main content

​
Overview

The agent_connections table manages connections between agents in a workflow. Each connection represents a data flow or relationship from a source agent to a target agent.

​
Table Schema

​
id
string
required
Unique identifier for the connection record (auto-generated UUID)
​
user_id
string
required
Foreign key reference to the authenticated user
​
workflow_id
string
required
Foreign key reference to the workflow this connection belongs to. Must be a valid UUID.
​
source_element_id
string
required
ID of the source workflow element where the connection originates
​
target_element_id
string
required
ID of the target workflow element where the connection terminates
​
created_at
string
ISO 8601 timestamp of when the connection was created
​
updated_at
string
ISO 8601 timestamp of the last connection update

​
TypeScript Interface

export interface Connection {
  id: string;
  sourceId: string;
  targetId: string;
  label?: string;
}

// Extended interface with database fields
export interface AgentConnection {
  id: string;
  user_id: string;
  workflow_id: string;
  source_element_id: string;
  target_element_id: string;
  created_at?: string;
  updated_at?: string;
}

​
CRUD Operations

​
Get All Connections

Retrieves all connections for the authenticated user. Endpoint: manage-connections (GET) Request: GET request with Authorization header Response: 
{
  "connections": [
    {
      "id": "conn-uuid-1",
      "user_id": "user-uuid",
      "workflow_id": "workflow-uuid",
      "source_element_id": "element-1",
      "target_element_id": "element-2",
      "created_at": "2026-03-03T10:00:00Z",
      "updated_at": "2026-03-03T10:00:00Z"
    }
  ]
}

​
Create Connection

Creates a new connection between two workflow elements. Uses upsert to prevent duplicates. Endpoint: manage-connections (POST) Request: 
{
  "workflowId": "workflow-uuid",
  "sourceElementId": "element-1",
  "targetElementId": "element-2"
}
Response: 
{
  "success": true
}
Error Responses: 
// Missing required fields
{
  "error": "Workflow ID, source element ID, and target element ID are required"
}

// Self-connection attempt
{
  "error": "Cannot connect an agent to itself"
}

// Invalid workflow ID format
{
  "error": "Invalid workflow ID format"
}

​
Delete Connection

Removes a connection between two workflow elements. Endpoint: manage-connections (DELETE) Request: 
{
  "workflowId": "workflow-uuid",
  "sourceElementId": "element-1",
  "targetElementId": "element-2"
}
Response: 
{
  "success": true
}

​
Validation Rules

​
UUID Validation

The workflow_id must be a valid UUID format. The system validates using this regex pattern: 
function isValidUUID(str: string) {
  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
  return uuidRegex.test(str);
}

​
Self-Connection Prevention

Connections cannot be created where source_element_id equals target_element_id. The system rejects such attempts with an error.

​
Relationships

  • user_id → References the authenticated user’s ID
  • workflow_id → References a workflow in the user_workflows table
  • source_element_id → References an element ID in the workflow’s elements array
  • target_element_id → References an element ID in the workflow’s elements array

​
Constraints

  • Unique constraint: The combination of workflow_id, source_element_id, and target_element_id must be unique (enforced by upsert with onConflict: 'workflow_id,source_element_id,target_element_id')
  • Self-connections are not allowed (source_element_id ≠ target_element_id)
  • The workflow_id must be a valid UUID
  • All three identifiers (workflow_id, source_element_id, target_element_id) are required

​
Usage Notes

  • Connections define the data flow and execution order in a workflow
  • The upsert operation prevents duplicate connections from being created
  • When deleting a workflow element, associated connections should also be removed
  • Connections are stored separately from the workflow data structure for better normalization and query performance
  • The system automatically updates the updated_at timestamp on upsert operations

Build docs developers (and LLMs) love

Get started for freeTalk to us