Getting Started

This guide walks you from zero to a running Mentionable agent reachable at @<name>@<your-domain> over ActivityPub (Mastodon/Fediverse), A2A (Google Agent-to-Agent), and Email.

Prerequisites

• A Vercel account (free tier is enough to start)
• A Gmail account for the email transport
• A Google Cloud project for OAuth and Pub/Sub (see Operator Guide)
• A domain pointed at Vercel (optional for testing, required for production federation)

Deploy in 5 minutes

Vercel’s one-click flow does not work cleanly for monorepo root-directory setups, so we use the vercel CLI instead — it is three commands:

# 1. Fork and clone the repository.
gh repo fork planetarium/mentionable --clone=true --remote=false
cd mentionable/examples/llm-agent-vercel

# 2. Link to Vercel and create the project.
pnpm dlx vercel@latest link --yes

# 3. Provision Neon Postgres (Vercel Marketplace integration):
#    open https://vercel.com/<your-team>/<project>/stores,
#    click "Create Database" → "Neon", accept defaults.
#    Vercel writes POSTGRES_URL into the project env automatically.

# 4. Set the three required non-database env vars.
pnpm dlx vercel@latest env add CONFIG_SECRET production   # openssl rand -hex 32
pnpm dlx vercel@latest env add CRON_SECRET production     # openssl rand -hex 32
pnpm dlx vercel@latest env add DOMAIN production          # e.g. agent.example.com

# 5. Bootstrap the Postgres schema (run once per fresh database).
vercel env pull .env.local
psql "$POSTGRES_URL" -f sql/init.sql

# 6. Deploy.
pnpm dlx vercel@latest --prod

After the deploy completes, attach your custom domain under Settings → Domains in the Vercel dashboard.

Configure your agent via /setup

Visit https://<your-domain>/setup. On first visit no auth is required. Fill in:

• LLM API key — an Anthropic key (sk-ant-...) or Vercel AI Gateway key
• System prompt — describe what your agent does
• Click Connect Gmail and complete the OAuth flow

After submitting, an admin token is shown once — save it. Every subsequent /setup visit requires it.

Your agent is now live at @<name>@<your-domain>.

Test with A2A

Send a message to your agent using the A2A JSON-RPC protocol:

curl -X POST https://<your-domain>/a2a/<name> \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Hello, agent!"}]
      }
    }
  }'

The agent replies with a JSON-RPC response containing the LLM’s answer.

Test over Email

Send an email to the Gmail address you configured during /setup. A reply lands within a few seconds.

Test over ActivityPub

Mention @<name>@<your-domain> from any Mastodon (or Fediverse) account. A reply toot appears shortly after.

What’s next

• Operator Guide — Gmail OAuth, custom domains, ActivityPub federation, env vars reference
• Agent Interface — implement your own Agent
• Normalized Message guide — understand the common message shape
• Transport Module guide — add new transports