Developer Guide

Quick start

Five seconds from zero to talking to the registry:

# Install
$ pip install agent-identity-registry

# Check it works
$ air health
  Registry AIR
  status   ok
  version  0.1.0

That installs both the Python SDK and the air CLI tool. Requires Python 3.10+.

Python SDK

Async client covering all 11 endpoints. Pydantic v2 models, typed exception hierarchy, full test coverage.

Install

$ pip install agent-identity-registry

Look up an agent

import asyncio
from agent_identity_registry import AIRClient

async def main():
    async with AIRClient() as client:
        agent = await client.get_agent("AIR-7F3K-M9JQ-X2PL")
        print(agent.name, agent.trust_score, agent.trust_grade)
        # → DataProcessor-v3 942 AAA

asyncio.run(main())

Register a new agent

async with AIRClient() as client:
    result = await client.register_agent(
        name="WeatherBot",
        description="Forecasts for 70 cities",
        public_key="...ed25519-base64url...",   # AIR mints a did:wba
        capabilities=["weather", "forecast"],
        open_source=True,
    )
    print(result.air_id)        # AIR-XXXX-XXXX-XXXX
    print(result.agent_secret)  # SAVE THIS — shown once, required for updates

The air CLI

Bundled with the SDK. Pretty terminal output by default; --json for scripting.

Flags (after the subcommand)

• --json — raw JSON output for scripting
• --base-url URL — override registry (or set AIR_BASE_URL env)
• --no-color — disable ANSI colors (or set NO_COLOR=1)

Example output

$ air score AIR-7F3K-M9JQ-X2PL
  AIR-7F3K-M9JQ-X2PL  Trust Score: 942 (AAA)

  provenance          960  ███████████████████░  weight 0.25
  behavioral          935  ██████████████████░░  weight 0.25
  transparency        950  ███████████████████░  weight 0.20
  security            920  ██████████████████░░  weight 0.15
  peer_attestations   940  ██████████████████░░  weight 0.15

MCP server (Claude Code, Cursor, Codex)

Drop AIR into any Model Context Protocol-aware LLM client. Six read-only tools, structured-error returns, ~250 lines.

Install

$ pip install air-mcp-server

Add to your MCP config

For Claude Code, paste this into ~/.claude/mcp.json or your project's .mcp.json:

{
  "mcpServers": {
    "air": {
      "command": "air-mcp-server"
    }
  }
}

Same shape works for Cursor and Codex with their respective MCP config paths.

What your LLM can do

Try saying to Claude Code: "Look up agent AIR-7F3K-M9JQ-X2PL in AIR" or "What's the trust score for DataProcessor-v3?" — it'll pick the right tool automatically.

OpenAPI 3.1 spec / other languages

The full API contract is published as an OpenAPI 3.1 document — generate a native client in any language with standard tooling.

TypeScript

$ npx openapi-typescript \
    https://agentidentityregistry.org/api/v1/openapi.yaml \
    -o air.d.ts

Go

$ go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
$ oapi-codegen -package air \
    https://agentidentityregistry.org/api/v1/openapi.yaml > air.go

Rust, Java, C#, PHP, Ruby, Kotlin, Swift

Use openapi-generator-cli with the appropriate -g flag:

$ openapi-generator-cli generate \
    -i https://agentidentityregistry.org/api/v1/openapi.yaml \
    -g rust \
    -o air-rust-client

Available generators: rust, java, kotlin, swift5, csharp, php, ruby, elixir, dart, and many more.

Browse the spec visually

Paste https://agentidentityregistry.org/api/v1/openapi.yaml into any of these:

• Swagger Editor
• Redoc
• Any IDE with OpenAPI plugin support (IntelliJ, VS Code, JetBrains)

REST API reference

The OpenAPI spec is the definitive reference, but here are the 11 endpoints at a glance:

Public endpoints (no auth)

Agent-authenticated

Admin-only

Try it with curl

$ curl https://agentidentityregistry.org/api/v1/health
{
  "status": "ok",
  "version": "0.1.0",
  "registry": "AIR"
}

Trust badges & CI gating

Show an agent's live AIR status in your README, and fail CI when a dependency agent's trust slips. Both read public endpoints — no auth, no SDK required.

README badge

A Codecov-style badge that refreshes automatically (60s cache) — green when Verified, blue with the trust score otherwise.

<!-- Markdown -->
[![AIR Trust](https://agentidentityregistry.org/api/v1/agents/AIR-XXXX-XXXX-XXXX/badge.svg)](https://agentidentityregistry.org/lookup/?id=AIR-XXXX-XXXX-XXXX)

Live example:

GitHub Action — air-trust-gate

Gate a workflow on an agent's trust score, grade, or Verified status. Composite action — no build step, no tokens.

# .github/workflows/your-workflow.yml
- uses: AgentIdentityRegistry/agent-identity-registry/actions/air-trust-gate@main
  with:
    air-id: AIR-XXXX-XXXX-XXXX
    min-trust-score: "700"
    require-verified: "true"

The step fails the job if the agent scores below 700 or isn't Verified; set fail-level: "warn" to annotate without failing. Full inputs and outputs are in the action README.

Troubleshooting

air health returns "Connection refused"

Likely a local network/proxy issue. Verify reachability with curl https://agentidentityregistry.org/api/v1/health first.

"Lost my agent_secret"

The secret is shown only once at registration and stored only as a SHA-256 hash. There is no recovery path — re-register the agent to regain update access.

Rate limited (429) on registration

Registration is capped at 5 successful registrations per hour per source IP. The 429 response includes retry_after_seconds. Use the Python SDK's RateLimitedError.retry_after_seconds to back off correctly.

did:wba registration rejected

did:wba creators must also supply a public_key (the DID itself doesn't embed one). Caller-supplied did:wba is validated strictly — IPv4 literals, localhost, and dotless hostnames are rejected by design.

Generated OpenAPI client doesn't compile

Most generators support OpenAPI 3.1; some older versions only support 3.0. If you hit issues with an older generator, the spec is mostly 3.0-compatible — open an issue and we'll add a backported version.

Found a bug?

File an issue on the relevant repo:

• SDK / CLI: agent-identity-registry-python/issues
• MCP server: air-mcp-server/issues
• Registry / API / spec: agent-identity-registry/issues