What the agent does
The agent reads where the page metadata already comes from, because structured data that disagrees with the visible page is worse than none. In a blog shaped like gatsbyjs/gatsby-starter-blog, package.json pins gatsby ^5.14.6, react ^18.1.0, gatsby-plugin-feed, gatsby-plugin-manifest and gatsby-transformer-remark, with npm as the package manager from package-lock.json and no test script. gatsby-config.js holds siteMetadata with title, author.name, author.summary, description, siteUrl and social.twitter. src/components/seo.js is a Seo component that reads that metadata with useStaticQuery and renders <title>, description, Open Graph and Twitter tags, and is used from each page's exported Head. src/templates/blog-post.js already marks the article with itemScope and itemType="http://schema.org/Article" microdata and queries title, date, description and excerpt for each post, and gatsby-node.js creates one page per Markdown file with a slug field.
The agent adds JSON-LD rather than extending the microdata, because the Gatsby Head API renders a <script type="application/ld+json"> cleanly and search engines read it without a DOM parse. seo.js gains an optional schema prop that, when present, renders the script with JSON.stringify. blog-post.js's Head builds a BlogPosting object from the page query: headline from title, datePublished from a new raw date field in the query beside the formatted one, description, author as a Person with author.name from siteMetadata, url and mainEntityOfPage from siteUrl plus the slug already in fields, and publisher from the site title. src/pages/index.js's Head gets a WebSite object with name, url and description.
Because gatsby-node.js declares Frontmatter.date as Date @dateformat in createSchemaCustomization, the raw ISO date is one more field in the template query, rawDate: date, so the formatted string the page shows stays as it is. The siteUrl in siteMetadata ends with a slash and slug starts with one, so the agent joins them without a double slash, the same join gatsby-plugin-feed does for the RSS url.
The repository has no tests, so the proof is the build. The agent runs npm ci and npm run build, then reads public/hello-world/index.html and public/index.html to show the script tags are present with the right @type, headline and datePublished, and runs npx prettier --check on the changed files since the format script uses Prettier. It pastes the JSON-LD from the built HTML in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add structured data to this Gatsby blog and open a pull request. Read package.json, gatsby-config.js, gatsby-node.js, src/components/seo.js, src/templates/blog-post.js, src/pages/index.js and content/blog/hello-world/index.md first. Add an optional schema prop to the Seo component that renders a script tag of type application/ld+json with JSON.stringify of the object. In blog-post.js, add a raw ISO date field to the page query beside the formatted one and build a BlogPosting object in Head with headline, datePublished, description, author as a Person from siteMetadata.author.name, url and mainEntityOfPage from siteUrl joined with fields.slug without a double slash, and publisher from the site title. In src/pages/index.js build a WebSite object with name, url and description. Keep the existing microdata attributes. Run npm ci and npm run build, show the script tags from public/index.html and public/hello-world/index.html in the pull request, and run npx prettier --check on the changed files. Do not change gatsby-config.js values, the feed plugin or the post content.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes src/components/seo.js, src/templates/blog-post.js and src/pages/index.js, and nothing else. The description shows the BlogPosting script from public/hello-world/index.html and the WebSite script from public/index.html as built in the sandbox, and the output of gatsby build and prettier --check.
The starter has no workflow, so the build output in the pull request is the check. On a blog deployed from a gatsby build step, that step runs on the pull request's branch and fails if a query field is misspelled.
A reviewer checks that datePublished is the ISO date and not the display string, that url has no double slash, that the author name comes from siteMetadata rather than a literal, and that the microdata on the article element is still there. Then they paste one built page into a structured data validator before merging.
Run it on every blog without JSON-LD
A team that runs several Gatsby sites sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own gatsby-config.js and templates, so a site whose posts carry an author in frontmatter uses that instead of the site author, and each run opens its own pull request.
Give the API key a webhook_url and Rush POSTs run.completed when each turn ends, with the session_url to read the pull request and the built JSON-LD from.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Structured data is easy to add and easy to get subtly wrong: a formatted date where an ISO one is expected, a URL with a double slash, a field the page query never asked for. In a Rush sandbox the agent runs gatsby build and reads the HTML it produced, so the pull request shows the JSON-LD as a crawler will see it, and every command and its output stays in the run's record.
The starter has no tests, so on a laptop the check is a manual build and a look at the output. The agent does that for every page type it touched, and the same request works unchanged on the next Gatsby site a team runs.
Frequently asked questions
Why JSON-LD when the template already has microdata?
The microdata marks the article element with schema.org/Article and headline, but carries no date, author or URL. JSON-LD in Head can state all of them from the page query without changing the markup, and the existing attributes stay for anything that reads them.
Where does the author come from?
From siteMetadata.author.name in gatsby-config.js, the same value src/components/bio.js shows under each post. A blog whose frontmatter carries a per-post author would read that field instead, which the agent does when it finds one.
Does it need a plugin?
No. Gatsby 5's Head export renders any element into the document head, so one <script type="application/ld+json"> in the Seo component does the job without react-helmet or a schema plugin.
How is it checked without tests?
The agent runs npm run build and reads the script tag out of the generated public/ HTML for a post page and the index, pasting both into the pull request. A reviewer can drop that HTML into a structured data validator.