> 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 Discovery & Cards

Agent Cards are machine-readable JSON documents that describe an AI agent's identity, capabilities, authentication methods, and service endpoints. They enable automated agent discovery and are compatible with the A2A protocol.

## Agent Card Format

The IDA Agent Card follows the A2A Agent Card specification with IDA-specific extensions:

```json
{
  "name": "Shopping Assistant",
  "description": "AI agent for grocery shopping, price comparison, and order management",
  "url": "https://shopping-agent.example.com",
  "provider": {
    "organization": "John Doe",
    "url": "https://example.com"
  },
  "version": "1.0.0",

  "identity": {
    "did": "did:adi:agent:7f3a9b2e1c4d...",
    "operatorDid": "did:adi:human001...",
    "trustScore": 85,
    "autonomyLevel": "Senior",
    "registeredAt": "2026-03-15T09:00:00Z",
    "verificationEndpoint": "https://ida.infinia.io/api/v1/agents/did:adi:agent:7f3a.../verify"
  },

  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "stateTransitionHistory": true
  },

  "skills": [
    {
      "id": "grocery-shopping",
      "name": "Grocery Shopping",
      "description": "Browse and purchase groceries from authorized merchants",
      "tags": ["shopping", "groceries", "e-commerce"],
      "examples": [
        "Buy milk, eggs, and bread from FreshMart",
        "Find the cheapest organic apples"
      ]
    },
    {
      "id": "price-comparison",
      "name": "Price Comparison",
      "description": "Compare prices across authorized merchants",
      "tags": ["shopping", "prices", "comparison"],
      "examples": [
        "Compare milk prices at FreshMart and OrganicCo"
      ]
    }
  ],

  "authentication": {
    "schemes": [
      {
        "scheme": "did-auth",
        "didMethod": "did:adi",
        "verificationEndpoint": "https://ida.infinia.io/api/v1/auth/verify"
      },
      {
        "scheme": "oauth2",
        "flows": ["client_credentials"],
        "tokenEndpoint": "https://shopping-agent.example.com/oauth/token",
        "scopes": ["agent:invoke", "agent:status"]
      }
    ]
  },

  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],

  "ida": {
    "delegationRequired": true,
    "requiredScope": ["shopping", "price-comparison"],
    "ibctFormat": "compact-jwt",
    "mcpEndpoint": "https://shopping-agent.example.com/mcp",
    "complianceCertificates": [
      {
        "standard": "EU AI Act",
        "credentialId": "urn:uuid:compliance-001",
        "verificationUrl": "https://ida.infinia.io/api/v1/credentials/verify/urn:uuid:compliance-001"
      }
    ]
  }
}
```

## .well-known Endpoint

Agent Cards are served at a well-known URL for automated discovery:

```
GET https://shopping-agent.example.com/.well-known/agent.json
```

This follows the A2A protocol convention and enables:

* Automated agent discovery by crawlers
* Service-to-agent handshake
* Agent-to-agent trust negotiation

### Setup

```javascript
// Express.js middleware
app.get('/.well-known/agent.json', (req, res) => {
  res.json(agentCard);
});
```

## Discovery Methods

### 1. Direct URL

If you know the agent's domain, fetch the Agent Card directly:

```bash
curl https://shopping-agent.example.com/.well-known/agent.json | jq
```

### 2. DID Resolution

Resolve the agent's DID to find the Agent Card service endpoint:

```bash
curl http://localhost:8080/api/v1/dids/did:adi:agent:7f3a... | jq '.didDocument.service[] | select(.type == "AgentCard")'
```

### 3. Agent Trust Registry Search

Search for agents by capability, trust score, or operator:

```http
GET /api/v1/agents/discover?capability=shopping&minTrustScore=80&state=active

{
  "agents": [
    {
      "did": "did:adi:agent:7f3a...",
      "name": "Shopping Assistant",
      "trustScore": 85,
      "autonomyLevel": "Senior",
      "capabilities": ["shopping", "price-comparison"],
      "agentCardUrl": "https://shopping-agent.example.com/.well-known/agent.json",
      "operator": {
        "did": "did:adi:human001...",
        "verified": true
      }
    }
  ],
  "total": 42,
  "page": 1
}
```

### 4. Agent Marketplace

The IDA portal provides a visual marketplace for browsing agents:

* Filter by category, trust score, autonomy level
* View Agent Cards with capability descriptions
* Delegate to an agent directly from the UI

## Agent Card Registration

When an agent is created, its Agent Card is automatically published:

```http
POST /api/v1/agents
Content-Type: application/json

{
  "name": "Shopping Assistant",
  "operatorDid": "did:adi:human001...",
  "agentCardUrl": "https://shopping-agent.example.com/.well-known/agent.json",
  "skills": [
    {
      "id": "grocery-shopping",
      "name": "Grocery Shopping",
      "tags": ["shopping", "groceries"]
    }
  ]
}
```

The API:

1. Creates the agent DID
2. Registers the Agent Card URL in the DID Document
3. Indexes the agent in the Trust Registry
4. Makes the agent discoverable via search

## Agent Card Verification

When a verifier or service receives an Agent Card, they should verify:

1. **DID Resolution**: Agent DID resolves on ADI blockchain
2. **Operator Verification**: Operator DID is active and valid
3. **Trust Score**: Score meets the verifier's threshold
4. **Card Integrity**: Agent Card URL matches the DID Document service endpoint
5. **Delegation**: Agent holds a valid delegation VC from the operator

```http
POST /api/v1/agents/verify-card
Content-Type: application/json

{
  "agentCardUrl": "https://shopping-agent.example.com/.well-known/agent.json"
}
```

```json
{
  "valid": true,
  "agent": {
    "did": "did:adi:agent:7f3a...",
    "name": "Shopping Assistant"
  },
  "checks": {
    "didResolution": "valid",
    "operatorDid": "valid",
    "trustScore": 85,
    "cardIntegrity": "valid",
    "delegationActive": true
  }
}
```

## Agent-to-Agent Trust Negotiation

When two agents connect for the first time, they exchange VCs to establish trust:

```mermaid
sequenceDiagram
    participant AgentA as Agent A (Buyer)
    participant AgentB as Agent B (Seller)

    AgentA->>AgentB: GET /.well-known/agent.json
    AgentB->>AgentA: Agent Card B

    AgentA->>AgentA: Verify Agent B's DID, trust score, capabilities

    AgentB->>AgentA: GET /.well-known/agent.json
    AgentA->>AgentB: Agent Card A

    AgentB->>AgentB: Verify Agent A's DID, trust score, delegation

    AgentA->>AgentB: Present delegation VC + capability VCs
    AgentB->>AgentA: Present sales authorization VC + compliance VCs

    Note over AgentA,AgentB: Both agents verified, negotiation begins
```

This follows the DIF Presentation Exchange v2 format for VC exchange.