Developer Guide

1. Endpoint Configuration

Make a POST request to the deployed Cloud Function URL.

• Method: POST
• Headers:
  • Content-Type: application/json
  • x-api-key: YOUR_API_KEY (Required for authorization)

2. Single Execution (Synchronous)

Trigger a single pipeline run. The request will block until the pipeline completes and returns the final execution results.

{
  "pipelineId": "string (required)",
  "inputs": {
    "node_id": "value", // Text inputs
    "image_node_id": "https://... or data:image/... or gs://..." // File inputs
  },
  "textOverrides": {
    "node_id": "replacement text" // Optional prompt overrides
  },
  "runParallel": true // Optional, defaults to true
}

Response (200 OK)

{
  "success": true,
  "runId": "run-123456789",
  "results": {
    "node_1": {
      "success": true,
      "output": { ... }
    }
  }
}

3. Batch Execution (Asynchronous)

Trigger multiple runs simultaneously by providing an inputsList. The server immediately returns a 202 Accepted while jobs process in the background. Use the Batch Jobs UI to monitor progress.

{
  "pipelineId": "string (required)",
  "folderId": "string (required for tracking)",
  "inputsList": [
    { "node_id": "value 1" },
    { "node_id": "value 2" }
  ]
}

Response (202 Accepted)

{
  "success": true,
  "message": "Batch execution started",
  "count": 2,
  "folderId": "folder_123"
}

1. Endpoint Configuration

Make a GET request to the deployed Cloud Function URL.

• Method: GET
• Headers:
  • x-api-key: YOUR_API_KEY (Required for authorization)

2. List Pipelines

Retrieve a minimal list of all available pipelines. You can optionally filter for pipelines explicitly exposed to Gemini Enterprise.

Request

Response (200 OK)

{
  "success": true,
  "pipelines": [
    {
      "id": "pipe_123",
      "name": "Image Generation",
      "description": "Creates an image",
      "updatedAt": "2026-06-19T00:00:00Z"
    }
  ]
}

3. Get Pipeline Details

Fetch the full definition of a specific pipeline, including its node graph and configuration.

Request

Response (200 OK)

{
  "success": true,
  "pipeline": {
    "id": "pipe_123",
    "name": "Image Generation",
    "data": { ... full React Flow graph data ... }
  }
}

4. Gemini Enterprise Config

Retrieve the global settings defined for the conversational Gemini Enterprise agent.

Request

Response (200 OK)

{
  "success": true,
  "config": {
    "agentName": "My Agent",
    "tone": "Professional",
    "description": "...",
    "systemPrompt": "..."
  }
}

Step 1: Type & Registry Definition

Define your node in app/pipelines/types.ts and register it in components/pipelines/constants.ts.

// components/pipelines/constants.ts
your_new_node_type: {
  type: 'your_new_node_type',
  label: 'My New Node',
  inputs: [
    { id: 'source_text', type: 'text', label: 'TXT', required: true }
  ],
  outputs: [
    { id: 'result', type: 'text', label: 'TXT' }
  ]
}

• Handle IDs: The system strictly uses a type:name format. Defining id: 'source_text', type: 'text' creates the handle text:source_text.

Step 2: UI Component & Editor Registration

Create a React Flow node component in components/pipelines/nodes/ using the standard NodeShell.

import { NodeShell } from '../ui/NodeShell';
import { InputLabeledHandle, OutputLabeledHandle } from './LabeledHandle';

export const YourNewNode = ({ data, selected }) => {
  return (
    <NodeShell label="My New Node" selected={selected}>
      {/* Matches registry definition */}
      <InputLabeledHandle name="source_text" dataType="text" label="TXT" />
      <OutputLabeledHandle name="result" dataType="text" label="RES" />
    </NodeShell>
  );
};

Next, register it in:

• components/pipelines/nodes/index.ts (Export the component)
• components/pipelines/node-categories.json (Add to Sidebar Palette)

Step 3: Execution Logic (Server)

Create the modular executor in actions/executors/your-new-node.ts.

export async function executeYourNewNode(step, inputs, runId, modelConfig) {
  // 1. Extract inputs matching the 'name' from registry
  const sourceText = inputs['source_text'];

  if (!sourceText) return { success: false, error: 'Missing input' };

  // 2. Perform logic
  const resultValue = `Processed: ${sourceText}`;

  // 3. Return output mapping to registry outputs
  return {
    success: true,
    output: { result: resultValue }
  };
}

Finally, map it into the central factory in actions/pipeline-execution.ts.

Step 4: Unit Testing & E2E Validation

Every new executor MUST have automated test coverage using Vitest.

• Unit Testing: Run npm test. Cloud SDKs and external calls are mocked by default in vitest.setup.ts.
• E2E Integration: If interacting with real GCP services (like Vertex AI), write tests in tests/e2e/nodes/ and run with INTEGRATION_TESTS=true npx vitest run tests/e2e/nodes/ using Application Default Credentials.

Step 5: Documentation & Data Schema

To ensure your node is usable and discoverable, update the following:

• Node Catalog: Create data/nodes/your-new-node.ts (NodeDoc) and data/nodes/your-new-node.md to render its landing page documentation.
• JSON Schema: Update data/pipeline.schema.json so the internal LLM generation agents know about your new node's syntax.
• Folder Runner (Optional): If your node ingests media, update calculatePipelineCapacity in lib/pipelines.ts so the Batch Jobs modal maps files correctly.
• Starter Template (Optional): Drop a your-new-node-type.json file in data/node-templates/ for automatic loading.