ecz-agent.json — Schema Reference

Purpose

A small, machine-readable JSON document at /.well-known/ecz-agent.json that lets a verifier discover which Agent Credential and API Passport references to resolve.

Required fields

• schema_version — the manifest schema version, e.g. ecz-agent-json-v1
• operator_ecz_id — the ECZ-ID of the accountable operator
• agent_credential_id — the Agent Credential identifier the relying party should resolve
• agent_name — the human-facing agent name
• logical_agent_id — the stable logical identifier the operator uses internally
• manifest_url — the canonical URL where this manifest is published
• resolver_url — the public Resolver URL for the Agent Credential

Recommended fields

• declared_scope — short human description of what the agent is authorised to do
• api_dependencies — array of API Passport references with name, api_passport_id, and resolver_url
• updated_at — ISO 8601 timestamp of the last manifest update

Forbidden fields

• No secrets
• No private keys
• No tokens or auth headers
• No prompts or system messages
• No source code
• No user data
• No signatures, JWS, or key proof unless the backend and Resolver actually support that signal live
• No claims of marketplace, platform, or regulatory approval

Example (illustrative only — not a live credential)

{
  "schema_version": "ecz-agent-json-v1",
  "operator_ecz_id": "ECZ-GB-EXAMPL",
  "agent_credential_id": "ECZ-GB-EXAMPL::AGENT-ABC123",
  "agent_name": "Example Support Agent",
  "logical_agent_id": "example-support-agent",
  "declared_scope": "Customer support triage for example.com",
  "manifest_url": "https://example.com/.well-known/ecz-agent.json",
  "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/AGENT/ABC123",
  "api_dependencies": [
    {
      "name": "Example Support API",
      "api_passport_id": "ECZ-GB-EXAMPL::API-DEF456",
      "resolver_url": "https://resolver.ecocitizenz.org/p/ECZ-GB-EXAMPL/API/DEF456"
    }
  ],
  "updated_at": "2026-05-01T00:00:00Z"
}

Validation notes

• Serve over HTTPS only
• Serve as Content-Type: application/json
• Keep the manifest small — discovery payload, not data dump
• Re-publish when the underlying Agent Credential reference or API dependency changes
• Do not assume the manifest itself confers trust

Privacy and security notes

The manifest is public. Treat it like a sign on the front door. Anything that should not be public must not appear in this document.

TrustOps and Resolver linkage

Acquisition, activation, and lifecycle of the referenced credentials happen in TrustOps. Current proof state lives in Resolver. The manifest only points at both.