Skip to content

Agent Identity Design Checklist

Use this checklist when designing, reviewing, or extending any code that creates, accepts, or acts on an agent identity in SecondBrain (AgentManifest, A2AAgentCard, A2AEnvelope, RunContext, SecondBrainRunner.fork_session, automations, MCP servers).

A change passes if every applicable question has a concrete, code-grounded answer. Current code lives under brain/agent_identity/. If an answer is "we don't model that yet," link to the gap in agent_identity_design.md rather than waving it away.

Working definition

Agent identity is the verifiable identity of a software or AI agent as an actor, separate from the human user, organization, app, or runtime it uses.

A useful agent identity answers the six questions below. They are the lens for every design review.

1. Who is this agent?

  • Does the change name the agent with a stable, canonical identifier (AgentManifest.id + version, or AgentURN from brain/agent_identity/urn.py)?
  • Is that identifier propagated end-to-end (manifest → card → envelope → RunContext.agent_name → event log → decision record)?
  • If a new agent kind is introduced, is it registered in the AgentBuilder registry / A2A card catalogue?
  • Is the version pinned so two runs of "the same agent" cannot silently diverge?

2. Who owns or authorized it?

  • Is there a structured owner (human, team, or service account) — preferably OwnershipSpec, not just AgentManifest.author: str | None?
  • Is the lifecycle status explicit (active, deprecated, revoked) and checked before minting or accepting an identity claim?
  • If the agent was created by another agent or an automation, is the creator captured (created_by, automation_id)?
  • Is the signing-key id that proves ownership recorded on the card?

3. What human, org, tenant, or workflow is it acting for?

  • Does RunContext.identity or the attached IdentityClaim carry an explicit Principal (user, service, automation, agent) — not a parallel user_sid / freeform actor authority?
  • For A2A or sub-agent calls, does the envelope/run carry an on_behalf_of chain so the original human is traceable through every hop?
  • Is the workflow/intent (intent, decision_key, automation_id) recorded so "for what" is answerable, not just "for whom"?
  • Are tenant boundaries enforced (e.g. A2AEnvelope.tenant, A2APushNotificationConfig.tenant)?

4. What is it allowed to do, for how long, and under what approval gates?

  • Is the tool surface declared on the manifest (ToolsSpec.tool_allowlist, ToolsSpec.tool_policies) — not implicit in code?
  • If the agent is manifest-backed, is the requested claim narrowed to AgentManifest.identity_scopes?
  • Are scopes attached to that surface and, where needed, enforced by ToolExecutor / ToolPolicy(identity_required=True)?
  • Is there a per-run expiry (RunBudget, timeout_s, IdentityClaim.exp)? No long-lived implicit authority.
  • Are approval gates explicit per intent (approval_tier, permission_mode, SafetyMode) and checked before privileged actions?
  • Is safe_mode/strict_mode respected (the kernel already toggles tool classes by mode)?

5. Which key, workload, model/runtime, version, policy, or environment proves it is really that agent?

  • Is the agent card signed (A2AAgentCardSigner.sign_card) and the signature verified on every accept?
  • Is a per-run identity claim issued — covering at minimum sub/agent URN, principal_chain, scopes, exp, run_id, model, provider, permission_mode, approval_mode, and policy_profile — and bound to a key the receiver can verify?
  • If a sub-agent is spawned (SecondBrainRunner.fork_session), is a new, narrower claim minted (inherits principal_chain, narrows scopes, sets fresh run_id and exp)?
  • Are model/provider/version recorded so "same agent, different model" is distinguishable in audit?
  • Are keys stored outside the repo (state dir, env, KMS) and never logged? Local HMAC keys should go through LocalIdentityKeyStore.

6. How are actions audited, revoked, rotated, and attributed?

  • Does every tool call / decision / A2A message log the identity claim hash or agent_identity_* metadata alongside run_id/trace_id?
  • Are decisions recorded via brain/decisions/ with a stable decision_key and evidence_refs pointing to the run trace?
  • Is there a revocation path — at minimum, marking an AgentManifest lifecycle as revoked, refusing to mint new claims for it, and exposing the local operator path through sb agent-identity revoke when applicable?
  • Is key rotation documented and tested for local identity keys and A2AAgentCardSigner (sb agent-identity rotate-key)?
  • Can an auditor reconstruct, from the event log alone, the chain of "human → which agent → which sub-agents → which tools → which side effects"?

How to use this in a code review

  1. Skim the six headings and mark each as ✅ (covered), ⚠️ (partial), or ❌ (not modelled).
  2. For any ❌, decide: blocks the change, deferred-with-issue, or genuinely out of scope. Link the issue to the agent_identity_design.md phase that picks it up.
  3. If the change introduces a new identity surface (a new manifest field, a new envelope, a new fork point), require ✅ on Q1, Q2, Q5, Q6 before merge.
  4. For runtime/policy changes, require ✅ on Q3, Q4, Q5.
  • agent_identity_design.md — current-state audit and proposed implementation plan.
  • vault/05_playbooks/research/2026-05-16-agent-identity.md — industry context (Microsoft Entra Agent ID, OAuth/OIDC, SPIFFE/SPIRE, NCCoE).
  • brain/policies/injection.py:46 — the identity_override rule treats identity as a defended boundary; this checklist is the constructive counterpart.