A2A Concentrator Mode

Purpose

This functional area lets an administrator turn ApiMapper into a governed hub for agent-to-agent traffic: a directory of remote A2A agents (internal or third-party) the platform can call on a caller's behalf, with the same credential custody, policy gating, and audit trail the platform already applies to downstream HTTP/SOAP APIs — extended to agents. It answers "who else can our agents talk to, under what rules, and how do those other agents show up to our own callers" without asking any caller to hold a remote agent's credentials directly.

Main Capabilities

• register a remote agent in the Agent Directory, bound to an existing downstream connection and credential
• grant or deny access to a registered agent, optionally scoped to one of its skills, one caller, or one client application
• expose a registered agent two independent ways: direct passthrough (its own dedicated route) and/or composite inclusion (its skills merged into a client's own Agent Card)
• refresh a registered agent's Agent Card on demand or on a recurring schedule
• bind a registered agent's skill(s) into a specific client application's composite Agent Card

How It Works

Registering an agent

Registering an agent does not create a new kind of connection or credential. Instead, a RegisteredAgent row references an existing TargetSystem (the agent's base URL) and TargetAuthenticationProfile (how to authenticate to it) — the same two building blocks every downstream HTTP/SOAP API already uses in this platform. This is deliberate: an agent, from a networking and credential-custody point of view, is just another downstream system the platform calls on a caller's behalf. Reusing TargetSystem/ TargetAuthenticationProfile means a registered agent gets outbound allowlist enforcement, credential storage discipline, and rotation support for free, instead of a parallel mechanism that would need to earn that trust separately.

An agent starts fully closed: reachable by nothing until an administrator explicitly opts it in to direct passthrough, composite inclusion, or both.

Granting access

An AgentAccessPolicy governs whether a given caller may invoke a given registered agent (optionally narrowed to one skill). Each policy row is a set of match dimensions — skill, caller, client application — any of which can be left blank to mean "matches everything for that dimension" — plus an allow/deny decision. When several policies match the same request, the most specific one wins: a policy naming a skill and a caller beats one naming only a skill, which beats one that applies agent-wide. This mirrors how ToolAccessPolicy already governs access to MCP tools, applied to a different resource kind (a registered agent, not a Mapping-derived tool).

Exposing an agent: composite inclusion vs. direct passthrough

A registered agent's skills reach a caller in one of two independent ways, and an administrator can enable either, both, or neither:

• Composite inclusion folds the agent's skill(s) into a client application's own composite Agent Card, indistinguishable in shape from that client's own local, tool-derived skills. A caller talking to the client's card sees one unified skill list — it does not need to know some of those skills are actually served by composing in another registered agent. Which skills get composed in, and for which client, is controlled by a separate binding (an A2aCardComposition row) an administrator authors from the client application's own configuration — not from the agent's — because the binding is really a statement about what a specific client's card should show, not a property of the agent itself.
• Direct passthrough exposes the agent at its own dedicated route, reachable without going through any client's composite card at all — useful when a caller wants to address the registered agent directly rather than through another client's unified surface.

Both paths still go through the same access-policy check and credential resolution before a call reaches the remote agent — exposure controls whether a route to the agent exists at all, not whether an individual call on that route is authorized.

Card refresh

A registered agent's own Agent Card (the metadata it publishes about itself and its skills) is fetched and cached, not queried live on every request — a remote agent being slow or briefly unreachable should not block every caller who wants to see what it offers. An administrator can trigger an immediate, single-agent refresh on demand, and a scheduled sweep refreshes every active registered agent across every tenant on a recurring interval so the cache does not go stale indefinitely on its own. If a refresh fails, the previously cached card is left untouched — a stale card that still describes the agent reasonably well is preferable to no card at all. The cached card is treated purely as display/composition content, never as something that drives an authorization or authentication decision; those decisions always come from the platform's own TargetAuthenticationProfile and AgentAccessPolicy configuration.

Functional Value

This gives an organization one governed place to see and control every agent-to-agent relationship its own agents participate in — the same posture the platform already gives administrators for its own MCP tool catalog — instead of individual integrations quietly holding their own credentials and bypassing every control this platform otherwise enforces.