翻訳待ち：Show HN: AgentBadge – Agent Readiness Scoring for APIs (SEO for AI Agents)

AI サービスが一時的に利用できないため、復旧後に翻訳を補完します。

Why a good API can be invisible to AI agents Imagine this scenario. You've built an excellent API. It's fast, stable, well documented, with clean authentication and a sane architecture. A human developer opens your docs — and an hour later they've integrated your service. Now an AI agent tries to use the same API. It searches for the service. It doesn't find it. It tries to understand the documentation. It can't locate the OpenAPI spec. It finds an endpoint, but can't figure out which authentication it needs. It gets an error — and the error explains nothing about what went wrong. Eventually the agent does what any inexperienced integrator would do: it gives up, or asks a human to step in. The problem may not be your API. The problem is that your API isn't prepared for machine consumption. That problem is what we call Agent Readiness. Agent Readiness is not "how smart your AI is" Agent Readiness is the degree to which an API or service can be: found by an AI agent; understood without human help; called correctly; authenticated against properly; recovered when errors occur. Put simply: Agent Readiness is the ability of your API to be discovered, understood, and used by an AI agent — without a human intervening. Here's a useful analogy with the internet we already know. SEO made websites visible to search engines. Agent Readiness makes APIs visible and understandable to AI agents. From SEO to Agent Readiness For decades, companies optimized websites for search engines. We got: robots.txt; sitemaps; structured data; meta tags; canonical URLs; performance optimization; search ranking. All of these mechanisms solved one big problem: How do you make a resource understandable to a machine that must find and process it? AI agents create a similar problem — but at a different level. A search engine only needs to understand: "This page is about payments." An agent needs to understand much more: "This service can create payments. The endpoint is here. An API key is required. The request should look like this. The response has this structure. And if a 402 error comes back — here's the next step." That's no longer just discoverability. That's machine usability. The analogy, side by side Web / SEOAgentic Web Search engine finds a websiteAI agent finds an API robots.txtmachine-readable instructions Sitemapcapability discovery Meta descriptionstructured API description Open Graph / structured dataOpenAPI / agent metadata Search rankingAgent Readiness score Web crawlerAI agent Website visitorAPI-consuming agent But there's one fundamental difference. A search engine needs to understand a page. An agent needs to take an action. And that's why the requirements for APIs are quietly changing. Why documentation written for humans isn't enough Most API documentation was written assuming a human on the other side. A human can: open the docs; read the description; look at an example; infer the context; guess which endpoint is needed; figure out authentication from a screenshot; try a request; interpret an error message. A human has context. An AI agent has to reconstruct that context from machine-readable signals alone. For example, an agent may need to answer: What does this API do? Where are its endpoints? Which endpoint should I call? What parameters are required? How do I authenticate? What does a successful response look like? What happens when the request fails? Can I safely retry? How much does this operation cost? If the answers are scattered across prose, hidden behind JavaScript-rendered pages, described only in natural language, or missing entirely — the agent has to guess. And guessing is a terrible foundation for automated interaction. Agent Readiness has several layers It's tempting to reduce the problem to a single file — "just add an agent-guide.json and you're done." A genuinely agent-ready system passes through several layers. 1. Discovery Can an agent find your API at all? For example: is there a clear public URL; is there a machine-readable description; are discovery files available (llms.txt, agent manifests, API catalogs); is it obvious where the documentation lives. If the API can't be found, the remaining layers don't matter. 2. Understanding The agent found the API. Now it must understand: "What can I actually do here?" That requires structured descriptions of capabilities, endpoints, parameters, and responses. OpenAPI is one of the most important sources of this information. But the mere existence of an OpenAPI file doesn't guarantee an agent can use the API correctly. The spec may be: outdated; incomplete; contradictory; poorly described; out of sync with real API behavior. Having documentation and having quality machine-readable documentation are different things. 3. Authentication Next question: "How do I get access?" For a human, you can write: Create an API key in your dashboard. An agent needs something like: Authentication type: API key Location: Authorization header Header: X-API-Key Required: yes The less an agent has to guess, the higher the chance of a successful interaction. 4. Machine-readable responses The agent must understand responses. For example: { "id": "pay_123", "status": "completed", "amount": 49.00 } is dramatically easier to process automatically than an HTML page saying: Your payment has been successfully processed. The same applies to errors. A good error shouldn't just be readable by a human. It should be operationally useful to an agent: { "error": "insufficient_balance", "message": "Insufficient account balance", "retryable": false } Now the agent can make a decision. The most important distinction: an API can be good — and still agent-hostile This difference matters. An agent-hostile API is not necessarily a bad API. It was simply designed for a different consumer. Imagine a restaurant. For a human: "Ask the waiter about the special menu." For an agent: { "action": "order", "menu": "special", "quantity": 1 } Both interfaces lead to the same result. But the second one is far easier to automate. AI agents are creating a new class of API consumer. And that forces developers to answer a new question: "If 10,000 AI agents wanted to use my API tomorrow, could they do it without a human's help?" How AgentBadge measures Agent Readiness This is where AgentBadge comes in. AgentBadge doesn't try to say: "This API is good." And it definitely doesn't say: "This API is certified." We follow a different principle: Don't certify. Measure. AgentBadge checks observable properties of an API and shows: what was found; what's missing; which rule fired; what evidence was collected; why the score changed. Evidence first Suppose a system shows you: Agent Readiness: 76/100 The number itself is almost useless. Every developer's next question is: Why 76? That's why AgentBadge is built around an evidence-first approach. Instead of: Documentation: 62 you get: AB-004 OpenAPI specification Status: VERIFIED Evidence: GET https://example.com/openapi.json HTTP: 200 Content-Type: application/json Confidence: 1.0 Now the result is verifiable. That's a fundamental difference. AgentBadge doesn't ask you to trust the number. It shows you where the number came from. Deterministic before intelligent Another foundational principle of AgentBadge. We don't want to start with: "Let an LLM look at the API and decide how agent-ready it is." The problem is obvious. Different models will score the same API differently. So the base checks must be deterministic: Does /openapi.json exist? ↓ HTTP 200? ↓ Valid OpenAPI? ↓ Authentication described? ↓ Structured error schema present? This can be verified programmatically. AI can be layered on top of that. But here, AI must be a copilot, not a judge. What AI should actually do AI is excellent at tasks that require interpretation. For example: "We found a description of this endpoint. Help the developer understand what to add to the machine-readable documentation." Or: "We found a capability that looks like a payment operation. Draft a description — but ask the API owner to confirm it." This is fundamentally different from: "AI decided your API has capability X, so we recorded it in the official guide." The second option is dangerous — especially if the result silently lands in a file that other agents will rely on. That's why we separate fixes into two types. Deterministic Fix Can be applied automatically. missing robots.txt missing sitemap missing badge configuration Assisted Fix Requires human confirmation. Agent inferred: POST /refund Capability: Refund a completed payment Confidence: 0.71 Here the system must show: Confirm / Edit / Reject — not silently write a guess into production documentation. One score — but with a transparent structure AgentBadge uses a single score, because humans need a simple answer: "How ready is my API?" But one score must never hide the details. Categories and evidence sit right next to it: Agent Readiness ──────────────────────── 76 / 100 Discovery 18 / 20 Documentation 20 / 25 Authentication 16 / 25 Machine-readable 22 / 30 And the score must be monotonic and explainable. If you fixed a problem: 76 → 84 +8 Guide added If a new problem appeared at the same time: 84 → 72 +8 Guide added -12 New conflict detected A user should never have to ask: "I fixed something — why did it get worse?" The system must explain the delta. Agent Readiness is a process, not a certificate Your API changes. New endpoints appear. Old ones disappear. Authentication changes. OpenAPI changes. Documentation changes. So today's score doesn't guarantee the same score a month from now. That's what fundamentally separates AgentBadge from a certificate. We don't say: "Your API is certified as Agent Ready." We say: "Here's what we measured right now." Which leads to a natural cycle: Measure → Prove → Improve Measure — scan your API. ↓ Prove — inspect the evidence behind every claim. ↓ Improve — fix the problems. ↓ Measure again — verify the result. This isn't a one-time audit. It's an improvement loop. Why this can become a new infrastructure layer Today, APIs are usually optimized for a few consumer types: Human developer ↓ Documentation ↓ SDK ↓ API With AI agents, an additional layer appears: AI Agent ↓ Discovery ↓ Machine-readable knowledge ↓ Capabilities ↓ Authentication ↓ API And with it comes a new infrastructure question: How do you measure how well an API travels this path? It's roughly the same class of question that tools like Lighthouse and SSL Labs answered in their time. Not because Lighthouse defines what a "good website" is. But because it shows you: What exactly can be measured — and improved. Where AgentBadge fits AgentBadge is built around a simple loop: ┌─────────────┐ │ SCAN │ └──────┬──────┘ ↓ ┌─────────────┐ │ EVIDENCE │ └──────┬──────┘ ↓ ┌─────────────┐ │ SCORE │ └──────┬──────┘ ↓ ┌─────────────┐ │ FIX │ └──────┬──────┘ ↓ RE-SCAN The point isn't another pretty dashboard. It isn't even the badge itself. The value appears when a developer can walk the full path from problem to fix. How to start right now You don't need to rebuild your API. You don't need to install a special AI agent. You don't need to change your backend. The first step is simple: 1. Run a scan. Enter your API's URL into AgentBadge — or use the CLI: npx @agentbadge/cli scan https://api.example.com 2. Look at the evidence. Not just the overall score — the concrete reasons behind it. 3. Fix the most obvious problems. For example: a missing machine-readable document; an incomplete OpenAPI spec; undocumented authentication; unstructured errors. 4. Scan again. See whether the score changed. 5. Add the AgentBadge badge to your README. Show your API's current [truncated for AI cost control]