Gemini Enterprise A2A Rules

Specialized rules for building A2A agents compatible with the Gemini Enterprise validator and runtime.

Rule 1 — Protocol and Transport

• Always use JSON-RPC 2.0.
• The root path / must handle POST requests for A2A logic.
• The root path / should handle GET requests for a basic health check (to avoid 405 errors during manual browser/connectivity verification).
• The JSON-RPC method for streaming content is message/stream.

Rule 2 — Agent Card (JSON Metadata)

The Gemini Enterprise validator is strict. The agent_card.json MUST:

• Use camelCase for all property names (e.g., inputModes instead of input_modes).
• Set protocolVersion: "v1" instead of schema_version.
• Every AgentSkill MUST include tags: [] (even if empty).
• Do not include non-standard fields like endpoints or schema_version.

Rule 3 — Response Lifecycle

• The agent MUST emit a TaskStatusUpdateEvent with final: true as its last event.
• Content should be emitted via TaskArtifactUpdateEvent BEFORE the final status update.
• Every event MUST include both task_id and context_id.

Rule 4 — Identity and Authorization

• To receive user_id and delegated tokens, the Agent Card MUST declare security_schemes and security fields.
• Identity and auth data must be extracted in middleware (or API Gateway), not within the AgentExecutor.
• Gemini injects an opaque Google Access Token directly into the HTTP Headers as Authorization: Bearer <TOKEN>.
• Identity Resolution: The token is not a JWT and cannot be decoded locally. You MUST call Google's Token Introspection endpoint (https://www.googleapis.com/oauth2/v3/userinfo) with the opaque token to resolve the user's email, sub (User ID), and hd (Hosted Domain).

Rule 5 — The "Infinite Auth Loop" and Google OAuth

• Do NOT use Mock OAuth Providers: Gemini Enterprise (via Vertex AI Agent Builder) strictly enforces token validation. Mock providers (e.g. returning unsigned JWTs with alg: none) will cause a silent rejection and trigger an infinite OAuth redirect loop.
• Production Standard: For organizations using Google Workspace, always use Google Cloud Platform (GCP) OAuth as the Identity Provider.
• Required Redirect URIs in GCP: https://vertexaisearch.cloud.google.com/oauth-redirect
• Offline Access: The Authorization URL provided to Gemini Enterprise MUST include the query parameter ?access_type=offline (e.g., https://accounts.google.com/o/oauth2/v2/auth?access_type=offline). This is required for Gemini to receive a refresh token.
• Validation: Your A2A server (or API Gateway) MUST include middleware to intercept the Authorization header and execute the token introspection call against Google's API before executing any logic.