forked from molecule-ai/molecule-core
24fec62d7f
Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1) with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo. Brand: Starfire → Molecule AI. Slug: starfire / agent-molecule → molecule. Env vars: STARFIRE_* → MOLECULE_*. Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform. Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent. DB: agentmolecule → molecule. History truncated; see public repo for prior commits and contributor attribution. Verified green: go test -race ./... (platform), pytest (workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```json
|
|
{
|
|
"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](../product/core-concepts.md) — What an Agent Card is
|
|
- [A2A Protocol](../api-protocol/a2a-protocol.md) — How the card fits into A2A
|
|
- [Workspace Runtime](./workspace-runtime.md) — How the card is generated at startup
|
|
- [Canvas UI](../frontend/canvas.md) — How the card drives node rendering
|