Skip to main content

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.

The three tracks​

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

TrackWhatWhereReference
A — Build the agent serviceBuild 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 listingInsert the agent into the marketplace's agents table, configure capabilities/steps/pricing/quotas, get the OAuth clientIdmarketplace-fleapoai-serviceTrack B
C — Wire the marketplace UIThe 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 datafleapo-marketplaceTrack 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.
  • 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.