Agent Cards

This is the first step toward building AI agents that can work together without you wiring them together by hand. Once you understand Agent Cards, you will be able to grasp how agents discover each other's abilities, how multi-agent systems coordinate without hardcoded links, and why trust matters when one agent calls another. This unlocks: Agent Communication Protocols, Agent Executors, and the Agent Loop itself.

Imagine you run a small company. You have a delivery driver, an accountant, and a customer service representative. They all work for you, but they don't know each other. To get a job done, you have to tell each one separately what to do, when to do it, and how to hand off the result. That is 'hardcoded integration' — you are the central planner, and every link is something you personally arranged. Now imagine instead that each employee carries a card in their pocket. The card says: 'My name is Priya. I am a delivery driver. I can transport packages within the city. To hire me, send a message with the pickup address, drop-off address, and time. I will reply with a confirmation and a tracking number.' Now, when the customer service rep needs a package delivered, they don't come to you. They look at the delivery driver's card, see that it matches their need, and directly send a message. The rep can also check the accountant's card to see if they can handle the billing. You are no longer the middleman. This is exactly what an Agent Card is for AI agents. Instead of a human, an AI agent (like a chatbot or a smart assistant) has a card that describes itself. The card is not written in English for people to read; it is written in a machine-readable format, like JSON, so that other agents can automatically understand it. The card says: who am I, what can I do, how do you talk to me (what inputs do I expect, what outputs do I give), and maybe some extra details like what physical location I cover or what security level I have. When another agent or a system needs a service, it searches through a directory of these cards, finds the one that matches its needs, and then uses the instructions on the card to make a call. This is called capability discovery. The card is the directory entry that makes discovery possible without hardcoding.

Think of a professional directory at a large hospital. There is a big binder in the reception office listing every doctor, their specialty, their office hours, their phone extension, and what they need from a referral. When a general physician discovers a patient has a heart issue, they do not know which cardiologist is available; they flip through the directory, find a cardiologist who is on duty and has the right expertise, and then make a call using the extension listed. The directory card is the Agent Card. It is machine-readable in the sense that the doctor can quickly parse it (though in the real world, it is human-reading, but the principle is the same). However, the analogy breaks down a little: in the hospital, the directory is maintained by a human, but in AI, the agent card is maintained by the agent itself or its creator, and the directory might be a decentralized registry. Also, the hospital directory only has one kind of card (doctor), but in AI, agent cards can be for any type of service: a weather agent, a calendar agent, a code interpreter agent. Another break: the doctor always trusts the directory entry, but in AI, you cannot always trust that the card is accurate. A malicious agent could say it can do something it cannot, so trust and authentication are needed alongside discovery. The card is only the address and the menu; it does not guarantee the kitchen is good.

An Agent Card is a machine-readable description of an agent's identity, capabilities, and interfaces, designed so that other agents can discover it, understand what it offers, and know exactly how to invoke it.

You have no prior notes on AI agents, but this concept is the groundwork. It sits at the intersection of how agents find each other (discovery) and how they communicate after the handshake. It relates directly to Agent Communication Protocols (the rules of conversation after the card is read) and Agent Executors (the runtime that actually processes the requests based on the card's interface specifications). It is also a foundation for Multi-Agent Systems, where many agents with different cards cooperate. Think of the card as the 'profile' that makes the protocol useful.