Skip to content

docs(a2a): document A2A agent on /api-docs/ + add A2A quickstart - #2215

Merged
jung-thomas merged 1 commit into
DEVfrom
docs/a2a-api-docs-and-quickstart
Sep 9, 2026
Merged

jung-thomas merged 1 commit into
DEVfrom
docs/a2a-api-docs-and-quickstart

Conversation

@jung-thomas

Copy link
Copy Markdown
Contributor

Why

The A2A (Agent2Agent) endpoint is a real first-party surface — public Agent Card at `/.well-known/agent-card.json`, JSON-RPC `POST /a2a`, five skills, ORD-registered — but it was only discoverable via `.well-known` and the ORD descriptor. Nothing on the human-facing `/api-docs/` landing page mentioned it, and there was no quickstart like the MCP one.

What

  • `hugo/content/api-docs/_index.md` — new A2A agent section (sibling to MCP server): what it is + how it differs from MCP, public Agent Card discovery, JSON-RPC transport, the five-skill table, the `Tutorial.MCP` client-credentials auth split (public card vs. authenticated calls), an inline `message/send` curl, and a link to the quickstart. Frontmatter `description` updated to mention A2A.
  • `docs/end-users/a2a-quickstart.md` (new) — mirrors `mcp-quickstart.md`: public discovery → internal/partner client-credentials (grounded in the app's XSUAA `cf env` credentials + a note that granting the scope to a separate consumer is a BTP-admin step), `message/send` / `message/stream` (SSE) / `tasks/get` examples, JSON-RPC error-code table (grounded against `srv/lib/a2a/rpc-router.js`), and the `/admin-ui/#joule` config panel.
  • `docs/.vitepress/config.ts` — register the new quickstart in the End Users sidebar (required by `check-docs-sidebar.cjs`).

Docs only — no changes to `agent-card.js`, `rpc-router.js`, or ORD annotations. Deliberately did not invent Joule Studio A2A UI click-paths.

Verification

  • `node scripts/check-docs-sidebar.cjs` → ok (133 pages, 142 links, includes the new page).
  • `npx vitepress build docs` → build complete, no errors.
  • Error-code table (`-32001`→401; `-32601/-32602/-32603`→200; 503 when disabled) verified against `srv/lib/a2a/rpc-router.js`.
  • All referenced files confirmed present.

The A2A (Agent2Agent) endpoint (public Agent Card, POST /a2a JSON-RPC,
five skills, Tutorial.MCP client-credentials) was only discoverable via
.well-known and ORD — nothing on the human-facing /api-docs/ page.

- Add an 'A2A agent' section to hugo/content/api-docs/_index.md, sibling
  to the MCP server section (discovery, transport, skills, auth split).
- Add docs/end-users/a2a-quickstart.md mirroring mcp-quickstart.md:
  public discovery vs internal/partner client-credentials, message/send +
  message/stream + tasks/get examples, JSON-RPC error codes, admin config.
- Register the new quickstart in the VitePress End Users sidebar.
@jung-thomas
jung-thomas merged commit 394fd38 into DEV Sep 9, 2026
4 checks passed
@jung-thomas
jung-thomas deleted the docs/a2a-api-docs-and-quickstart branch September 9, 2026 02:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant