Agent-Ready App Manifests: A 1‑Page Template to Make Your App Discoverable to AI Agents
Written by AppWispr editorial
Return to blogAGENT-READY APP MANIFESTS: A 1‑PAGE TEMPLATE TO MAKE YOUR APP DISCOVERABLE TO AI AGENTS
AI agents (assistant systems, tool-using LLMs, and orchestration platforms) increasingly read small root-level files and structured metadata to discover and interact with web apps. This post gives founders and product operators a practical, copy‑paste 1‑page manifest plus llms.txt/agents.json checklist, example manifests for SaaS, mobile, and playable demos, JSON‑LD snippets for discovery, and a concise rollout/rollback plan that minimizes SERP risk.
Section 1
Why a 1‑page agent manifest matters (and what agents look for)
AI agents discover apps through a small stack of lightweight surfaces: robots.txt for crawling rules, llms.txt as a short briefing index, agents.txt/agents.json as capability manifests, and JSON‑LD or schema.org markup on landing pages for structured discovery. Making a single, consistent declaration drastically reduces friction for agents and prevents misinterpretation of your product’s capabilities or licensing.
Practically, agents prefer: a root-level plain text brief (llms.txt), a machine‑readable manifest (agents.json or similar), and JSON‑LD embedded on the landing page describing the product as a SoftwareApplication. Standards and community practices are still evolving, but implementing these surfaces now captures early agent referrals without heavy engineering.
- Single-source truth reduces divergence between agent readers and human docs.
- Root-level plain text files are cheap to host and easy to audit.
- JSON‑LD/Gschema markup boosts structured discovery and complements plain-text manifests.
Section 2
Copy‑paste 1‑page Agent-Ready App Manifest (template + SaaS, mobile, demo examples)
Below is a compact, single‑file manifest you can drop at /agent-manifest.json (or /agents.json) and link from llms.txt. The manifest intentionally keeps fields small and audit-friendly: identity, owner/contact, entry points (landing, OpenAPI, demo), capabilities, permitted actions, and change-log metadata for auditability. Use this as the authoritative machine-readable declaration agents consult.
Following the general template are three concrete examples: a SaaS product, a mobile app, and a playable demo. Each shows the minimal fields agents typically read: id, name, owner, endpoints, capability tags, and a short human-readable 'how to start' pointer.
- Host the manifest at the root (example: https://example.com/agents.json) and reference it from llms.txt.
- Keep an immutable id and include a recent 'updated' timestamp for agent cache invalidation.
- Include explicit 'DisallowedActions' or a License pointer to avoid unwanted behaviors.
Sources used in this section
Section 3
llms.txt + agents.json checklist: what to put where
llms.txt should be a short, H1/H2‑structured Markdown file that gives agents a one‑screen briefing and links to the machine‑readable surfaces (agents.json, OpenAPI, MCP, demo). Keep it human readable: a one-line product summary, owner, contact, and a short 'start here' section with links to your manifest, API catalog, and developer guide.
agents.json (or /agent-manifest.json) is the machine contract. The checklist below maps required vs recommended fields, how to version, and what to log for attribution and analytics. Implementing both makes your landing page discoverable for a wide range of agents from research prototypes to production orchestrators.
- llms.txt essentials: H1 title, one-line summary, 'Start:' links to /agents.json and OpenAPI, Contact:, License:.
- agents.json essentials: id, name, owner (name + domain), endpoints (landing, openapi, mcp), capabilities (tags), allowed_actions, updated_iso8601.
- Recommended: include an analytics callback URL for agent referrals, and a short 'how to authorize' block for actions requiring tokens.
Section 4
JSON‑LD & Schema.org snippets for landing pages
JSON‑LD with schema.org's SoftwareApplication type is a stable, search-engine-friendly way to describe your app. Embed a concise SoftwareApplication JSON‑LD snippet in the <head> of your landing page describing name, description, applicationCategory, url, and an @id that matches the id in your agents.json manifest when feasible. This creates a linked discovery surface agents and search engines can dereference.
For callable actions (install demos, open APIs) expose those entry points through clear URLs in the manifest and mirror them in JSON‑LD. Avoid including sensitive credentials or internal endpoints in public metadata. Use JSON‑LD for static descriptive fields and rely on agents.json for dynamic capability declarations (pricing tiers, tool endpoints).
- Include SoftwareApplication, name, url, sameAs, and offers if pricing is public.
- Keep JSON‑LD descriptive — leave executable details and auth flows to agents.json or a protected OpenAPI endpoint.
- Use matching @id values between JSON‑LD and agents.json to make the entity dereferenceable.
Section 5
Rollout and rollback: avoid SERP loss and agent confusion
Roll out agent discovery in staged steps to avoid search engine or ranking surprises: 1) deploy manifests and JSON‑LD to a staging domain, 2) validate with select agents (developer/test agents), 3) gradually expose via canary on a small percentage of production traffic, and 4) monitor search console, server logs, and agent referral analytics for anomalies. Keep robots.txt unchanged during early tests to avoid search impact.
Rollback is straightforward if you follow the one-file principle: revert the single manifest and llms.txt change first. Because search engines and agents cache manifests, include a 'updated' timestamp and a short 'deprecated' flag in your manifest to accelerate downstream cache invalidation. When removing agent surfaces, replace content with a clear deprecation message rather than an immediate 404 to avoid link rot or misattribution.
- Canary: expose agent manifest on 1–5% of traffic before full rollout.
- Keep a single authoritative file for faster audits and easier rollback.
- If rollback needed: update manifest to 'deprecated: true' + timestamp, then remove after 72–96 hours once referrals stop.
Sources used in this section
FAQ
Common follow-up questions
Where should I host llms.txt and agents.json?
Host both files at the root of your canonical domain (example: https://yourdomain.com/llms.txt and https://yourdomain.com/agents.json) so agents can find them predictably. Reference agents.json from llms.txt and mirror descriptive fields in landing-page JSON‑LD.
Will adding these files hurt SEO or my SERP rankings?
Not if you roll them out carefully. Start in staging, canary them on a small percentage of traffic, and avoid sudden content removals. Use descriptive JSON‑LD (Schema.org SoftwareApplication) rather than large content dumps. Monitor Search Console and server logs during rollout.
What sensitive information should I avoid putting into public manifests?
Never include API keys, internal URLs, private database endpoints, or user PII. Keep manifests declarative (endpoints, capability tags, contact, license) and put auth flows behind documented OpenAPI endpoints requiring proper authorization.
Do I need to support every agent standard or protocol?
No. Start with a minimal manifest and llms.txt and add fields for the ecosystems you care about (OpenAPI pointer, MCP for tool servers, analytics hook). Prioritize consistency across your manifests and landing-page JSON‑LD.
Sources
Research used in this article
Each generated article keeps its own linked source list so the underlying reporting is visible and easy to verify.
GitHub
agents-txt/README.md at main · agents-txt/agents-txt · GitHub
https://github.com/agents-txt/agents-txt/blob/main/README.md
GitHub
agents-txt/app/site/src/content/spec/AGENTS-TXT-STANDARD.md · agents-txt
https://github.com/agents-txt/agents-txt/blob/main/app/site/src/content/spec/AGENTS-TXT-STANDARD.md
Software App (SoftwareApplication) Schema | Google Search Central
https://developers.google.com/search/docs/appearance/structured-data/software-app
Hugging Face
AI Agent Documentation: A Guide to llms.txt, AGENTS.md, SKILL.md, and MCP — Hugging Face Blog
https://huggingface.co/blog/phranzia/ai-agent-documentation-guide
Referenced source
Agent Surface · Agent Discovery Checklist
https://agentsurface.dev/docs/discovery/aeo-checklist
Schema.org
SoftwareApplication - Schemaorg Type
https://schema.org/SoftwareApplication
Next step
Turn the idea into a build-ready plan.
AppWispr takes the research and packages it into a product brief, mockups, screenshots, and launch copy you can use right away.