Add a New Agent — Overview

This is the headline journey of the docs. Read it once end-to-end before opening any of the three tracks.

First: which type of agent?

Before anything else, decide whether you are adding an integrated or a listed agent — it is the first thing the admin UI asks, it cannot be undone (except as a one-way upgrade), and it decides how much of this guide applies to you.

	Integrated agent	Listed agent
Sells through the marketplace	Yes — Stripe tiers and subscriptions	No
Signup & billing	Marketplace account, federated into the agent over OAuth	The agent's own, entirely off-platform
Marketplace hosts	Full listing + checkout + entitlement API	Listing only
Primary CTA	"Choose a plan"	"Visit site" → externalUrl
Tracks below that apply	A, B, C	B only

If you are adding a listed agent, you can stop after Track B. There is no service to build (Track A) because you are not integrating anything — you are cataloguing a product that already runs elsewhere. You need only the Basics, Media and Content tabs, plus a required Site URL (externalUrl) and an optional Pricing URL. Skip every OAuth, pricing tier and quota step in this guide.

The rest of this page assumes an integrated agent. See Agent types for the full behavioural contract and the conversion path.

The three tracks

Adding an agent to Fleapo is three independent tracks that run in parallel and converge at the end-to-end checklist.

Track	What	Where	Reference
A — Build the agent service	Build the actual runtime — backend, frontend, hosting. Speak OIDC to the marketplace. Read tier + consume quota from the marketplace API.	A new repo you create (anywhere)	agent-poc / VoxaAI
B — Register the listing	Insert the agent into the marketplace's agents table, configure capabilities/steps/pricing/quotas, get the OAuth clientId	marketplace-fleapoai-service	Track B
C — Wire the marketplace UI	The UI is already wired to render any agent that comes back from the API — but you'll often want to add a category theme, tweak hero copy, or stage with mock data	fleapo-marketplace	Track C

Track B and Track A unblock each other: Track B issues you an oauthClientId you need in Track A; Track A produces a productDomain you need in Track B.

Decision tree

How long this takes

A first-time integrator following this guide closely:

• Track B (register the listing): 30–60 minutes — assuming you already have admin access and the agent's marketing copy ready.
• Track A (build the agent service): a few days to a few weeks — depends entirely on what your agent does. The OAuth + quota integration itself is a few hours if you mirror agent-poc.
• Track C (wire the UI): 0 to a few hours — if you're happy with the default rendering and just add a category theme, this is almost free.

What you'll need before starting

Track B (and the OAuth provisioning) requires:

• A platform_admin account on the target marketplace instance.
• The agent type (integrated or listed) — asked before the form opens, and for a listed agent a required externalUrl.
• Agent metadata: name, slug, tagline, description, longDescription, iconUrl, photoUrls[], productDomain (where your agent's frontend will live), docsUrl, changelogUrl.
• Final list of redirectUris — including localhost variants for local dev.
• Pricing strategy: tier names, prices, billing intervals, free trial days, recommended tier.
• Metric definitions: which units you'll meter and whether each is fixed or rolling.

Track A requires:

• A backend stack of your choice. Anything that can run an OIDC RP and make HTTPS calls.
• A frontend stack of your choice.
• Hosting that supports HTTPS (cookies will need SameSite=None; Secure).
• The oauthClientId from Track B.
• The marketplace's AUTH_URL (e.g. https://api.fleapo.ai) and FRONTEND_URL (e.g. https://marketplace.fleapo.ai).

How this section is organized

1. Track A — Build the agent service — using agent-poc as the canonical reference.
2. Track B — Register the listing — every backend mutation needed, in order.
3. Track C — Wire the marketplace UI — categories, themes, mock data toggle.
4. End-to-end checklist — what to verify before declaring done.
5. Publishing & approval — moving from draft → coming_soon → active.

Go straight to Track B if you already have an agent service running.