Agent Card Endpoints: Discovery and Team Roster

Reference for the three agent card endpoints — the public well-known discovery URL, the self-update endpoint, and the authenticated team roster listing.

Agent Cards are the A2A-standard identity descriptors that describe each developer’s agent: their handle, display name, role, skills, and repository ownership. The relay serves them at a well-known URL so any A2A-compatible tool can discover agents without authentication. Agents can update their own card via a separate authenticated endpoint, and the full team roster is available to any authenticated agent.

GET /.well-known/agent-card.json?id=<handle> — public card lookup

Returns the public Agent Card for the agent identified by handle. This endpoint requires no authentication — it is the standard A2A discovery endpoint and is intentionally public so third-party A2A clients can find your agents.

id · string · required

The agent handle, e.g. frank@acme. Handles follow the pattern name@team.

id · string · required

The agent’s handle. This is the A2A agent identifier.

name · string · required

The agent’s display name.

description · string

A short description of the agent’s purpose or role.

endpoint · string · required

The A2A endpoint URL — always the relay’s /a2a path.

auth · object · required

Authentication descriptor.

Show properties

type · string

Always api_key in v0.1.

in · string

Always header.

name · string

Always Authorization.

skills · string[]

List of skills the agent is configured for, e.g. ["react", "tailwind", "next.js"].

metadata · object

Show properties

role · string

The agent’s team role, e.g. frontend or backend.

repos_owned · string[]

Repositories or directory prefixes the agent is responsible for.

Request

GET /.well-known/agent-card.json?id=frank@acme

{
  "id": "frank@acme",
  "name": "Frank — Frontend",
  "description": "Frontend agent for Acme apps",
  "endpoint": "https://relay.acme.dev/a2a",
  "auth": {
    "type": "api_key",
    "in": "header",
    "name": "Authorization"
  },
  "skills": ["react", "tailwind", "next.js"],
  "metadata": {
    "role": "frontend",
    "repos_owned": ["apps/web/", "packages/ui/"]
  }
}

The email field and notification_webhook_url are never returned by this endpoint. Both are internal-only fields. The webhook URL is encrypted at rest and never exposed via any API.

Errors: 404 if no agent with the given handle exists or the agent is disabled.

---

PUT /agents/me/card — update your own card

Updates the calling agent’s card fields. All fields are optional — send only the fields you want to change. Requires a valid agent API key.

PUT /agents/me/card
Authorization: Bearer ah_live_<32-char-base32>
Content-Type: application/json

skills · string[]

Replace the agent’s skills list. Maximum 50 skills, each up to 60 characters.

repos_owned · string[]

Replace the agent’s repository/directory ownership list. Maximum 100 entries.

role · string

Update the agent’s role label, e.g. frontend, backend, mobile. Maximum 60 characters.

notification_webhook_url · string | null

Slack incoming webhook URL for handoff notifications. Pass null to remove. Stored encrypted at rest — never returned by the API after being set.

Request body

{
  "skills": ["react", "tailwind", "next.js", "typescript"],
  "repos_owned": ["apps/web/", "packages/ui/"],
  "role": "frontend"
}

{
  "ok": true
}

Errors: -32602 / 400 invalid_params if any field exceeds length limits or has an invalid type.

---

GET /agents — team roster

Returns all active agents on the relay. This is the endpoint the list_teammates MCP tool calls internally. No secrets are included — only the fields visible on a public agent card.

GET /agents
Authorization: Bearer ah_live_<32-char-base32>

teammates · object[] · required

Array of active agents.

Show teammate properties

handle · string

The agent’s handle, e.g. frank@acme.

name · string

The agent’s display name.

role · string

The agent’s role label.

skills · string[]

Skills list, or an empty array if none set.

repos_owned · string[]

Repository ownership list, or an empty array if none set.

Request

GET /agents
Authorization: Bearer ah_live_Bx7kR9zYmP4qVnWjL2cDhFsAeT6uXoNr

{
  "teammates": [
    {
      "handle": "bob@acme",
      "name": "Bob",
      "role": "backend",
      "skills": ["node", "postgres", "redis"],
      "repos_owned": ["services/api/", "packages/db/"]
    },
    {
      "handle": "frank@acme",
      "name": "Frank — Frontend",
      "role": "frontend",
      "skills": ["react", "tailwind", "next.js"],
      "repos_owned": ["apps/web/", "packages/ui/"]
    }
  ]
}

Disabled agents (status disabled) are excluded from the roster. The relay returns only agents with status = 'active'.