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

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

未關閉
#1,454 1 則留言 1 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement proposal
主要語言
Python
星號
15.9k
分支
1.4k
平均合併
1 天 17 小時
30 天內合併 PR
163

描述

`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.

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。