AI API Mapper
Technical walkthrough →
Technical walkthrough →
/ docs · functional specification

The full platform
functional reference.

Every functional area of AI API Mapper documented at implementation depth so architects, security reviewers, and platform engineers can evaluate the product with real technical context.

A2A · Agent Card discovery
On this page

A2A Agent Card Discovery

Purpose

This functional area lets an A2A client discover what a tenant's client application can do — its identity, security requirements, and callable skills — before sending any message.

Main Capabilities

  • publish a public, unauthenticated Agent Card summarizing available skills
  • publish an authenticated extended card (Phase 1: identical content to the public card)
  • reshape the same authorization-filtered tool catalog MCP's tools/list already exposes into A2A skills
  • declare the platform's actual inbound security schemes (JWT bearer, API key) rather than inventing new ones

How Discovery Works

An Agent Card is generated per (tenantId, clientId) — the same scoping axis every other Runtime and SDK surface already uses, not a separately-addressed persona. There is no protocol-level way for a caller to discover a (tenantId, clientId) pair it doesn't already know; the same way clientId is already handed out today as SDK configuration, not enumerated.

The card's skills[] is built by taking the exact tool catalog RuntimeToolCatalogService already computes — the same authorization-filtered, tenant/client-scoped list tools/list returns — and reshaping each entry's identity, description, and modes into A2A's skill shape. Nothing about tool exposure, toolset scoping, or authorization filtering is recomputed or duplicated; only the wire-shape mapping is new. A tool visible via MCP is automatically visible via A2A under the same effective name, and a caller denied a tool under MCP's authorization is denied the same skill under A2A — there is one authorization decision, viewed through two protocols.

Public Card vs Authenticated Extended Card

  • Public card (GET /.well-known/agent-card.json, unauthenticated): omits anything sensitive — no internal identifiers beyond the stable tool name, no per-tenant policy detail.
  • Authenticated extended card (GetExtendedAgentCard over JSON-RPC): requires the same bearer/API-key authentication as every other Runtime endpoint. In Phase 1 its content is identical to the public card — the authorization filter already happened when the catalog was built, so there is nothing further to reveal once a caller has authenticated.

Security Scheme Declaration

The card's declared securitySchemes reflect what the platform's inbound authentication middleware already enforces — JWT bearer via a trusted identity provider, or an API key — never something the platform doesn't actually support. No new inbound authentication mechanism is introduced by A2A; the card simply describes the two schemes that already gate every other Runtime endpoint.

Skill Identity Parity With MCP

A skill's id/name is the tool's effective name, the same identity value MCP's tools/list would produce for the same tool. This is intentional: a client that talks to a tenant's tools over both protocols (for example, during a migration from MCP-only to A2A-aware tooling) sees the same tool identities either way, so governance/audit records and any external tooling keyed on tool name stay consistent across protocols.

Functional Value

This area lets an A2A-compliant client — an orchestrator, another agent — discover a tenant's governed capabilities without a human first configuring a bespoke integration, the same value MCP's discovery surface already provides, extended to a second class of caller.

PreviousOverviewA2ANextTask lifecycleA2A