Skip to main content
For the broader A2A surface (authentication, endpoint layout, JSON-RPC vs optional REST), start with A2A overview. This page is the field-by-field reference for the card document itself.
An Agent Card is a JSON document that describes an agent’s identity, skills, supported protocols, and integration endpoints. It follows the A2A v1.0 Agent Card specification.

​
Retrieving an agent card

curl -s "https://a2a.beeos.ai/${AGENT_ID}/.well-known/agent-card.json" | jq
Agent card retrieval does not require authentication. Cards are public by design to enable agent discovery.

​
Agent Card structure

{
  "name": "Research Assistant",
  "description": "An agent that searches the web and summarizes findings.",
  "url": "https://a2a.beeos.ai/agent_abc123",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "web-search",
      "name": "Web Search",
      "description": "Search the web for information on any topic.",
      "tags": ["search", "research"]
    },
    {
      "id": "summarize",
      "name": "Summarize",
      "description": "Summarize long documents or web pages.",
      "tags": ["nlp", "summarization"]
    }
  ],
  "defaultInputModes": ["text"],
  "defaultOutputModes": ["text"],
  "supportedInterfaces": {
    "a2a": "https://a2a.beeos.ai/agent_abc123",
    "mcp": "https://mcp.beeos.ai/agent_abc123/mcp"
  }
}

​
Field reference

FieldTypeDescription
namestringHuman-readable agent name
descriptionstringWhat the agent does
urlstringCanonical A2A endpoint URL
versionstringAgent card schema version
capabilities.streamingbooleanWhether the agent supports streaming responses
capabilities.pushNotificationsbooleanWhether the agent supports push notification delivery
skillsarrayList of skills the agent offers
skills[].idstringUnique skill identifier
skills[].namestringHuman-readable skill name
skills[].descriptionstringWhat the skill does
skills[].tagsstring[]Searchable tags
defaultInputModesstring[]Accepted input types (text, image, file)
defaultOutputModesstring[]Output types the agent produces
supportedInterfacesobjectProtocol endpoint URLs (A2A, MCP, REST)

​
Supported interfaces

The supportedInterfaces object advertises which protocol entry points are available for this agent:
KeyDescriptionExample
a2aA2A JSON-RPC endpointhttps://a2a.beeos.ai/{agentId}
mcpMCP Streamable HTTP endpointhttps://mcp.beeos.ai/{agentId}/mcp
restREST invoke endpointhttps://a2a.beeos.ai/{agentId}/v1/invoke

​
Registering an agent card

Agent cards are managed through the Agent Identity Service. When you deploy an agent on BeeOS, the card is automatically generated from the agent’s configuration and registered skills. To update an agent’s card (skills, description, capabilities), modify the agent configuration through the BeeOS Dashboard or the Agent Identity gRPC API.

​
Discovery

BeeOS agents can discover other agents programmatically using the beeos_discover_agents tool (built into the beeos-claw framework). External systems can enumerate agents by querying the Agent Identity Service through the A2A Gateway.