agent-cards

Agent Cards

In a Hermes Desktop chat you can show a card instead of describing things in prose: a question with buttons, an approval to confirm before you act, or a task whose progress updates in place. Cards are drawn by Hermes Desktop with the Grokbot Override plugin. Slack, Telegram, the CLI and other channels do not draw them: there, write plain text.

When to show a card

1. A choice or a yes/no confirmation: ask with the built-in clarify tool (it shows a question card).
2. Before anything outward or irreversible (sending, posting, paying, booking, deleting): an approval card, then wait.
3. A job that takes more than about a minute: one task card, kept up to date.
4. Everything else: plain text. Cards only in the Hermes Desktop chat.

1. Question cards: the clarify tool

You need no files for these. Call clarify with one to five questions:

{ "questions": [ { "question": "Which night works?", "choices": ["Thursday", "Friday", "Saturday"] } ] }

• Up to four choices per question (each a short label). The card always adds a row where the user can type their own answer.
• "multi_select": true lets the user pick several.
• Leave out choices to ask an open question.
• Put your suggestion first and the card marks it recommended.

The answer comes back as the tool's result. Continue from it; do not ask the same thing again in text.

2. Approval, task and email cards: a card file plus one line

These cards live in a JSON file in your working directory for this chat. Your reply only points at it.

The card file

Write the file with your file tool at a relative path, by convention cards/<id>.json. The id is c- plus a short slug, unique in this chat (c-7f3a). The whole file must stay under 32 KB.

{
  "schema": "card.v1",
  "kind": "approval",
  "title": "Book the lake cabin",
  "status": { "state": "awaiting-approval" },
  "body": [
    { "type": "kv", "rows": [["Night", "Friday"], ["Guests", "2"], ["Total", "$180"]] }
  ],
  "actions": [
    { "label": "Book it", "style": "primary", "send": "APPROVE c-9b book the cabin" },
    { "label": "Not yet", "send": "HOLD c-9b" }
  ]
}