# The Connect Agent Card

The card is served at `https://connectbyjbrh.com/.well-known/agent-card.json`, declares A2A protocol version `1.0.0`, points at the JSON-RPC endpoint `/a2a`, and advertises five documentation skills. It also declares what is not there: no streaming, no push notifications, empty security schemes and `supportsAuthenticatedExtendedCard: false`.

- **Status:** Available
- **Audience:** developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/developers/agent-card/

## Fetching it

```http
GET /.well-known/agent-card.json HTTP/1.1
Host: connectbyjbrh.com

200 OK
Content-Type: application/json
Cache-Control: public, max-age=300
Access-Control-Allow-Origin: *
```

The permissive CORS header is deliberate: a well-known document another agent fetches from a browser is useless if the browser refuses it, and nothing in the card is private. The five-minute cache reflects how often it changes, which is on a deploy.

An earlier draft of the specification used `/.well-known/agent.json`. That path also answers, with the same body plus a `Link` header naming `/.well-known/agent-card.json` as canonical, so an agent built against the draft finds Connect rather than concluding it does not speak A2A.

## Every field

| Field | Value | What it tells a caller |
|---|---|---|
| `protocolVersion` | `1.0.0` | Which A2A revision the card and endpoint follow |
| `name` | Connect by JBRH | The agent's name; never the retired product name |
| `description` | One paragraph | What Connect is, ending with the sentence that this card exposes documentation skills only |
| `url` | `https://connectbyjbrh.com/a2a` | Where to send `message/send` |
| `preferredTransport` | `JSONRPC` | JSON-RPC over HTTP, not gRPC or REST |
| `provider` | JBRH Digital Solutions | Who operates the agent, with a URL |
| `version` | The product version | Moves with the product, so a cached card can be compared |
| `documentationUrl` | `/developers/` | Where a human goes next |
| `iconUrl` | An SVG mark | For a directory listing the agent |
| `capabilities` | `streaming: false`, `pushNotifications: false`, `stateTransitionHistory: false` | Three explicit refusals — do not open a stream, do not register a callback, do not expect task history |
| `defaultInputModes` | `text/plain` | Send text; there is no audio or file input here |
| `defaultOutputModes` | `text/plain`, `text/markdown`, `application/json` | Replies may be prose, Markdown or structured data |
| `skills` | Five entries | Each with an id, name, description, tags, examples and its own modes |
| `securitySchemes` | `{}` | No scheme is defined, because no call needs a credential |
| `security` | `[]` | No requirement applies to any operation |
| `supportsAuthenticatedExtendedCard` | `false` | There is no private card with more skills in it |
| `additionalInterfaces` | One JSON-RPC entry | The same endpoint, declared in the list form some clients read |

## The five skills

**`explain-connect`** — Answer a question about what Connect is and does, from the published documentation, including what it deliberately does not do.
**`search-connect-docs`** — Search the public documentation and return the pages that answer a question, with canonical URLs and capability status.
**`describe-capability`** — Report the current status of a named capability — available, operator-only, foundation, or not yet — with the page that says so.
**`explain-workflow`** — Walk one workflow stage by stage, from the trigger to the audit entry, including what can fail at each stage.
**`explain-integration`** — Explain how Connect uses a protocol or integrates with a provider, and state plainly where it does not.

Each skill carries example questions in the card itself, which is what a directory or a routing agent reads to decide whether Connect is worth asking. The examples were chosen to include the awkward ones — *Is call recording available?*, *Does Connect guess prospect email addresses?* — because a card that only advertises the flattering questions misleads the agent reading it.

## Reading the absences

Three fields are more informative than the skills. `streaming: false` means a `message/stream` call is refused rather than degraded. Empty `securitySchemes` and `security` mean there is nothing to authenticate with, not that authentication is optional. And `supportsAuthenticatedExtendedCard: false` means the public card is the whole advertised surface — there is no richer card behind a credential, and asking for one returns an error saying so.

The file on disk is authoritative and is generated from the same registry as the rest of the documentation, so the card cannot drift from what the pages say. If the generated file is missing — a checkout that has not run the build — the route still answers with a minimal card that says it is a fallback, rather than returning `404` from a well-known URI that other agents probe.

## Questions

### Can I cache the card?

Yes, and the response asks you to for five minutes. Compare the `version` field to notice a change; it moves with the product version rather than on an unrelated schedule.

### Why does the card list no security schemes at all?

Because every skill reads public documentation. An empty scheme list is the accurate declaration: a caller needs no credential, and there is no scope to request. See [Interoperating over A2A](/developers/a2a-integration/).

### Is there a second card for partners?

No. `supportsAuthenticatedExtendedCard` is `false` and the two methods that would fetch an extended card return the A2A error `-32004` with a sentence saying the public card is the whole advertised surface.

## Related

- [Interoperating over A2A](https://connectbyjbrh.com/developers/a2a-integration/)
- [Developers and AI agents](https://connectbyjbrh.com/developers/)
- [The Connect MCP server](https://connectbyjbrh.com/developers/mcp-server/)
- [The A2A Agent Card](https://connectbyjbrh.com/docs/protocols/agent-card/)
- [A2A — the Agent2Agent protocol](https://connectbyjbrh.com/docs/protocols/a2a/)
- [A2A agent discovery](https://connectbyjbrh.com/docs/protocols/a2a-discovery/)
- [Well-known URIs](https://connectbyjbrh.com/docs/protocols/well-known-uris/)

## What this page is based on

- `webapp/.well-known/agent-card.json`
- `backend/app/a2a_server.py` — the card routes and the fallback card
- A2A specification 1.0.0 — https://a2a-protocol.org/latest/specification/