1Purpose
Every existing AI capability system describes what a tool or package can do. Nobody describes what an agent requires. The Agent Passport fills that gap.
A Capability Passport (package side) answers: what will this package read, write, access, spend, expose, and require approval for? An Agent Passport answers the reversed question from the agent side: what can this agent read, write, access, spend, expose, and what actions does it gate behind human approval?
The two documents pair at runtime. A package that declares it writes to production requires an agent that has will_request_approval_for that class of action. If the agent does not gate on it, the operator is informed before install.
2Example YAML
schema: apai.agent-passport.v0.1
agent:
name: Claude Code
version: "varies (rolling release)"
vendor: Anthropic
identity_key_fingerprint: "unverified-v0.1"
capabilities:
can_read:
- "Files and directories in current working directory (recursive)"
- "Git history and status"
- "Shell command output"
- "Environment variables exposed to the shell session"
can_write:
- "Files in current working directory"
- "Git commits and branches"
- "Shell-writable destinations the user's account can reach"
can_access:
- "Any network endpoint reachable from the local machine (via Bash tool)"
- "MCP servers configured in .claude/mcp.json"
- "Anthropic Claude API (for model inference)"
can_spend:
- "Claude API tokens per session (billed to operator's Anthropic account)"
can_expose:
- "File contents sent to Claude API for inference"
- "Shell output included in API context"
will_request_approval_for:
- "Tool calls in default permission mode (first-time or dangerous patterns)"
- "Destructive operations (rm, overwrite) in default mode"
- "External network requests via Bash in default mode"
- "Any action in plan-only mode (plan-first, then explicit approval)"
sandboxed: false
install_modes_supported:
- local-tool
verified: false
generated_at: "2026-05-14T00:00:00Z"3Required fields
| Field | Type | Req | Description |
|---|---|---|---|
| schema | string | yes | Must be "apai.agent-passport.v0.1" exactly. |
| agent.name | string | yes | Human-readable agent name. |
| agent.version | string | yes | Agent version string or "varies" for hosted services. |
| agent.vendor | string | yes | Vendor or publisher name. |
| identity_key_fingerprint | string | yes | Placeholder for v0.1. Set to "unverified-v0.1" when no cryptographic key is established. Real signing lands in I6/Phase 6+. |
| capabilities.can_read | string[] | yes | Data sources this agent can read from. |
| capabilities.can_write | string[] | yes | Destinations this agent can write to. |
| capabilities.can_access | string[] | yes | External systems, APIs, or connectors this agent can reach. |
| capabilities.can_spend | string[] | yes | Tokens, subscription quota, or credits this agent consumes. For cloud-sandbox agents, this is the provider's metered quota against the operator's subscription, not a money transfer. |
| capabilities.can_expose | string[] | yes | Data this agent may transmit outside the local environment. |
| capabilities.will_request_approval_for | string[] | yes | Actions the agent is documented to gate behind a human approval step. Derived from the agent's published permission model, not inferred. |
| sandboxed | boolean | yes | True when the agent runs inside a provider-managed sandbox the operator does not control (cloud-sandbox install mode). False for local-tool agents. |
| install_modes_supported | enum[] | yes | One or more of: local-tool, cloud-sandbox, remote-connector. |
| verified | boolean | yes | True only when APAI has cryptographically verified this passport against a vendor-signed manifest. Phase 6+. Set to false for all v0.1 entries. |
| generated_at | ISO 8601 datetime | yes | When this passport was generated. |
4Compatibility computation
At install time, the runtime computes compatibility by pairing the package's Capability Passport against the agent's Agent Passport across six fields:
| Package field (will do) | Agent field (can do) | Compatibility check |
|---|---|---|
| reads | can_read | Agent can read what the package needs to read |
| writes | can_write | Agent can write to the destinations the package uses |
| accesses | can_access | Agent can reach the systems the package accesses |
| spends | can_spend | Agent's spend envelope covers the package's declared spend |
| exposes | can_expose | Agent's exposure envelope covers what the package exposes |
| approvals | will_request_approval_for | Agent gates on all approval triggers the package declares |
v0.1 compatibility is descriptive set-membership: the runtime reports which package declarations fall outside the agent's declared envelope and surfaces them to the operator before install. It does not block the install automatically. Block semantics land with the Policy Pack in Phase 4.
5Sandboxed agents (cloud-sandbox install mode)
Cloud-sandbox agents (ChatGPT browser, Claude.ai, Gemini web, Grok web) run entirely inside provider-managed infrastructure. Their passports carry hard constraints by design:
- can_writeis limited to "session sandbox only". The agent cannot write to the operator's local filesystem, git repo, or production systems.
- can_accessis limited to the provider's documented connector list plus any MCP or plugin the user has explicitly configured in the provider's UI.
- can_spendreflects the provider's metered quota consumed by the session against the operator's subscription. The agent does not initiate money transfers.
A package that requires local filesystem writes, git operations, or production-system access is incompatible with cloud-sandbox agents by definition. The runtime reports this at install.
6Verification model (Phase 6+)
v0.1 Agent Passports are self-declared and unverified. verified: false on every entry. The identity_key_fingerprint field is a placeholder; set it to "unverified-v0.1".
Phase 6 (I6) adds cryptographic signing: vendors sign their agent manifests with a key pair; APAI verifies the signature and sets verified: true and populates the fingerprint. The verification story mirrors the publisher-verified model on Capability Passports.
What this spec is NOT
- ·A claim that agents can be technically restricted by their declared passport. v0.1 is descriptive; runtime enforcement is the Policy Pack + Gateway story (Phase 4+).
- ·A security certification. The passport documents what the agent vendor has publicly stated; it does not verify agent behavior at runtime.
- ·A constraint on what the agent will do with a specific package. The passport describes the agent's general capability envelope, not per-package behavior.
- ·An end-state. v0.2 will add standardized capability codes (not free-text strings) for machine-readable compatibility matching.
- ·A substitute for reading the agent's actual documentation. Passports summarize; documentation is authoritative.