Apps SDKGuide5 min

Decide what state belongs in a ChatGPT App component

A state-management guide for ChatGPT Apps that need to stay predictable across tool calls and UI interactions.

Real example

Example: local filters vs durable shortlist state

A ChatGPT App shows a list of vendor options. The user filters by budget locally, then saves three vendors to a project shortlist.

Keep filter text, sort order, and selected UI tab in component state. Send saved shortlist changes through an authenticated tool or server route that validates ownership.

The UI feels interactive while durable business data stays in the system of record.

Tutorial path

How to implement it

Step 01

Classify each field as visual state, user draft state, tool result, or durable server state.

Step 02

Keep filters, selected rows, and temporary edits local when they do not affect business data.

Step 03

Send durable changes through tools or server APIs that can validate authorization.

Step 04

Rehydrate the component from tool results instead of assuming a long-lived browser session.

Step 05

Test reload, repeated tool call, and partial-result scenarios.

Checklist

Ready when these are true

State ownership documented

Server owns durable changes

Local state can reset safely

Repeated tool call tested

No hidden authorization in UI

Field notes

What matters in practice

Component state is for interaction and presentation, not hidden business authority.

Durable workflow state should live in your server or data source.

The app should recover gracefully when the conversation or tool result changes.

Avoid these mistakes

Common failure modes

Do not treat component state as trusted state.

Do not assume the component will live forever across conversation changes.

Do not hide failed saves behind optimistic UI with no recovery.

Practical tip

If losing the state would harm the business workflow, it belongs on the server.

Apply this to a build