Spec Proposal: Deployment metadata

[marianogonzalez]

The Problem:

AI catalog conflates "what the agent is" (identity) with "where it lives" (instance). This is fine in the open internet but doesn't scale that well for assets living inside the enterprise:

• The SAME logical agent runs in dev, staging, and prod
• The SAME logical agent has replicas in us-east, eu-west, ap-southeast (this may be hidden behind a load balancer, but not always)
• These are NOT different agents - they're different instances of the same agent

The geolocation comes with additional concerns like compliance requirements and data residency restrictions. The point could be made
that this is no different from auth and should be delegated to each assets card or modeled through metadata. However:

• None of the standard cards have these concepts
• Metadata without standardization is suboptimal
• It hinders the agent's ability to safely install new capabilities at runtime

Proposal: Structured deployment metadata

• Keep the url attribute as the default entry point for the resource
• Enrich the entry with an optional instances array which lists all valid URLs alongside deployment information such as:
  • environment
  • region
  • data residency
  • compliance

{
  "identifier": "urn:ai:acme.com:finance:invoice-processor",
  "displayName": "Invoice Processor",
  "url": "https://api.acme.com/agents/invoice",
  "type": "application/a2a-agent-card+json",
  "instances": [
    {
      "instanceId": "invoice-prod-us",
      "environment": "production",
      "url": "https://api.acme.com/agents/invoice",
      "region": "us-east-1"
    },
    {
      "instanceId": "invoice-prod-eu",
      "environment": "production",
      "url": "https://eu-api.acme.com/agents/invoice",
      "region": "eu-west-1",
      "dataResidency": ["EU"],
      "compliance": "GDPR"
    }
  ]
}

This makes it possible to create deterministic guardrails to make sure agents only select assets that conform to their own compliance rules.

Discovery Value:

• Test discovery in staging without prod impact
• Discover geo-appropriate instances (EU clients → EU instances for data residency)
• Support canary discovery (discover beta instance for testing/shadowing)
• Maintain single logical identity across deployment pipeline

Alternatives Considered:

• Simply use different catalogs: If my agent can only use GDPR compliant assets, then just point it to a previously curated/filtered catalog
  • While a valid solution, it's less flexible: What if GDPR is only required for some operations and only for clients associated to a specific geography? This approach overly complicates management and can lead to inconsistencies

[litzki-systems]

SOVP-v1 as per-instance attestation anchor

The instances shape in this proposal maps cleanly onto SOVP-v1's attestation scope. SOVP records infrastructure state at the instance level — one attestation per deployed host, not per logical agent identity. The instanceId + url pair in each entry is a natural anchor for a SOVP-v1 entry in trustManifest.attestations.

Concretely: invoice-prod-eu on eu-west-1 carries its own SOVP attestation reflecting the EU-region hardening baseline. A consuming agent checks the SOVP record for that specific instance before connecting, independently of the prod-us attestation.

This composes with the compliance field proposed here: dataResidency: ["EU"] declares the policy intent; the SOVP-v1 attestation in trustManifest.attestations provides the cryptographic evidence that the instance meets it.

The extended shape would look like:

{
  "identifier": "urn:air:acme.com:finance:invoice-processor",
  "displayName": "Invoice Processor",
  "url": "https://api.acme.com/agents/invoice",
  "type": "application/a2a-agent-card+json",
  "instances": [
    {
      "instanceId": "invoice-prod-eu",
      "environment": "production",
      "url": "https://eu-api.acme.com/agents/invoice",
      "region": "eu-west-1",
      "dataResidency": ["EU"],
      "compliance": "GDPR",
      "trustManifest": {
        "attestations": [
          {
            "type": "SOVP-v1",
            "uri": "https://eu-api.acme.com/.well-known/sovp-identity.json",
            "digest": {
              "alg": "sha256",
              "value": "<SHA-256 over JCS-canonical identity record bytes>"
            }
          }
        ]
      }
    }
  ]
}

The trustManifest sits inside each instance entry rather than at the catalog level — because the attestation is instance-specific. A verifier recomputes the digest from the artifact bytes independently, with no issuer callback.

Cross-reference: #41 (SOVP-v1 pre-execution infrastructure attestation type).

[marianogonzalez]

@litzki-systems adding SOVP is a great idea and completely agree that attestations should be added on the instance entry. The only thing I would add is that it should also be possible to add it on the global attestation that applies to the default url. I see the instances as an advanced feature for advanced enterprise governance. It should be easy for an "internet facing" agent to provide that attestation as well

[litzki-systems]

Agreed. The global url case is the simpler baseline. A single SOVP-v1 entry in trustManifest.attestations at the catalog root covers any internet-facing agent without instances.
The instance-level attestation then extends this naturally for the enterprise deployment shape you described: each instanceId carries its own attestation reflecting the specific regional hardening baseline. A verifier checks the SOVP record for that instance independently. Both cases use identical verification logic: recompute the digest from the artifact bytes, check the DNS anchor. No issuer callback either way. Will update §5.2.2 in PR #48 accordingly.