Package com.tnsai.identity

Interface AgentPrincipal

public interface AgentPrincipal
Verifiable identity for an agent participating in the framework (TNS-298). Every ActionExecutor dispatch is attributed to one of these so the resulting AgentLiabilityRecord carries a traceable principal.

Why a separate primitive

The framework already has DID for W3C Decentralized Identifier work; that's a representation format, not an attribution primitive. AgentPrincipal layers the audit-relevant fields on top: stable id, version (changes when behaviour changes), runtime fingerprint (build hash + config hash so the same logical agent run on a different binary is distinguishable), and an optional Attestation that ties the identity back to an external credential provider (ERC-8004 attestation, signed certificate, AIUC-1 audit binding, …).

Identity vs. observability

Identity answers who; observability answers what. Liability records pair the two — "this agent did this thing" — so an audit trail can hold a principal accountable for an action.

Implementations

Default implementation is a record produced by AgentPrincipalProvider.issue(com.tnsai.identity.AgentDescriptor). Custom impls can wrap external identity systems (Keycloak / Auth0 / Ethereum) — the SPI is narrow on purpose so adapters stay thin.
Since:
0.10.0 (TNS-298)

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<Attestation>
    attestation()
    Optional cryptographic / external-system attestation binding the identity to an outside trust root (ERC-8004 on-chain proof, KMS signed cert, signed JWT, AIUC-1 audit binding).
    String
    id()
    Stable identifier — same across every dispatch from the same logical agent instance.
    String
    runtimeFingerprint()
    Hash that captures the full runtime: build artefact hash + the agent's configuration hash.
    String
    version()
    Version stamp that changes when the agent's behaviour changes — a new system prompt, a new tool catalog, a new underlying LLM model.

  • Method Details

    • id

      String id()
      Stable identifier — same across every dispatch from the same logical agent instance. Format is opaque; consumers MUST NOT parse it. UUID, DID, ERC-8004 address, anything that's stable.

    • version

      String version()
      Version stamp that changes when the agent's behaviour changes — a new system prompt, a new tool catalog, a new underlying LLM model. Consumers compare versions to detect "this agent has been updated, audit findings against the prior version no longer apply".

    • attestation

      Optional<Attestation> attestation()
      Optional cryptographic / external-system attestation binding the identity to an outside trust root (ERC-8004 on-chain proof, KMS signed cert, signed JWT, AIUC-1 audit binding). Empty when the identity is purely process-local (the default
      invalid reference 
      DefaultLocalIdentity
      , which a single-tenant deployment trusts implicitly).

    • runtimeFingerprint

      String runtimeFingerprint()
      Hash that captures the full runtime: build artefact hash + the agent's configuration hash. Two physical processes running the exact same binary with the exact same config produce the same fingerprint; differences (a config change, a JAR upgrade, a sidecar swap) produce different fingerprints. Auditors use this to tell "same logical agent, different deployment" apart from "same logical agent, same deployment".