URLによるエージェントオンボーディング：ドキュメントを読まずにAgentShareを統合する

Autonomous agents don’t “browse” products—they bootstrap from machine-readable entrypoints. This post is a URL-first onboarding guide for AgentShare ( https://agentshare.dev ): a structured price & offer layer for AI agents, with optional MCP support. Everything below is real, live, copy/pasteable . I’m not asking you to trust a blog post—start with the URLs and verify. What AgentShare is (honest scope) AgentShare provides: Structured product prices and offers from connected sources A JSON REST API plus optional MCP Streamable HTTP A curated MCP registry (editor-reviewed listings that pair well with price/offer workflows) Current focus (high-quality, daily updates) includes: AI local hardware (Raspberry Pi, Jetson, SBCs) mini PCs, components, accessories robotics (kits, arms, servos) drones & robot/RC power (LiPo, LiFePO4, NiMH) The canonical coverage spec is public: GET https://agentshare.dev/coverage The canonical entrypoint: agent.json Start here: GET https://agentshare.dev/agent.json Mirror: GET https://agentshare.dev/.well-known/agentshare.json This file is designed to be the single source of truth for onboarding: discovery URLs, auth method, MCP endpoint, tools, and scope. Real payload (canonical fields) Below is a verbatim, current-shape example based on the live agent.json on agentshare.dev : { "schema_version" : "1.0" , "name" : "AgentShare" , "type" : "commerce_price_api" , "description" : "Structured product prices and offers from marketplaces (AI hardware, robotics, drones & robot/RC power) — JSON API plus optional MCP Streamable HTTP." , "base_url" : "https://agentshare.dev" , "human_documentation_url" : "https://agentshare.dev/docs" , "discovery_urls" : { "this_file" : "https://agentshare.dev/agent.json" , "well_known" : "https://agentshare.dev/.well-known/agentshare.json" , "well_known_discovery_index" : "https://agentshare.dev/.well-known/discovery.json" , "mcp_json" : "https://agentshare.dev/mcp.json" , "meta" : "https://agentshare.dev/api/v1/meta" , "agent_capabilities" : "https://agentshare.dev/api/v1/agent-capabilities" , "health" : "https://agentshare.dev/api/v1/health" , "openapi" : "https://agentshare.dev/openapi.json" , "llm_txt" : "https://agentshare.dev/llm.txt" , "mcp_stdio_repo_llms_txt" : "https://raw.githubusercontent.com/anhmtk/agentshare-mcp/main/llms.txt" , "legal_index" : "https://agentshare.dev/legal/index.json" , "coverage" : "https://agentshare.dev/coverage" }, "authentication" : { "type" : "api_key" , "header" : "X-API-Key" , "note" : "Required for /api/v1/search, /api/v1/offers/*, /api/v1/products/*, MCP /mcp. Not required for meta, health, agent.json, /mcp.json." }, "signup" : { "register" : "POST /api/v1/auth/register" , "register_url" : "https://agentshare.dev/api/v1/auth/register" , "body_json" : { "email" : "string" , "password" : "string (min 8 chars)" }, "returns" : "api_key once (same format as agshp_...)" }, "api_version" : "1.0.0" , "coverage" : { "spec_url" : "https://agentshare.dev/coverage" , "focus_summary" : "Focus (high quality, daily updates): AI local hardware (Raspberry Pi, Jetson, SBCs), mini PCs, components, accessories, robotics (kits, arms, servos), drones & robot/RC power (LiPo, LiFePO4, NiMH packs). Expanding/beta: phones, tablets, general consumer electronics, home appliances — canonical list: GET /coverage." }, "mcp" : { "streamable_http_url" : "https://agentshare.dev/mcp" , "same_key_as_rest" : true }, "mcp_listings" : { "positioning" : "Curated, editor-reviewed MCP registry for data, operations, and commerce-adjacent tools—built to pair with AgentShare price and offer APIs, not as a generic open directory." , "landing" : "https://agentshare.dev/registry" , "entries_json" : "https://agentshare.dev/api/v1/registry/entries" , "summary_json" : "https://agentshare.dev/api/v1/public/mcp-registry/summary" }, "tools" : [ { "name" : "search_products" , "description" : "Search products across sources with prices and freshness metadata" , "method" : "GET" , "path" : "/api/v1/search" , "query_params" : [ "q" , "limit" ], "requires_auth" : true }, { "name" : "best_offer" , "description" : "Lowest in-stock offer for a query" , "method" : "GET" , "path" : "/api/v1/offers/best" , "query_params" : [ "q" ], "requires_auth" : true }, { "name" : "best_offer_under_budget" , "description" : "Best offer under max price" , "method" : "GET" , "path" : "/api/v1/offers/best-under-budget" , "query_params" : [ "q" , "max_price" ], "requires_auth" : true }, { "name" : "product_detail" , "description" : "Product by id with prices by source" , "method" : "GET" , "path" : "/api/v1/products/{id}" , "requires_auth" : true }, { "name" : "submit_product_url" , "description" : "Alpha: suggest a marketplace product page URL for catalog coverage (community). JSON body: url (required), notes (optional). Rate-limited; optional X-API-Key raises hourly cap." , "method" : "POST" , "path" : "/api/v1/products/submit" , "body_json" : { "url" : "string (https product page)" , "notes" : "string (optional)" }, "requires_auth" : false }, { "name" : "service_meta" , "description" : "Capabilities and endpoint list (no auth)" , "method" : "GET" , "path" : "/api/v1/meta" , "requires_auth" : false } ], "data_sources" : [ "aliexpress" , "accesstrade" ] } If your agent can read this JSON, it can onboard without any human docs. The “bootstrap checklist” (5 URLs to start) If you’re writing a new agent integration, here’s the minimal “boot sequence”: 1) Identify the service & URLs GET /agent.json https://agentshare.dev/agent.json 2) Confirm liveness GET /api/v1/health https://agentshare.dev/api/v1/health 3) Confirm capabilities (no auth) GET /api/v1/meta https://agentshare.dev/api/v1/meta 4) Confirm machine-facing capability spec GET /api/v1/agent-capabilities https://agentshare.dev/api/v1/agent-capabilities 5) Confirm coverage boundaries GET /coverage https://agentshare.dev/coverage Auth model (simple on purpose) AgentShare currently uses API keys : Header: X-API-Key: <your_key> (Some clients also support Authorization: Bearer <your_key> ) Per agent.json , auth is required for: /api/v1/search /api/v1/offers/* /api/v1/products/* MCP /mcp Not required for: /api/v1/meta /api/v1/health /agent.json /mcp.json Signup (get a key) The onboarding endpoint is: POST https://agentshare.dev/api/v1/auth/register Example: curl -s https://agentshare.dev/api/v1/auth/register \ -H "Content-Type: application/json" \ --data-binary "{ \" email \" : \" [email protected] \" , \" password \" : \" change-me-please \" }" Security note: store the api_key safely. The system is designed so keys should not be casually re-exposed. Price tools: the practical agent workflow The canonical tools list is in agent.json under tools[] . A typical agent loop: 1) Search curl -s "https://agentshare.dev/api/v1/search?q=raspberry%20pi%205&limit=5" \ -H "X-API-Key: YOUR_KEY" 2) Best offer curl -s "https://agentshare.dev/api/v1/offers/best?q=raspberry%20pi%205" \ -H "X-API-Key: YOUR_KEY" 3) Best offer under budget curl -s "https://agentshare.dev/api/v1/offers/best-under-budget?q=raspberry%20pi%205&max_price=120" \ -H "X-API-Key: YOUR_KEY" 4) Product detail by id curl -s "https://agentshare.dev/api/v1/products/123" \ -H "X-API-Key: YOUR_KEY" (Use IDs returned by search results.) MCP onboarding (Streamable HTTP) If your environment supports MCP remote servers: https://agentshare.dev/mcp This is a Streamable HTTP MCP endpoint—not a browser page. Many clients require Accept: text/event-stream or equivalent. Per agent.json : same API key as REST same base service You can also discover MCP metadata via: GET https://agentshare.dev/mcp.json OpenAPI (for tool generation) Per discovery URLs: GET https://agentshare.dev/openapi.json Tooling note: some deployments disable interactive docs UI while keeping openapi.json available for machines. Treat OpenAPI as a generation artifact, not the primary discovery system— agent.json is. The curated MCP registry (contributions welcome) AgentShare also maintains a curated MCP registry— editor-reviewed to prevent spam. Landing page: https://agentshare.dev/registry Verified entries (JSON): https://agentshare.dev/api/v1/registry/entries Summary (JSON): https://agentshare.dev/api/v1/public/mcp-registry/summary Why a curated registry? Because agent infra collapses quickly if the directory turns into “everything plus spam”. I’d rather ship something smaller, trustworthy, and composable. If you get “no data”: here’s the right action Coverage is transparent, but real demand is messy. If your agent hits a query that returns nothing, you can help by submitting a specific product URL: POST https://agentshare.dev/api/v1/products/submit (no auth required) Example: curl -s https://agentshare.dev/api/v1/products/submit \ -H "Content-Type: application/json" \ --data-binary "{ \" url \" : \" https://example.com/product-page \" , \" notes \" : \" What the agent tried to find and why \" }" This helps turn real agent demand into better coverage—without guessing which catalogs to crawl. Founder note (why I built it this way) I’m a founder from Vietnam building an agent-native system with limited resources. My bias is: Ship real endpoints Make everything verifiable by URL Be explicit about coverage Let the community pull the roadmap via real usage If you’re building agents and you want a cleaner onboarding story, tell me what’s missing. If you find contradictions between this post and live endpoints, that’s a bug—please report it. TL;DR (copy/paste URL list) https://agentshare.dev/agent.json https://agentshare.dev/.well-known/discovery.json https://agentshare.dev/llm.txt https://agentshare.dev/api/v1/health https://agentshare.dev/api/v1/meta https://agentshare.dev/api/v1/agent-capabilities https://agentshare.dev/coverage https://agentshare.dev/openapi.json https://agentshare.dev/mcp https://agentshare.dev/mcp.json https://agentshare.dev/api/v1/auth/register https://agentshare.dev/api/v1/products/submit If you want to collaborate on the discover