How to Write an AI Agent Card: Template and Fields

What an AI Agent Card Is

An AI agent card is a structured metadata document that describes an agent’s identity, purpose, capabilities, and access requirements before it interacts with other systems, agents, or users. Rather than free-text documentation, current agent interoperability specifications, including Google’s Agent2Agent (A2A) protocol, define the agent card as a JSON document that a client or orchestrator can retrieve and parse programmatically.

Anthropic’s Model Context Protocol (MCP) applies a related pattern at the tool level, requiring each tool an agent can invoke to be declared with a name, description, and structured input schema before it can be called. For platform engineering teams, the practical implication is that an agent card is not a README or a design document. It is a machine-readable artifact that a runtime environment can use to make access decisions, which is why its field structure matters more than its prose.

Agent Card at a Glance

A useful internal template groups fields into four blocks that can be reviewed and updated independently.

Core Fields an Agent Card Template Should Include

• Identity: stable name, unique agent ID, owning team or individual, and version identifier.
• Capabilities: declared skills or tools, each with clear input and output schemas where applicable.
• Permissions: authentication scheme and the access scope the agent is authorized to use.
• Provenance: build source, deployment environment, and the team accountable for the agent.

How Agent Card Fields Map to Runtime Enforcement

The value of a well-structured agent card is realized only when a runtime environment actively checks agent behavior against it. A capability or skills list is not simply documentation of intent; it can serve as the authoritative scope that a policy engine uses to permit or deny individual tool calls, which is the basis for least-privilege enforcement rather than blanket agent trust.

Because current specifications keep authentication data separate from capability declarations, an internal agent card template should preserve the same separation: an identity and permissions block, and a capabilities and tools block, that can be updated independently as access requirements change without touching the description of what the agent does.

This distinction also supports incident investigation. When an agent’s observed behavior diverges from its declared capabilities or tool scope, that discrepancy is a primary signal worth logging and reviewing, since it indicates either a misconfigured card or an agent operating outside its intended boundaries. Trussed AI’s runtime governance and agent identity and permissions capabilities are designed to evaluate agent activity against declared scope at execution time and support audit logging of any deviation, rather than treating the card as a static reference checked only at onboarding.

Governance and Audit Considerations

Neither A2A nor MCP, as currently published, mandates a standardized provenance field. Enterprises deploying multi-agent systems need to fill that gap internally if audit and incident-response processes require tracing an agent back to its build source, owning team, or deployment environment.

This matters in tool-calling environments, where an agent’s runtime behavior is the result of a chain of tool invocations that may span multiple systems. An agent card that records provenance alongside declared capabilities gives incident responders a clear starting point: what the agent was authorized to do, what it was permitted to access, and who is accountable for it.

Because public agent protocols are still under active revision and inconsistent in field naming across specifications, teams should document their own schema decisions independently, so the organization’s audit trail does not depend on an external specification remaining stable.

Frequently asked questions