# A2A Protocol

Connects agent-native apps over A2A with discovery and authentication.

- Repository: https://github.com/BuilderIO/agent-native (7579 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BuilderIO/agent-native --skill a2a-protocol -g -a claude-code -y`
Codex: `npx skills add BuilderIO/agent-native --skill a2a-protocol -g -a codex -y`
Cursor: `npx skills add BuilderIO/agent-native --skill a2a-protocol -g -a cursor -y`
Gemini CLI: `npx skills add BuilderIO/agent-native --skill a2a-protocol -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add BuilderIO/agent-native`

## Description

How agent-native apps discover, authenticate with, and call each other over A2A. Use when connecting one app to another, debugging a remote agent that won't authenticate, exposing skills to peers, or calling agents from scripts.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# A2A Protocol (Agent-to-Agent)

## Rule

Agents call other agents over A2A, a JSON-RPC protocol for discovery and
delegation. Use it only when the user explicitly asks to involve a peer, or
the requested outcome requires data, credentials, or a capability owned by
that peer and unavailable through the local app's actions. The local app's
actions are the default; a peer's availability or ability to enrich a result
is not enough. When a peer supplies input, keep authoring and editing artifacts
native to the local app here.

When a handoff qualifies under the rule above, preserve the peer boundary: do
not have app A generate and execute raw SQL against app B's database, or expose
B's internal tools directly to A as a substitute for delegation. The receiving
agent has context, skills, and guardrails the caller doesn't. If a justified
A2A call is unreliable, fix the delegation path (timeouts, retries, or typed
terminal states) instead of bypassing it app by app.

Connecting app A to an Agent-Native app B is two independent things, and both
must be true:

1. **B is registered on A** as a `remote-agents/<id>.json` resource.
2. **A and B share a secret**, so A's signed JWT verifies on B.

Neither is a code change, and neither is symmetric. Registering B on A does not
let B call A. A hosted peer uses provider-specific endpoint and credential
metadata in place of the shared Agent-Native secret, but it still does not make
the provider's model or SDK an A2A endpoint.

## A2A is already mounted

`createAgentChatPlugin` calls `mountA2A` for every app, so a generated app
already serves:

- `GET /.well-known/agent-card.json`, public discovery, with a larger
  authenticated capability view for verified sibling callers
- `POST /_agent-native/a2a`, JSON-RPC, authenticated

Do not add a `mountA2A` server plugin to enable A2A; it is on. Hand-mounting is
only for a bespoke card or a custom handler (see **Custom mount** below).

The rest: https://github.com/BuilderIO/agent-native/blob/HEAD/.agents/skills/a2a-protocol/SKILL.md