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

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

Open
#1,454 1 comment 1 reaction 0 assignees View on GitHub
enhancement proposal
Dominant language
Python
Stars
15.9k
Forks
1.4k
Avg merge
1d 17h
Merged PRs (30d)
163

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.