Skip to main content

agents.md.liquid

The agents.md.liquid template renders the agents.md file, which is hosted at the /agents.md URL.

The agents.md file is the canonical, agent-facing description of a store. It tells AI agents and shopping assistants how to discover the store's commerce capabilities and how to transact with it, including:

  • The store's Universal Commerce Protocol (UCP) discovery and Model Context Protocol (MCP) endpoints.
  • Read-only browsing URLs for product, collection, and search data.
  • The store's published policies.
  • Guidance for personal shopping agents, such as the Shop skill.

Shopify generates an agents.md file by default, which works for most shops, so this template isn't included in any themes by default.

Tip

The agents.md file is served at the bare primary domain, without a locale or Shopify Markets subfolder prefix. It has no localized counterpart.

Anchor to Relationship to llms.txt and llms-full.txtRelationship to llms.txt and llms-full.txt

agents.md is the canonical agent-discovery document. The /llms.txt and /llms-full.txt URLs are alternate URLs that mirror the content of /agents.md by default on Shopify stores, so agents that request either one still find a usable document.

Because of this, the agents.md.liquid template is the fallback for all three URLs. When a request is served, Shopify looks for a theme template in the following order, and uses the first one it finds:

URLTemplate lookup order
/agents.mdagents.md.liquid → Shopify-generated default
/llms.txtllms.txt.liquid → agents.md.liquid → Shopify-generated default
/llms-full.txtllms-full.txt.liquid → agents.md.liquid → Shopify-generated default

This means that if you add only an agents.md.liquid template, then it's used for all three URLs. To make one of the llms URLs diverge, add a dedicated llms.txt.liquid or llms-full.txt.liquid template — it takes precedence for that URL only, while the others keep mirroring agents.md.

Anchor to LocationLocation

The agents.md.liquid template is located in the templates directory of the theme:

└── theme
├── layout
├── templates
| ...
| ├── agents.md.liquid
| ...
...

If your theme doesn't already contain the agents.md.liquid template, then you can add it with the following steps:

  1. From your Shopify admin, go to Online Store > Themes.

  2. Find the theme that you want to edit, and then click ... > Edit code.

  1. In the left sidebar, locate the Templates folder.
  2. Right-click on the Templates folder.
  3. Click New File from the context menu.
  4. Name the file agents.md.liquid.
  5. Press Enter to create the file.

Anchor to ContentContent

This template can't be a JSON template. It must be agents.md.liquid.

The template accepts standard Markdown and Liquid. To help you build agent instructions with values that stay in sync with the store's actual commerce configuration, the template exposes an agents object alongside the standard global Liquid objects (such as request and shop).

Anchor to The ,[object Object], objectThe agents object

The agents object provides auto-populated UCP and agent-interaction metadata for the store:

PropertyTypeDescription
agents.store_namestringThe name of the store.
agents.store_urlstringThe full URL of the store, using the bare primary domain.
agents.ucp_discovery_urlstringThe UCP discovery URL for the store ({store_url}/.well-known/ucp).
agents.mcp_endpoint_urlstringThe MCP (Model Context Protocol) endpoint URL ({store_url}/api/ucp/mcp).
agents.ucp_versionsarray of stringThe supported UCP versions, newest first. Derived from the store's UCP implementation, so it stays in sync automatically.
agents.currencystringThe store's primary currency code, such as USD.
agents.sitemap_urlstringThe store's sitemap URL ({store_url}/sitemap.xml).

For example:

templates/agents.md.liquid

# Agent Instructions — {{ agents.store_name }}

This document describes how AI agents can interact with the online store at {{ agents.store_url }}.

## Commerce Protocol (UCP)

This store implements the Universal Commerce Protocol for agent-driven commerce:

- Discovery: `GET {{ agents.ucp_discovery_url }}`
- MCP endpoint: `POST {{ agents.mcp_endpoint_url }}`

### Supported UCP versions
{% for version in agents.ucp_versions %}
- {{ version }}{% if forloop.first %} (latest stable){% endif %}
{% endfor %}

## Read-only browsing

- All products: `GET /collections/all`
- Product JSON: `GET /products/{handle}.json`
- Sitemap: {{ agents.sitemap_url }}

Pricing and availability are returned in {{ agents.currency }}.
Caution

Avoid outputting potentially private merchant data, such as contact email addresses or phone numbers, in this file. The Shopify-generated agents.md deliberately omits contact details because the file is broadly cached and served to every agent that requests it.

Anchor to UsageUsage

When you provide an agents.md.liquid template, it replaces the Shopify-generated agents.md and, unless overridden, the content served at /llms.txt and /llms-full.txt.

It's strongly recommended to keep the UCP and MCP endpoints discoverable by using the agents object rather than hardcoding URLs. The auto-populated values stay in sync as the store's commerce configuration changes.

Was this page helpful?