# Optional real AI provider

The assistant starts in **Demo** mode with language-aware sample replies. They are deterministic examples, not generated reasoning; demo mode does not inspect photo contents.

For a real assistant, copy `.env.example` to `.env.local` and set `AGENT_BACKEND=openai` and configure both values:

```dotenv
AGENT_BACKEND=openai
OPENAI_API_KEY=your_server_api_key
OPENAI_MODEL=a_responses_api_model_available_to_your_account
```

Restart the server. The UI reads `/api/agent` to report the connection mode in conversation information; live mode requires both values. The selected model is entirely under your control; choose a vision-capable model to process photos. Do not put either value in a `NEXT_PUBLIC_` variable.

`POST /api/agent` accepts `{ locale, messages: [{ id?, role: 'user' | 'assistant', text, image? }] }` and returns newline-delimited JSON events: `mode`, `delta`, `card`, `reference`, `done`, or `error`. The transport uses [OpenAI's Responses streaming API](https://developers.openai.com/api/docs/guides/streaming-responses) and its [image input format](https://developers.openai.com/api/docs/guides/images-vision), with `store: false`, a bounded transcript, and a 60-second timeout. Client cancellation aborts the upstream request. Failures stay visible and retryable; they never silently fall back to a sample answer.

The provider receives up to 20 eligible messages (40,000 text characters), the latest two user images, stable message IDs, quoted/forwarded source references, and product-choice context. An older latest product choice is reserved as a compact memory entry when it falls outside the recent-message window. Provider credentials stay on the server.

In live mode, assistant-chat content and included images are sent to the configured provider. People chats stay local. **Add application authentication and rate limiting before exposing a keyed endpoint publicly.** This workspace preview listens on loopback and uses demo mode.

The live adapter is verified with mocked upstream streams, including provider errors and cancellation. No paid request or account/model availability check was performed.