AI Agents

Agent Discovery & Cards

View as Markdown

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:

1{
2  "name": "Shopping Assistant",
3  "description": "AI agent for grocery shopping, price comparison, and order management",
4  "url": "https://shopping-agent.example.com",
5  "provider": {
6    "organization": "John Doe",
7    "url": "https://example.com"
8  },
9  "version": "1.0.0",
10
11  "identity": {
12    "did": "did:adi:agent:7f3a9b2e1c4d...",
13    "operatorDid": "did:adi:human001...",
14    "trustScore": 85,
15    "autonomyLevel": "Senior",
16    "registeredAt": "2026-03-15T09:00:00Z",
17    "verificationEndpoint": "https://ida.infinia.io/api/v1/agents/did:adi:agent:7f3a.../verify"
18  },
19
20  "capabilities": {
21    "streaming": false,
22    "pushNotifications": true,
23    "stateTransitionHistory": true
24  },
25
26  "skills": [
27    {
28      "id": "grocery-shopping",
29      "name": "Grocery Shopping",
30      "description": "Browse and purchase groceries from authorized merchants",
31      "tags": ["shopping", "groceries", "e-commerce"],
32      "examples": [
33        "Buy milk, eggs, and bread from FreshMart",
34        "Find the cheapest organic apples"
35      ]
36    },
37    {
38      "id": "price-comparison",
39      "name": "Price Comparison",
40      "description": "Compare prices across authorized merchants",
41      "tags": ["shopping", "prices", "comparison"],
42      "examples": [
43        "Compare milk prices at FreshMart and OrganicCo"
44      ]
45    }
46  ],
47
48  "authentication": {
49    "schemes": [
50      {
51        "scheme": "did-auth",
52        "didMethod": "did:adi",
53        "verificationEndpoint": "https://ida.infinia.io/api/v1/auth/verify"
54      },
55      {
56        "scheme": "oauth2",
57        "flows": ["client_credentials"],
58        "tokenEndpoint": "https://shopping-agent.example.com/oauth/token",
59        "scopes": ["agent:invoke", "agent:status"]
60      }
61    ]
62  },
63
64  "defaultInputModes": ["text"],
65  "defaultOutputModes": ["text"],
66
67  "ida": {
68    "delegationRequired": true,
69    "requiredScope": ["shopping", "price-comparison"],
70    "ibctFormat": "compact-jwt",
71    "mcpEndpoint": "https://shopping-agent.example.com/mcp",
72    "complianceCertificates": [
73      {
74        "standard": "EU AI Act",
75        "credentialId": "urn:uuid:compliance-001",
76        "verificationUrl": "https://ida.infinia.io/api/v1/credentials/verify/urn:uuid:compliance-001"
77      }
78    ]
79  }
80}

.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

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

Discovery Methods

1. Direct URL

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

$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:

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

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

1GET /api/v1/agents/discover?capability=shopping&minTrustScore=80&state=active
2
3{
4  "agents": [
5    {
6      "did": "did:adi:agent:7f3a...",
7      "name": "Shopping Assistant",
8      "trustScore": 85,
9      "autonomyLevel": "Senior",
10      "capabilities": ["shopping", "price-comparison"],
11      "agentCardUrl": "https://shopping-agent.example.com/.well-known/agent.json",
12      "operator": {
13        "did": "did:adi:human001...",
14        "verified": true
15      }
16    }
17  ],
18  "total": 42,
19  "page": 1
20}

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:

1POST /api/v1/agents
2Content-Type: application/json
3
4{
5  "name": "Shopping Assistant",
6  "operatorDid": "did:adi:human001...",
7  "agentCardUrl": "https://shopping-agent.example.com/.well-known/agent.json",
8  "skills": [
9    {
10      "id": "grocery-shopping",
11      "name": "Grocery Shopping",
12      "tags": ["shopping", "groceries"]
13    }
14  ]
15}

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
1POST /api/v1/agents/verify-card
2Content-Type: application/json
3
4{
5  "agentCardUrl": "https://shopping-agent.example.com/.well-known/agent.json"
6}
1{
2  "valid": true,
3  "agent": {
4    "did": "did:adi:agent:7f3a...",
5    "name": "Shopping Assistant"
6  },
7  "checks": {
8    "didResolution": "valid",
9    "operatorDid": "valid",
10    "trustScore": 85,
11    "cardIntegrity": "valid",
12    "delegationActive": true
13  }
14}

Agent-to-Agent Trust Negotiation

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

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