Building an AI agent workflow with Layers

Loop 1: onboarding

Triggered when your end-customer signs up in your product and opts into growth automation. The sequence:

1. Create a Layers project for the customer
2. Ingest their codebase (GitHub path) or App Store listing (mobile path) to extract brand context
3. Provision SDK credentials and generate install instructions
4. Connect their social accounts via OAuth
5. Generate first content batch and route through approval

Sample code for the core flow (GitHub path):

// Step 1: Create the project
const projectRes = await fetch("https://api.layers.com/v1/projects", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LAYERS_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: customer.name,
    customerExternalId: customer.id, // your own ID, lets you look up later without storing Layers' UUID
    timezone: customer.timezone,
    primaryLanguage: customer.language ?? "en",
  }),
});
const project = await projectRes.json();

// Step 2: Ingest their GitHub repo (async — returns a job)
const ingestRes = await fetch(
  `https://api.layers.com/v1/projects/${project.id}/github/ingest`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LAYERS_API_KEY}`,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      installationId: customer.githubInstallationId,
      repo: "acme/acme-app",
    }),
  },
);
const { jobId: ingestJobId } = await ingestRes.json();
const ingestResult = await waitForJob(ingestJobId);

The full walkthrough with all five steps is in onboard a customer end-to-end. That's the canonical reference — this playbook focuses on the agent-level orchestration around it.

Handling async gracefully

An onboarding flow can take anywhere from 30 seconds to 15 minutes depending on how much scaffolding is involved (repo size, content generation, OAuth flows on the customer side). Your agent has two patterns:

Pattern A: Synchronous polling with progress updates. Good if the customer is actively watching a setup screen in your UI. Stream progress updates to them as each job completes.

Pattern B: Asynchronous with webhook notifications. Good if onboarding can happen in the background. Register a webhook for events like content.generated, project.ready, social_account.connected, and handle them as they fire. See webhooks.

Production agents usually do both: poll for the first 60 seconds while the UI is open, then fall back to webhooks for anything still pending.

What failure looks like

Your agent creates 100 projects simultaneously, hits the rate limit, half of them fail partway. No retries, no idempotency keys, users stuck in half-onboarded state. Fix: use Idempotency-Key header on every mutation endpoint — Layers dedupes on that header for 24 hours, so retries are safe. Add a job queue on your side with exponential backoff. See idempotency and rate limits.

Loop 2: publish-to-learn

Runs on a daily cadence per customer. The sequence:

1. Read recent performance metrics for the customer's project
2. Identify top-performing organic posts (winners)
3. Clone or amplify winners into new content
4. Kill or deprioritize losers
5. Schedule the new content through the customer's connected accounts

This loop is what publish to learn walks through in detail. The agent version:

// Daily cron per customer
async function runPublishToLearn(projectId: string) {
  // 1. Find this week's top performers
  const topRes = await fetch(
    `https://api.layers.com/v1/projects/${projectId}/top-performers?metric=engagement_rate&window=7d&limit=5`,
    { headers: { Authorization: `Bearer ${process.env.LAYERS_API_KEY}` } },
  );
  const { items: topPerformers } = await topRes.json();

  if (topPerformers.length === 0) {
    // Fresh project, no data yet. Skip this cycle.
    return { skipped: true, reason: "no_performance_data" };
  }

  // 2. Clone the best performer as 2 variants
  const newContainerId = crypto.randomUUID();
  const cloneRes = await fetch(
    `https://api.layers.com/v1/content/${newContainerId}/clone-from-post`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.LAYERS_API_KEY}`,
        "Idempotency-Key": crypto.randomUUID(),
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        projectId,
        sourcePlatformPostId: topPerformers[0].platformPostId,
        mode: "fork",
        variations: 2,
      }),
    },
  );
  const { jobId } = await cloneRes.json();
  const job = await waitForJob(jobId);

  // 3. The container is generated. Approval can auto-approve or queue for human review.
  //    That's configured on the project's approval policy.
  return { containerId: job.containerId, topPerformerId: topPerformers[0].platformPostId };
}

The critical design choice here is how the agent decides what to act on. Three ranking axes:

• engagement_rate — for early-stage projects where absolute views are noisy
• conversions — if the customer has SDK installed and is tracking conversion events
• roas — for mature projects with ads running

Your agent should pick the axis based on the project's stage. Early-stage: engagement. Later: conversions or ROAS. The top-performers endpoint accepts any of these.

What failure looks like

Your agent blindly clones the top performer every day, even when the "top" post hasn't crossed a meaningful threshold. Within two weeks the content feed is variations on the same mediocre post. Fix: set a minimum threshold (e.g., only clone if top performer engagement_rate > 0.04), and cap clones-per-source at 4-5. See when clones stop helping.

Loop 3: optimization

The shortest loop, because most of it happens without your agent doing anything. Layers' paid-media optimizer runs nightly and makes decisions automatically: pausing underperforming ads, refreshing creative pools, scaling budgets incrementally.

Your agent's job in this loop is to:

1. Read the decision log and surface material decisions to the customer
2. Override when the customer disagrees with a specific call
3. Inject fresh creative when the pool gets thin

Reading the decision log:

const metricsRes = await fetch(
  `https://api.layers.com/v1/projects/${projectId}/ads-metrics?` +
  `since=${weekAgo}&until=${now}&groupBy=ad&metrics=spend&metrics=conversions&metrics=cpa`,
  { headers: { Authorization: `Bearer ${process.env.LAYERS_API_KEY}` } },
);
const adMetrics = await metricsRes.json();

// Surface: ads spending heavily with no conversions (likely pauses are coming)
const worryAds = adMetrics.series.filter(
  (ad) => ad.spend > 50 && ad.conversions === 0
);

Overriding a decision:

// If the customer wants to keep a specific creative in rotation regardless of score:
await fetch(`https://api.layers.com/v1/projects/${projectId}/ads-content/${adsContentId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.LAYERS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ override: "include" }),
});

See optimizer decisions for the full override model and creative selection for how the selection algorithm ranks the pool.

When to keep the agent out of optimization

Don't have your agent auto-override optimizer decisions without customer consent. The optimizer is built on data; your agent, even if LLM-powered, is reasoning about a sparse context of what it thinks the customer wants. The override column (include, exclude, null) is there for explicit human or agent intervention, not automatic countermanding of the scorer.

If you find your agent wants to override regularly, the tuning needs to happen on project config (CPA targets, fatigue thresholds) not on individual creatives. Talk to Layers support about config tuning if you're hitting this a lot.

Reference architecture

Here's how the three loops fit together in a production agent:

┌─────────────────────────────────────────────────────────┐
│                   Your product                          │
│                                                          │
│  ┌─────────────┐     ┌──────────────┐    ┌───────────┐ │
│  │  Customer   │     │  Onboarding  │    │ Dashboard │ │
│  │   signup    │───▶ │     loop     │    │ (progress)│ │
│  └─────────────┘     │  (one-time)  │    └───────────┘ │
│                      └──────┬───────┘                   │
│                             │                           │
│                             ▼                           │
│  ┌─────────────────────────────────────────────────┐   │
│  │            Background job runner                 │   │
│  │                                                   │   │
│  │  - Publish-to-learn loop (daily per customer)   │   │
│  │  - Optimization review (daily per customer)     │   │
│  │  - Webhook ingestion                             │   │
│  └────────────────┬────────────────────────────────┘   │
│                   │                                      │
└───────────────────┼──────────────────────────────────────┘
                    │
                    ▼
         ┌──────────────────────┐
         │  Layers Partner API  │
         │                      │
         │  - /v1/projects      │
         │  - /v1/content       │
         │  - /v1/metrics       │
         │  - /v1/top-performers│
         │  - /v1/ads           │
         │  - /v1/jobs          │
         └──────────┬───────────┘
                    │
                    ▼
         ┌──────────────────────┐
         │  Layers execution    │
         │                      │
         │  - Content gen       │
         │  - Distribution      │
         │  - Ads optimizer     │
         │  - UGC pipeline      │
         │  - SDK ingest        │
         └──────────────────────┘

Your product handles the UI and customer-facing logic. Layers handles the growth execution. The two communicate through the Partner API (outbound calls) and webhooks (inbound events).

Webhook events to subscribe to

These are the events most agents care about:

Register these via the webhooks API. HMAC signing is handled for you — verify with the secret returned at registration.

When to use an LLM in the loop

Most of the code above isn't LLM-driven. It's plain API orchestration. Where does an LLM add value?

Good LLM uses:

• Generating the initial project brief from a customer intake form
• Writing the customer-facing explanation of what the optimizer just did
• Deciding what to show a customer in their dashboard summary
• Interpreting ambiguous customer feedback ("my last post was weird") into concrete API actions

Bad LLM uses:

• Replacing the optimizer with LLM-based ad decisions (the optimizer is data-driven; LLMs hallucinate without data)
• Generating content outside of Layers' content pipeline (lose the safety/approval/scoring layers)
• Automatically deciding to release a leased account or pause ads without customer consent

The rule of thumb: use LLMs for language tasks (explaining, summarizing, interpreting), not for control tasks (acting on the customer's behalf without explicit consent). Layers already does the control tasks with the scoring pipeline, optimizer, and approval gate — your LLM doesn't need to recreate those.