An agent that can prove who it is

An agent identity is a cryptographic name the toolkit gives an agent: an Ed25519 key pair and a decentralised identifier it can present, so a gate can later check who is acting, not only what action was chosen.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

Every part before this one governed what the shop agent does: an allow-list, a policy file, an audit trail. None of them asked who is making the call. The identity package answers that. It gives the agent a key pair and a DID, a name derived from its public key that no one else can forge, which the rest of this part signs actions with, delegates from, and revokes.

Creating an identity

AgentIdentity.create is the factory. It takes a name and a sponsor, an email for whoever stands behind the agent, and an optional capability list. It mints a fresh key pair and returns an identity whose status starts as active. There is no generate method; create is the one entry point.

AgentIdentity.create(name, sponsor, capabilities=None, organization=None)

Running the factory and reading a few fields shows what an identity carries. The DID is printed as a shape rather than its value, because the key pair is random, so the identifier is different on every run.

import warnings; warnings.simplefilter("ignore")
from agentmesh.identity.agent_id import AgentIdentity

# one identity for the shop agent, signed by whoever sponsors it
shop = AgentIdentity.create("shop-agent", sponsor="ops@shop.example",
                            capabilities=["read", "refund", "order_status"])

did = str(shop.did)
print("name    :", shop.name)
print("status  :", shop.status)
print("did form:", did.startswith("did:mesh:"), "| id chars:", len(shop.did.unique_id))

name    : shop-agent
status  : active
did form: True | id chars: 32

What the DID document holds

A DID document is the public half of the identity: it names the verification key, its type, and where the agent can be reached. It carries no private key, so it is the part you publish or hand to another party that needs to check the agent. to_did_document returns it as a plain dict in the W3C shape.

# the DID document is the public half others use to check the agent
doc = shop.to_did_document()

print("doc keys:", list(doc.keys()))
print("@context:", doc["@context"])
print("key type:", doc["verificationMethod"][0]["type"])
print("service :", doc["service"][0]["type"])

doc keys: ['@context', 'id', 'verificationMethod', 'authentication', 'service']
@context: ['https://www.w3.org/ns/did/v1']
key type: Ed25519VerificationKey2020
service : AgentMeshIdentity

Reading the identity

• The DID is self-describing. It reads did:mesh: followed by a 32-character identifier derived from the key, so two agents never share one and no one can claim another's.
• The document is the W3C shape. Its @context points at the DID v1 vocabulary, and the keys are the standard five, so a tool that understands DIDs can read it without knowing this toolkit.
• The key is Ed25519. The verificationMethod type is Ed25519VerificationKey2020, the same curve used to sign and verify in the next lesson.
• The status starts active. It is a mutable field, which the revocation lesson flips to revoked when an agent should no longer be trusted.

An identity vs an API key

Where an agent identity helps

• A fleet of agents sharing one tool server, where each call must say which agent made it, not only that some caller did.
• An audit trail that has to name the actor, so a signed DID in the record ties a decision to one agent.
• A hand-off between organisations, where the other side checks the DID document instead of trusting a shared secret.

Related

• Previous: Merkle proofs and CloudEvents
• Next: Signing an action and verifying it
• See also: Where the audit trail is written
• Reference: Agent Governance Toolkit documentation