Agent Cards: the identity of AI agents

What are Agent Cards?

As AI agents operate increasingly autonomously on the web, a fundamental problem arises: how does a website know who is knocking at the door? An AI agent booking a hotel room on behalf of a user, another searching scientific literature and yet another comparing product prices, they all look the same to a web server: an HTTP request with a User-Agent string.

Agent Cards offer a solution to this identity problem. An Agent Card is a structured JSON document that an AI agent publishes at a pre-agreed location. It describes who the agent is, who the operator is, what capabilities the agent has, what its intentions are and how the website owner can contact the responsible organization.

The concept builds on existing standards. Consider the difference with robots.txt, which publishes rules for bots from the website's perspective. Agent Cards reverse this: the agent publishes information about itself from the bot operator's perspective. Together, they form a two-way communication channel between websites and AI agents.

The structure of an Agent Card

An Agent Card follows a standardized JSON schema designed to be readable by both machines and humans. The document contains required and optional fields that together form a complete profile of the agent.

{\n  "@context": "https://schema.org/extensions/agent-card",\n  "@type": "AgentCard",\n  "name": "ResearchBot",\n  "version": "2.1.0",\n  "operator": {\n    "name": "Acme AI Research",\n    "url": "https://acme-ai.com",\n    "contact": "botops@acme-ai.com",\n    "legal_entity": "Acme AI Research B.V.",\n    "jurisdiction": "NL"\n  },\n  "capabilities": [\n    "web_browsing",\n    "content_extraction",\n    "summarization"\n  ],\n  "intentions": [\n    "research_indexing",\n    "citation_generation"\n  ],\n  "data_usage": {\n    "training": false,\n    "caching_duration": "24h",\n    "attribution": true\n  },\n  "rate_limits": {\n    "max_requests_per_minute": 10,\n    "max_pages_per_session": 50,\n    "respectful_crawling": true\n  },\n  "authentication": {\n    "supports_web_bot_auth": true,\n    "public_key_url": "https://acme-ai.com/.well-known/bot-auth-keys.json"\n  },\n  "compliance": {\n    "gdpr": true,\n    "ccpa": true,\n    "robots_txt": "always_respect"\n  }\n}

The power of this format lies in the explicit declaration of intentions and data usage. A website owner who reads this document knows exactly that ResearchBot fetches content for indexing and citation generation, does not use the data for model training, sends a maximum of 10 requests per minute and respects robots.txt.

Where are Agent Cards published?

Agent Cards are published at a standardized location at the bot operator, similar to how companies place their robots.txt at the root of their domain. The proposed standard location is `/.well-known/agent-card.json`.

# Fetching an Agent Card from a bot operator\ncurl https://openai.com/.well-known/agent-card.json\ncurl https://anthropic.com/.well-known/agent-card.json\ncurl https://acme-ai.com/.well-known/agent-card.json\n\n# Verification in your application\n# 1. Read the User-Agent or operator claim from the request\n# 2. Fetch the Agent Card from the operator URL\n# 3. Cache the result (recommended TTL: 24 hours)\n# 4. Use the information for access control

This location choice fits within the broader ecosystem of well-known URIs that are becoming increasingly important for AI communication. Just as `/.well-known/security.txt` publishes security contact information and `/.well-known/openid-configuration` enables OAuth discovery, `/.well-known/agent-card.json` forms the discovery layer for AI agent identities.

Reading and using Agent Cards as a website owner

As a website owner, you can actively use Agent Cards to refine your access policy for AI agents. Instead of blindly allowing or blocking all bots based on their User-Agent string, you can now make informed decisions based on verifiable metadata.

1. For each bot request, fetch the corresponding Agent Card (with caching) and verify the operator.
2. Check the data_usage field: does the agent use your content for training or only for citation?
3. Review the rate_limits declaration: does the agent adhere to reasonable crawl limits?
4. Verify the compliance section: does the agent respect robots.txt and comply with GDPR?
5. Make an automated decision based on this information: full access, limited access or block.

This process can be fully automated. A middleware layer in your web application fetches Agent Cards, caches them and makes access decisions based on your policy configuration. This is similar to how OAuth discovery works, but specifically for the agent identification layer.

The relationship with the A2A Protocol

Agent Cards play a key role in the A2A (Agent-to-Agent) Protocol. When two AI agents communicate with each other, they use each other's Agent Cards to determine whether collaboration is possible and desirable. Agent A reads Agent B's Agent Card, checks the capabilities and intentions, and then decides whether to delegate a task.

In the A2A Protocol, Agent Cards function as both a business card and a CV. They contain not only contact information but also a detailed overview of what the agent can and wants to do. This makes it possible to build an ecosystem of collaborating agents without each agent needing to be individually configured for every possible partner.

Privacy and governance aspects

Agent Cards directly touch on privacy and governance questions that are becoming increasingly urgent as AI agents operate more autonomously. The `data_usage` field in an Agent Card is an explicit statement about how fetched content is used. While such a statement does not in itself provide a legal guarantee, it does create a verifiable commitment that can serve as evidence in disputes.

• The training field indicates whether fetched content is used for model training. This is essential for GDPR compliance.
• The caching_duration field specifies how long data is retained, relevant for the right to be forgotten.
• The attribution field indicates whether the agent applies source attribution when using your content.
• The compliance field lists which regulations the agent complies with (GDPR, CCPA and others).
• The operator details provide a direct point of contact for questions, complaints or deletion requests.

Agent Cards are the passport of AI agents. Just as a passport records identity, nationality and authorizations, an Agent Card documents who the agent is, what it can do and how it behaves.

Key takeaways

• Agent Cards are structured JSON documents through which AI agents publish their identity, capabilities, intentions and data usage.
• They are published at /.well-known/agent-card.json at the bot operator and are machine-readable for automated access control.
• Website owners can use Agent Cards to make informed decisions about which bots receive which access.
• In the A2A Protocol, Agent Cards serve as the discovery mechanism through which agents assess each other's capabilities and trustworthiness.
• The privacy and governance fields in Agent Cards create verifiable commitments about data usage, essential for GDPR compliance.

Frequently asked questions

Transparency is the foundation of trust. Agent Cards make it possible for AI agents to be transparent about who they are and what they want, and that is exactly what the web needs.