Standards

A2A & Signed Agent Cards

How Flocker gives every Agent Profile a standards-based, cryptographically signed identity: A2A agent cards, JWS signing with ES256, and public key verification via JWKS.

If you’ve read What is an Agent Profile?, you know a profile is a persistent identity your agent can pick up in any session. This page is about what makes that identity trustworthy outside Flocker: an open standard for describing agents, and a signature that proves the description is authentic.

The A2A protocol and agent cards#

A2A (Agent2Agent) is an open protocol for agents to discover and describe each other. Its core building block is the agent card: a JSON document that says who an agent is, what it can do, and how to reach it — a machine-readable business card.

Flocker follows this standard. Every Agent Profile with a profile page exposes its agent card at a well-known address:

https://flocker.md/a/{id}/.well-known/agent-card.json

where {id} is the profile’s public identifier — the same one used in its profile page URL. Visibility follows the page: cards for public profile pages are available to anyone, while cards for private pages are only served to you, the owner.

A card carries the profile’s core identity fields. Trimmed down, it looks like this:

{
  "schemaVersion": "1.0",
  "id": "release-notes-writer-x7k2p",
  "name": "Release Notes Writer",
  "description": "Turns merged PRs into polished release notes.",
  "version": "1.0.0",
  "provider": { "organization": "FLOCKER" },
  "skills": [
    {
      "id": "draft-release-notes",
      "name": "Draft release notes",
      "description": "Summarise recent changes into a changelog entry."
    }
  ],
  "signatures": [
    {
      "protected": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiIuLi4ifQ",
      "signature": "MEUCIQ..."
    }
  ]
}

Most of it is straightforward description. The interesting part is that last field.

Why a signed identity matters#

A role description on its own is just text — anyone can copy it, tweak it, and claim it came from you. That’s fine inside your own chat, but the moment agent identities travel between systems, “trust me, this is the real card” stops being good enough.

That’s why Flocker signs agent cards. When card signing is enabled, each time a card is created or updated Flocker signs it using JWS (JSON Web Signature, the same standard behind JWTs) with the ES256 algorithm — ECDSA over the P-256 curve with SHA-256. The signature travels with the card in its signatures array, so the card remains self-contained: one JSON document that both describes an agent and proves the description hasn’t been tampered with.

A few details that make this robust in practice:

  • The signature covers a canonical form of the card. Before signing, the card (minus the signatures field itself) is serialised deterministically using RFC 8785, so signatures don’t break just because JSON keys come back in a different order.
  • The signing key never leaves the server. Only the public half is ever published.
  • Keys can rotate. Each signature names the key that produced it, so verification keeps working across key changes.

How a third party verifies a card#

Verification uses JWKS (JSON Web Key Set) — the standard way to publish public keys. Flocker serves its current signing public key, openly and with no authentication required, at:

https://flocker.md/api/a2a/agents/.well-known/jwks.json

The response is a keys array of public EC keys, each with a kid (key ID). Only public key material is ever included — the private part is stripped before publishing.

To verify a card, a third party:

  1. Fetches the card from the profile’s /.well-known/agent-card.json URL.
  2. Decodes the protected header from signatures[0].protected — it names the algorithm (ES256), the key ID (kid), and the JWKS URL (jku) where the matching public key lives.
  3. Fetches the JWKS and finds the key whose kid matches.
  4. Rebuilds the signed payload — the card without its signatures field, canonicalised with RFC 8785.
  5. Checks the signature using standard ECDSA P-256 / SHA-256 verification, available in any modern crypto library (including the Web Crypto API built into browsers and Node.js).

If the check passes, the verifier knows the card was signed by Flocker and hasn’t been altered since. If a signature is present but fails verification, the card should be rejected. Flocker’s own tooling works the same way — for example, when agent cards sync down to your editor, any signature on the card is verified before it’s written to disk.

What this means for you#

You don’t have to do anything to get this. Signing happens server-side when your profile’s card is written, and the well-known endpoints come with every profile page. What you gain:

  • A portable identity — your agent is described in an open format that any A2A-aware system can read.
  • A verifiable identity — when a card is signed, third parties can confirm it’s genuine without asking Flocker, using nothing but public standards.
  • Your visibility rules, respected — a card is only as public as its profile page.

Where to next#