ag-ui-protocol / ag-ui-protocol/ag-ui

feat(a2a): upgrade @ag-ui/a2a and @ag-ui/a2a-middleware to A2A Protocol v1.0 (@a2a-js/sdk@1.x)

Abierto
#2,358 4 comentarios 1 reacción 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
15.9k
Forks
1.4k
Merge medio
1 d 17 h
PR fusionados (30 d)
163

Descripción

## Summary

Upgrade the official AG-UI ↔ A2A bridge packages to **A2A Protocol Specification v1.0**, by moving from `@a2a-js/sdk@^0.2.x` to `@a2a-js/sdk@1.x`.

Today:

| Package | Declared dependency | Wire format in converters/tests |
| --- | --- | --- |
| `@ag-ui/a2a` (`0.0.6`) | `@a2a-js/sdk@^0.2.2` | v0.3-style (`kind: "text"`, `status-update`, etc.) |
| `@ag-ui/a2a-middleware` | `@a2a-js/sdk@^0.2.2` | same |

Meanwhile:

- A2A Protocol **v1.0.0** shipped (2026-03)
- Official `@a2a-js/sdk` is at **1.0.x** and implements the v1.0 data model / transports
- New A2A agents (e.g. Python SDK samples) speak v1.0 by default (unified `Part` without `kind`, `ROLE_*` / `TASK_STATE_*` enums, wrapped stream events, `supportedInterfaces`, etc.)

As a result, `@ag-ui/a2a` cannot cleanly talk to a pure v1.0 A2A peer without a compatibility layer or dual-version agent.

> **Status note:** `@ag-ui/a2a` README currently marks the integration as **Experimental**. This issue proposes graduating the wire-format support to A2A v1.0 while keeping the package stability expectations clear.

## Motivation

- A2A v1.0 is the stable production protocol line
- AG-UI docs position A2A as the Agent↔Agent layer complementary to AG-UI; the bridge should track the stable A2A line
- Avoid forcing every AG-UI host to pin remote agents to v0.3 forever

## Proposed scope

### In scope
1. Bump `@a2a-js/sdk` to `^1.0.0` (or latest 1.x) in:
- `integrations/a2a/typescript`
- `middlewares/a2a-middleware`
2. Update converters in `integrations/a2a/typescript/src/utils.ts` (and related types/tests) for v1.0 breaking changes, at least:
- `Part`: member-based content (`text` / `raw` / `url` / `data`) instead of `kind`
- Roles / task states: `ROLE_*`, `TASK_STATE_*`
- Stream event discrimination: wrapped members (`task` / `message` / `statusUpdate` / `artifactUpdate`) instead of top-level `kind`
- Agent Card: prefer `supportedInterfaces[]` (keep reading legacy fields only if needed for compat)
3. Update unit tests + dojo A2A examples as needed
4. Document supported A2A protocol version(s) in the package README

### Compatibility question (please advise)
Should the bridge:
- **A)** Speak **v1.0 only**, or
- **B)** Support **v1.0 + v0.3** (e.g. choose interface from Agent Card `protocolVersion`, or rely on `@a2a-js/sdk` compat helpers)?

My preference is **B** if maintainable, so existing v0.3 agents keep working during migration.

### Out of scope (unless maintainers want it bundled)
- Broader A2AAgent feature gaps already tracked elsewhere (shared state / HITL / richer Task-Artifact mapping) — see #762, #1938, #1968
- Designing a new push-notification transport — see #2106

## Related issues
- #762 — missing AG-UI features on A2AAgent bridge
- #1938 — `RunAgentInput.state` dropped
- #1968 — forward context/tools through `@ag-ui/a2a`
- #2106 — pushNotifications / A2A PushNotificationConfig alignment

None of the above explicitly tracks the **protocol v1.0 / SDK 1.x upgrade**.

## Willingness to contribute

I can take this if maintainers agree on scope + compatibility strategy.

Please assign me (or point to anyone already working on it) and tag code owners as appropriate (`@ag-ui-protocol/copilotkit`).

## Checklist before implementation
- [ ] Confirm no duplicate work already in progress
- [ ] Agree on compat strategy (v1.0-only vs dual-version)
- [ ] Agree on package versioning / changelog expectations for `@ag-ui/a2a` and `@ag-ui/a2a-middleware`

Thanks!

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.