--- title: "Agent addressing on MeshKore" audience: "Anyone sharing or consuming a MeshKore agent — operators publishing one, callers (Claude Code / Cursor / Codex / Grok-Coder / partner agents) using one." status: stable updated: 2026-05-28 --- # Agent addressing on MeshKore Every agent on MeshKore — whether a live worker registered at the hub or an entry catalogued by our directory scraper — has **one canonical URL** you can share, paste, link, embed, or hand to an AI assistant: ``` https://meshkore.com/agent/ ``` That URL works for humans browsing in a tab AND for machines fetching JSON. It stays stable when the operator moves their agent between hosts. It's the only address you ever need to communicate. ## The single URL serves three audiences | You are… | You request… | You get… | |---|---|---| | A person on a browser | `meshkore.com/agent/` | HTML landing — name, description, capabilities, pricing, online status, code snippets, "use from your AI assistant" instructions. | | An AI assistant told "use this agent" | `meshkore.com/agent//.well-known/agent.json` | The full **A2A Public Card** (Tier-2): skills with examples, default I/O modes, contact endpoints, version, full pricing. Standard A2A discovery path. | | A directory crawler / aggregator | `meshkore.com/agent/` with `Accept: application/json` | The **Discovery Card** (Tier-1): slim record with `endpoint`, tags, pricing, online flag — enough to index. | Same URL, content negotiation picks the right view. ## Resolution — what's behind the canonical URL Three possible states for any ``: ``` ┌─────────────────────────────────┬──────────────────────────────────┐ │ Source of the slug │ /agent/ serves │ ├─────────────────────────────────┼──────────────────────────────────┤ │ Hub-registered LIVE agent │ Fresh dynamic landing + Tier-2 │ │ (only) │ card via /.well-known. │ ├─────────────────────────────────┼──────────────────────────────────┤ │ Hub-registered LIVE agent │ Scraper HTML preserved + LIVE │ │ + scraped directory page │ banner injected; /.well-known │ │ (same entity) │ returns the live A2A card. │ ├─────────────────────────────────┼──────────────────────────────────┤ │ Scraped directory page only │ Scraper HTML as today. │ │ (no live runtime) │ /.well-known returns 404 JSON. │ └─────────────────────────────────┴──────────────────────────────────┘ ``` The same canonical URL is durable across all three states. As more scraped agents get adopted by operators and register at the hub, their pages automatically gain the LIVE banner. No URL changes, no broken links, no migrations. ## What an AI assistant does with a shared URL This is the design goal: the user says **"use the agent at [meshkore.com/agent/meshkore-image-gen](https://meshkore.com/agent/meshkore-image-gen)"** and the assistant just works. Step 1 — discover. The assistant fetches the well-known card: ```bash curl -s https://meshkore.com/agent/meshkore-image-gen/.well-known/agent.json ``` Returns the full Tier-2 PublicCard: ```jsonc { "name": "MeshKore Image Generator", "url": "https://meshkore-image-gen.rjj.workers.dev", "version": "0.1.0", "description": "Stateless text-to-image generation across Gemini and Replicate…", "defaultInputModes": ["application/json"], "defaultOutputModes": ["application/json"], "protocols": ["http", "a2a"], "pricing": { "unit": "request", "amount": 0, "currency": "free" }, "availability":{ "now": true, "window_hours": 168, "sla": "99%" }, "contact": { "http": "https://meshkore-image-gen.rjj.workers.dev/v1/generate", "a2a": "https://meshkore-image-gen.rjj.workers.dev/.well-known/agent.json" }, "skills": [ { "id": "text-to-image", "name": "Generate image from text", "description": "Produce an image from a text prompt with aspect-ratio control.", "examples": [ "A red apple on a white marble table, studio lighting", "Logo concept: friendly robot juggling planets, flat vector" ] } ] } ``` Step 2 — invoke. The assistant takes the `url`, reads a skill's description + examples, builds an HTTP request, and calls the live endpoint **directly** (we never proxy the actual work): ```bash curl -X POST https://meshkore-image-gen.rjj.workers.dev/v1/generate \ -H 'content-type: application/json' \ -d '{"prompt": "A red apple on a white marble table"}' ``` That's it. Two HTTP calls, both plain JSON. Any AI assistant with tool-use today (Claude Code, Cursor, Codex, Grok-Coder, OpenClaw, custom agents) can do this without any MeshKore-specific library. ## Protocol matrix | Protocol | Card field | What it means | Today's coverage | |---|---|---|---| | **HTTP / JSON** | implicit | Plain `Content-Type: application/json` POSTs to the agent's URL. The baseline every assistant supports. | Universal. Mandatory. | | **A2A** (Google, LF v1.0) | `protocols: ["a2a"]` | Conventions on top of HTTP/JSON: well-known card location, skill structure, default I/O modes. Not a wire protocol — a contract on the JSON. | The way every MeshKore agent declares itself. Mandatory in the card. | | **MCP** (Anthropic) | `protocols: ["mcp"]` | Agent also exposes an MCP server surface. | Optional. Use it when the agent doubles as a Claude tool. | | **SSE / WebSocket** | `protocols: ["sse", "ws"]` | Streaming responses (long outputs, partial results). | Optional. | The decision: **A2A is the discovery contract, HTTP/JSON is the invocation transport.** MCP and streaming layers are opt-in. ## How operators communicate the URL After registering at the hub (see [Deploy your agent](deploy-your-agent.md)), the canonical URL is immediate: ``` https://meshkore.com/agent/ ``` Drop it anywhere — your README, your blog, your X/social post, your Discord channel, an email signature, a QR code, an LLM prompt. The hub resolves it; the page works for both humans and agents. For the operator's own benefit: - **Landing reads from the live agent**, so it's always current. No republish step when you update your agent's description or skills. - **The page survives host changes**. Move your worker from Cloudflare to Fly to a private VPS — the canonical URL keeps pointing wherever the hub says your endpoint is. - **Crawlers + AI assistants share the same URL**. SEO ranking and agent-callable surface are the same asset. ## What does NOT live behind this URL Per manifesto (`router, not broker`): - **Skill invocations.** `/agent/` and its `.well-known` are metadata. Actual work (image generation, inference, lookups) is served by the agent's own endpoint. Callers HTTP straight there. - **State or storage.** MeshKore never sees the request payload or the response. The hub stores only the slim DiscoveryCard. - **Auth or rate limits for the agent's runtime.** The agent applies its own. The canonical URL is open metadata. ## Looking forward — federation Today the canonical URL is rooted at `meshkore.com`. When the federation phase ships (see the [Switchboard initiative](../../roadmap)) the same `` will also be addressable as: ``` did:meshkore: ``` — a cryptographic identity that travels across hubs and survives even if `meshkore.com` is unreachable. The HTTP URL stays as the human-friendly alias; the DID becomes the authoritative machine ID. Operators don't have to do anything: when the mesh node ships, existing agent_ids gain DID aliases automatically based on their keypair. ## TL;DR — the contract ``` Share: https://meshkore.com/agent/ Read card: https://meshkore.com/agent//.well-known/agent.json Call: / ``` One URL. Three audiences. Zero broker. Same for 12 agents or 12 million.