This tutorial walks through a complete integration with the CXP Agent Platform: the code you write in your own repository, the configuration a platform admin does in the UI, and the contracts that join the two.
What you will build
A revenue analytics integration for a fictional org, acme, made of two agents and one custom UI:
| Piece | What it is | Why it is here |
|---|---|---|
revenue-chat | An interactive agent. A user asks a question in natural language; the agent queries a warehouse and answers. | Shows the on-demand path, credential resolution, and live progress. |
nightly-etl | A scheduled agent. Every night it pulls data from an external source into the warehouse. | Shows the scheduled path and long-running work with no UI. |
| Revenue Chat zone app | A standalone Next.js app that provides the chat UI, stitched into the platform at /acme/revenue-chat/app. | Shows a zone — the only way to ship bespoke per-agent UI. |
Two agents rather than one is deliberate: between them they cover every way a run can start, and they show that agents in the same org share credentials and runtime configuration without sharing code paths.
How the pieces fit
┌─ Your repository ──────────────────────┐ ┌─ CXP Agent Platform ─────────────┐
│ │ │ │
│ Trigger.dev tasks │ │ Org, users, roles │
│ revenue-chat-agent ────────────────┼──→│ Agent records + runtime config │
│ nightly-etl │ │ Credential storage │
│ │ │ Schedules │
│ Zone app (Next.js) │ │ Run history + run detail │
│ /acme/revenue-chat/app ←───────────┼───│ Zone proxy + per-request JWT │
│ │ │ │
│ Your own database │ │ Stores JSONB only — │
│ domain tables, chat history │ │ no files, no per-agent tables │
└────────────────────────────────────────┘ └──────────────────────────────────┘
│ ▲
│ resolve credentials, report run state │
└────────────────────────────────────────┘
The division of labour never changes: you own execution and domain data, the platform owns identity, configuration, credentials, and the run record.
Prerequisites
- Node 20+ and familiarity with TypeScript and the Next.js App Router.
- A Trigger.dev project (self-hosted or cloud) that you can deploy tasks to.
- A database of your own if your agents need one. The platform stores JSONB only — it is not where your domain data lives.
- A platform administrator. Creating orgs, agents, runtime environments, and credential requirements are all administrator-only actions. If that is not you, you will need someone who holds that role; this tutorial marks those steps clearly.
- A Nango account only if any credential is OAuth, with the integration you need already configured in it. API keys do not need Nango at all.
- A platform maintainer, but only if you are building a zone app. Registering a zone is a change to the platform's own source plus a redeploy — it is the one step with no admin UI, so it is a request you make rather than something you can do yourself. See Register the zone. Building and running a zone locally needs none of this.
This tutorial uses Trigger.dev throughout. n8n is also a supported runtime, and the differences are covered in the API Reference and architecture pages, but every code sample here is a Trigger.dev task.
Build order
The order matters more than it looks. Two steps in particular are easy to get wrong by doing them too late:
- Register the zone before creating the agent. The per-agent zone JWT secret is minted when the agent record is created, and only if a zone is already registered for that
(org, agent)pair. - Deploy the zone before registering its URL, then redeploy the platform without build cache — the asset proxy is generated at build time.
The pages below are in a working order that respects both.
Walkthrough
- Architecture and choices — the decisions to make before writing code, and what each one commits you to.
- Roles and permissions — which steps need an administrator and which do not.
- Project layout — how to structure the repository that holds your agents and your zone.
- Platform setup — org and runtime environments, done once per customer.
- OAuth integrations with Nango — the provider app, the Nango integration, and how they reach the platform. Skip if you need no OAuth.
- Create the agent — the agent record, field by field, and where its keys live.
- Write the agent task — the payload envelope, the output contract, and deploying.
- Credentials — declaring requirements, connecting them, and resolving them at runtime.
- Triggering runs — every way a run can start, and how to choose.
- Build the zone app — a Next.js app that renders inside the platform.
- Zone data and tenancy — the zone's own database, and who may see which rows.
- Register the zone — wiring the zone to the platform.
- Run lifecycle and progress — what the user sees while a run executes.
- Deploy and go live — environments, deployment, and the go-live checklist.
- Troubleshooting — the failure modes that cost the most time.
If you are only building a custom UI for an agent that already exists, skip to Build the zone app. If you only need the platform to watch an agent you run yourself, read the standalone section of Architecture and choices and then the ingest reference — most of this tutorial will not apply to you.