Skip to content

fix(addie): make agent registration self-explanatory#3781

Merged
EmmaLouise2018 merged 4 commits into
mainfrom
EmmaLouise2018/aao-register-no-member
May 2, 2026
Merged

fix(addie): make agent registration self-explanatory#3781
EmmaLouise2018 merged 4 commits into
mainfrom
EmmaLouise2018/aao-register-no-member

Conversation

@EmmaLouise2018

@EmmaLouise2018 EmmaLouise2018 commented May 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Make member agent registration self-explanatory.

Four issues with the existing flow surfaced from a real user attempt:

  1. The dashboard CTA was unclear. + Add agent did not match the registry concept of enrolled agents.
  2. The Addie seed prompt was nonsensical for first-time registration. Clicking the button sent I want to add an agent for compliance monitoring. to Addie — compliance monitoring is a downstream benefit, not the reason to register.
  3. Addie did not drive a complete intake. When asked to register, Addie listed only 2 of the supported auth modes and re-used the "for compliance monitoring" framing from the tool description.
  4. No member-facing docs explained the click path. docs/registry/registering-an-agent.mdx did not show a member how to actually get from the dashboard to a registered agent.

This PR makes the path obvious end-to-end:

  • Button: rename + Add agent+ Register agent on /dashboard/agents (header + empty state).
  • Seed prompt: all three call sites (dashboard-agents.html x2, services/org-health.ts) now send Help me register my agent. — natural first-person phrasing instead of compliance jargon. Centralized as a REGISTER_AGENT_SEED_PROMPT constant in dashboard-agents.html, mirrored in org-health.ts.
  • Addie tool description: rewrite save_agent to lead with AAO registry registration, list the four persistable auth modes (none / static bearer / static basic / OAuth client credentials), and explicitly state that agent type is server-resolved from a capability snapshot — never asked. Trimmed by ~45% by pushing the intake script into behaviors.md.
  • Addie behaviors: new section in behaviors.md walks Addie through a structured intake (URL → auth method choice → matching fields → protocol) before calling save_agent. Includes a paste-it-all shortcut for power users, an explicit override of the "act immediately on a pasted URL" rule when intent is registration, a no-echo-secrets rule, and an error-recovery branch (probe timeout, auth rejected, validation, permission denied).
  • OAuth user authorization is now described as a separate step — register with None, then click Authorize on the agent card. save_agent no longer advertises a fifth auth mode it can't actually persist.
  • Docs: expand the "How agents end up in the registry" section in docs/registry/registering-an-agent.mdx with the explicit click path: sign in → /dashboard/agents+ Register agent → what Addie will ask. Adopts the post-feat(registry): remove discovered agents from public surface #3780 single-enrollment-path framing (no source: registered/discovered, no four-paths model — those are gone from the public registry surface). Aligns tier wording with the live gate (Professional tier or higher) and describes type resolution as a capability-snapshot read, not a live probe.
  • Link fix: /login was 404ing; replaced with /auth/login (AuthKit handles both sign-in and sign-up via that route). Caught by check:owned-links in CI.

Rebase notes

Rebased on main after #3780 merged. The four-paths / source: registered|discovered framing this PR originally extended is gone from the public registry surface, so the docs change now adapts the click-path walkthrough into main's single-enrollment-path structure rather than restructuring around a "section 1" that no longer exists.

Test plan

  • On /dashboard/agents, the header CTA reads + Register agent and the empty-state CTA reads Register your first agent.
  • Clicking either CTA opens /chat with Addie pre-loaded with Help me register my agent..
  • Addie's first reply mentions the AAO registry (not "compliance monitoring") and lists the four persistable auth modes.
  • Addie does not ask the user for the agent type.
  • Addie collects URL, optional name, auth method, matching credential fields, then calls save_agent.
  • On org-health quick actions, the "Register a buyer/seller agent" link uses the same updated seed prompt.
  • Mintlify docs render: ## How agents end up in the registry contains the numbered click-path; no stale source: registered/discovered or four-paths language remains.
  • All /auth/login links in the docs and Addie behaviors resolve (no 404).

@EmmaLouise2018 EmmaLouise2018 requested a review from bokelley as a code owner May 1, 2026 20:41
@EmmaLouise2018 EmmaLouise2018 force-pushed the EmmaLouise2018/aao-register-no-member branch from 1513635 to ab69b1d Compare May 1, 2026 21:56
- Rename dashboard CTA "+ Add agent" → "+ Register agent"
- Replace seed prompt sent to Addie. Old: "I want to add an agent
  for compliance monitoring." (compliance framing was confusing for
  first-time registration). New: "I want to register an agent in
  the AAO registry. What information do you require?" Updated in
  dashboard-agents.html (header CTA, empty-state CTA) and
  org-health.ts (org-health quick action)
- Reframe Addie's save_agent description around AAO registry
  registration; surface all four auth modes (none / static
  bearer-or-basic / OAuth client credentials / OAuth user) and
  state explicitly that agent type is auto-detected — never asked
- Teach Addie to drive a structured intake (URL → auth method →
  matching fields → protocol) before calling save_agent
- Add a "Quickstart: register your agent (members)" section to
  docs/registry/registering-an-agent.mdx with the explicit sign-up
  → /dashboard/agents → "+ Register agent" path
The bare /login route returns 404; the actual entry point is
/auth/login, which redirects to WorkOS AuthKit and handles both
sign-in and sign-up. Caught by check:owned-links in CI.
Remove the duplicate "Quickstart" section that sat above the four-paths
list and fold its content into "1. Self-registration (members only)" so
there's one canonical place a member learns the click path. Also fixes
the ?org parameter (id, not slug), aligns tier wording with the live
gate, and describes type resolution accurately (capability snapshot,
not live probe).
#3780 removed `source: registered/discovered` from the public registry
surface and collapsed the four-paths model. Update the changeset
description to match — the docs change now expands the one enrollment
path that remains, not "section 1" of a four-section list.
@EmmaLouise2018 EmmaLouise2018 force-pushed the EmmaLouise2018/aao-register-no-member branch from c135671 to 1b6a478 Compare May 2, 2026 04:42
@EmmaLouise2018 EmmaLouise2018 merged commit d32bc37 into main May 2, 2026
22 checks passed
@EmmaLouise2018 EmmaLouise2018 deleted the EmmaLouise2018/aao-register-no-member branch May 2, 2026 04:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant