ag-ui-protocol / ag-ui-protocol/ag-ui
`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs
- 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
Evaluación
Este issue todavía no se ha evaluado.