Agency Onboarding

PreviousNext

The /onboarding/agency interview, from the website to the agency dashboard with Roster

Overview

/onboarding/agency is the onboarding for agencies: agencies that represent talent, and agencies that buy talent for brands. It starts with the agency's website, researches it, and asks what kind of agency it is only when the research cannot tell. Then it asks the person's name. There is no roster question: the roster is added from the dashboard after sign-up. It ends on the agency dashboard, with Roster on.

The account is the agency. The person filling it in is saved as the contact. It runs on the same page, chat, research card, photo card and sign-up as Agent Setup Onboarding.

Flow

What Z asks

The questions are AGENCY_LANDING_INTERVIEW_QUESTIONS in packages/z-agent/srv/src/onboarding-questions.ts, asked one at a time in this order.

#AreaWhat Z asksCovered when
1sources"What's your agency's website? Add any social handles too, so I can learn who you work with."A website or handle (researched), or the agency name when the site cannot be opened
2agencyKind"Do you represent talent, or buy for brands?"The research role or description says which. Asked only when it does not
3contact"And your full name, first and last? Not the agency, you, the person I'll be working with."The person's full name
  • The kind question has exactly two options. The agent never offers "both"; an agency that does both counts as representing talent. When Z does ask it, the two answers show as canned chips: "I represent talent" and "I buy for brands".
  • The framework's website question ends with "and pull your roster". That part is left out: pulling the roster from the site is blocked (ZLY-2023), so the agent does not promise it.

No roster question

  • The interview does not ask who is on the roster, or which brands an agency buys for. The persona instructions tell the agent not to.
  • Sign-up turns Roster on, and the roster is added from the dashboard, where the file upload lives.
  • The agent never says it is building an agent for each person or pulling the roster from the site.
  • If they mention talent anyway, no accounts are created from those names.

Handles that are not the company

Research reads @handles as well as links (see Research Tool and Findings Card). In the brand and agency interviews that is a risk: an example of the talent a brand wants, or talent an agency mentions, is someone else's handle. Two rules keep them off the company:

  • Prompt. The brand's ideal-talent area and the agency persona instructions tell the agent never to call researchTool for those handles.
  • Code. In brand and agency, the links in a chat reply are saved as the company's only while no link is saved yet, which is the website step (savesChatLinksAsOwn in applyOnboardingChatTurn).

After sign-up

  1. Photo. "Add your logo so your talent and brands see who they're with." Skip works too.
  2. Sign up. The auth modal opens on the page, prefilled with the agency name.
  3. Claim. Bouncer and Scout are enabled. The account type becomes agency, and in the same transaction setAccountType enrolls Roster. The onboarding is copied to the account memory: the agency as identity.displayName, the person as identity.contactName.
  4. Dashboard. The agency dashboard opens, with the roster ready for a file upload.

Key files

AreaFile
Questionspackages/z-agent/srv/src/onboarding-questions.ts (AGENCY_LANDING_INTERVIEW_QUESTIONS)
Goal, persona instructions, Distil notepackages/z-agent/srv/src/onboarding-instructions.ts (LANDING_FLOWS.agency)
Opening lines, link rule, account typepackages/z-agent/srv/src/onboarding-copy.ts (AGENCY_INTRO, AGENCY_SITE_ASK, savesChatLinksAsOwn, accountTypeForOnboardingFlow)
Chat turn and claimpackages/z-agent/srv/src/onboarding.ts (applyOnboardingChatTurn, finalizeOnboardingRoom)
Account type and Rosterpackages/db/src/access/account.ts (setAccountType)
Logo wordingpackages/offers/client/src/app/components/onboarding/copy.ts (PHOTO_ASK_AGENCY)
Routeapps/zooly-app/app/(pages)/onboarding/agency/page.tsx

Testing

  • Unit tests: onboarding-questions.test.ts, onboarding-instructions.test.ts and onboarding-copy.test.ts on the server.
  • Manual walkthrough: tests/manual/zly-2026-onboarding-three-flows.md, stage 3. It checks that the agent never asks for the roster.