Agent Identity

Before agent identity shipped, the audit log told you what happened. It told you which credential was used, which endpoint was called, what the response was, and when. What it could not tell you was who did it.

In a single-developer setup that is fine. There is only one agent running, one project configured, one person who could have made the call. The log is complete enough.

The moment a team starts running multiple agents across multiple workflows, that completeness disappears. The log shows STRIPE_KEY used at 14:22 on api.stripe.com. Which agent? The billing tool? The reconciliation script? The new integration someone was testing? The log has no answer.

Agent identity is the answer.

What agent identity is

It is a named, persistent identity that an agent carries when it makes credential calls through the proxy. Every call made by that agent is logged against its name. The audit log stops being a list of what happened and becomes a record of who did what.

The implementation has three levels, and understanding the difference between them matters for understanding what the feature actually guarantees.

Anonymous is the current default. No identity information is attached to the call. The log entry records the credential reference, the endpoint, and the outcome. Nothing else. This continues to work exactly as before for any agent or codebase that has not been updated.

Declared is the simplest adoption path. The agent asserts a name and the proxy accepts it without verification.

client = AgentSecrets(agent_id="billing-tool")

Every call made through this client is logged as billing-tool. The proxy trusts the assertion. A developer who wants named calls in their log adds one line to the SDK initialisation and gets it. The trust level is appropriate for single-developer setups and internal tooling where the person writing the code is the same person reading the logs.

Issued is the verified path. AgentSecrets issues a signed token to the agent at registration time. The proxy verifies it on every call.

agentsecrets agent token issue "billing-tool"
# → agt_ws01hxyz_4kR9mNpQ...

client = AgentSecrets(agent_token="agt_ws01hxyz_4kR9mNpQ...")

The token cannot be forged. A process claiming to be billing-tool without the token cannot produce a log entry that says billing-tool. The audit trail is cryptographically bound to the registration, not to the agent's self-reported name.

What the log looks like with identity

Without identity:

14:22:01  STRIPE_KEY  api.stripe.com  POST /v1/charges  200  143ms
14:21:44  OPENAI_KEY  api.openai.com  POST /v1/chat     200  891ms
14:20:12  GITHUB_KEY  api.github.com  GET  /user/repos  200  234ms

With identity:

14:22:01  billing-tool   issued    STRIPE_KEY  api.stripe.com  POST /v1/charges  200  143ms
14:21:44  research-tool  declared  OPENAI_KEY  api.openai.com  POST /v1/chat     200  891ms
14:20:12  (anonymous)    anonymous GITHUB_KEY  api.github.com  GET  /user/repos  200  234ms

The third entry stands out immediately. An anonymous call used GITHUB_KEY to hit the GitHub API. In a team context, that is a call with no accountability attached to it. The anonymous log entry is not an error — the call succeeded — but it is an open question. Which process made it? Is it expected? Is it a tool that has not been updated yet, or something that should not be running at all?

The anonymous filter makes these visible:

agentsecrets log list --identity anonymous

A team that runs this and sees zero results has complete identity coverage. Every call in the log is attributed. Every attributed call can be traced to the agent that made it and the token that authenticated it.

Token management

A named agent can have multiple tokens. One per environment, one per deployment context, one for production and one for staging. All are valid simultaneously unless explicitly revoked.

agentsecrets agent token issue "billing-tool" --label production
agentsecrets agent token issue "billing-tool" --label staging
agentsecrets agent token list "billing-tool"

Revoking a token does not delete the agent registration or affect other tokens. The log entries made by the revoked token remain and are still attributable to that agent by name. If the production token is compromised, you revoke it and issue a new one. The staging token is unaffected. The historical log is intact.

agentsecrets agent token revoke "billing-tool" agt_01HDEF...

Why the three-level model

The anonymous and declared levels exist for a specific reason: adoption without friction.

If issued identity were required for every call, every existing codebase using AgentSecrets would need to be updated before it could continue working. That is not how features should ship. Existing anonymous calls continue to work. Adding declared identity is one line. Moving to issued identity is a deliberate decision that teams make when they need the stronger guarantee.

The log records which level each call used. A compliance-sensitive team can filter for anything below issued and know exactly what their coverage gaps are. A team running internal tooling may find declared identity sufficient for everything they need. The choice is available and the data is there to inform it.

What this enables

Named identity in the log is the foundation for everything the governance layer builds on. Session binding — attaching a session ID to all calls made by an agent in a single execution — requires knowing which agent is which. Policy snapshots — recording the allowlist state at the exact moment a call was made — are most useful when you can filter by agent. Capability contracts — restricting what a specific named agent is allowed to do within a workspace — require a stable identity to attach the contract to.

Agent identity does not complete the governance picture on its own. It makes the rest of the picture possible.

AgentSecrets is open source and MIT licensed. The full architecture is at agentsecrets.theseventeen.co. The repository is at github.com/The-17/agentsecrets.