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

`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs

Abierto
#1,454 1 comentario 1 reacción 0 asignados Ver en GitHub
enhancement proposal
Lenguaje dominante
Python
Estrellas
15.9k
Forks
1.4k
Merge medio
1 d 17 h
PR fusionados (30 d)
163

Descripción

`RunAgentInput` currently requires non-null strings for `threadId` and `runId`, while `@ag-ui/client` auto-generates IDs by default when values are missing.
That makes backend-owned ID flows awkward for systems where IDs are database keys.

### Why this matters

I’m running FastAPI + Cosmos DB. `thread_id` and `run_id` are backend-owned identifiers, so I need a clean way for the client to say: “server, mint canonical IDs”.

Right now the behaviour is asymmetric in SDK internals:

```ts
// constructor
this.threadId = threadId ?? uuidv4();

// prepareRunAgentInput
runId: parameters?.runId || uuidv4();
```

So `threadId: ""` can pass through as a sentinel, but `runId: ""` is replaced.
That is brittle and undocumented as protocol intent.

Related workaround already exists in AG-UI integration code:

```py
thread_id = input.thread_id or str(uuid.uuid4())
```

### Proposal (3 coordinated changes)

1. **Core schema (`@ag-ui/core`)**
Allow nullable IDs:
- `threadId: z.string().nullable()`
- `runId: z.string().nullable()`

2. **SDK behaviour (`@ag-ui/client`)**
Preserve explicit `null` (server-mint intent), while keeping current auto-generation for `undefined` (backward compatible).
Also consider allowing per-run `threadId` override in `RunAgentParameters`.

3. **Spec/docs text**
Define clear semantics:
- `threadId: null` => server mints thread ID
- `runId: null` => server mints run ID
- Unknown non-null `threadId` => integration-defined (strict reject vs permissive create), but must be documented
- IDs in `RunStartedEvent` are authoritative for the run

### Backward compatibility

- Existing clients sending non-null strings: unchanged
- Existing SDK default behaviour: unchanged for `undefined`
- New behaviour is opt-in via explicit `null`

### References / citations

- #147 (current JS ID handling shape)
- #1243 (thread ID handling mismatch downstream)
- #566 (thread ID not propagated in some flows)
- `integrations/langgraph/python/ag_ui_langgraph/agent.py` (`thread_id = input.thread_id or str(uuid.uuid4())`)

Happy to open a coordinated PR (core schema + client handling + docs + tests) if maintainers agree with direction.

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.