a2aproject / a2aproject/a2a-samples

ITK: v0.3/v1.0 SSE streaming wire format incompatibility

Aberta
#476 0 comentários 0 reações 1 responsável Reivindicada por @kdziedzic70 Ver no GitHub
Linguagem predominante
Jupyter Notebook
Estrelas
1.8k
Forks
751
Métricas de merge de PRs
Nenhum PR com merge em 30d

Descrição

## Problem

The ITK test runner and v1.0 agents use incompatible SSE wire formats, which means streaming interop tests are not actually validating SSE event structure.

### Test runner (pydantic SDK, `a2a-sdk==0.3.25`)

Expects flat events with `kind` discriminator and lowercase state enums:

```json
data: {"kind": "status-update", "taskId": "tsk-1", "status": {"state": "working"}}

data: {"kind": "artifact-update", "taskId": "tsk-1", "artifact": {"parts": [{"kind": "text", "text": "hello"}]}}
```

### Python v1.0 agent (protobuf SDK, `a2a-sdk==1.0.0a0`)

Emits `StreamResponse` wrapper with `oneof` payload and SCREAMING_SNAKE_CASE enums:

```json
data: {"result": {"statusUpdate": {"taskId": "tsk-1", "status": {"state": "TASK_STATE_WORKING"}}}}

data: {"result": {"artifactUpdate": {"taskId": "tsk-1", "artifact": {"parts": [{"text": "hello"}]}}}}
```

### Differences

| Aspect | pydantic SDK (v0.3) | protobuf SDK (v1.0) |
|--------|-------------------|-------------------|
| Event wrapper | flat, `kind` discriminator | `StreamResponse.result` oneof |
| State enum | `working`, `completed` | `TASK_STATE_WORKING`, `TASK_STATE_COMPLETED` |
| Role enum | `agent`, `user` | `ROLE_AGENT`, `ROLE_USER` |
| Part format | `{"kind": "text", "text": "..."}` | `{"text": "..."}` (no `kind`) |

## Impact

1. **No single SSE format satisfies both consumers.** An agent emitting pydantic format works for the test runner but not for v1.0 agents receiving streaming callbacks in a multi-hop chain. An agent emitting protobuf format interops with v1.0 agents but the test runner may fail to parse.

2. **Streaming tests pass for the wrong reason.** The `v10-core-streaming` tests pass because token verification checks the final concatenated result, not individual SSE events. The ITK is not validating that SSE events conform to the v1.0 wire format.

3. **Agents must hide streaming capability.** When adding the Elixir agent (PR #475), we had to intentionally *not* advertise `capabilities.streaming=true` to avoid parse failures during multi-hop callbacks where different SDKs handle the downstream response.

## Suggested fixes

1. **Upgrade the ITK test runner** to use `a2a-sdk>=1.0.0a0` (protobuf SDK) — aligns with v1.0 agents natively
2. **Add format detection** in the test runner's SSE parser to handle both pydantic and protobuf event formats
3. **Separate v0.3 and v1.0 streaming tests** so each uses the matching SDK for parsing
4. **Add SSE event structure assertions** to streaming tests — currently only the final result is checked

## Reproduction

1. Run `v10-core-streaming` test (Python v1.0 + Go v1.0)
2. Capture the actual SSE events emitted by each agent
3. Compare against what `testlib.py` can parse
4. Note: tests pass but individual events may not parse correctly

## Context

Discovered while adding the Elixir v1.0 agent to the ITK (PR #475). The Elixir agent implements SSE streaming but cannot advertise it due to this format mismatch.

cc @kdziedzic70

Guia de contribuição

Abrir o guia de contribuição

Direção de pesquisa

The issue is in the ITK test runner's SSE parser in `testlib.py`. First, examine the `v10-core-streaming` tests to see how they currently pass. Then, capture the actual SSE events from a Python v1.0 agent and a Go v1.0 agent to compare formats. The fix involves updating the parser to handle both pydantic and protobuf SDK formats, or upgrading the test runner to use the protobuf SDK. Done looks like the test runner correctly parsing events from both SDK versions and the streaming tests asserting on individual event structure.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
elixir, go, python
Domínio
api, backend-api-design, testing
Tipo de issue
Bug
Dificuldade
4/5
Tempo estimado
3-5 dias
Status de atividade
Estagnada
Clareza
Claramente especificada
Facilidade para iniciantes
35/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.