Skip to content

A2A and A2UI

Memory exposes an Agent2Agent (A2A) agent interface that other agents and agent platforms can discover and call, and it emits A2UI surfaces so those callers can render agent output as UI rather than prose.

This page is the compatibility contract: what version of each protocol the server implements, which transports and catalogs it advertises, and what it does not support. Read it before pointing a registry, a host, or another agent at this server.

Surface Implemented Notes
A2A protocol v1.0 only All other versions are rejected with VERSION_NOT_SUPPORTED
A2A transport HTTP+JSON application/a2a+json; no gRPC, no JSON-RPC
A2A streaming Yes POST /message:stream (SSE), POST /tasks/{id}:subscribe
A2A push notifications No Every push-notification route answers PUSH_NOTIFICATION_NOT_SUPPORTED
A2A extended card Yes Per-project skills; requires agents:read
A2UI protocol v0.9.1 Encoded in the extension URI and stamped on each surface envelope that carries a version (the deleteSurface teardown frame omits it)
A2UI catalogs memory-basic Custom catalog; see A2UI catalogs
A2UI integration A2UI-over-A2A card extension Surfaces stream as application/a2ui+json data parts
Auth Bearer project API token (emt_…) The card declares this bearer scheme only — no OAuth2/OIDC scheme; the OAuth flow issues no agents:* scope
Tenant selection X-Project-ID header, or a project-scoped token Never path-scoped

The A2A routes are served by the API host (APP_URL), which is a different host from the web UI (WEB_UI_URL). Card-documented asset URLs therefore point at the web UI; card-documented endpoints point here.

Terminal window
curl https://api.memory.emergent-company.ai/.well-known/agent-card.json

Unauthenticated. Returns the static, tenant-blind platform card: name, description, provider, the advertised interface, the A2UI and agent-metadata extensions, and a static skills directory describing what the platform does. It never contains project, org, or tenant identifiers.

Terminal window
curl https://api.memory.emergent-company.ai/extendedAgentCard \
-H "Authorization: Bearer $MEMORY_TOKEN" \
-H "X-Project-ID: $PROJECT_ID"

Requires agents:read. Returns the same card with skills derived from the project’s external-visibility agent definitions, one skill per agent, plus the bearer security declaration. This is the card to use when you need to know which agents a caller can actually invoke.

Every route except the global card requires a Bearer credential carrying the route’s scope. This page documents the project API token (emt_…), which is the supported integration credential; its scope is checked against the scopes list the token was minted with.

Route Scope
POST /message:send agents:write
POST /message:stream agents:write
GET /tasks, GET /tasks/{id} agents:read
POST /tasks/{id}:cancel agents:write
POST /tasks/{id}:subscribe agents:read
GET /extendedAgentCard agents:read

The same scope is enforced for signed-in sessions (for example a memory login credential), where it is resolved from the caller’s role in the addressed project rather than from the token’s claims:

Project role agents:read agents:write
project_admin yes yes
project_user yes no
project_viewer yes no

Every project role carries agents:read, so any member can fetch the card and read tasks. agents:write — message:send, message:stream and tasks/{id}:cancel — comes only with project_admin; a project_user or project_viewer session, including memory a2a send or memory acp after memory login, is refused with PERMISSION_DENIED. memory acp forwards every prompt over message:stream, so it is a write surface even though it drives an agent rather than a task; its documented setup uses MEMORY_PROJECT_TOKEN, whose default scopes include agents:*.

A superadmin_full session carries the full catalogue. A session with no project membership resolves to its org_admin entitlements when it has them, and otherwise to the deployment’s MEMORY_OIDC_DEFAULT_SCOPES; neither set includes agents:* by default, so it is refused here unless the default is changed. An unrecognised project role — or a role lookup that fails — does not fall back to that default: the mapping fails closed to no scopes at all, so the session is refused here even when MEMORY_OIDC_DEFAULT_SCOPES names agents:*.

The card declares a single bearer security scheme, for emt_… tokens, and no OAuth2 or OIDC scheme. The server does run an OAuth 2.1 authorization server (/.well-known/oauth-authorization-server, authorization-code with PKCE), but its scope allowlist — graph:read, graph:write, schema:read, projects:read, chat:use — does not include agents:read or agents:write, so a token obtained through it is refused here with an insufficient-scope error. Mint a project API token carrying the scope you need (see Not supported).

The project comes from the X-Project-ID header, or from the token itself when the token is project-scoped (a project-scoped token cannot be redirected to a different project by the header). A request with neither is rejected with PROJECT_REQUIRED, and an addressed project whose organization the caller does not belong to is rejected with PERMISSION_DENIED (or NOT_FOUND when the project does not exist) — the header is a selector, never a grant. The scope is checked before the selector: a credential that does not carry the route’s scope is refused with PERMISSION_DENIED even if it also omits X-Project-ID.

POST /message:send runs an agent and returns a buffered envelope. POST /message:stream runs the same agent and streams SSE events. Both accept an A2A Message carrying text parts and, optionally, an a2uiAction metadata entry (see Responding to a surface).

The card advertises the A2UI-over-A2A binding:

{
"capabilities": {
"extensions": [
{
"uri": "https://a2ui.org/a2a-extension/a2ui/v0.9.1",
"params": { "supportedCatalogIds": ["memory-basic"] }
}
]
}
}

supportedCatalogIds is the list of catalog ids this server can resolve for createSurface.catalogId.

A UI message is emitted as an A2A data part whose metadata.mimeType is application/a2ui+json. The data member is an ordered array of A2UI envelope messages (createSurface, updateComponents, updateDataModel, deleteSurface). A2UI-incapable clients ignore the part and read the text parts instead, so one stream serves both renderer classes.

Memory ships one catalog, memory-basic, with nine components tuned for agent approval and review flows rather than for general layout:

Component Purpose
proposal Review, accept or reject a proposed change
approval Gate a tool call behind an explicit decision
question Ask the user a question and resume the run with the answer
code Show a code block with language metadata
entity Preview a knowledge-graph entity
object-form Edit a graph object’s fields
todo Show task progress
result Show a structured operation result
sources Cite the documents and chunks a claim came from

The catalog is closed: agent output is validated against it, and output that falls outside it is repaired by re-prompting the model. Surface messages naming any other catalogId are rejected with an INVALID_ARGUMENT issue list.

When the user acts on a surface, send the action back on the next message as message metadata:

{
"role": "ROLE_USER",
"parts": [{ "text": "Approved." }],
"metadata": {
"a2uiAction": { "surfaceId": "surface-1", "action": { "componentId": "approve", "response": "accept" } }
}
}

The action is folded into the user message that resumes the run, so the agent sees both the decision and the accompanying text.

Be explicit about these before integrating:

  • A2A v0.3 and earlier. The server implements v1.0 and rejects any other A2A-Version with VERSION_NOT_SUPPORTED. Registries and hosts that speak only v0.3 (Gemini Enterprise among them) need a v0.3 compatibility shim in front of this server.
  • Path-scoped project addressing. The project is a header or a token claim, never a path segment, so a host that cannot send custom headers cannot select a project.
  • OAuth for agent calls. The card declares a bearer emt_… project API token scheme and no OAuth2 or OIDC scheme. The deployment’s OAuth 2.1 authorization server issues tokens scoped to graph:read, graph:write, schema:read, projects:read and chat:use — not agents:read or agents:write — so a token a third-party app obtains through that flow cannot call these routes. Mint a project API token with the scope you need instead.
  • Standard A2UI catalogs. Only memory-basic is served. A renderer that implements just the standard A2UI component set cannot draw these surfaces.
  • Push notifications. Not implemented. The six routes exist only to answer PUSH_NOTIFICATION_NOT_SUPPORTED: GET /tasks/{id}/pushNotificationConfigs, GET /tasks/{id}/pushNotificationConfigs/{configId}, POST /tasks/{id}/pushNotificationConfigs, PUT /tasks/{id}/pushNotificationConfigs/{configId}, DELETE /tasks/{id}/pushNotificationConfigs, DELETE /tasks/{id}/pushNotificationConfigs/{configId}.
  • Agent-to-agent delegation over A2A. A caller invokes one of the project’s agent definitions; the server does not itself fan out to other A2A agents.

The card carries the agent_metadata/v1 extension so agent galleries can show an author and a contact address:

{
"uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
"params": {
"authorName": "Emergent Company",
"contactEmail": "support@emergent-company.ai"
}
}

This is forward-looking: Gemini Enterprise is the reference implementation of the extension, but it requires A2A v0.3 and cannot register this server yet (see Not supported). The fields are advertised because any registry that consumes the extension gets a correct author and contact for free, and because adding it later means re-publishing the card.

The iconUrl field is absolute and points at the web UI’s 512 px icon. The advertised origin is the frontend origin — WEB_UI_URL, or APP_URL when that is unset — because the gateway serves /assets/*, not the API host. If neither is configured, it falls back to the interface origin so the value is never empty.