Create the agent

The agent record is what ties your task on the runtime to a page on the platform. Creating one requires a platform admin.

If this agent will have a zone app, register the zone first. The per-agent zone JWT secret is minted during agent creation, and only when a zone is already registered for this (org, agent) pair. Do Register the zone steps 1–2 now, then come back. If you forget, it is recoverable — rotate the secret afterwards — but the clean path is cheaper.

Go to /acme/agents/new.

1. Basic info

Agent Name — required, up to 100 characters. What the customer sees: Revenue Chat.

Slug — required. Auto-generated from the name while you have not touched it. Lowercase alphanumeric segments separated by single hyphens: revenue-chat.

The slug becomes the agent's URL segment and, for zone-backed agents, part of the zone's compiled basePath. It must match the key you used in the zone registry. Changing it later means rebuilding the zone with a new ZONE_AGENT_SLUG; the settings page warns you about this when you try.

Description — optional, up to 500 characters. Worth writing — it appears in the agent list where a customer is choosing between agents.

Initial Status — three options, default Discovery:

Status	Meaning
`Discovery`	Being set up. Not visible to members, and no executions are allowed.
`Active`	Live and runnable.
`Disabled`	Visible but not runnable.

Leave it on Discovery. You are about to configure credentials and deploy code; you do not want a schedule firing against a half-built agent. Flip it to Active at the end, in Deploy and go live.

2. Environment

Who controls the lifecycle? — Platform-managed (the default) or Standalone-managed. Choose Platform-managed. Picking Standalone hides everything below, because none of it applies.

Runtime — Trigger.dev or n8n. Choose Trigger.dev. Switching this resets the runtime environment selection, so pick it before the next field.

Runtime Environment — select the environment you created in Platform setup: Trigger.dev Acme Production. The dropdown also offers:

Enter credentials manually — supply API URL, secret key, and webhook secret on this agent instead. Works, but duplicates secrets per agent.
Add new environment… — opens the environment form in a dialog without losing what you have typed here.

Only environments matching the selected runtime are listed.

Task ID — required, and this is the field that actually connects the two systems. It must be the exact id string from your task definition:

export const revenueChatAgent = task({
  id: 'revenue-chat-agent',
  // ...
})

so here you type revenue-chat-agent. A typo produces a run that fails immediately with a "task not found" error from the runtime — check this field first when that happens.

Max run duration (minutes) — optional; blank uses the platform default of 120 minutes. Set it to something realistic for the agent: it bounds how long the platform waits before treating a run as stuck, and it caps the wait window for synchronous trigger endpoints. Keep it consistent with the task's own maxDuration, which is expressed in seconds.

3. Miscellaneous

Status poll interval (seconds) — 10 to 3600, default 60. How often the platform asks the runtime how a run is doing. The default is right for most agents; lower it for short interactive runs where a stale status is visible to a user, raise it for hour-long batch jobs.

Nango Environment — select Nango Acme Production if any credential requirement will be OAuth. Leaving it at None (not configured) disables the OAuth option when you declare credential requirements, with the reason shown inline. You can set it later.

Press Create Agent. You land on the agent's overview page at /acme/revenue-chat.

4. What creation generated for you

Beyond the record itself, creating the agent minted secrets:

An ingest API key, always.
A zone JWT secret, if and only if a zone was already registered for acme / revenue-chat.
An agent API key for resolving credentials and calling back.

5. Where the keys live

All of these are under the Agent Settings group in the sidebar, visible only to platform admins. Every one of them can be revealed and rotated; none is show-once.

Page	Key	Give it to
`/acme/revenue-chat/api-key`	`agent_api_key`	Your task code — resolving credentials, run callback, waitpoints
`/acme/revenue-chat/integration`	`ingest_api_key`	Whatever starts runs from outside the platform
`/acme/revenue-chat/webhooks`	`webhook_token`	Callers that cannot send an API key (see Triggering runs)
`/acme/revenue-chat/zone-jwt-secret`	`zone_jwt_secret`	Your zone app's `ZONE_JWT_SECRET`

The /api-key page also shows the agent's numeric id. You need it: it appears in every endpoint URL, and a zone app passes it in trigger payloads.

Two switches are off by default and are not on the create form:

Allow external triggers on /integration. Until you enable it, the trigger, trigger-and-wait, and register endpoints return 403. Enabling it also reveals the exact endpoint URLs for this agent.
Allow webhook triggers on /webhooks. The first time you enable it, the webhook token is minted.

Leave both off unless something outside the platform needs to start runs.

If /zone-jwt-secret says Not set — rotate to generate, the registry entry was added after the agent was created. Press rotate; that generates the secret and is the full fix.

6. Populate the two agents

Repeat for the scheduled agent, with two differences: name Nightly ETL, slug nightly-etl, task id nightly-etl, and a much longer Max run duration — this one moves data for a while. It gets no zone, so no zone JWT secret, and it needs no external trigger switches because the platform's own scheduler starts it.

Two agents is a choice here, not a requirement. Nothing stops one agent having a zone app, schedules, and external triggers at once — the surfaces are independent, and an agent that ingests on a schedule while its zone offers a manual "run now" is a perfectly ordinary shape. The tutorial splits them only so each example stays small. If your case is one agent doing both, create one.