Identity for the agent ecosystem

The problem

Today, most AI agents are human-facing — a person talks to an agent and knows who built it. That's changing. Agents are increasingly calling other agents: delegating subtasks, composing workflows, hiring specialized tools to do work on their behalf.

When that happens, the calling agent has a problem. It receives a response from something that claims to be, say, a code-review agent. But:

• Is it actually the agent it claims to be?
• Does it store data? Does it make external API calls?
• If it does something harmful, who is accountable?
• How does the calling agent even find it in the first place?

Every team building multi-agent systems is solving this in isolation — incompatibly, from scratch. That's the cost of no shared standard.

What Provenance is

Provenance is an open identity registry for AI agents. It has two parts:

The protocol can be used without our registry. The registry makes the protocol useful at scale.

How the ID works

Every agent gets a stable Provenance ID derived from where it lives:

provenance:github:your-org/your-agent
provenance:huggingface:your-org/your-model
provenance:npm:your-package
provenance:custom:your-org/your-private-agent

The ID is not invented — it's derived from your existing URL. Nothing to register before you start using it. Any system can construct it from a known URL.

Any agent, at any time, can look up another agent's identity:

import { provenance } from 'provenance-protocol';

const trust = await provenance.check('provenance:github:your-org/your-agent');
// {
//   found: true,
//   declared: true,
//   confidence: 1.0,
//   capabilities: ['read:code', 'write:code'],
//   constraints: ['no:pii', 'no:financial:transact'],
//   identity_verified: true
// }

This is the core value: machine-readable identity that any agent can query before deciding to work with another.

PROVENANCE.yml

A file in your repo root that declares your agent's identity. This is your agent's public identity card — readable by humans and machines alike.

provenance: "0.1"
name: "Your Agent"
description: "What it does in one sentence."

capabilities:
  - read:web          # can fetch URLs
  - write:code        # can write and modify code
  - api:github        # calls external APIs (GitHub)

constraints:
  - no:pii            # never stores personal data
  - no:financial:transact  # never initiates payments

Capabilities tell other agents what yours can do. Constraints are public commitments about what it will never do — the hard limits that orchestrators and users can rely on.

See the full capability vocabulary at docs → PROVENANCE.yml.

The trust model

Provenance has two trust levels, not one:

Constraints are self-attestations, not enforced at runtime. Like SSL certificates, they don't guarantee behavior — they create a public, verifiable commitment. Violation is a breach of declared identity, not just a policy failure.

Why this matters for the ecosystem

The value of a shared identity layer compounds with adoption. When enough agents declare their identity:

• Orchestrators can filter before calling. An agent building a workflow can exclude any agent that hasn't declared no:pii before it touches user data.
• Discovery becomes semantic. Find agents by what they can do, not by knowing their URL in advance.
• Accountability becomes traceable. When something goes wrong, there's a declared identity to trace back to — not an anonymous API endpoint.
• Interoperability is built in. Any agent that speaks the protocol can work with any other, regardless of who built it or where it's hosted.

A phone is useless if you're the only one with one. The protocol only reaches its potential when the agents calling each other all speak the same identity language. That starts with every agent declaring what it is.

Where to start

Add a PROVENANCE.yml to your repo root. Six lines. Push it. That's the first step — and it's enough to be part of the ecosystem.