Skip to content
↑↓ to move · Enter to openEsc to close
Release notes · scenarios · content · release notes

How the scenario library is built, and what keeps it honest

Shipped · commits 2b8b035, 2577838

The scenario library shows one handshake in many settings: an agent makes a claim, the counterparty refuses to act on the claim alone, the claim becomes a proof, and specific, scoped claims get checked. Every scenario also plays without AgenID, because the comparison is the argument. It shipped on 2026-09-18, and server-rendered search landing copy for each page followed on 2026-09-21.

This post explains why the scenarios are a typed data model rather than hand-written pages, and which tests stop a future edit from quietly dropping a disclosure. The short version is that a scenario is an illustration of the protocol, not the resolution of a real agent, and the code is built around that difference.

Illustrations are not resolutions

A surface that presents a real agent's state must read its level from the authoritative response and route it through the canonical trust-presentation module. The Verification Card, both badges and /issue all do. A surface that illustrates the protocol may name a level it is explaining, but only while saying unmissably that it is an illustration and only while stating what the reference deployment can issue today.

Several scenarios illustrate L2, L3 and L4, so that statement matters. The reference deployment at agenid.com issues nothing above L1_REGISTERED today: L2 and higher require a VerificationAssertion signed by a root authority key, and that key has not been created yet. L5 is reserved and is not issuable at all.

Disclosures are required members of the type

The two disclosures, the example-flow label and the issuance ceiling, are not optional fields a future author can forget. They are required, and test/scenarios.test.ts asserts that every scenario carries them and that each one reaches the rendered page. The project's commit history is the reason: disclosures that depended on review conventions have gone missing before.

The same type constrains what a scenario can say at all:

  • The only identifier any scenario uses is the spec's example, agenid:01J8Z3K3F2QZ9X6V7R4T8N2W5Y. No scenario invents one, and no key material appears in any form.
  • Level names are verbatim from v1.1.1, and the illustrated-level type omits L5 entirely. L5 is reserved, so it cannot be named.
  • Rows have four tones: verified, declared, pending and neutral. There is no failed tone. Absence of verification is not a negative finding, and DECLARED renders amber, never emerald.
  • Any scenario that shows a nonce must say that challenge-response is a proposed interaction pattern. v1.1.1 defines the signed objects, not that exchange.

Every scenario ends by stating what it did not prove

Each scenario carries a separate block listing what AgenID deliberately does not decide, and a scoped proves statement: what was established and, more importantly, what was not. In the dentist appointment scenario the practice still decides what the caller may book. In agent delegation each hop is attributable, but the scope of each delegation is set by the operators.

Which agent is acting is not the same question as what it is allowed to do. AgenID answers the first. Protocol v1.1.1 defines no signed authorization object, so permission stays with the operator and with the party on the other side.

Search landing copy under the same guards

The 2026-09-21 change gave each scenario page server-rendered prose for readers and crawlers: a keyword-bearing title and H1, a meta description, explanatory sections, an FAQ that is also emitted as FAQPage JSON-LD, and links to related scenarios. The animation carries the argument; the prose makes the page readable without it.

That copy lives in the same module directory as the scenario data on purpose, so every existing guard, including no L5, no invented identifier, no key material and no hard-coded color, applies to it as well. test/scenario-seo.test.ts adds guards for title and description length, coverage of every page, overclaim vocabulary, and the requirement that each page still states what cannot be issued.

How to use it

Start at /how-it-works and pick a setting close to your own, such as buying tires for a multi-seller comparison or procurement for business purchasing. Toggle between the two endings. Then register a real agent at /issue and resolve it at /verify to see what the reference deployment returns today, which is DECLARED and L1_REGISTERED.

Frequently asked questions

Are the agents in the scenarios real?

No. Scenarios are illustrations of the protocol. They use the spec's example identifier only and carry a label saying they are an example verification flow.

Can I get the L2 or L3 level a scenario shows?

Not today. The reference deployment at agenid.com issues nothing above L1_REGISTERED today: L2 and higher require a VerificationAssertion signed by a root authority key, and that key has not been created yet. L5 is reserved and is not issuable at all.

Why is there no red state in any scenario?

Because an unfinished or absent check is not evidence against an agent. The type has no failed tone, and pending checks render amber.

What agenid.com issues today

The reference deployment at agenid.com issues DECLARED and L1_REGISTERED only. L2_DOMAIN_VERIFIED and higher require a VerificationAssertion signed by a root authority key, and that key has not been created yet. L5 is reserved by the specification and is not issuable at all.

Identity is not permission

Which agent is acting and who declared it is one question. What that agent is allowed to do is another, and it stays with the party on the other side and with the operator. Protocol v1.1.1 defines no signed authorization object.

Give your agent an identity

Register an agent in the browser — the signing key is generated on your device and never sent to AgenID — or resolve an existing AgenID and re-check its signature yourself.