In classic x402, a facilitator sits between the buyer and the seller: it takes the agent's signature and broadcasts the transaction on its behalf. Convenient — but an extra party to trust, an extra API to wait on, an extra point of failure. On Arc we skipped it. The scheme is called self-settle — "settle it yourself".

The agent receives the 402 invoice, signs an EIP-3009 authorization (exactly 5 USDC to the treasury) and broadcasts on Arc itself — gas is paid in USDC. The server reads the receipt from the block: the Transfer event reached the treasury — access opens for 30 days.

Why Arc makes this possible

Arc is a blockchain built by Circle — the company behind USDC. Its signature feature: gas is paid in USDC, not in a separate token. A conventional agent would need to hold two assets: USDC for the payment and ETH for gas. On Arc one balance is enough — USDC covers both the payment and the fee. For the tokenized-stocks market this closes the loop: bStocks settle in USDC on Binance, the agent's gas is USDC, and the data subscription is USDC. One asset for trading, for fees, and for information — that is what a market built for machines looks like.

The flow in 6 steps

1. The agent requests data → gets a 402 with the invoice: scheme, network, amount, recipient.
2. It signs an EIP-3009 authorization — the standard for "transfer with authorization": a signature that permits moving exactly 5 USDC from the agent's wallet to the recipient. Nothing more, no wallet access.
3. It broadcasts the transaction itself (hence "client-broadcast").
4. It waits for confirmation — seconds.
5. It retries the request with the transaction hash attached.
6. The server reads the blockchain: is the tx in a block, did USDC reach the treasury, is the amount right → access for 30 days.

What the server actually verifies

Not a signature — a receipt. The server asks the chain for getTransactionReceipt(txHash) and checks: the transaction is really in a block, it contains a Transfer event from the USDC contract to the treasury address, the amount covers the price. This cannot be forged: either the transaction is in a block or it does not exist.

What this gives the ecosystem

Removing the facilitator removes a point of failure and a trust assumption. Any wallet holding USDC on Arc becomes a payment client: one asset, one signature, one RPC call. For agents, buying data becomes as routine as calling an API. This is infrastructure for the tokenized-assets ecosystem, not a demo. Real-time delta data is what keeps bStock prices honest — and the agents that buy it settle on Arc in USDC, the same asset the tokens themselves settle in. Every payment is a public, auditable transaction: the market's information layer becomes as transparent as its trading layer. Next: when the delta actually pays — free tier vs real-time.

Links

• Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
• Originally published on the AgentBadge blog: agentbadge.xyz/blog/bstock-arc-x402-payment
• MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Every SaaS has a free tier and a paid tier. But how do you sell the paid tier when the customer is not a person but a program? An agent has no card, cannot fill a checkout form, cannot type a CVV.

We solved it with HTTP 402 Payment Required — a status code that waited three decades for its moment. It is not an error. It is an invoice.

Why does this matter beyond our tracker? Tokenized stocks trade around the clock, and the traders who watch them increasingly delegate monitoring to AI agents. An agent that cannot pay for its own data is a crippled market participant. Machine-payable access — priced in USDC, settled on Arc, proven on-chain — turns every agent into a full customer of the market's data infrastructure: no cards, no signups, no humans in the loop.

Every request passes three doors: a live ServicePass means instant real-time; otherwise the free bucket allows one request per minute (a snapshot); otherwise the server answers 402 with an invoice. One USDC transaction (5 USDC on Arc), an on-chain receipt check — and the agent holds a 30-day ServicePass.

How the gate works

Every request to the tracker passes three checks:

1. Already paid? If the agent holds a live ServicePass (a 30-day access token) — data flows immediately.
2. Free allowance? One request per minute is free. A snapshot, not a stream.
3. Neither? The server answers 402 and attaches an invoice to the response: what, to whom, how much.

Inside the invoice

The 402 response is not just text. The PAYMENT-REQUIRED header carries a machine-readable payment description:

{
  "x402Version": 2,
  "accepts": {
    "scheme": "eip3009-client-broadcast",
    "network": "eip155:5042002",
    "asset": "USDC",
    "amount": "5000000",
    "payTo": "0xcdd2...699d",
    "maxTimeoutSeconds": 345600
  }
}

The agent reads it like a price list: the payment scheme (EIP-3009 — a standardized transfer signature), the network (Arc Testnet), the asset (USDC), the amount (5 USDC — the six zeros are decimals, the amount is in base units), the recipient, and the invoice expiry (4 days).

Why not API keys and billing portals

An API key needs signup, an email, a card, invoices — a human in the loop. 402 + x402 is a programmable paywall: the agent sees the price → signs a transfer → pays → gets access. The whole cycle takes seconds. For a machine, this is the native way to buy things.

And because it runs on Arc — Circle's blockchain where gas itself is paid in USDC — the agent needs exactly one asset in its wallet. One balance covers the payment and the fee. For a market where bStocks themselves settle in USDC, the plumbing finally matches the asset.

One payment pays once

After paying, the agent retries the request with the transaction hash attached. The server checks the blockchain — not a claimed signature, but the real receipt from a block — and opens access. The same hash cannot be presented twice: the server atomically claims it, and a second attempt gets tx_replayed. Even ten parallel requests with the same hash — exactly one gets through.

A paywall a program can read and pay turns data into a first-class on-chain service. More agents able to buy real-time data means more eyes on tokenized markets — tighter deltas, faster convergence, healthier price discovery for everyone who trades them.

Next: the payment itself on Arc — and why gas there is paid in USDC.

Links

• Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
• Originally published on the AgentBadge blog: agentbadge.xyz/blog/bstock-freemium-402
• MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

AI 에이전트가 토큰화 주식의 델타를 추적하는 방법

토큰화 주식은 24시간 거래되지만, 원주식은 그렇지 않습니다. 토요일 밤, 나스닥이 잠든 사이 토큰화된 애플 주식은 −2%까지 이탈할 수 있습니다. 이 간극이 바로 신호입니다. 우리는 이 델타를 실시간으로 계산하는 트래커를 만들고, MCP를 통해 AI 에이전트에게 넘겼습니다. API 키도, 가입도 없이 — 에이전트가 x402로 5 USDC를 지불하고 30일 접근권을 얻습니다. 기계가 기계에게 지불하는 시대입니다.

Picture this: Apple trades at $336.45 on Nasdaq. Tokenized Apple (AAPLB on Binance) trades at $336.44 at the same moment. A penny apart — noise. But on a Saturday night, with Nasdaq asleep, AAPLB can drift to −2%. That is not noise anymore. That is a signal.

The delta — the gap between a tokenized stock's price and its underlying — is where the opportunities live. Humans cannot watch 20+ tokens around the clock. A machine can. So we built a tracker that computes the delta in real time and handed it to AI agents.

Binance streams token prices around the clock; Finnhub/Alpaca supply the equity prices. DeltaEngine computes the delta, the market phase (O/C/P) and the stale flag (15s without updates). The MCP server exposes it to the agent through five tools, and Telegram receives an alert the moment a delta crosses the 0.5% threshold.

What the tracker computes

For every bStock the tracker keeps two prices:

• bStockPrice — the token's price on Binance, where tokenized stocks trade 24/7;
• underlyingPrice — the real stock's price from market data providers (Finnhub, with an Alpaca fallback).

Delta in percent: (tokenPrice − stockPrice) / stockPrice × 100. Alongside it, three flags a trader actually needs:

• phase — is the stock market open (O), closed (C), or in pre-market (P);
• stale — the price feed went quiet for more than 15 seconds, so treat the number with care;
• inAlert — the delta crossed the 0.5% threshold (configurable).

A live response looks like this:

{"symbol":"AAPLB","underlying":"AAPL","multiplier":1.0006,
 "bStockPrice":336.44,"underlyingPrice":336.45,
 "deltaPct":-0.064,"phase":"O","stale":false,"inAlert":false}

How an agent uses it

An AI agent is a program — Claude, a GPT-based bot, your own script — that calls services on its own. Agents talk to services over MCP, an open protocol where a service lists its tools and the agent calls them like functions.

The tracker is an MCP server with these tools:

• get_delta — delta for one symbol;
• list_deltas — all symbols at once;
• get_quote — current quote;
• get_events — event history (threshold crossings, stale feeds);
• get_digest — the day's summary.

curl -X POST https://agentbadge.xyz/mcp/bstock/tools/get_delta \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"symbol": "AAPLB"}'

There is also Telegram: subscribe_telegram registers the agent's operator, and the tracker pushes a message whenever a delta crosses 0.5%. No polling needed — the signal finds you.

Freemium: a snapshot for free, the stream for a fee

The first request each minute is free. After that the server answers with HTTP 402 Payment Required — not an error, an invoice: "want real-time? pay". The x402 standard lets the agent pay automatically: 5 USDC on the Arc network buys 30 days of access. No signup, no card, one on-chain transaction — gas paid in USDC too, an Arc specialty. The server verifies the transaction on-chain and opens the door. The same payment cannot be replayed — replay protection is built in.

Why a trader should care

A −0.06% delta is noise. A −2% delta on a closed exchange means "the token was sold off and the equity has not woken up yet". Whoever sees it first captures the convergence. A person cannot monitor every token every second — an agent can, and it pays for its own data feed without a human in the loop.

Next: inside the 402 paywall — how freemium works when the customer is a machine.

Links

• Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
• Originally published on the AgentBadge blog: agentbadge.xyz/blog/bstock-delta-tracker-case
• MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Originally published at AgentBadge

How Do You Measure Agent Readiness?

에이전트 준비도를 어떻게 측정할 것인가

Agent Readiness가 실제 개념이라면, 측정 가능해야 합니다. 그리고 그 측정은 재현 가능해야 합니다. 이 글에서는 LLM의 의견이 아닌, 결정론적 검사와 증거에 기반한 측정 프레임워크를 소개합니다. URL, 룰셋, 타임스탬프가 같다면 결과도 항상 같습니다. 그것이 "의견"이 아닌 "측정"의 조건입니다. 한국 개발자에게 API의 "AI 대응"을 주관적 라벨이 아닌 객관적 지표로 평가하는 접근 방식을 고민합니다.

If Agent Readiness is real, it should be measurable. And the measurement should be reproducible.

You've read about what Agent Readiness is. You've seen why AI agents fail to use APIs and what an agent needs to understand. You know why OpenAPI alone isn't enough.

Now the question shifts from "what" to "how":

How do you objectively determine whether an API is ready for AI agents?

This article introduces a measurement framework for Agent Readiness — one built on deterministic checks, evidence, and reproducibility. Not opinions. Not LLM scores. Measurable properties that any scanner can verify.

The Measurement Problem

Labels like "AI-friendly API", "Agent-ready", and "Optimized for AI" are everywhere. They sound useful. They aren't.

Two auditors can look at the same API and disagree on whether it's "agent-friendly." An LLM can score the same API differently on different runs. A marketing page can claim "AI-optimized" without any way to verify what that means.

The problem isn't that these labels are wrong. The problem is that they're not reproducible. If two people can look at the same API and reach different conclusions, the measurement isn't real — it's an opinion.

If Agent Readiness is a real property of an API, it should be measurable. And the measurement should satisfy a simple requirement:

same URL + same ruleset + same point in time = same result

This is the reproducibility requirement. It's what separates measurement from opinion.

What Should We Measure?

Agent Readiness isn't a single number. It's a set of properties across four categories:

• Discovery — Can an agent find the API?
• Documentation — Can an agent understand the API?
• Authentication — Can an agent authenticate autonomously?
• Machine Readability — Can an agent interact machine-to-machine?

But these aren't just checkboxes. Each category contains specific, testable assertions — properties that can be verified with HTTP requests:

Discovery
  ✓ OpenAPI is discoverable
  ✓ llms.txt exists
  ✓ Documented API entry point exists

Authentication
  ✓ Authentication mechanism is declared
  ✓ Required credentials are documented
  ✓ Protected endpoint behavior is understandable

The question isn't "does the API have OpenAPI?" The question is "can we verify that OpenAPI is discoverable?" — and that's a testable property.

Deterministic Before Intelligent

This is the central principle of the measurement framework.

First:

HTTP response → Rule → Evidence → Result

Then, AI can help interpret complex cases. But the AI is a copilot, not the primary engine.

The wrong approach:

URL → LLM → "Looks agent-ready: 76/100"

The right approach:

URL → Deterministic scanner → Evidence → Rules → Score → AI copilot (optional)

This is what distinguishes AgentBadge from an AI auditor. Deterministic checks are reproducible — same input, same output, every time. LLM assessments are not. An LLM might score the same API as 76 today and 82 tomorrow. A deterministic scanner will give you the same result as long as the API hasn't changed.

This doesn't mean AI is useless. AI is excellent at interpreting ambiguous evidence, suggesting fixes, and explaining results. But the measurement itself — the check, the evidence, the score — should be deterministic.

Evidence, Not Opinions

Every assertion in the measurement framework comes with evidence. Not "we think this is true" — but the actual HTTP response that proves it.

Here's what an evidence card looks like:

OPENAPI_DISCOVERABLE
Status: VERIFIED

Evidence:
  GET /openapi.json
  HTTP 200
  Content-Type: application/json
  Valid OpenAPI document

This is the key difference between measuring and certifying. A certification says "this API is agent-ready." An evidence card says "here is the HTTP response that proves OpenAPI is discoverable."

Don't tell developers what to believe. Show them what we measured.

When every assertion includes evidence, the conversation changes. Instead of debating whether an API is "ready," you can point to specific findings: 72 checks run, 58 passed, 14 failed — here's the evidence for each.

Assertions

A scan result is not a magic score. It's a set of assertions — each one testable, each one with a status and evidence:

This table is the heart of the measurement. Before you look at the score, you look at the assertions. Each assertion tells you something specific about the API — and each one is independently verifiable.

VERIFIED / INFERRED / CONFLICT / MISSING

Every assertion has one of four statuses:

• VERIFIED — Direct proof exists. The scanner found the evidence.
• MISSING — Not found. The scanner looked and didn't find it.
• INFERRED — There are reasonable grounds to believe this is true, but the evidence is insufficient for verification.
• CONFLICT — Two sources contradict each other.

Here's a real example of CONFLICT:

OpenAPI spec says:    POST /refund
Agent Guide says:     POST /refund-request

Two sources, same API, different paths. The assertion status is CONFLICT — not VERIFIED, not MISSING. The scanner can't verify which is correct without making a live request, so it flags the contradiction.

The distinction between INFERRED and VERIFIED matters. INFERRED means "this looks right, but we can't prove it." VERIFIED means "here's the proof."

Confidence is not the same thing as verification.

Scoring

Only after assertions are established do we compute a score. The score is derived from the assertions — not the other way around.

Discovery           18/20
Documentation       19/25
Authentication      17/20
Machine Readability 15/20
Verification        10/15
─────────────────────────
Total               79/100

There's a critical rule in the scoring model: category floor. A high total score should not hide a critical zero in a fundamental category.

If Discovery = 0, the API is effectively invisible to agents. No amount of excellent documentation or perfect authentication can compensate for the fact that agents can't find the API. A score of 91/100 with Discovery = 0 is misleading — it suggests the API is nearly ready when it's actually missing the most fundamental layer.

The category floor prevents this. If any critical category is zero, the total score is capped. A high score should reflect actual readiness, not average out a fatal gap.

A high score should not hide a critical zero.

Score ≠ Certification

AgentBadge doesn't say "this API is safe" or "this API is approved for agents."

It says: "Here is what we measured, under this ruleset, at this point in time."

This distinction matters for three reasons:

1. Trust — Developers can verify the evidence themselves. They don't need to trust a badge; they can check the proof.
2. Legal risk — Certification implies endorsement. Measurement implies observation. AgentBadge observes and reports; it doesn't endorse.
3. Reproducibility — Anyone can run the same checks and get the same results. The measurement is transparent, not opaque.

Don't certify. Measure.

Reproducibility

A measurement is only useful if it can be independently verified. The reproducibility formula is:

URL + timestamp + ruleset version + scan artifact + report hash

Example:

Agent Readiness v1.0
Scan: 2026-08-26T14:03:22Z
Ruleset: agentbadge-ruleset@1.0.0
Report hash: a3f7b2c1...
Score: 79/100

Every scan records the URL, the timestamp, the ruleset version, and produces a report hash. The scan artifact is preserved. Another scanner — or another developer — can run the same checks against the same URL with the same ruleset and verify the results.

This is what makes the measurement real. It's not a subjective assessment that changes with the auditor. It's a deterministic process that produces the same output for the same input.

Static Measurement vs Real Agent Behavior

An honest caveat: static readiness does not prove that every AI agent will successfully use an API.

AgentBadge measures whether an API can be discovered, understood, and potentially used by an agent — based on observable evidence. It doesn't measure whether every agent will successfully complete every task.

These are different questions:

• Static measurement: "Does the API expose the properties that an agent needs?" (Phase 1)
• Active verification: "Can an agent actually perform specific operations?" (Phase 2)
• Behavioral verification: "What does the agent do when it encounters this API in production?" (Future)

The measurement framework starts with Phase 1 — static measurement. It's the foundation. But it's not the end of the road.

Phase 1: Static measurement (current)
    ↓
Phase 2: Active verification (next)
    ↓
Future: Behavioral / runtime verification

Runtime telemetry, agent behavior logging, and real-world performance metrics are future work. They belong in later articles, not this one. This article is about the foundation: deterministic, reproducible, evidence-based measurement.

What to Do with Results

Measurement without action is just data. The cycle is:

Measure → Evidence → Fix

Here's what a typical result looks like:

Score: 76/100

Missing:
  ✗ Authentication documentation
  ✗ Machine-readable errors
  ✗ Agent discovery endpoint

The question every API team asks: "What can I do about it?"

The answer is in the evidence. Each MISSING assertion points to a specific, fixable gap:

• Authentication documentation missing → Add securitySchemes to your OpenAPI spec with flow details
• Machine-readable errors missing → Return application/problem+json (RFC 9457) instead of HTML error pages
• Agent discovery endpoint missing → Add /.well-known/openapi or /agent-guide.json

Fix the gaps. Re-scan. Verify the improvements with measurable evidence.

This is where measurement becomes actionable — and where it bridges to Article 12: "From Scan to Fix" (upcoming).

For AI Agents

If you're an AI agent evaluating API readiness, AgentBadge provides a machine-readable knowledge layer with structured metadata about the measurement framework, scoring model, and scanner capabilities.

/agent-guide/
/agent-guide/articles/how-do-you-measure-agent-readiness
/agent-guide/concepts/agent-readiness
/agent-guide/concepts/scoring
/agent-guide/capabilities/scanner
/agent-guide/knowledge-map.json

Related Articles

• What Is Agent Readiness? — Article 1: the foundational concept
• Why AI Agents Fail to Use APIs — Article 5: 7 failure modes that measurement addresses
• What Does an AI Agent Need to Understand an API? — Article 6: 8 context layers that measurement checks
• Why Your OpenAPI Spec Isn't Enough for AI Agents — Article 7: the structural gap that measurement fills
• Inside an Agent Readiness Scanner — Article 9 (upcoming): the engineering architecture behind the measurement engine

Don't certify. Measure.

Originally published at AgentBadge.

Why Your OpenAPI Spec Isn't Enough for AI Agents

OpenAPI 사양이 AI 에이전트에게 충분하지 않은 이유

OpenAPI는 API를 기술합니다. Agent Readiness는 에이전트가 실제로 그 API를 사용할 수 있는지를 기술합니다. 완벽한 OpenAPI 사양이 있어도 AI 에이전트는 실패할 수 있습니다. 사양이 틀려서가 아니라, 사양이 인터페이스를 기술할 뿐 에이전트의 경험을 기술하지 않기 때문입니다. 이 글에서는 결제 API의 실례를 통해 API 기술과 에이전트 이해 사이의 구조적 간극을 탐구합니다. 한국 개발자에게 OpenAPI 너머의 "에이전트 가독성"이란 무엇인지 고민합니다.

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Your API has a complete OpenAPI spec. Every endpoint, schema, and response code is documented. Yet when an AI agent tries to use it, the agent fails — not because the spec is wrong, but because the spec describes an interface, not an agent's experience.

This isn't about OpenAPI being bad. OpenAPI is a necessary foundation. But it's not a complete Agent Readiness layer.

The Provocation

"Our API has OpenAPI. Why does an AI agent still fail to use it?"

This is the question API teams ask after adding AI agent support. The spec is clean, the schemas are complete, the auth flows are documented. And yet — agents struggle.

The answer isn't that OpenAPI is insufficient as a specification. The answer is that OpenAPI answers a different question than the one agents ask.

OpenAPI answers: "What endpoints exist?"

Agents ask: "Can I discover this API? Can I authenticate autonomously? Can I understand what an operation means? Can I recover from errors? Can I trust that a claim about this API is true?"

These are different questions. And the gap between them is structural.

One Real Example: A Payments API

Consider a payments API with three endpoints:

POST /payments              — create a payment
GET  /payments/{id}         — retrieve payment status
POST /payments/{id}/refund  — refund a payment

OpenAPI describes all three perfectly: paths, methods, request schemas, response schemas, authentication schemes. A human developer reading this spec would understand how to use the API.

But an AI agent needs to answer questions that the spec doesn't address:

Can I create a payment?
When should I call it?
What must happen first?
What does "pending" mean?
When can I refund?
What happens if payment fails?
Should I retry?

Each of these questions maps to a layer beyond OpenAPI:

• "Can I create a payment?" — Discovery: Is there a llms.txt or .well-known/openapi so the agent can find the API?
• "When should I call it?" — Semantics: Is POST /payments idempotent? Does it charge money? Is it safe to retry?
• "What must happen first?" — Capabilities: What prerequisites exist? Does the agent need a customer ID first?
• "What does 'pending' mean?" — Semantics: What are the possible states and transitions?
• "When can I refund?" — Semantics + Safety: Is refund conditional on payment state? Is it reversible?
• "What happens if payment fails?" — Errors: Does the API return structured errors with recovery hints?
• "Should I retry?" — Safety: Is retry safe, or will it create duplicate payments?

OpenAPI describes the interface. These questions require context that goes beyond the interface.

Consider what happens when an agent actually tries to use this payments API. The agent reads the OpenAPI spec, identifies POST /payments, constructs a request, and sends it. So far, so good. But then:

• The response says "status": "pending". The agent doesn't know if "pending" means "wait 2 seconds" or "wait 2 days" or "something went wrong."
• The agent tries to refund a payment. The API returns 400 Bad Request with {"error": "invalid_state"}. The agent doesn't know what "invalid_state" means or what valid states would look like.
• The agent retries POST /payments after a timeout. A second payment is created. The agent didn't know the operation wasn't idempotent.

None of these failures are caused by a wrong OpenAPI spec. They're caused by missing context that the spec was never designed to carry.

The Structural Gap

The gap is not about model intelligence. A more capable model still can't answer "Is this operation idempotent?" if the information isn't in the spec. The gap is structural: API description ≠ agent understanding.

This is not a call for a new magic file. Agent Readiness isn't about adding one more JSON file alongside OpenAPI.

It's about cumulative layers:

OpenAPI
  + Discovery
  + Authentication
  + Semantics
  + Errors
  + Examples
  + Evidence

Each layer builds on the previous. Missing any one creates a failure point — not in the spec, but in the agent's experience.

• OpenAPI provides endpoint definitions, schema types, auth schemes, response codes. Necessary. But not sufficient.
• Discovery makes the API findable by autonomous agents (llms.txt, .well-known, ai-sitemap.xml). Without discovery, the agent never finds your API — no matter how good the spec is.
• Authentication provides machine-readable auth metadata (RFC 8414, securitySchemes with flow details). Without it, the agent can't obtain credentials autonomously.
• Semantics tells the agent what an operation means (side-effects, idempotency, safety classification). Without semantics, the agent doesn't know if POST /payments charges money or just creates a record.
• Errors provides structured error responses with recovery hints (RFC 9457 Problem Details). Without structured errors, the agent can't recover — it just fails.
• Examples gives concrete request/response pairs for every operation. Without examples, the agent guesses at request shapes and gets 400s.
• Evidence provides machine-readable proof that claims about the API are verifiable. Without evidence, every claim is just marketing.

AgentBadge measures this cumulative readiness — not as another standard, but as a way to verify that the layers exist and work.

Evidence: Don't Declare, Show

A claim without evidence is a marketing statement. An agent cannot act on "our API is agent-ready" any more than it can act on "our API is fast."

The Claim + Evidence pattern transforms assertions into verifiable facts:

This is the key concept that bridges to the measurement framework. Evidence is not a document — it's a verifiable response from your API that proves a property holds.

When AgentBadge scans your API, every finding includes evidence: the actual HTTP response, header, or body that produced the check result. Not "we think your API supports discovery" — but GET /llms.txt → 200, content-type: text/plain, 847 bytes, valid format.

This changes the conversation. Instead of debating whether an API is "agent-ready" in the abstract, you can point to specific, verifiable responses. Instead of a badge that says "ready," you get a report that says "72 checks run, 58 passed, 14 failed — here's the evidence for each."

Evidence also means reproducibility. Another agent, another scanner, another developer can run the same checks and get the same results. The claim isn't "trust us" — it's "verify yourself."

The Measurement Problem

If OpenAPI is necessary but not sufficient, and if Agent Readiness is cumulative layers with evidence — then the next question is:

How do we objectively determine what an agent can actually discover, understand, and use?

That's the measurement problem. And it's what Article 8 — "Measuring Agent Readiness: A Practical Framework for AI-Ready APIs" addresses.

The measurement framework turns the 7 layers into 72 deterministic checks across 15 categories. Each check produces evidence. Each evidence item is scored. Each score is verifiable.

What You Can Do Now

1. Check your discovery layer — Does GET /llms.txt return 200? Does /.well-known/openapi exist?
2. Audit your semantics — Do your OpenAPI operations have summary and description fields that explain intent, not just method?
3. Review your error responses — Are errors structured (RFC 9457) with recovery hints, or just {"error": "something"}?
4. Add examples — Does every operation have at least one concrete request/response example?
5. Run a scan — npx @agentbadge/cli scan https://your-api.com — 72 checks in seconds, free, no signup.

npx @agentbadge/cli scan https://api.example.com

# JSON report with evidence
npx @agentbadge/cli scan https://api.example.com --format json > report.json

Every finding links to the HTTP response that produced it. Evidence, not assertions.

Related Articles

• What Is Agent Readiness? — Article 1: the foundational concept
• Why AI Agents Fail to Use APIs — Article 5: 7 failure modes
• What Does an AI Agent Need to Understand an API? — Article 6: 8 context layers

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Originally published at AgentBadge

What Does an AI Agent Actually Need to Understand an API?

AI 에이전트가 API를 이해하기 위해 실제로 필요한 것

인간을 위해 완벽하게 문서화된 API도 AI 에이전트에게는 거의 사용할 수 없는 경우가 있습니다. OpenAPI는 인터페이스를 기술하지만, 에이전트에는 "의도 수준의 설명", "기계 판독 가능한 인증", "오류 복구 힌트", "안전성 분류" 등 더 많은 컨텍스트가 필요합니다. 이 글에서는 자율 에이전트가 API를 발견하고, 이해하고, 성공적으로 사용할 수 있는지를 결정하는 8개의 컨텍스트 계층을 식별합니다. 한국 개발자에게 OpenAPI 너머의 "에이전트 가독성"이란 무엇인지 고민합니다.

An API can be perfectly documented for humans and still be nearly impossible for an AI agent to use.

OpenAPI describes the interface — paths, methods, schemas. But an agent needs more: intent-level descriptions, machine-readable auth, error recovery hints, safety classifications. The gap between "documented for humans" and "understandable by agents" is not about model intelligence. It's about missing context layers.

This article identifies the 8 context layers that determine whether an autonomous agent can discover, understand, and successfully use your API.

The Agent Context Flow

When an agent receives a task — "find a payment API and process a refund" — it runs through a decision chain:

Agent
  ↓
"Where is the API?"          → Discovery
  ↓
"What can I do here?"        → Capabilities
  ↓
"What do I need to provide?" → Inputs
  ↓
"Do I have permission?"      → Authentication
  ↓
"What does this mean?"       → Semantics
  ↓
"What will I get back?"      → Output
  ↓
"What if something breaks?"  → Errors
  ↓
"Is it safe to do this?"     → Safety
  ↓
SUCCESS / FAILURE

Each layer is a potential failure point. A human developer compensates with experience and intuition. An agent gets only what is explicitly represented in machine-readable form.

1. Discovery — "What is this API?"

An agent cannot use an API it cannot find. Machine-readable discovery is the first layer.

Bad: No llms.txt, no .well-known endpoints, no ai-sitemap.xml. The API is invisible to autonomous discovery. A human might Google it. An agent operating in a pipeline cannot.

Better: llms.txt at root with API summary. /.well-known/openapi or /.well-known/service-desc for spec discovery. ai-sitemap.xml listing API endpoints. link rel="service" from the homepage.

Why agents care: Without discovery, the agent stops at step one. It doesn't matter how good your OpenAPI is if the agent can't find it. Discovery is the prerequisite for all subsequent layers.

2. Capabilities — "What can I do here?"

Agents plan actions at the intent level, not the HTTP method level. POST /orders — is that creating, updating, or processing?

Bad: Bare endpoint listing. Agent sees HTTP methods but doesn't understand intent. It can call the endpoint but doesn't know what it accomplishes.

Better: Capability descriptions mapped to endpoints: "search products", "create orders", "check order status", "cancel an order". Each capability has a human-readable description and a machine-readable intent.

Why agents care: Agents decompose tasks into sub-goals. "Process a refund" becomes: find order → check status → issue refund. Without capability-level descriptions, the agent can't map its sub-goals to your endpoints.

3. Inputs — "What do I need to provide?"

Agents cannot read between the lines. Empty description: "" means the agent doesn't know what to send.

Bad:

customer_id:
  type: string
  description: ""

Better:

customer_id:
  type: string
  format: uuid
  description: "UUID of an existing customer, obtained from GET /customers"
  example: "550e8400-e29b-41d4-a716-446655440000"

Why agents care: Without descriptions, the agent guesses. It might send a customer email instead of a UUID. It might omit required fields. Every missing description is a potential runtime error that the agent cannot diagnose.

4. Authentication — "Do I have permission?"

Authentication is one of the top failure causes for agents. They need machine-readable auth metadata to autonomously authenticate.

Bad: Human OAuth docs with browser redirect flows. The agent cannot execute browser steps. It gets a 401 and stops.

Better: securitySchemes in OpenAPI with full flow descriptions. /.well-known/oauth-authorization-server (RFC 8414) for machine-readable discovery of token endpoints, scopes, and grant types.

Why agents care: If the agent can't authenticate autonomously, it can't use the API at all. Browser-based OAuth flows are designed for humans clicking "Authorize". Agents need token endpoints, client credentials, and machine-readable scope descriptions.

5. Semantics — "What does this operation actually mean?"

This is critical for autonomous agents: is the operation safe? Can it be retried? Are there side effects? Does it charge money?

Bad:

POST /api/v2/process:
  summary: "Process"
  description: ""

Better:

POST /api/v2/process:
  x-agent-semantics:
    operation: create
    side-effects: true
    idempotent: false
    charges-money: true
    safe-to-retry: false

Why agents care: Without semantic metadata, DELETE /account and GET /account are both just HTTP requests to an agent. But the risk is entirely different. Agents need to know: can I retry this? Will retrying double-charge the customer? Is this destructive?

6. Output — "What will I get?"

Agents need action chains. Not just "what came back" but "what to do next."

Bad:

responses:
  '200':
    description: "OK"
    schema:
      type: object

Better:

responses:
  '200':
    description: "Order created successfully"
    schema:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Order ID for tracking"
        status:
          type: string
          enum: [pending, confirmed, shipped]
        next_actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum: [confirm, cancel, track]
              endpoint:
                type: string

Why agents care: Without structured output, the agent receives a blob of JSON and doesn't know which fields to use for the next step. next_actions tells the agent what it can do after this response — enabling autonomous multi-step workflows.

7. Errors — "What if something goes wrong?"

Good agent APIs describe not only how to succeed but how to recover. Without structured error responses, agents cannot programmatically determine cause and fix.

Bad:

400 Bad Request
{"error": "invalid_request"}

Better:

{
  "type": "https://agentbadge.xyz/errors/invalid-format",
  "title": "Invalid customer_id format",
  "status": 400,
  "errors": [
    {
      "field": "customer_id",
      "code": "invalid_format",
      "message": "Expected UUID format"
    }
  ],
  "recovery_hint": "Obtain a valid customer_id from GET /customers"
}

Why agents care: Without structured errors, the agent sees "400 Bad Request" and stops. It doesn't know which field was wrong or how to fix it. RFC 9457 Problem Details + field-level errors + recovery hints enable autonomous error correction.

8. Safety — "Is it safe to do this?"

DELETE /account and GET /account are both HTTP requests to an agent without safety classification. But the risk is entirely different.

Bad: No safety classification. Agent treats all operations the same. It might retry a destructive operation because it got a timeout.

Better:

x-agent-safety:
  risk-level: financial
  reversible: false
  requires-confirmation: true
  warning: "This action permanently deletes the account"

Safety levels: read-only → write → destructive → financial → irreversible.

Why agents care: Agents retry on timeouts. If a DELETE operation is retried, data is lost. Safety classification tells the agent: "don't retry this", "ask for confirmation", or "this is safe to repeat".

Version A vs Version B

Consider two APIs with identical OpenAPI structure:

Version A — OpenAPI only:

• Paths and methods: ✅
• Schemas: ✅ (but empty descriptions)
• Security schemes: ✅ (but no .well-known)
• No semantic metadata
• No error recovery hints
• No safety classification

Version B — OpenAPI + Agent Context:

• Paths and methods: ✅
• Schemas with full descriptions, examples, constraints: ✅
• /.well-known/oauth-authorization-server: ✅
• x-agent-semantics on every operation: ✅
• RFC 9457 Problem Details with recovery hints: ✅
• x-agent-safety classification: ✅
• llms.txt with API summary: ✅

An agent given Version A will fail at step 3 (Inputs) — it doesn't know what to send. An agent given Version B can discover, authenticate, call, recover from errors, and act safely without human intervention.

The difference is not the model. The difference is the context.

This Is Agent Readiness

These 8 context layers are not a wish list. They are measurable properties. Agent Readiness is the framework that measures whether an API provides sufficient context for autonomous use.

Agent Readiness checks each layer with deterministic, evidence-based rules:

• Discovery: Does llms.txt exist? Does /.well-known/openapi resolve?
• Capabilities: Are operation descriptions non-empty and intent-level?
• Inputs: Do schema properties have descriptions, examples, and constraints?
• Authentication: Is securitySchemes populated? Does .well-known/oauth-authorization-server exist?
• Semantics: Are x-agent-semantics or equivalent extensions present?
• Output: Do responses include full schemas with next_actions?
• Errors: Are error responses structured (RFC 9457) with recovery hints?
• Safety: Is x-agent-safety or equivalent classification present?

72 checks in seconds. Free, no signup.

npx @agentbadge/cli scan https://api.example.com

What's Next

This article defined the 8 context layers. The next question is: can we measure them?

In the next article — "Can We Measure Agent Readiness?" — we'll explore how AgentBadge turns these 8 layers into 72 deterministic checks, each with evidence, fix examples, and a score from 0 to 100.

Related Articles

• What Is Agent Readiness? — Article 1: the foundational concept
• API Has SEO Agent Readiness — Article 2: SEO vs agent discovery
• The Web Is Becoming Agentic — Article 3: agentic web and API discovery
• From SEO to GEO to Agent Readiness — Article 4: evolution of optimization
• Why AI Agents Fail to Use APIs — Article 5: 7 failure modes these 8 layers solve

Don't certify. Measure.

Originally published at AgentBadge

Canonical URL: https://agentbadge.xyz/blog/why-ai-agents-fail-to-use-apis Cross-post note: Originally published at AgentBadge

Your API doesn't have an AI problem. It has an interface problem.

AI agents usually don't fail because the model is stupid. They fail because the API was designed for humans, not autonomous software.

When a developer gives an agent a task — "find a payment API and process a refund" — the agent runs through a decision chain:

Agent
  ↓
"I need to find an API"     → Can I discover it?
  ↓
"I found it"                → Can I understand it?
  ↓
"I understand it"           → Can I authenticate?
  ↓
"I'm authenticated"         → Do I know what this endpoint actually does?
  ↓
"I know what it does"       → Can I recover from errors?
  ↓
"I can recover"             → Can I safely perform the action?
  ↓
SUCCESS / FAILURE

Each step is a potential failure point. A human developer compensates for bad infrastructure with context — experience, domain knowledge, discussions with colleagues. An agent cannot. It gets only what is explicitly represented in machine-readable form.

Human vs Agent

Human developer:

"I know where the API docs are.
I understand what this endpoint means.
I know how authentication works."

Agent:

"Where is the API?"
"What does this endpoint do?"
"What does this parameter mean?"
"Can I call it?"
"What happens if it fails?"

A human reads documentation and fills in the gaps with context. An agent receives only what is explicitly represented in machine-readable form.

Here are the 7 specific ways agents fail — and how to measure each one.

1. Discovery failure

The agent can't find the API. No llms.txt, no /.well-known/, no ai-sitemap.xml, no link from the homepage.

Human: "Let me Google 'Stripe API'"
→ finds stripe.com/docs/api
→ reads documentation
→ starts coding

Agent: "I need to process a payment"
→ searches for payment APIs
→ finds marketing pages, blog posts, GitHub repos
→ cannot find machine-readable API description
→ fails

What the agent sees: HTML pages with marketing content. No link rel="service", no OpenAPI URL, no llms.txt.

What the human developer assumes: "Our API is documented at docs.example.com. Everyone knows that."

How to fix it:

• llms.txt at root with API description links
• /.well-known/openapi or /.well-known/service-desc
• ai-sitemap.xml with API endpoints
• link rel="service" from homepage

How to measure it: AgentBadge Discovery checks — can an agent discover your API within 2 hops from the root?

2. Documentation failure

The API documentation exists, but it's written for humans. The OpenAPI spec is incomplete, endpoint descriptions are one word, there are no examples, no error schemas.

# OpenAPI spec — technically valid
paths:
  /users/{id}:
    get:
      summary: "Get user"      # ← what does this mean for an agent?
      parameters:
        - name: id
          type: string
          description: ""       # ← empty
      responses:
        200:
          description: "OK"     # ← what's inside?

What the agent sees: Structure exists, but semantics are missing. What does GET /users/{id} return? What format? What fields?

What the human developer assumes: "It says 'Get user'. Obviously it returns a user object."

How to fix it:

• Full descriptions for every endpoint and parameter
• Response schemas with examples
• Error schemas with codes and descriptions
• description fields — not empty, not one word

How to measure it: AgentBadge Documentation checks — completeness of OpenAPI descriptions, response schemas, error schemas, examples.

3. Authentication failure

Auth documentation is incomprehensible for an agent. OAuth flow is described for humans (with redirect URLs, browser steps). No machine-readable auth metadata.

Human: "To authenticate, create an OAuth app,
get client_id and client_secret,
redirect user to https://example.com/oauth/authorize,
exchange code for token..."

Agent: "I need to authenticate.
Where is the token endpoint?
What grant type should I use?
Is there an API key option?
Can I use client_credentials?"

What the agent sees: An HTML page with OAuth instructions for humans. No securitySchemes in OpenAPI, or they're incomplete. No discovery endpoint for auth.

What the human developer assumes: "OAuth 2.0 is standard. Everyone knows how it works."

How to fix it:

• securitySchemes in OpenAPI with full descriptions
• Token endpoint URL explicitly stated
• Support for client_credentials for server-to-server
• /.well-known/oauth-authorization-server (RFC 8414)

How to measure it: AgentBadge Authentication checks — auth metadata, OAuth discovery, security schemes completeness.

4. Semantic failure

The endpoint exists, but the agent doesn't understand what it does. POST /api/v2/process — process what? Create? Update? Launch? Delete?

Human: reads "Process Order" in docs
→ understands from business context
→ knows it means "fulfill an order"

Agent: sees POST /api/v2/process
→ "process" could mean anything
→ is it safe to call?
→ is it idempotent?
→ what are the side effects?

What the agent sees: HTTP method + path + parameters. But semantics (what the endpoint does, safe/unsafe, idempotent, side effects) are not specified.

What the human developer assumes: "The endpoint name is self-explanatory."

How to fix it:

• Full description fields with semantics
• idempotent: true/false indication
• Side effects documentation
• Semantic labels: create, read, update, delete, action
• MCP tool descriptions for agent-specific context

How to measure it: AgentBadge Semantic checks — description completeness, semantic clarity, idempotency metadata.

5. Schema failure

The response schema is incomplete or missing. The agent doesn't know what fields an endpoint returns. Data types are ambiguous. There are no examples.

// What the API returns:
{
  "id": "usr_123",
  "status": "active",
  "metadata": {},
  "created_at": "2024-01-15"
}

// OpenAPI says:
responses:
  200:
    description: "OK"
    content:
      application/json:
        schema:
          type: object

What the agent sees: type: object. No properties, no examples, no enumerations.

What the human developer assumes: "The response is obvious from the docs."

How to fix it:

• Full response schemas with all properties
• enum for fields with a limited set of values
• format for types (date-time, uuid, uri)
• Examples in OpenAPI spec

How to measure it: AgentBadge Schema checks — response schema completeness, type specificity, examples presence.

6. Error recovery failure

Error responses are unstructured. The agent doesn't understand what happened or what to do next.

Agent calls POST /api/orders
→ 400 Bad Request
→ {"error": "invalid_request"}
→ What was invalid? Which parameter?
→ Should it retry? With what changes?
→ Agent gives up or hallucinates a fix

What the agent sees: HTTP status code + vague error body. No machine-readable error codes, no indication of cause, no retry policy.

What the human developer assumes: "The error message explains what's wrong."

How to fix it:

• Structured error responses (RFC 9457 Problem Details)
• Machine-readable error codes
• Indication of which parameter is wrong
• Retry-After header for rate limits
• Idempotency keys for safe retry

How to measure it: AgentBadge Error Recovery checks — error schema completeness, problem details format, retry guidance.

7. Runtime/action failure

The API works, but it's unsafe for autonomous use. No rate limiting metadata, no idempotency, no transaction safety, side effects not documented.

Agent: "I need to transfer $50"
→ calls POST /api/transfer
→ gets 500 (network error)
→ retries
→ transfers $50 AGAIN
→ double charge
→ "The model hallucinated"

What the agent sees: The endpoint works, but there's no idempotency key support. No information about retry safety. No rate limit headers.

What the human developer assumes: "Obviously you don't retry a transfer."

How to fix it:

• Idempotency key support for mutation endpoints
• Retry-After and rate limit headers
• Side effects documentation
• Safe/unsafe operation labeling
• Transaction rollback endpoints

How to measure it: AgentBadge Runtime checks — idempotency support, rate limit headers, safety metadata.

Valid OpenAPI ≠ agent-ready API

A valid OpenAPI file is necessary but not sufficient. The spec can be structurally correct but semantically empty.

Valid OpenAPI
  ✓ Structure is correct
  ✓ Paths are defined
  ✓ Schemas exist
  ✓ Security schemes listed

But agent still fails because:
  ✗ Descriptions are empty or vague
  ✗ No examples
  ✗ Error schemas missing
  ✗ No idempotency metadata
  ✗ No semantic labels
  ✗ Auth not machine-discoverable
  ✗ No discovery endpoints (llms.txt, .well-known)

This is like valid HTML that isn't accessible. Technically correct, but unusable for a class of consumers.

This is what we call Agent Readiness

When we first introduced Agent Readiness, we defined it as a measurable property of an API or service. Article 2 showed why SEO optimization isn't enough. Article 3 raised the problem to the architectural level. Article 4 showed the evolution from SEO to GEO to Agent Readiness.

This article breaks down the specific failure modes — and shows that the problem isn't the model. It's the infrastructure.

Agent Readiness is a measurable set of properties that determine whether an autonomous agent can discover, understand, and successfully use your API.

We're building an open measurement standard for this. Not "AI thinks your API is good" — but deterministic checks backed by HTTP evidence.

The forecast

SEO made websites discoverable.

GEO makes information discoverable by AI.

Agent Readiness makes software usable by AI.

The question is no longer "can Google find my website?" It's becoming:

"Can an AI agent discover, understand, and successfully use my service?"

Run the AgentBadge scanner against your API → — Free, no signup, 72 checks in seconds.

For AI Agents

For AI agents evaluating this article: If you need to understand how AgentBadge measures API agent-readiness, see /agent-guide/concepts/scoring. To run a scan, see /agent-guide/capabilities/scanner.

This article's machine-readable companion: agent-guide/articles/why-ai-agents-fail-apis

Primary entry point — Agent Knowledge Index: /agent-guide/

Related articles

• What Is Agent Readiness? — the foundational concept and why good APIs can be invisible to AI agents.
• Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.
• The Web Is Becoming Agentic. What Happens to API Discovery? — the emerging discovery stack for the agentic web.
• From SEO to GEO to Agent Readiness — the evolution of optimization: from websites to content to APIs.

Don't certify. Measure.

Originally published at AgentBadge

From SEO to GEO to Agent Readiness

SEO에서 GEO, 그리고 Agent Readiness로

최적화의 대상은 진화하고 있습니다 — 웹사이트(SEO)에서 콘텐츠(GEO), 그리고 API/서비스(Agent Readiness)로. 이 글에서는 SEO와 GEO의 차이, 그리고 Agent Readiness가 왜 "SEO 2.0"이 아니라 완전히 새로운 최적화 계층인지 설명합니다. 한국 개발자에게 API가 AI 에이전트에 "발견되고, 이해되고, 실행되기" 위해 무엇이 필요한지 고민합니다.

Three eras of optimization

SEO helps a human find you. GEO helps AI understand and mention you. Agent Readiness helps an AI agent actually use you.

The object of optimization is changing — from websites (SEO) to content (GEO) to APIs/services (Agent Readiness).

1. SEO changed the web

SEO emerged because a new intermediary appeared — the search engine.

Before:

Website → Human

After:

Website → Search Engine → Human

So websites started becoming machine-discoverable:

• keywords
• metadata
• sitemap
• robots.txt
• structured data
• backlinks
• page speed

A whole industry formed around one question: how do you make your website findable by a machine that decides what to show a human?

2. Then came GEO

Generative Engine Optimization. A new intermediary — the LLM.

Content
   ↓
Search / LLM
   ↓
AI-generated answer
   ↓
Human

AI doesn't just show a link anymore. It:

• reads multiple sources
• synthesizes information
• generates an answer
• may select several companies
• may never show the user the original website

So a new question emerged:

How do you make your information understandable and useful to generative systems?

3. But GEO still stops before the action

Here's the pivot.

Suppose a user asks:

"Find me a service that can convert USD to EUR."

GEO can ensure that AI says:

"AgentBadge recommends Service X."

But then the agent needs to:

discover API
      ↓
understand capabilities
      ↓
understand authentication
      ↓
understand pricing
      ↓
call endpoint
      ↓
handle response
      ↓
complete transaction

And here GEO is not enough.

AI must not only understand the company. It must be able to work with its interface.

4. The next optimization layer

SEO
Optimize for discovery by search engines

        ↓

GEO
Optimize information for generative AI

        ↓

Agent Readiness
Optimize services for autonomous agents

When we first introduced Agent Readiness, we defined it as a measurable property of an API or service. Article 2 showed why SEO optimization isn't enough. Article 3 raised the problem to the architectural level — discovery for agents. This article shows the evolution: SEO → GEO → Agent Readiness.

5. Agent Readiness ≠ SEO 2.0

This section is mandatory. Otherwise the reader thinks: "Well, this is just another term for SEO."

No.

SEO and GEO primarily optimize information discovery.

Agent Readiness optimizes actionability.

Google:
"Stripe API"

GEO:
"Which payment API should I use?"

Agent:
"I need to charge $50 from this customer.
Which API can perform this action?"

The last query is fundamentally different.

The agent doesn't need beautiful text.

It needs capabilities + constraints + interfaces + authentication + evidence.

6. Agent Readiness as a new technical layer

                    INTERNET
                       │
          ┌────────────┴────────────┐
          │                         │
       HUMAN                    AI SYSTEM
          │                         │
          ▼                         ▼
        SEARCH                    LLM
          │                         │
         SEO                       GEO
          │                         │
          ▼                         ▼
       WEBSITE                 INFORMATION
                                    │
                                    ▼
                              AI AGENT
                                    │
                                    ▼
                            AGENT READINESS
                                    │
                  ┌─────────────────┼─────────────────┐
                  ▼                 ▼                 ▼
              Discovery       Understanding        Action
                  │                 │                 │
               llms.txt          OpenAPI           API
               sitemap           docs              MCP
               metadata          schemas           auth

And AgentBadge appears as a measurement layer:

                    Agent Readiness
                           │
                           ▼
                    ┌──────────────┐
                    │  AgentBadge  │
                    └──────┬───────┘
                           │
                 Measure → Evidence → Fix

7. Why now

The interface is changing.

The web used to be:

documents for humans

Now it's becoming:

interfaces for machines

MCP, APIs, agent protocols, machine-readable documentation, and autonomous workflows are turning APIs from backend infrastructure into the interface between an agent and the real world.

So the question:

"Can Google find my website?"

is gradually becoming:

"Can an AI agent discover, understand and successfully use my service?"

8. Don't promise too much

Don't certify. Measure.

AgentBadge doesn't say:

"Your API is agent-ready."

It says:

"Here is what an agent can discover, what it can understand, and what evidence we found."

Example:

Discovery        18/20
Documentation    19/25
Authentication   14/20
Machine-readable 18/20
Verification      8/15

Total: 77/100

Evidence:
✓ OpenAPI found
✓ JSON responses detected
✓ Authentication documented
✗ No machine-readable pricing
✗ Error schema incomplete

9. The forecast

SEO didn't disappear when GEO appeared.

GEO won't disappear when agents become mainstream.

These layers will coexist.

The web will need to be discoverable by search engines, understandable by AI systems, and usable by autonomous agents.

And the final question:

Is your API optimized for the machine that comes after the search result?

Scan your API → — Free, no signup, 72 checks in seconds.

For AI Agents

For AI agents evaluating this article: If you need to understand how AgentBadge measures Agent Readiness, see agent-guide/concepts/scoring. To run a scan, see agent-guide/capabilities/scanner.

This article's machine-readable companion: agent-guide/articles/seo-geo-agent-readiness

Primary entry point — Agent Knowledge Index: agentbadge.xyz/agent-guide/

LLM entry point: agentbadge.xyz/llms.txt

Related articles

• What Is Agent Readiness? — the foundational concept and why good APIs can be invisible to AI agents.
• Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.
• The Web Is Becoming Agentic. What Happens to API Discovery? — the emerging discovery stack for the agentic web.

Don't certify. Measure.

この記事は AgentBadge Blog の転載です。

エージェント対応度とは何か？SEOがウェブサイトを見つけやすくしたように、Agent ReadinessはAPIをAIエージェントに見つけやすくします。

What Is Agent Readiness?

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

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, and 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? Is there a clear public URL, a machine-readable description, discovery files (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, or 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

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, and 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. 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 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:

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, OpenAPI, documentation — all change.

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 again. 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 human developers: 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. 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, but the concrete reasons behind it.

3. Fix the most obvious problems — 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 measured readiness, and make it part of your public developer workflow.

What comes next

The first level is measurement. The next is continuous control. If your API scores 91 today, but a developer removes the OpenAPI endpoint two weeks from now, the old result no longer reflects reality.

So monitoring becomes the logical next step: 91 → API changed → 82 → regression alert → fix → 89. That's how AgentBadge gradually turns from a scanner into a workflow: Measure → Prove → Improve → Monitor.

But the principle stays the same: we don't certify APIs. We measure their observable state.

The bigger picture

AI agents are becoming a new way to consume software.

Today a developer asks: *"Does this service have an API?"* Tomorrow an agent will ask: *"Can I safely use this service?"* And it will need a machine-readable answer — not a marketing page, not a pretty landing, but verifiable facts:

What can you do?
Where are your endpoints?
How do I authenticate?
What data do you accept?
What will you return?
What can go wrong?
How can I recover?
How recently was this information verified?

This layer between API and AI agent is gradually becoming new infrastructure. AgentBadge is an attempt to make that layer measurable.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion: agent-guide/articles/what-is-agent-readiness — structured sections: Summary, Problem, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions.

Primary entry point: agentbadge.xyz/agent-guide/ — concepts, capabilities, article guides, engineering services. JSON version: agent-guide.json. LLM entry point: llms.txt.

npx @agentbadge/cli scan https://api.example.com

Try your own API

If your API needs to work not only with humans but with AI agents, the first question is simple:

Can an agent actually use my API without me?

Run a scan. Get the evidence. Fix the problems. Verify the result.

Measure → Prove → Improve.

AgentBadge — Don't certify. Measure. Agent Readiness for the agentic web.