Let an AI assistant leave an inquiry for a small business, starting with one JSON file

#webdev #ai #wordpress #opensource

An AI assistant should not stop at reading about a business: it should be able to leave an inquiry that a human owner gets as an e-mail.

When people look for a roofer, a tax advisor or an electrician, more of them now ask an AI assistant instead of a search engine. The assistant then reads websites that were built for humans: hero images, menus, cookie banners, a services page three clicks deep. It has to guess what the business actually does, and even when it gets it right, the conversation ends there.

The first step is telling it clearly. The A2A protocol (Agent2Agent, an open standard for agents talking to services) defines an agent card: a small JSON file at a fixed address, /.well-known/agent-card.json. It says who you are, what you offer and where an agent can reach you. Think of it as a business card for machines.

We maintain a small open source kit that writes and checks these cards: agent-card-starter. Python standard library only, Python 3.9 and newer, MIT licensed, no account, works offline.

Write your first card

pip install agent-card-starter

agent-card init \
  --name "Muster Roofing Ltd" \
  --description "Roofer in Musterstadt, repairs and new roofs." \
  --website https://www.example.com \
  --skill "Flat roof sealing"

agent-card validate .well-known/agent-card.json --strict

init validates before it writes and never overwrites an existing card without --force. Pass --skill once per service. validate runs the same checks offline, so you can put it in CI.

What a card looks like

This is the example from the repo, a fictional German roofer, trimmed:

{
  "name": "Beispiel Dachdecker GmbH",
  "description": "Fiktives Beispiel. Dachdeckerbetrieb für Neubau, Sanierung und Reparatur ...",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://tuer.beispiel-dachdecker.example/mcp",
      "protocolBinding": "MCP",
      "protocolVersion": "2025-06-18"
    }
  ],
  "provider": {
    "organization": "Beispiel Dachdecker GmbH",
    "url": "https://www.beispiel-dachdecker.example"
  },
  "skills": [
    {
      "id": "flachdach",
      "name": "Flachdach abdichten",
      "description": "Abdichtung und Reparatur von Flachdächern ...",
      "tags": ["flachdach", "abdichtung", "reparatur"]
    }
  ]
}

The field names follow A2A v1.0. One skill per real service, with a stable id. Upload the file to https://<your-domain>/.well-known/agent-card.json and you are readable.

What to keep out of the card

The card is public. We learned to keep three things out of it:

Prices. They change, and an assistant quoting last year's price helps nobody.
Phone numbers and personal e-mail addresses. Scrapers read cards too.
Promises. "Available tomorrow" is a promise a human should make, not a JSON file.

The validator warns about the first two. The third one is on you.

Going one step further: an MCP endpoint

MCP (Model Context Protocol) is the other open standard in this space. It lets an assistant call small tools on your side. The kit ships a minimal MCP example server over stdio with two tools: leistungen (list services) and anfrage_anlegen (leave an inquiry). Try it from a clone:

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | python3 server/mcp_server.py

anfrage_anlegen is the part that matters most to a business owner: the assistant leaves an inquiry, a human answers. In the kit it is a stub on purpose, because a public inquiry endpoint attracts spam on day one. Before you expose one, you need HTTP transport, rate limiting, a honeypot field and a privacy notice. The README lists what is missing instead of pretending it is done.

There is also an MCP server card example (examples/mcp-server-card.json). It follows the Server Card proposal (SEP-2127), which may still change, so check the current schema before you publish.

What this does not do

Honest part: nothing here guarantees that an assistant will mention or recommend you. The standards are young and nobody can tell you today how many assistants read agent cards. What the card does is remove guessing. If an assistant looks, it finds clean, current facts at a known address.

On our own site we see the crawlers of the large AI assistants fetch these files every day. That is a signal, not a ranking.

WordPress

Most small businesses do not run Python. For them we built Open Door for AI Assistants (ODAA), a free WordPress plugin that creates the same card, an llms.txt and a read only MCP endpoint from three questions: company name, services, contact e-mail. An optional hosted inquiry service passes inquiries from assistants on to the owner by e-mail, with spam protection and a confirmed address. The plugin is in review at the WordPress.org plugin directory and will be linked here when it is live.

Try it, break it, tell us

Repo: https://github.com/flowboxx/agent-card-starter
Install: pip install agent-card-starter
If you publish a card with it, post it in the repo Discussions under "Show and tell". If the validator rejects something valid, open an issue.

The kit is maintained by flowboxx, an agency that builds AI doors for businesses.

DEV Community