Developer Guide to AXO

As a developer, you're responsible for creating the technical infrastructure that enables Agent Experience Optimization. This guide covers the essential technical implementations that make your content accessible to LLM agents.

Schema & Structured Data

JSON-LD Implementation

LLM agents rely heavily on structured data to understand content context. Companies like Shopify and Stripe have seen significant improvements in AI agent citations after implementing proper schema markup. Implement JSON-LD markup for key content types:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Your Article Title",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2024-01-15",
  "dateModified": "2024-01-20",
  "description": "Clear, factual description",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://yoursite.com/article"
  }
}

Essential Schema Types for AXO

• Article: For blog posts, guides, and informational content
• FAQPage: For frequently asked questions
• HowTo: For step-by-step instructions
• Organization: For company and contact information
• Product: For product pages and specifications

Semantic HTML Structure

Proper Heading Hierarchy

LLM agents parse content hierarchically. Use headings to create clear content structure:

<h1>Main Topic</h1>
  <h2>Subtopic A</h2>
    <h3>Detail A1</h3>
    <h3>Detail A2</h3>
  <h2>Subtopic B</h2>
    <h3>Detail B1</h3>

Semantic Elements

Use HTML5 semantic elements to provide context:

<article>
  <header>
    <h1>Article Title</h1>
    <time datetime="2024-01-15">January 15, 2024</time>
  </header>
  
  <section>
    <h2>Key Information</h2>
    <p>Factual content that agents can reference...</p>
  </section>
  
  <aside>
    <h3>Related Information</h3>
    <p>Supporting details...</p>
  </aside>
  
  <footer>
    <p>Source: <cite>Authoritative Reference</cite></p>
  </footer>
</article>

Content APIs for Agent Access

Structured Content Endpoints

Create API endpoints that serve content in agent-friendly formats:

// /api/content/[slug]/route.ts
export async function GET(request: Request, { params }: { params: { slug: string } }) {
  const content = await getContent(params.slug)
  
  return Response.json({
    title: content.title,
    summary: content.summary,
    facts: content.keyFacts,
    lastModified: content.updatedAt,
    sections: content.sections.map(section => ({
      heading: section.heading,
      content: section.content,
      facts: section.extractedFacts
    }))
  })
}

AXO Manifest Endpoint

Provide a manifest that describes your site's AXO capabilities:

// /api/axo-manifest/route.ts
export async function GET() {
  return Response.json({
    site: "https://yoursite.com",
    axoVersion: "1.0",
    contentTypes: ["articles", "guides", "faqs"],
    lastUpdated: new Date().toISOString(),
    endpoints: {
      content: "/api/content/{slug}",
      search: "/api/search",
      sitemap: "/sitemap.xml"
    },
    policies: {
      crawlable: true,
      citable: true,
      updateFrequency: "daily"
    }
  })
}

llms.txt Implementation

Implement the proposed llms.txt file (spec) to help AI agents discover and understand your site:

# Create /public/llms.txt
# Agent Experiences - Agent Experience Optimization (AXO) Resource

This website provides detailed resources for Agent Experience Optimization (AXO) - the practice of optimizing websites and content for LLM agents and AI search systems.

## Site Structure
- Homepage: https://yoursite.com/ - Overview of AXO concepts and role-based navigation
- Developer Guide: https://yoursite.com/guides/developers - Technical implementation details
- Writer Guide: https://yoursite.com/guides/writers - Content creation best practices
- Admin Guide: https://yoursite.com/guides/admins - Site management and monitoring
- SEO Guide: https://yoursite.com/guides/seo - AXO integration with traditional SEO
- AXO Playbook: https://yoursite.com/axo-playbook - Comprehensive best practices
- Glossary: https://yoursite.com/glossary - AXO terminology and definitions
- Blog: https://yoursite.com/blog - Latest insights and case studies

## Key Features
- Structured data implementation with JSON-LD
- Semantic HTML5 markup
- Citation-ready content formatting
- Agent-friendly content APIs
- Comprehensive sitemap generation

Performance Optimization

Fast Loading for Agents

LLM agents may crawl your site frequently. Optimize for speed:

• Static Generation: Use Next.js static generation for content pages
• Caching: Implement proper HTTP caching headers
• Compression: Enable gzip/brotli compression
• CDN: Use a CDN for global content delivery

Efficient Crawling

Make it easy for agents to discover and access content:

// Generate complete sitemaps
export default function sitemap(): MetadataRoute.Sitemap {
  return [
    {
      url: 'https://yoursite.com',
      lastModified: new Date(),
      changeFrequency: 'daily',
      priority: 1,
    },
    // Include all content pages with accurate lastModified dates
    ...contentPages.map(page => ({
      url: `https://yoursite.com/${page.slug}`,
      lastModified: page.updatedAt,
      changeFrequency: 'weekly',
      priority: 0.8,
    }))
  ]
}

Clean Metadata Implementation

Page-Level Metadata

Implement detailed metadata for each page:

export const metadata: Metadata = {
  title: 'Specific, Descriptive Title',
  description: 'Clear, factual description under 160 characters',
  keywords: ['relevant', 'keywords', 'for', 'content'],
  authors: [{ name: 'Author Name', url: 'https://author-profile.com' }],
  openGraph: {
    title: 'Specific Title',
    description: 'Clear description',
    type: 'article',
    publishedTime: '2024-01-15T00:00:00.000Z',
    modifiedTime: '2024-01-20T00:00:00.000Z',
    authors: ['Author Name'],
  },
  robots: {
    index: true,
    follow: true,
    googleBot: {
      index: true,
      follow: true,
    },
  },
}

Consistent URL Structure

Design URLs that are predictable and meaningful:

✅ Good: /guides/developers/schema-implementation
✅ Good: /blog/2024/axo-best-practices
❌ Bad: /p/123456/dev-guide
❌ Bad: /content?id=abc&type=guide

Technical Checklist

Testing Your Implementation

Validation Tools

• Schema Markup Validator: Test your JSON-LD implementation
• HTML5 Validator: Ensure semantic markup is correct
• Lighthouse: Check performance and accessibility
• Sitemap Validator: Verify your sitemap is properly formatted

Agent-Friendly Testing

Test how agents might interact with your content:

1. Content Extraction: Can key facts be easily identified?
2. Navigation: Is the content structure logical and hierarchical?
3. Updates: Are modification dates accurate and current?
4. Performance: Does the site load quickly for automated crawlers?

Common Implementation Mistakes

• Missing or incorrect JSON-LD: Agents can't understand content context
• Poor heading hierarchy: Content structure is unclear to parsers
• Outdated metadata: Modification dates don't reflect actual changes
• Slow loading: Agents may timeout or skip slow pages
• Broken internal links: Agents can't discover all content

References

1. Schema.org Documentation - Schema.org Community
2. HTML5 Semantic Elements - MDN Web Docs
3. Next.js Metadata API - Vercel

Ready to implement these technical foundations? Start with JSON-LD structured data and semantic HTML, then gradually add the API endpoints and performance optimizations.