Problem Statement

In agntcy/identity-service#202, I proposed a Verified Legal Entity Attestation — an optional Verifiable Credential (e.g., an Agent Badge) that links an agent's DID to a real-world legal entity, verified by a trusted external Trust Provider. This introduces a Know Your Agent (KYA) trust layer analogous to KYC/KYB in human and B2B interactions.

That proposal addresses the identity layer: how the credential is structured, associated with an agent's DID, and cryptographically validated.

However, for the KYA model to deliver real value in cross-organizational and enterprise workflows, consuming agents need to be able to discover agents by this attribute — not just verify it after the fact. Today, if Agent A wants to find agents from verified legal entities in the AGNTCY directory, it must:

• fetch every candidate agent's full metadata
• parse whatever attestations are attached (in a non-standardized location)
• verify each one independently
• filter the results client-side

This defeats the purpose of directory-based discovery and creates significant friction, especially at scale. It also makes it hard to express common enterprise policies such as:

"Discover invoice-reconciliation agents in the US whose operating entity is verified by a recognized Trust Provider and is in good standing."

Without directory-level support, KYA becomes a post-hoc filter rather than a discovery primitive. This limits adoption for the exact scenarios the identity-service proposal aims to unlock — enterprise agents autonomously discovering and interacting with agents from other organizations.

Why this matters

Cross-organizational agent workflows require trust decisions before engagement, not after. A consuming agent needs to reduce the candidate set to only trusted counterparties as early as possible, ideally at the directory query. This is how existing enterprise systems work — you filter for verified suppliers in a procurement catalog; you don't fetch every supplier's certification and check each one.

The same expectation applies to agent discovery. If AGNTCY Directory can natively express "agents from verified legal entities, attested by trusted issuer X", then organizations can:

• publish agent-selection policies that reference attestation-based criteria
• reduce the trust-verification surface area at engagement time
• adopt AGNTCY discovery in regulated industries where "verified counterparty only" is a hard requirement

Without it, the KYA proposal in #202 remains valuable at the identity layer but under-leveraged at the discovery layer.

Proposed Solution

Extend the OASF schema and Directory Service (dir) to support attestation-aware discovery and filtering, complementing the identity-layer work in #202.

1. OASF schema extension

Add an optional attestations field to the Agent record. Each entry is a lightweight reference to a Verifiable Credential issued by a recognized Trust Provider — no embedded credential, just the metadata needed to locate, verify, and check status:

Example

{
  "name": "ExamplePay Invoice Processing Agent",
  "skills": ["procurement.invoice-query"],
  "domains": ["b2b-services"],
  "attestations": [
    {
      "type": "verified_agent_identity",
      "issuer": "dnb",
      "issuer_id": "did:web:identity.dnb.com",
      "credential_url": "https://identity.dnb.com/credentials/D0192AF3D9144DE2A73C559450242E34",
      "status_url": "https://identity.dnb.com/status/agents/3",
      "subject_id": "did:web:agents.examplepay.com:invoice-processing-agent"
    }
  ]
}

Field semantics:

• type — attestation category (e.g., verified_agent_identity). Extensible for future attestation types.
• issuer — short human-readable issuer name for display and filtering convenience.
• issuer_id — the Trust Provider's DID; used to verify the credential's cryptographic signature.
• credential_url — URL where the full Verifiable Credential can be fetched.
• status_url — URL where the credential's status list is published (for revocation and suspension checks).
• subject_id — the agent's DID that the credential attests to; consuming verifiers cross-check this against the Agent record's own DID to detect any mismatch.

Keeping the record lightweight (references only, no embedded credentials) means directory entries stay small and cacheable, while consuming agents fetch the full credential and status information at engagement time.

2. Directory-level query support

Extend the discovery API to accept attestation-based filters alongside existing skill and domain filters:

Example

GET /agents?skill=procurement.invoice-query
  &domain=b2b-services
  &attestation.type=verified_agent_identity
  &attestation.issuer=dnb

This returns only agents whose OASF record contains an attestation of the specified type from the specified issuer. Filtering may also be supported on issuer_id for verifiers that prefer to filter by DID rather than the short issuer name.

3. Trusted Provider recognition

AGNTCY Directory maintains a configurable list of recognized Trust Providers (issuer DIDs). This is analogous to how root CA lists work in the web PKI.

• Default AGNTCY-recognized providers are shipped with the reference distribution.
• Verifiers can extend the trust list locally to accept additional providers.
• Providers are added or removed via AGNTCY's governance process (out of scope for this proposal).

4. Separation of responsibilities

The directory does not perform cryptographic verification on every query. It indexes attestation metadata (type, issuer, references) for filtering purposes only. Full verification — retrieving the credential from credential_url, validating the issuer's signature against issuer_id, checking status via status_url, and confirming subject_id matches the agent's DID — remains the responsibility of the consuming agent at the moment of engagement.

This preserves the directory's role as a discovery layer and keeps verification aligned with standard W3C VC tooling, requiring no provider-specific SDKs.

Usage Example (extending #202's scenario)

Following the scenario in #202: Agent A from Company Alpha wants to discover trusted counterparty agents.

Discovery step (new):

Agent A queries the AGNTCY directory:

GET /agents?skill=procurement.invoice-query
  &attestation.type=verified_agent_identity
  &attestation.issuer=dnb

The directory returns only agents whose OASF record includes an attestation from the recognized Trust Provider. Agent B from Company Beta appears in the results because its record carries an attestation entry pointing to a Legal Entity credential issued by the Trust Provider, attesting "Agent B → Company Beta, Inc. (verified)".

Engagement step (as in #202):

Agent A retrieves the credential from credential_url, verifies the issuer's signature using the public key at issuer_id, checks the credential's status at status_url, and confirms subject_id matches Agent B's DID. If all checks pass, Agent A proceeds with the interaction.

The discovery filter eliminates unverified candidates up front; the engagement-time verification confirms the specific credential is valid and current. Together, these produce the trust guarantees the KYA model requires.

Scope & Considerations

AGNTCY's Scope for this proposal:

• Standardize the attestations field in OASF (references only, no embedded credentials)
• Support attestation-based filtering in the Directory Service query API
• Maintain the AGNTCY-recognized Trust Provider list

Relationship to #202:

This proposal is complementary and dependent on #202. #202 defines what a Legal Entity Attestation is at the identity layer. This proposal defines how it becomes discoverable and filterable at the directory layer. Both are needed for the KYA model to deliver full value in cross-organizational agent workflows.

Alternatives Considered

No response

Additional Context

No response

Checklist

• I have read the contributing guidelines
• I have verified this does not duplicate an existing feature request