🧩 Agent Cards
A Documentation Standard for Operational AI Agents
🧠 Overview
Agent Cards provide a lightweight, structured standard for documenting AI agents — covering their behavioral attributes, memory design, tool integrations, communication protocols, and governance metadata.
This work extends the model-centric transparency artifacts (Model Cards, FactSheets) into the agentic AI era, supporting reproducibility, comparability, and governance of autonomous and multi-agent systems.
📘 Accepted at: MICAI 2025 Workshops
📚 Series: Lecture Notes in Artificial Intelligence (LNAI)
🏢 Publisher: Springer Nature Switzerland AG
Table 1 Proposed Agent Card Template
| Section | Description |
|---|---|
| Agent version | Semantic version of the agent release (e.g., 1.2). |
| Agent Name | Identifier of the agent. |
| Agent Role(s) | Planner, Executor, Critic, Orchestrator (list specific roles). |
| Inputs | Text files, APIs, structured and unstructured data. |
| Outputs | API responses or text. |
| Memory | Short-term: current turn/context window profile; Long-term. |
| Tools/Functions | Capabilities the agent can invoke beyond its core LLM, such as calculators, retrieval modules, external APIs, internal spreadsheets, or domain-specific tools. Document the type of tool, its intended purpose, and how it extends the agent’s abilities. |
| Communication | Human interface (chat/UI); agent-to-agent protocols; message schemas/versions; handoff/approval policies. |
| Monitoring | Logged metrics (latency, token usage, error rate); trace IDs; inference profile/feature flags; SLOs and alert routes. |
| Governance | Safety filters/guardrails; PII/PHI handling; data retention and access control; approvals and audit checkpoints. |
| Versioning | Release tag/date; prompt hash; toolchain/SBOM; external dependency versions; overall reproducibility hash. |
| Known Limitations | Current scope boundaries; partial automation notes; known brittleness or non-determinism sources (e.g., upstream API variability). |
| Evaluation | Benchmarks/KPIs (e.g., RAG quality, long-context stress); calibration/abstention policy; evaluation datasets/snapshots; last run date and results. |
YAML for LLM
agent cards for ai agent
agentcard: 1.0
meta:
name: TaxBot
version: 0.7.3
owner: Tax Operations — Data/AI
last_updated: 2025-10-10
purpose:
objective: "Assist with personal and business tax queries, document intake, and filing prep with traceable, policy‑compliant outputs"
users: [Tax Analyst, Accountant, Taxpayer]
interface:
inputs: [question, PDF, XML, XLSX]
outputs: [answer, citation_list, filing_checklist, action_proposal]
tools:
- name: tax_rules_db
scope: read-only
eligibility: requires jurisdiction and tax_year
- name: parse_tax_pdf
leakage_guard: no final filing decisions
- name: sat_portal_client
scope: read-only
eligibility: authenticated user session
autonomy:
allowed_actions: [draft_client_email, create_case_ticket]
requires_approval_for: [submit_return, modify_client_profile]
memory:
persistent: session_summaries (TTL: 30d)
pii: masked_at_ingest; encryption_at_rest: AES256
policies:
deference_gate: gamma=-3.0 until verify+readiness>=tau
prohibited_content: [store raw IDs, off‑policy advice]
evaluation:
kpis: {first_response_time_p50: "<30s", hallucination_rate: "<1%", citation_coverage: ">=95%"}
red_team: [prompt_injection, refund_scam, identity_theft_vector]
ops:
envs: [dev, staging, prod]
logging: structured_traces to s3://agent-logs
rollback: blue/green with canaries
risks:
- name: pii_leakage
mitigation: strict scopes + PII scrubbing + DLP scanners
⚙️ Installation
pip install agentcard
For testing:
pip install -i https://test.pypi.org/simple/ agentcard
🚀 Quick Start
from agentcard import AgentCard
card = AgentCard.from_yaml("example.yaml")
print(card.name) # TaxAdvisorBot
card.register_to_phoenix()
Output
Registered agent agent-001 with Phoenix observability.
📖 Citation
If you use Agent Cards in your research, please cite:
Urteaga-Reyesvera, J. C., & Lopez Murphy, J. J. (2025).
Agent Cards: A Documentation Standard for Operational AI Agents.
In MICAI 2025 Workshops (Lecture Notes in Artificial Intelligence).
Springer Nature Switzerland AG. (Forthcoming)
https://github.com/CarlosUrteaga/AgentCard
BibTeX
@inproceedings{urteaga2025agentcards,
author = {Urteaga-Reyesvera, J. Carlos and Lopez Murphy, Juan Jose},
title = {Agent Cards: A Documentation Standard for Operational AI Agents},
booktitle = {Proceedings of the MICAI 2025 Workshops},
series = {Lecture Notes in Artificial Intelligence},
publisher = {Springer Nature Switzerland AG},
note = {Forthcoming},
year = {2025},
url = {https://github.com/CarlosUrteaga/AgentCard}
}
Metadata
Release files for agentcard 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentcard-0.1.1.tar.gz | 5.4 kB | Without provenance | Details for agentcard-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentcard-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agentcard-0.1.1-py3-none-any.whl |
Total release size: 11.0 kB
Release files / agentcard-0.1.1.tar.gz
| Download URL | agentcard-0.1.1.tar.gz |
|---|---|
| Size | 5.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1b1b3c49c46c14b020bfa1483ded92409093b81418f525ead4fb6726fe96d1ff
|
|
BLAKE2b-256 checksum How to use checksums |
8fcc6fc2d5d7b91bf5562a445c64b847514dbbc4a1fa3a45d36621391e46a0eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Release files / agentcard-0.1.1-py3-none-any.whl
| Download URL | agentcard-0.1.1-py3-none-any.whl |
|---|---|
| Size | 5.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7607539e17e237041db2dda50b217e3854fd6d7383cb1d1c8ff09f43e3b8146d
|
|
BLAKE2b-256 checksum How to use checksums |
188383dc0db4bd9374b749d3614a0b50a55683d9a604013be6a4aad36e780d3c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Security for agentcard 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.