> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# Agent DID Specification

## did:adi:agent Method

The `did:adi:agent` sub-method extends `did:adi` for AI agent identifiers. Agent DIDs are registered on the ADI blockchain and include agent-specific metadata in their DID Document.

### ABNF Syntax

```abnf
agent-did = "did:adi:agent:" agent-id
agent-id  = 1*64HEXDIG
```

### Examples

```
did:adi:agent:7f3a9b2e1c4d5f6a8b0c2d4e6f8a0b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f
did:adi:agent:a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890
```

## Agent DID Document Schema

An agent DID Document extends the standard `did:adi` document with the `agent` property block:

```json
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://ida.infinia.io/ns/did/v1",
    "https://ida.infinia.io/ns/agent/v1"
  ],
  "id": "did:adi:agent:7f3a9b2e1c4d5f6a8b0c2d4e6f8a0b2c...",
  "controller": "did:adi:operator001...",

  "verificationMethod": [
    {
      "id": "did:adi:agent:7f3a...#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:adi:agent:7f3a...",
      "publicKeyMultibase": "z6Mkw6QUbN4PqGmPVjR..."
    }
  ],

  "authentication": ["did:adi:agent:7f3a...#key-1"],
  "assertionMethod": ["did:adi:agent:7f3a...#key-1"],
  "capabilityInvocation": ["did:adi:agent:7f3a...#key-1"],

  "keyAgreement": [
    {
      "id": "did:adi:agent:7f3a...#key-agreement-1",
      "type": "X25519KeyAgreementKey2020",
      "controller": "did:adi:agent:7f3a...",
      "publicKeyMultibase": "z6LSe2nPYf9r7QmX..."
    }
  ],

  "service": [
    {
      "id": "did:adi:agent:7f3a...#a2a",
      "type": "AgentToAgent",
      "serviceEndpoint": "https://agent.example.com/a2a"
    },
    {
      "id": "did:adi:agent:7f3a...#agent-card",
      "type": "AgentCard",
      "serviceEndpoint": "https://agent.example.com/.well-known/agent.json"
    },
    {
      "id": "did:adi:agent:7f3a...#mcp",
      "type": "MCPServer",
      "serviceEndpoint": "https://agent.example.com/mcp"
    }
  ],

  "agent": {
    "operator": "did:adi:operator001...",
    "name": "Shopping Assistant",
    "description": "AI agent for grocery shopping and price comparison",
    "model": {
      "provider": "OpenAI",
      "name": "gpt-4o",
      "version": "2026-03-01",
      "hash": "sha256:abc123..."
    },
    "capabilities": [
      "shopping",
      "price-comparison",
      "order-placement",
      "receipt-management"
    ],
    "autonomyLevel": "Junior",
    "state": "active",
    "registeredAt": "2026-03-15T09:00:00Z",
    "activatedAt": "2026-03-15T09:05:00Z",
    "trustScore": 74,
    "maxDelegationDepth": 1,
    "compliance": [
      {
        "standard": "EU AI Act",
        "status": "compliant",
        "credentialId": "urn:uuid:compliance-001"
      }
    ]
  },

  "created": "2026-03-15T09:00:00Z",
  "updated": "2026-03-28T10:00:00Z",
  "versionId": 3,
  "deactivated": false
}
```

## Agent Property Block

### Required Fields

| Field            | Type         | Description                                                                  |
| ---------------- | ------------ | ---------------------------------------------------------------------------- |
| `operator`       | string (DID) | DID of the human/organization who deployed and is accountable for this agent |
| `name`           | string       | Human-readable agent name                                                    |
| `model.provider` | string       | AI model provider (e.g., OpenAI, Anthropic)                                  |
| `model.name`     | string       | Model identifier (e.g., gpt-4o, claude-3-opus)                               |
| `capabilities`   | string\[]    | Tags describing what the agent can do                                        |
| `autonomyLevel`  | string       | One of: Intern, Junior, Senior, Principal                                    |
| `state`          | string       | One of: registered, active, suspended, decommissioned                        |
| `registeredAt`   | datetime     | When the agent DID was created                                               |

### Optional Fields

| Field                | Type      | Description                                    |
| -------------------- | --------- | ---------------------------------------------- |
| `description`        | string    | Human-readable description                     |
| `model.version`      | string    | Model version string                           |
| `model.hash`         | string    | Hash of the model weights/config for integrity |
| `activatedAt`        | datetime  | When the agent received its first delegation   |
| `trustScore`         | integer   | Current on-chain trust score (0-100)           |
| `maxDelegationDepth` | integer   | Max sub-delegation hops allowed                |
| `compliance`         | object\[] | Compliance attestations                        |

## Agent DID Creation

### Request

```http
POST /api/v1/agents
Content-Type: application/json
Authorization: Bearer <operator-api-key>

{
  "name": "Shopping Assistant",
  "description": "AI agent for grocery shopping and price comparison",
  "operatorDid": "did:adi:operator001...",
  "model": {
    "provider": "OpenAI",
    "name": "gpt-4o",
    "version": "2026-03-01"
  },
  "capabilities": ["shopping", "price-comparison", "order-placement"],
  "autonomyLevel": "Intern",
  "services": [
    {
      "type": "AgentToAgent",
      "serviceEndpoint": "https://agent.example.com/a2a"
    }
  ]
}
```

### Response

```json
{
  "agentDid": "did:adi:agent:7f3a9b2e1c4d5f6a...",
  "didDocument": { "..." },
  "keys": {
    "authentication": {
      "keyId": "did:adi:agent:7f3a...#key-1",
      "publicKey": "z6Mkw6QUbN4PqGmPVjR...",
      "privateKey": "** STORE IN AGENT RUNTIME - SHOWN ONCE **"
    }
  },
  "agentCard": {
    "url": "https://agent.example.com/.well-known/agent.json"
  },
  "transactionHash": "0xagent..."
}
```

## Differences from Standard DID Documents

| Feature                | Standard DID           | Agent DID                                  |
| ---------------------- | ---------------------- | ------------------------------------------ |
| Identifier prefix      | `did:adi:`             | `did:adi:agent:`                           |
| Controller             | Self or chosen DID     | Operator's DID (required)                  |
| `agent` property       | Not present            | Required                                   |
| `capabilityDelegation` | Optional               | Requires Principal autonomy                |
| Service types          | DIDComm, LinkedDomains | AgentToAgent, AgentCard, MCPServer         |
| Trust score            | Not applicable         | On-chain via Agent Trust Registry          |
| Lifecycle states       | Active/Deactivated     | Registered/Active/Suspended/Decommissioned |

## Validation Rules

An agent DID Document is valid if:

1. All standard DID Document validation rules pass (see [DID Document Schema](../did-method/did-document.md))
2. `id` starts with `did:adi:agent:`
3. `controller` references a valid non-agent DID (the operator)
4. `agent` object is present with all required fields
5. `agent.operator` matches `controller`
6. `agent.state` is one of the allowed values
7. `agent.autonomyLevel` is one of: Intern, Junior, Senior, Principal
8. `agent.capabilities` is a non-empty array
9. If `agent.state` is `decommissioned`, `deactivated` must be `true`

## Agent Decommissioning

When an agent is decommissioned:

```http
POST /api/v1/agents/did:adi:agent:7f3a.../decommission
Authorization: Bearer <operator-api-key>

{
  "reason": "replaced_by_newer_version",
  "confirm": true
}
```

This triggers:

1. Agent state set to `decommissioned` on-chain
2. All delegation VCs held by this agent are revoked
3. All capability and compliance VCs are revoked
4. All active IBCTs are invalidated
5. Sub-agents delegated by this agent lose their delegations
6. DID Document is updated with `deactivated: true`