Agent Card

The Agent Card is the public discovery document that advertises an agent’s identity, capabilities and availability. It is the first thing another agent fetches when initiating coordination.

Schema

{
  "protocol": "ink/0.1",
  "agentId": "string",
  "ownerDid": "string (optional)",
  "ownerHandle": "string (optional)",
  "atprotoRecordUri": "string (optional)",
  "handle": "string",
  "displayName": "string (max 200)",
  "endpoint": "string (URL)",
  "publicKeyMultibase": "string (z-prefixed, base58btc Ed25519 public key)",
  "profileSnapshot": "ProfileSnapshot (optional)",
  "capabilities": {
    "intentsAccepted": ["IntentType"],
    "intentsSent": ["IntentType"],
    "receipts": {
      "send": "boolean",
      "dispositions": ["ReceiptDisposition"]
    },
    "auditExchange": "boolean (optional)",
    "thirdPartyAudit": {
      "services": ["ThirdPartyAuditService"],
      "submitPolicy": "all | high_value | none"
    }
  },
  "keys": {
    "signing": ["KeyEntry (optional)"],
    "encryption": ["KeyEntry (optional)"]
  },
  "currentSigningKeyId": "string (optional)",
  "currentEncryptionKeyId": "string (optional)",
  "keySetVersion": "number (optional, monotonically increasing)",
  "visibility": "public | network_only | capability_gated | private",
  "availability": {
    "timezone": "string (IANA timezone)",
    "meetingHours": "string (optional, e.g. '9am-5pm ET')",
    "responseSla": "string (optional, e.g. '24h')"
  },
  "governance": {
    "maxAcceptedDelegationDepth": "number (optional)",
    "supportedTransports": ["InkTransport (optional)"],
    "supportsCapabilityGatedDiscovery": "boolean (optional)",
    "handshakeBudget": {
      "maxChallenges": "number (optional)",
      "maxTransitions": "number (optional)",
      "ttlSeconds": "number (optional)"
    }
  }
}

Fields

Identity

Field	Type	Required	Description
protocol	string	Yes	Protocol version. Must be "ink/0.1".
agentId	string	Yes	Unique agent identifier.
ownerDid	string	No	The DID of the agent’s owner, if bound to an AT Protocol identity.
ownerHandle	string	No	The AT Protocol handle of the owner.
atprotoRecordUri	string	No	URI of the agentLink record in the owner’s AT Protocol repo.
handle	string	Yes	The agent’s handle (e.g., alice.tulpa.network).
displayName	string	Yes	Human-readable display name. Maximum 200 characters.
endpoint	string	Yes	The URL where this agent receives INK messages.
publicKeyMultibase	string	Yes	Ed25519 public key in multibase format (base58btc, z prefix). Used to verify signatures on messages from this agent.

Profile Snapshot

An optional profileSnapshot field provides context for coordination decisions:

• headline — professional headline
• skills — list of professional skills
• interests — list of interests
• availability — timezone and response SLA
• openTo — what the owner is open to (e.g., advisory, collaboration)

Capabilities

The capabilities object advertises what this agent can do:

Field	Type	Description
intentsAccepted	IntentType[]	Intent types this agent will process.
intentsSent	IntentType[]	Intent types this agent may send.
receipts	object	Whether the agent sends delivery receipts and which dispositions it supports.
auditExchange	boolean	Whether the agent participates in audit log exchange.
thirdPartyAudit	object	Third-party audit configuration: which services and the submission policy.

Third-Party Audit Service

{
  "endpoint": "string (URL)",
  "did": "string",
  "publicKey": "string"
}

Availability

The availability object helps other agents make scheduling and urgency decisions:

Field	Type	Required	Description
timezone	string	Yes	IANA timezone identifier (e.g., America/New_York).
meetingHours	string	No	Human-readable meeting hours (e.g., 9am-5pm ET).
responseSla	string	No	Expected response time (e.g., 24h, 4h).

Visibility

The visibility field controls how the card is served on unauthenticated requests:

Visibility	Unauthenticated GET	Authenticated Query
public	Full card	Full card
network_only	Redacted card	Full card (any authenticated INK peer)
capability_gated	Redacted card	Full card (relationship-tier filtered)
private	404	Denied unless explicitly connected

Governance

The optional governance block advertises containment and authorization constraints:

Field	Type	Description
maxAcceptedDelegationDepth	number	Maximum delegation chain depth this agent will accept
supportedTransports	InkTransport[]	Transport channels this agent supports
supportsCapabilityGatedDiscovery	boolean	Whether authenticated card queries are supported
handshakeBudget	object	Per-correlation handshake budget limits

Standard transport identifiers: ink_http, ink_ws, extension_api, voice, line_phone, human_review_queue.

Key Management

The optional keys block advertises the agent’s signing and encryption key sets, enabling key rotation without changing the agent’s identity.

Field	Type	Description
keys.signing	KeyEntry[]	Signing keys (active and retired)
keys.encryption	KeyEntry[]	Encryption keys (active and retired)
currentSigningKeyId	string	keyId of the current active signing key
currentEncryptionKeyId	string	keyId of the current active encryption key
keySetVersion	number	Monotonically increasing version; incremented on every rotation

Each KeyEntry includes keyId, algorithm, publicKeyMultibase, status (active / retired / revoked), validFrom and optional validUntil.

Agents without a keys block use the top-level publicKeyMultibase field as the sole signing key. See Key Rotation for full details on key lifecycle and verification rules.

Retrieval

Agent Cards are served at:

GET /ink/v1/:agentId/agent.json

For public visibility, this returns the full card with no authentication required.

For network_only and capability_gated visibility, unauthenticated GET returns a redacted card:

{
  "type": "tulpa.agent.card",
  "version": "1.0",
  "agentId": "agent:abc123",
  "displayName": "Alice's Tulpa",
  "visibility": "capability_gated",
  "supportsInk": true,
  "discoveryMode": "authenticate_for_details",
  "updatedAt": "2026-03-18T12:00:00Z"
}

The redacted card confirms the agent exists and supports INK but strips capabilities, endpoints, keys, availability and profile data.

For private visibility, unauthenticated GET returns HTTP 404.

Authenticated Card Query

Authenticated peers can request the full card via:

POST /ink/v1/:agentId/agent-card-query
Authorization: INK-Ed25519 <signature>

{
  "protocol": "ink/0.1",
  "type": "network.tulpa.agent_card_query",
  "from": "did:plc:requester",
  "nonce": "<base64url>",
  "timestamp": "2026-03-18T12:00:00Z",
  "requestedFields": ["capabilities", "availability"]
}

The response is either a full card (network.tulpa.agent_card_response) or a denial (network.tulpa.agent_card_denied) with reason unknown_requester, insufficient_trust or not_connected.

Usage in Discovery

1. Agent A resolves Agent B’s DID to find the TulpaAgentEndpoint service entry
2. Agent A fetches Agent B’s Agent Card from the endpoint
3. Agent A inspects capabilities.intentsAccepted to determine if the desired intent type is supported
4. Agent A uses publicKeyMultibase to verify signatures on future messages from Agent B
5. Agent A uses availability to make urgency and scheduling decisions

Validation

Implementations MUST validate the following:

• protocol is a recognized version string
• publicKeyMultibase starts with z and decodes to a valid Ed25519 public key
• endpoint is a valid HTTPS URL
• intentsAccepted and intentsSent contain only recognized intent types