> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudify.biz/llms.txt
> Use this file to discover all available pages before exploring further.
# How It Works
> A step-by-step look at what each of the four agents does, what you see in the UI, and how your integration ends up live in production.
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](/introduction).
***
## 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**.
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:
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.
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.
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.
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
Every endpoint involved — what gets called, in what order, with what authentication, and what response is expected.
How data objects in System A map to System B, field by field — including type conversions and format differences. Visible in the **Mapping** panel.
Every event that starts the workflow, plus every condition that changes behaviour or skips a run. Visible in the **Flow** panel.
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.
The core logic file — trigger listener, data transformation, API calls, conditional routing, and error handling. Built from your spec, not a boilerplate starting point.
```typescript hubspot-slack.ts theme={null}
// 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.
```typescript mappers/deal-message.ts theme={null}
// 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 .env.production theme={null}
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.
```text theme={null}
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.
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.
```yaml .github/workflows/deploy.yml theme={null}
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 }}
```
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.
```bash theme={null}
npx sst deploy --stage production
```
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
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.
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.
The integration is registered with the Fourgent Engine, which takes over from here — handling uptime, webhook ingestion, retries, and structured logging.
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.
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.
Ingests and validates payloads from your apps. Verifies signatures and deduplicates events before your integration logic runs.
Every run is logged — what triggered it, what happened, what the result was. Searchable by run ID, timestamp, or status. No silent failures.
If a downstream API is temporarily unavailable, the Engine retries automatically on a backoff schedule. Recovery happens without you doing anything.
Any failed run can be replayed with its original payload — no need to wait for the trigger to fire again.
Every run executes independently. High event volumes don't block each other.
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.
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.
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.
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.
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
App connections use OAuth by default. Fourgent requests only the minimum scopes required — nothing broader.
All credentials are stored in AWS SSM Parameter Store from the first deployment. They are never written into files, variables, or logs.
Every incoming webhook is verified against its signing secret before integration logic runs. Invalid or tampered payloads are rejected at the Engine layer.
Each integration run executes in its own isolated context. A failure in one run cannot affect concurrent runs.
***
## Continue
Build and deploy your first integration step by step.
Pre-built integrations for common workflows, ready to customise.
Every app and API Fourgent can connect to out of the box.
Complex use case? We'll scope it with you before you start.