molecule-core/docs/agent-runtime/agent-card.md

Agent Card

Every workspace publishes an Agent Card at /.well-known/agent-card.json. This is a standard A2A document that describes the workspace's identity, capabilities, and how to communicate with it.

Example

{
  "name": "Reno Stars SEO Agent",
  "description": "Bilingual EN/ZH SEO page builder for Vancouver renovation companies",
  "version": "1.2.0",
  "url": "https://seo-agent.reno-stars.com",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true
  },
  "defaultInputModes": ["text/plain", "application/json"],
  "defaultOutputModes": ["text/plain", "application/json", "text/html"],
  "skills": [
    {
      "id": "generate_seo_page",
      "name": "Generate SEO Landing Page",
      "description": "Creates a bilingual EN/ZH Next.js page targeting a renovation keyword",
      "tags": ["seo", "bilingual", "nextjs"],
      "examples": ["Generate a page targeting 'kitchen renovation Vancouver'"]
    }
  ],
  "supportedInterfaces": [
    { "protocol": "JSONRPC", "url": "https://seo-agent.reno-stars.com/a2a" }
  ]
}

How the Agent Card Is Used

By the Platform

• The platform reads the card when a workspace registers
• Stores the full card in Postgres (workspaces.agent_card JSONB column)
• Caches the workspace URL in Redis for fast resolution

By the Canvas

• The canvas renders node UI directly from the card
• Node title comes from name
• Skill badges come from skills[].name
• Input/output port types come from defaultInputModes / defaultOutputModes

By Peer Workspaces (Automatic Skill Injection)

When a workspace builds its system prompt, it pulls Agent Cards from all reachable peer workspaces (siblings, children, parent) and appends their skill descriptions. This way a calling workspace (e.g. Business Core) knows what it can ask the SEO agent to do without any manual wiring.

The mechanism:

1. On startup, the workspace queries the platform for peer Agent Cards via GET /registry/:id/peers
2. Skill descriptions from those cards are appended to the agent's system prompt
3. When a peer updates its card (AGENT_CARD_UPDATED event), the workspace rebuilds its system prompt automatically

This means adding a new skill to a workspace makes it immediately available to all reachable peers — no manual wiring, no restarts.

Lifecycle

1. Workspace container starts
2. Agent Card is generated from the workspace config
3. A2A server publishes it at /.well-known/agent-card.json
4. Workspace sends POST /registry/register with the card
5. Platform stores the card in Postgres
6. Canvas reads the card and renders the node

Live Updates

When a workspace's skills change at runtime:

1. Workspace rescans skills folder, rebuilds Agent Card
2. Workspace sends POST /registry/update-card with the new card
3. Platform stores the updated card, writes AGENT_CARD_UPDATED event
4. Platform broadcasts via WebSocket to all subscribers — both canvas clients and peer workspaces

Both canvas clients and workspace agents subscribe to the same platform WebSocket at /ws. The platform filters events server-side using X-Workspace-ID — each workspace only receives events about workspaces it can communicate with (via CanCommunicate()). Canvas clients receive all events (no workspace ID header).

When a peer workspace receives AGENT_CARD_UPDATED, it rebuilds its system prompt automatically. When the canvas receives it, it updates the node's skill badges.

Related Docs

• Core Concepts — What an Agent Card is
• A2A Protocol — How the card fits into A2A
• Workspace Runtime — How the card is generated at startup
• Canvas UI — How the card drives node rendering