From the field #08 - AX: the agent experience your site is missing

Part 3: twenty green probes, five lessons, and the pack

Part 1 made the case that your site has a UX and no AX. Part 2 was the build - custom Agent Cards and MCP discovery manifests across six portals, in seventy minutes.

This part is the half everybody skips. A manifest that returns a 200 tells you the file shipped. It tells you nothing about whether an agent can actually read it, parse it, and act on it. So I check, the same way every time, and I do not call it done until the probes are green.

Twenty probes, green

The agent layer is verifiable from the command line, which is the whole reason it is worth trusting. There is no vibe here. Either the manifest is there and valid, or it is not.

# A2A Agent Card present and valid JSON?
curl -s https://portfolio.sdet.it/.well-known/agent.json | jq .

# MCP discovery manifest present and valid?
curl -s https://portfolio.sdet.it/.well-known/mcp.json | jq .

# sitemap actually at the path agents check?
curl -s https://portfolio.sdet.it/sitemap-index.xml | xmllint --format - | head

# does the MCP endpoint answer with real tool descriptions?
curl -s 'https://portfolio.sdet.it/mcp?tool=list_articles&language=en' | jq .

The first three lines are the probes I count: the Agent Card, the MCP manifest, the sitemap, run against six portals for eighteen. The fourth is a deeper spot-check - does the MCP endpoint actually answer with real tool descriptions - run where it matters. Then two more on the private knowledge base, where the bearer-gated endpoint has to refuse an unauthenticated call correctly and the extra llms-full.txt has to be there. Twenty counted probes. All twenty green after deploy.

Green here does not mean “the build passed.” It means every portal returns a valid Agent Card, every MCP manifest points at a live endpoint, the public ones answer and the gated one refuses correctly. That is the difference between shipping a file and shipping a thing an agent can use.

One probe taught me to write better probes. An earlier audit had flagged a missing sitemap across the board, and it was wrong - it was checking /sitemap.xml when the framework emits /sitemap-index.xml. The sitemaps had been there all along. The lesson was not about sitemaps. It was that a probe checking the wrong path reports a false gap with total confidence, and a false gap sends you fixing something that was never broken. The probe is code too. It gets the same scrutiny as the thing it checks.

And one deploy fought back. A cross-repo private GitHub Action failed to resolve on one self-hosted runner, so that portal went out by manual SSH while the rest deployed clean. Because the portals are independent, the sprint did not stall. The root cause is still an open follow-up, and I am naming it because that is the deal with From the Field: the one that breaks gets reported too.

Five lessons

The layer is simple. Getting it right across a fleet is where the time goes. These five cost me the hours.

1. Custom per portal beats a generic template, every time. The skills in an Agent Card must match the real /mcp tool surface exactly. A portfolio agent and a docs agent are different agents with different skills, and a copy-pasted card that claims skills a portal does not have produces an agent that calls into nothing. The proof that mine are custom is that they are visibly different - seven skills on the portfolio, five on the docs site, named for what each one actually does.

2. A private API still belongs in the discovery layer - gated, not hidden. The instinct for a private endpoint is to leave it out. Wrong. The right answer is an Agent Card that declares the asset exists and declares it is closed: bearer auth, skills described vaguely, the real tool surface not enumerated. An agent learns the asset is real and learns it needs credentials. Present and honest about being shut.

3. A dynamic endpoint, not a static file. Anything bilingual built from one source into two deploys will ship the wrong URL from a static public/.well-known/agent.json. Read Astro.site at build time and the manifest is correct on every deploy with no duplication. This is the same pattern the llms.txt endpoint already used, which is the tell that it was the right call.

4. /.well-known/ is the first place an agent looks, so put the manifests there. It is not decoration. RFC 8615 makes /.well-known/ the conventional location for exactly this kind of discovery metadata, and the tooling checks it first before falling back to anything else. Serve your Agent Card and MCP manifest from the well-known path or expect to be missed by the agents that look in the standard place.

5. The spec moves under you, so build with aliases. I shipped these cards in May. By the time I packaged the method in June, A2A had reached v1.0, moved the official card path from /.well-known/agent.json to /.well-known/agent-card.json, switched auth from authentication.schemes to securitySchemes, and added signed cards as a trust model. Roughly five weeks, one renamed path and a reshaped auth block. The lesson is not “chase every change” - it is build so a change cannot break you. Serve the new path and keep the old one as an alias. My portals still serve the May shape; the pack below is built to the v1.0 shape with the alias in place. On a standard this young, backward-compat is not politeness, it is how you avoid going invisible the week the path moves.

Where AX goes, and what I will not pretend is shipped

Here is the honest line, because being precise about built-versus-roadmap is the whole brand.

What is shipped is read-only discovery. Six portals tell an agent what they are and what they can answer, and the public ones let it read. That is real, it is live, you can curl it.

What is not shipped is the action layer. The next frontier of AX is an agent that does something transactional through your site - books the call, files the inquiry, completes the task - not just reads it. That requires auth, rate limits, write paths, and a human gate in the right place, and none of it is running in my portals today. I am not going to draw it as if it were. It is where this goes, and it is a real design problem, not a feature I am quietly serving.

Take the pack

You do not have to rebuild the discovery layer from this article. I packaged exactly what is in this episode - the A2A Agent Card endpoint, the backward-compat agent.json alias, the MCP discovery manifest, the build-time-origin pattern so one source serves every domain - into a clone-and-run pack. MIT, built to the current A2A v1.0 spec, not the May shape my portals still run. Drop it into your site, change the names and the skills, and you have the same agent-discovery layer.

github.com/darco81/agent-ready-pack

If you also want the other half of being legible to AI - not agent discovery but getting cited by ChatGPT, Perplexity, and Google’s AI Overview - that is a separate MIT pack, llms.txt and JSON-LD and OG and the AI-crawler robots policy: github.com/darco81/ai-seo-pack.

No pitch attached to either. You build it yourself, on your own stack, without me in the room. If you do and you want to compare notes, or you hit the action-layer question and want to think it through with someone who has already mapped it, my DMs are open.

Series wrap

Three parts, one idea.

Your site has a UX and almost certainly no AX. The agentic web is standardizing on MCP for agent-to-tool and A2A for agent-to-agent, and in a year a site gets judged not only by how a person experiences it but by whether an agent can discover what it does and connect. The fix is an agent-discovery layer: a custom Agent Card and an MCP manifest per portal, honest about capabilities, gated where the API is private, served from the well-known path an agent checks first.

Everything I claimed is built is live on six portals and returns a green probe. The seventy-minute number is a real fleet sprint, held exactly as it happened. The path moved under me between shipping it and writing this, and I told you that too, because a standard this young rewards honesty over polish. A site an agent can trust is one whose manifest tells it exactly what it can and cannot do, and the same standard applies to the person describing how it was built.

From the Field is what I actually build, what breaks, and what I learn. Real projects, real numbers, real bugs. No tutorials.