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

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

Đang mở
#1,454 1 bình luận 1 reaction 0 người được giao Xem trên GitHub
enhancement proposal
Ngôn ngữ chính
Python
Star
15.9k
Fork
1.4k
Merge trung bình
1 ngày 17 giờ
Pull request đã merge (30 ngày)
163

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.