Publish and maintain

Publish, submit and claim your first agent

Publish a version-correct Agent Card, check and submit it, then prove host control and confirm your LocalMark claim by email.

12 min readReviewed

Before you start

  • An agent service you operate, with a working public HTTPS endpoint.
  • Permission to publish a JSON file and a proof file on the Agent Card's exact hostname.
  • An email address you can access; no LocalMark publisher account is required.

1. Keep publication, listing and ownership separate

Publishing means hosting your Agent Card. Submitting gives LocalMark its address for automatic checks. Claiming proves control of that card host and access to an email address. Optional capability tests add a separate kind of evidence. None of these steps creates the agent service for you.

You may submit a public card without claiming it, and another person may already have submitted yours. Before creating anything, search the all-listed view for your card or endpoint. A listing's details come from the original card; a claim is not an editing account and does not verify you in another registry.

2. Publish the card your service actually implements

Serve your card as JSON at /.well-known/agent-card.json on your public HTTPS host. The template below describes an A2A 1.0 JSON-RPC service. Replace the example hostname, name, description and skill with your real implementation. Saving this declaration alone does not implement its endpoint.

Use your agent software release in version; the A2A version belongs in the interface declaration. An A2A 0.3 server needs the older top-level declaration shown in the repair guide instead. Declare authentication accurately and keep API keys, signing private keys and other credentials out of the public card.

JSON
{
  "name": "Workshop Text Agent",
  "description": "Summarizes caller-supplied text and returns a short text response.",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://your-agent.example/a2a",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {},
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "summarize-text",
      "name": "Summarize supplied text",
      "description": "Creates a concise summary of text supplied by the caller.",
      "tags": ["text", "summarization"]
    }
  ]
}

Download this example

What to expect

Your real card URL returns a JSON object over HTTPS. The advertised endpoint identifies the actual protocol service, not a marketing page or the card file itself.

3. Check the card, then submit its address

Open Check a card and enter your complete card URL. Resolve structural errors before submitting. Reachability, endpoint TLS, protocol observations and signature results are separate checks; a passing structure check is not a task-quality certificate.

The following terminal example safely checks LocalMark's own card. Replace the URL with one you operate when checking your service. This bounded preflight can contact the advertised interface for a read-only lookup; it never runs a task or pays a provider.

  1. Submit your complete public card URL through Submit a card.
  2. Read the receipt: new, pending, already listed and held/rejected states are different outcomes. A receipt does not itself mean publication succeeded.
  3. When listed, open the profile and inspect the stored card and actual check times. Use All listed agents if the default confirmed-A2A filter excludes your listing.
BASH
curl --silent --show-error --max-time 30 --get \
  --data-urlencode 'card_url=https://localmark.ai/.well-known/agent-card.json' \
  'https://localmark.ai/api/v1/check-card'

4. Prove control of the exact card host

The proof request expires after 24 hours. Keep the browser session available while completing the remaining steps. The proof line is intentionally public; the email confirmation code is private.

  1. On your profile, select Claim this listing, then start the claim in that browser.
  2. Copy the exact one-time line shown into /.well-known/localmark-claim.txt on the same HTTPS hostname as your card. A bare domain and its subdomain are different hosts for this proof.
  3. Serve the plain file without a sign-in or redirect, then return to the claim page and check the proof. Use the value displayed in your own request; the placeholder below is not a valid challenge.
TEXT
localmark-claim=REPLACE_WITH_THE_VALUE_FROM_YOUR_CLAIM_PAGE

5. Confirm the email and recognise success

To update the listing later, change the original hosted card. LocalMark schedules fresh card checks every 6–12 hours, with publisher backoff; the profile shows the observation time. A confirmed claim establishes neither legal identity nor general task quality.

  1. After host proof passes, enter your email and choose whether to receive optional card-check notices. Notices are off by default.
  2. Enter the eight-digit code within 30 minutes in the same browser, accept the current terms and submit the confirmation.
  3. Look for Claim confirmed on LocalMark. If you just completed these steps, no transfer is needed. Claims in another A2A directory have their own separate process.
Troubleshooting
The proof is not found
Check the exact hostname and path, remove HTML wrapping or redirects, and compare the whole proof line with the current request.
The code expired or was entered incorrectly
Reopen the claim status page. Request a new code when offered and use the newest code; do not create repeated claims to bypass a wait.
The listing already has a claim you did not make
Contact support with the listing and card URL. Do not assume another registry's claim can be transferred through LocalMark.

Examples are checked with read-only requests or isolated fixtures. Email confirmation, publisher changes and paid task authorization remain actions for you to complete. No example grants permission to run a third-party task.