How It Works - Cloudify Documentation

This page walks through what actually happens during a Fourgent session — agent by agent. If you haven’t read the intro yet, start with Welcome to Fourgent.

You type. Four agents take it from there.

When you describe an integration in Fourgent — something like “When a deal closes in HubSpot, send a message to #sales in Slack” — you’re not filling out a form or configuring a template. You’re starting a conversation that hands off through four specialized agents, each one responsible for a specific part of getting your integration live. You can watch every step happen in real time: in the chat on the left, and across the four panels on the right — Progress, Files, Flow, and Mapping. Fourgent session in progress — HubSpot to Slack integration

Fourgent session in progress — HubSpot to Slack integration

Here’s what happens at each stage.

Starting a Session

Before the agents begin, Fourgent needs one thing from you: a clear description of what you want to build. You don’t need to know which APIs are involved, what the field names are, or how authentication works. Just describe the business outcome:

“When a deal is marked Closed Won in HubSpot, send a Slack message to #sales with the deal name and value.”

“Every hour, sync new customer records from Salesforce into our PostgreSQL database.”

“When a Zendesk ticket is marked urgent, create a Jira issue and alert the #support-escalations channel.”

Fourgent will ask a focused follow-up question or two if it needs to close a gap — which trigger to use, whether a condition applies, which direction data should flow. Once it has enough, it hands off to the first agent. You’ll see the handoff happen in the chat: HANDOFF TO ONBOARDING SPECIALIST.

The more specific your description, the fewer questions get asked. You don’t need to be technical — just be specific about the trigger, the apps, and the outcome.

Agent 1 — The Onboarding Agent

What it does: Connects to your apps, discovers exactly what’s available, and defines every rule before any code is written. This is the most important stage. Everything the Coding Agent builds comes from the specification the Onboarding Agent produces. If the spec is complete, the integration works. If it isn’t, edge cases break things in production. The Onboarding Agent handles four things in sequence:

Connects to your apps

It authenticates with both platforms — via OAuth or API key, whichever each app requires. It confirms the connections are live and that it can access the data objects your integration will use.You’ll see this in the chat as connections are retrieved and verified, one by one.

Discovers what's available

Once connected, it inspects both platforms — endpoints, data objects, field structures, event types. It maps out exactly what data exists on each side and where the two systems differ.For a HubSpot → Slack integration, this means understanding which HubSpot deal fields exist, which webhook events fire on deal stage changes, and what Slack’s message API expects.You’ll see this as API Endpoints Found in the chat.

Maps your specific workflow

With both systems understood, it defines your workflow in precise terms — what triggers it, what data moves, what conditions apply, and what the result should look like.This is where it asks targeted questions to prevent failures later:

“Should we include the deal owner’s name in the Slack message?” “Should this fire for all pipelines, or only your Enterprise pipeline?” “What should happen if the deal has no amount set?”

These aren’t generic prompts. They’re generated from the actual field structures and known edge cases of your specific platforms.

As the workflow is mapped, the Flow and Mapping panels on the right begin to populate.

Locks down every edge case

Before handing off, it documents every edge case — null values, duplicate records, data mismatches, conditions that should skip or halt a run. Nothing is left for the Coding Agent to guess.

What it produces

API Connection Map

Every endpoint involved — what gets called, in what order, with what authentication, and what response is expected.

Field Mapping

How data objects in System A map to System B, field by field — including type conversions and format differences. Visible in the Mapping panel.

Trigger & Condition Registry

Every event that starts the workflow, plus every condition that changes behaviour or skips a run. Visible in the Flow panel.

Edge Case Register

Null value rules, duplicate handling, data mismatch strategies — all resolved before the Coding Agent starts.

The Coding Agent does not start until the Onboarding Agent’s specification is complete. Skipping or rushing through its questions produces incomplete specs — and incomplete specs produce integrations that fail in production.

Agent 2 — The Coding Agent

What it does: Takes the Onboarding Agent’s specification and writes the integration code — real TypeScript, not templates or config files. Every file is shaped to your exact workflow. The field mappings, business rules, error handling, and edge cases defined in onboarding are all reflected in the code. Your engineering team can read, modify, and audit every line.

Integration Handler
Field Mapper
Config & Secrets

The core logic file — trigger listener, data transformation, API calls, conditional routing, and error handling. Built from your spec, not a boilerplate starting point.

hubspot-slack.ts

// HubSpot → Slack integration handler
// Generated from: Onboarding spec | Session: fg_xk291
import { HubSpotClient } from '@hubspot/api-client';
import { SlackClient } from './clients/slack';
import { formatDealMessage } from './mappers/deal-message';

export async function onDealClosedWon(dealId: string) {
  const deal = await hubspot.crm.deals.basicApi.getById(dealId);

  // Business rule: Enterprise pipeline only
  if (deal.properties.pipeline !== config.enterprisePipelineId) return;

  const message = formatDealMessage(deal);
  await slack.chat.postMessage({ channel: '#sales', ...message });
}

A dedicated file for translating fields between systems. Kept separate so field mappings can be updated without touching core logic.

mappers/deal-message.ts

// Field mapping: HubSpot Deal → Slack Message

export function formatDealMessage(deal: HubSpotDeal): SlackMessage {
  return {
    text: `Deal closed: *${deal.properties.dealname}*`,
    blocks: [
      {
        type: 'section',
        fields: [
          { type: 'mrkdwn', text: `*Value:* ${formatCurrency(deal.properties.amount)}` },
          { type: 'mrkdwn', text: `*Owner:* ${deal.properties.hubspot_owner_id}` },
        ],
      },
    ],
  };
}

Environment configuration with credentials referenced by path — never hardcoded in files or logs.

.env.production

HUBSPOT_ACCESS_TOKEN=${ssm:/fourgent/hubspot/access_token}
SLACK_BOT_TOKEN=${ssm:/fourgent/slack/bot_token}

As files are generated, they appear in the Files panel on the right. You can open and read each one.

Agent 3 — The Testing Agent

What it does: Runs a full test suite against the integration — before deployment is allowed to proceed. Test cases are built directly from the Onboarding Agent’s specification. Every trigger, condition, and edge case becomes a named test scenario. Payloads are constructed from your actual platform data shapes, not placeholder values.

Testing Agent — Running test suite
hubspot-slack.test.ts | 5 tests | TypeScript

TEST RESULTS

✅  PASS   Sends Slack message on Closed Won deal in Enterprise pipeline
✅  PASS   Skips deals outside Enterprise pipeline
✅  PASS   Handles null deal amount gracefully (omits value field)
✅  PASS   Deduplicates: skips if deal ID already processed
❌  FAIL   Deal owner lookup failed — owner ID not resolving to display name
           No fallback defined for unresolvable owner IDs

When a test fails, the Testing Agent does not proceed to deployment. It surfaces the failure with a precise explanation, routes the unresolved issue back through the spec, patches the code, and re-runs the affected tests. This loop continues until the suite is clean. Test results are visible in the Progress panel as they run.

Deployment is blocked until every test passes. A failure caught here costs nothing. The same failure in production costs data integrity and engineering time.

Agent 4 — The Deployment Agent

What it does: Takes the tested integration and ships it to production — infrastructure, secrets, CI/CD, and all.

CI/CD Pipeline

A GitHub Actions workflow is generated and committed to your repository. Every future change to the integration triggers an automated cycle — install, test, deploy — without manual intervention.

.github/workflows/deploy.yml

name: Deploy Lighthouse Integration
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run integration tests
        run: npm test
      - name: Deploy to Lighthouse Engine
        run: npx sst deploy --stage production
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Deploys the infrastructure

The Deployment Agent uses SST (Serverless Stack) to provision the underlying AWS infrastructure — Lambda functions, event sources, and environment bindings — directly from your integration code. No manual setup required.

npx sst deploy --stage production

Secrets Management

All credentials and tokens are moved to AWS SSM Parameter Store. They are never stored in committed files or plain environment variables. The integration references them by path at runtime.

HubSpot access token → SSM Parameter Store

QuickBooks OAuth credentials → SSM Parameter Store

Webhook signing secrets → SSM Parameter Store

Secures your credentials

All app credentials are moved to AWS SSM Parameter Store. They are never stored in committed files or environment variables — the integration references them by path at runtime.

Runtime Registration

The integration is registered with the Lighthouse Engine — the runtime environment that manages uptime, webhook ingestion, retries, and structured logging from the moment your integration goes live.

Registers with the Fourgent Engine

The integration is registered with the Fourgent Engine, which takes over from here — handling uptime, webhook ingestion, retries, and structured logging.

Handoff Report

A HANDOFF.md is generated and committed alongside the code. It documents what the integration does in plain language, every system involved and how they authenticate, where all secrets are stored, and the test results from Stage 3.This file exists for your engineering team — so they can understand, support, and extend the integration without reverse-engineering the code.

Generates a handoff report

A HANDOFF.md file is generated and committed alongside the code. It documents what the integration does in plain language, every system involved, where credentials are stored, and the full test results.This file is for your engineering team — so they can understand, support, and extend the integration without reverse-engineering the code.

Once the Deployment Agent finishes, your integration is live. The Progress panel updates to show the active deployment.

After Deployment — The Fourgent Engine

The Fourgent Engine is the runtime layer that keeps your integration running reliably once it’s live. You don’t manage it — it runs in the background.

Webhook Manager

Ingests and validates payloads from your apps. Verifies signatures and deduplicates events before your integration logic runs.

Structured Logging

Every run is logged — what triggered it, what happened, what the result was. Searchable by run ID, timestamp, or status. No silent failures.

Automatic Retries

If a downstream API is temporarily unavailable, the Engine retries automatically on a backoff schedule. Recovery happens without you doing anything.

One-Click Replay

Any failed run can be replayed with its original payload — no need to wait for the trigger to fire again.

Event-Driven Processing

Every run executes independently. High event volumes don’t block each other.

Condition-Based Routing

Workflows that branch at runtime — different paths for different record types or values — are handled by the Engine without extra code.

Making Changes After Launch

Your integration doesn’t freeze after deployment. If your workflow changes — a new condition, a new field, a new app — describe the update in the chat and Fourgent handles it end to end: updates the code, re-runs the relevant tests, and redeploys.

Your engineers can also modify the code directly. Fourgent works with the existing codebase — any external changes are picked up when the agent next runs, and redeployment goes through SST as normal.

Your Code, Your Repository

Everything the Coding Agent generates belongs to you and lives in your repo.

What files does Fourgent commit to my repository?

Every file generated is committed to your repo:

Integration handler (*.ts)
Field mappers (mappers/*.ts)
Error handlers (handlers/*.ts)
Test suite (*.test.ts)
SST configuration (sst.config.ts)
Environment config reference (.env.production)
Handoff documentation (HANDOFF.md)

You can clone, read, and audit every line.

Can my engineers modify or extend the code?

Yes. The generated code is standard TypeScript with no proprietary wrappers. Engineers can add logic, extend handlers, or pull files into a larger codebase.Run the test suite after any manual change before redeploying.

What if we stop using Fourgent?

The code continues to work independently. The Fourgent Engine handles runtime, but the integration logic is standard TypeScript that can be deployed to any compatible environment. There is no lock-in at the code layer.

Is the generated code auditable?

Yes. All files follow standard patterns with inline comments. Credentials are stored externally and referenced by path — nothing sensitive appears in source code or logs. The HANDOFF.md provides a plain-language audit trail for non-technical reviewers.

Security

OAuth Where Available

App connections use OAuth by default. Fourgent requests only the minimum scopes required — nothing broader.

Secrets Never in Code

All credentials are stored in AWS SSM Parameter Store from the first deployment. They are never written into files, variables, or logs.

Payload Validation

Every incoming webhook is verified against its signing secret before integration logic runs. Invalid or tampered payloads are rejected at the Engine layer.

Isolated Run Execution

Each integration run executes in its own isolated context. A failure in one run cannot affect concurrent runs.

Continue

Quickstart

Build and deploy your first integration step by step.

Browse Templates

Pre-built integrations for common workflows, ready to customise.

Supported Connectors

Every app and API Fourgent can connect to out of the box.

Talk to the Team

Complex use case? We’ll scope it with you before you start.

​You type. Four agents take it from there.

​Starting a Session

​Agent 1 — The Onboarding Agent

​What it produces

API Connection Map

Field Mapping

Trigger & Condition Registry

Edge Case Register

​Agent 2 — The Coding Agent

​Agent 3 — The Testing Agent

​Agent 4 — The Deployment Agent

​After Deployment — The Fourgent Engine

Webhook Manager

Structured Logging

Automatic Retries

One-Click Replay

Event-Driven Processing

Condition-Based Routing

​Making Changes After Launch

​Your Code, Your Repository

​Security

OAuth Where Available

Secrets Never in Code

Payload Validation

Isolated Run Execution

​Continue

Quickstart

Browse Templates

Supported Connectors

Talk to the Team

You type. Four agents take it from there.

Starting a Session

Agent 1 — The Onboarding Agent

What it produces

Agent 2 — The Coding Agent

Agent 3 — The Testing Agent

Agent 4 — The Deployment Agent

After Deployment — The Fourgent Engine

Making Changes After Launch

Your Code, Your Repository

Security

Continue