# Agent Cards

Machine-readable descriptions of an agent's identity, capabilities and interfaces, so other agents can discover and invoke it.

**Rests on:** Agent Communication Protocols

**Leads to:** MCP Connectors

*AI Agents · AI Agents*


## Why learn this

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.


## The intuition

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.


## An analogy

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.


## Definition

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.


## How it connects

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.


## From scratch, in Python

```python
Let's build a simple agent card in Python. First, we need a dictionary to hold the card's details. In Python, a dictionary is a way to store key-value pairs; you can look up a value by its key, like a real dictionary. Here is an example:

    card = {
        "name": "WeatherAgent",
        "description": "Provides current weather forecasts for any city.",
        "capabilities": ["get_weather"],
        "inputs": {"city": "string"},
        "outputs": {"forecast": "string"}
    }

Now, to make it more useful, let's write a function that can read this card and tell us if it can handle a specific capability. A function is a reusable block of code that does a specific task. We'll define a function called `can_do` that takes a capability name and returns True if the card lists it, False otherwise.

    def can_do(card, capability):
        if capability in card["capabilities"]:
            return True
        else:
            return False

Let's use it:

    result = can_do(card, "get_weather")
    print(result)  # prints True

We can also add a simple way to invoke the agent based on the card. Let's assume the agent is a function itself. Here is the full example:

    def weather_agent(city):
        return "Sunny, 25C"  # a stub

    card["agent_func"] = weather_agent

    def invoke_agent(card, inputs):
        if not can_do(card, "get_weather"):
            return "Capability not found"
        return card["agent_func"](inputs["city"])

    print(invoke_agent(card, {"city": "Mumbai"}))  # prints Sunny, 25C

This shows the essence: the card tells you how to call the agent (the function) and what to pass (the inputs).
```


## The same thing, with a framework

```python
In a real agent framework, you might use a schema-based approach. For example, in LangChain or AutoGen, you might define an agent with a name, description, and functions, and they automatically generate a card. Underneath, they still Python dictionaries and functions. Here is a pseudo-code example:

    from some_agent_framework import Agent

    agent = Agent(
        name="WeatherAgent",
        description="Provides current weather",
        functions=[get_weather_function]
    )

    # The framework automatically creates a card from this, using reflection
    # to inspect the function signature and docs.

This hides the card creation, but it is doing the same thing: serializing the agent's metadata into a machine-readable format.
```


## What the code does

First, we define a dictionary `card` with keys like 'name', 'capabilities', etc. A dictionary is a container that holds pairs of keys and values; you can access a value with `card["name"]` which gives "WeatherAgent". The `capabilities` value is a list (a list is an ordered collection) containing a single string. The function `can_do` takes the card and a capability string; it checks if the capability is in the list using the `in` operator, which tests membership. This is a simple loop over the list items internally. Then we define a separate function `weather_agent` that simulates the actual work; in practice, this would be the agent's backend, maybe calling a weather API. We attach this function to the card dictionary under the key 'agent_func', showing that the card can also carry a reference to the 'executor'. Finally, the `invoke_agent` function uses the card to decide if it can handle the request, and if so, calls the stored function with the input. The card acts as both a description and a pointer to the implementation.


## Common misconceptions

**Agent Cards are just documentation** — The card is only for humans to read, like a README file.

Agent cards are machine-readable and actively used by other agents to make decisions. They are not passive text; they are structured data that triggers actions. In fact: Agent cards are executable descriptions: they specify the input/output schema and capabilities, and they are parsed and used by code.

**Cards are static and never change** — Once an agent card is written, it never updates.

Agents can be updated with new capabilities, and the card should reflect that to stay accurate. Also, context can change (e.g., service endpoints). In fact: Agent cards should be versioned and updated dynamically to reflect the agent's current state.

**A card is the agent itself** — The card defines the complete behavior, so viewing the card means you know what the agent does internally.

The card is only the interface contract; the internal logic, weights, and state are hidden. It tells you what to call and what to expect, but not how it works. In fact: The card is a public interface; the agent's implementation is private.

**If the card says it can do it, it can** — Trusting the card is enough; if it lists a capability, the agent must handle it.

Cards can be outdated, incorrect, or maliciously misleading. Agents may claim capabilities they do not have. In fact: Discovery must be accompanied by verification and authentication (e.g., checking a digital signature or a trusted registry).

**Cards are only for other agents** — Humans don't need to see the card.

Even for human developers, the card is a specification for integrating with the agent. It's also used in UIs for configuration. In fact: Cards serve both human and machine consumers; they are the source of truth for integration docs.


## In short

An Agent Card is a structured, machine-readable description of what an agent is, what it can do, and how to call it. It enables capability discovery, so agents can find each other without hardcoded links. It must be trusted and authenticated, because discovery alone is not safety. Remember: the card is the directory entry, not the agent's brain.


## Where this is used

Agent Cards are the backbone of modern agentic AI systems. In large language model (LLM) applications, an agent is not just a model; it is a loop that includes tools. When an LLM needs to perform an action like looking up a database or sending an email, it does not hardcode the tool call; it consults a list of available tools, each described by an agent card. For example, in OpenAI's function calling, each function's JSON schema is an agent card: it lists the name, description, and parameters. The LLM reads this card and decides if it should call the function. This is exactly the discovery process. In small models running on devices (like a phone or laptop), agent cards are even more critical because resources are tight. Instead of loading every possible skill into memory, the device can read a lightweight card to see if the agent has the capability to, say, handle a voice command. If not, it can defer to a cloud agent. In retrieval-augmented generation (RAG), agent cards are used for routing: a system might have multiple specialized agents, each with a card describing its domain (e.g., 'financial documents', 'medical research'). When a query comes in, the system uses a retriever to match the query against the card descriptions, picks the most relevant agent, and then invokes it using the card's interface. This allows scaling to many agents without hardcoding which query goes where. In agentic systems that plan and call tools, the planner operates on the cards: it sees a list of possible actions (each from a card), and it simulates the outcome of each action based on the card's description, choosing the best one. The mechanism is: the card gives a response in a consistent format, so the planner can reason over the options. In everyday applied machine learning, such as recommendation systems or forecasting, agent cards are used internally to divide work. For example, a recommendation engine might have separate agents for 'new users', 'popular items', etc., each with a card. The main system uses the cards to decide which agent to call based on the user's context. Developers using frameworks like LangChain, AutoGen, or CrewAI write code that declares the card (often via decorators or class definitions) and the framework handles the discovery. What breaks when done badly: if the card is inaccurate (e.g., the capability list is wrong), other agents may call it erroneously, leading to errors. If the card does not specify the interface clearly (e.g., data formats), the calling agent may send invalid inputs. If there is no authentication, a malicious agent could impersonate another and cause security issues. So, production systems must validate cards and add digital signatures.


---

Read this on the web: https://basavapurushottam.com/learn-ai/agent-cards
