AI agents builder hub: IA + SEO follow-ups from #17994

[konopkja]

Context

While reviewing PR #17994 ("AI content updates"), five observations came up that are broader than the PR itself. They affect the shape of the AI agents builder hub as a whole and deserve their own discussion rather than blocking the content PR. Filing here so they are tracked.

All evidence is cited to files on the PR branch ai-content-updates at commit 5b37726 or to the deploy preview.

1. /ai-agents/ vs /decentralized-ai/ — pick a spine

The two landing pages overlap on verifiable inference, AI-assisted wallets, and ERC-8004. Each page's intro CTA points at the other, creating a circular handoff:

• ai-agents/index.md line ~37: tells generalists to go to /decentralized-ai/.
• decentralized-ai/index.md line ~24: tells builders to go to /ai-agents/.

A reader arriving cold on either page cannot tell whether the other is the next step or a parallel track.

Options:

• (A) /decentralized-ai/ = concept / explainer that funnels to /ai-agents/ = builder depth. Mirrors the /defi/ (explainer) vs /developers/docs/ (builder) precedent. Strip builder-adjacent sections from /decentralized-ai/.
• (B) Unify both under /ai/ with "Learn" and "Build" sub-sections.

(A) is cheaper and matches existing sitewide patterns. Medium confidence, worth a content-team discussion.

2. /ai-agents/ vs /ai-agents/ethereum/ — keyword cannibalization

Both target "Ethereum AI agents" intent. Preview <title> tags:

• /ai-agents/ → "AI agents on Ethereum | Builder hub"
• /ai-agents/ethereum/ → "Ethereum for AI agents"

Meta descriptions differ, which partially mitigates, but H1s and title intent overlap. Medium confidence.

Fix options: differentiate titles and meta further, or make /ai-agents/ethereum/ a child of the hub rather than a top-level peer.

3. "Foundation / Core infrastructure / Ecosystem" taxonomy is authoring-facing

Used in the hub landing (ai-agents/index.md) and in the "Continue exploring" block on 5 sub-pages. Two placements actively mislead the reader:

• Frameworks is filed under Ecosystem. Getting started step 3 (getting-started.md lines 197-215) tells every builder to install one immediately. "Ecosystem" signals "optional / adjacent", which contradicts the tutorial flow.
• Use cases is filed under Foundation. It is reference material, not prerequisite reading.

Proposed rename to reader intent:

• Start here — hub landing, Ethereum for AI agents, Getting started
• Build blocks — Wallets, Frameworks, Verification, Identity, Payments
• Reference — Use cases, Layer 2s, Data

Confidence: medium on the specific rename, high on the current taxonomy being wrong.

4. "Continue exploring" block is duplicated markdown on 5 sub-pages

ai-agents/{frameworks,getting-started,identity,verification,wallets}/index.md each end with an identical ~17-line Foundation / Core infrastructure / Ecosystem nav block. Adding a new sub-page means editing 6 markdown files.

This is a site-nav responsibility, not content. The /developers/docs/* hub solves it with the Docs layout's SideNav + DocsNav components. A dedicated builder-hub layout (or extending an existing one) that renders a sidebar from the hub's page structure would eliminate the duplication entirely.

Confidence: high on the duplication (visible in markdown). Medium on the right implementation — could also be a lighter shared MDX partial.

5. FAQPage JSON-LD on every page: reconsider post-Aug 2023 policy

All 7 new hub pages plus /decentralized-ai/ emit FAQPage JSON-LD from the new faqItems frontmatter (via app/[locale]/[...slug]/page-jsonld.tsx). Per Google Search Central, Aug 2023:

The FAQ rich result will now only be shown for well-known, authoritative government and health websites.

ethereum.org is neither, so no rich-result payoff. The schema is valid and content-match is mostly clean (one drift found on wallets.md, filed separately in the PR review), but emitting FAQPage on every page adds schema surface with no documented SEO upside and some boilerplate-signal risk.

Counter-argument: there is evolving SEO research suggesting FAQPage schema may help with AI Overviews and generative search, even without rich results. Worth a judgment call by the content team.

Options:

• Keep FAQPage only on the hub landing and top 1-2 most-linked sub-pages.
• Drop entirely.
• Keep as-is if you weight AI-Overview visibility higher than the boilerplate risk.

Confidence: medium. Policy is clear; impact is debated.

[mnelsonBT]

Hey @konopkja , let's talk through these.

— For 1. /ai-agents/ vs /decentralized-ai/ — pick a spine
These are two different target audiences, goals, and sections of the site, so A. is already applied. But stripping "builder-adjacent sections from /decentralized-ai/." will mitigate discovery for someone who lands on one page but is actually the target user for the other.
Hence the structure

"ai-agents/index.md line ~37: tells generalists to go to /decentralized-ai/.
decentralized-ai/index.md line ~24: tells builders to go to /ai-agents/." 

This is to provide clear pathways across the two resources, which are distinct.

— For 4. "Continue exploring" block is duplicated markdown on 5 sub-pages
Your issues were scoped to use .mdx for all; let's address adding "a dedicated builder-hub layout (or extending an existing one)" so there can be internal navigation on this set. There are only 3-4 of the pages included in the pop-out nav, so otherwise a reader would have to go back to the main landing page after reading each page in order to continue navigation.

— For 5. FAQPage JSON-LD on every page: reconsider post-Aug 2023 policy
This is for LLMO (primary) keyword (secondary) - not rich results focused.

I can address 2&3 on the existing PR.

[mnelsonBT]

Issues 2 & 3 for taxonomy were addressed on main PR #17994 with commit f76106c:

• Renamed /ai-agents/ethereum/ from "Ethereum for AI agents" → "Why Ethereum for AI agents" (title, meta, H1) and updated /ai-agents/ metaTitle to AI agent builder hub | ethereum.org so the two pages target distinct search intents (builder-action vs. evaluation). All stale references across the hub updated to match.
• Taxonomy rename (AI agents builder hub: IA + SEO follow-ups from #17994 #18036 item 3): Replaced "Foundation / Core infrastructure / Ecosystem" with "Start here / Core building blocks / Ecosystem and tooling"

Recommendations for remaining items

• 1. "/ai-agents/ vs /decentralized-ai/ — pick a spine" -> Recommend disregarding
  • Pages are in different sections, on different topics, for different audience learning levels, with cross-references to support discovery if a user lands on one instead of the other.
  • Consider improving "further reading" on Decentralized AI use case page to more closely align with target.
• 4. "Continue exploring" block is duplicated markdown on 5 sub-pages" -> Recommend addressing via design update
  • UX design should evaluate other page format that allows for sub-section navigation, creating new with component re-use vs. using existing template based on site design system best practice. Transition for all pages will be straightforward refactor.
• 5. "FAQPage JSON-LD on every page" -> Disregard
  • Goal for FAQ is not rich test results