# Configure Agent Template

This is the packaged shell for a new Configure agent. Use it only when you want a fresh chat shell. If your product already has an agent, integrate Configure in place by adding the hosted browser script, a Link or Personalization entry, and the server-side profile runtime.

The template keeps one chat thread, one composer, hosted auth inline in the conversation, hosted Configure surfaces inline where they belong, and a reading indicator on the first message after Link while that message streams.

Do not redesign the shell by default. Change:

- `.env`
- `public/brand.css`
- `public/brand.js`
- `server.mjs`

Everything else should stay fixed unless the project already has a strong product shell worth preserving.

## Setup

In the app that will use this template:

```bash
npx configure setup
npm install configure
```

Choose **For my users**. `npx configure setup` writes:

- `CONFIGURE_API_KEY`
- `CONFIGURE_PUBLISHABLE_KEY`
- `CONFIGURE_AGENT`

Then fill in the runtime values shown in `.env.example`:

- `CONFIGURE_AGENT_NAME` for the visible shell title, if you want one
- `MODEL_PROVIDER`
- `MODEL_NAME`
- one real provider key:
  - `ANTHROPIC_API_KEY`
  - `OPENAI_API_KEY`
  - or `OPENROUTER_API_KEY`

Without a real provider key, hosted auth and profile surfaces still work, but live chat and tool execution do not.

## Brand surface

Change only these files for the visual identity:

- `public/brand.css` — shell colors and token values
- `public/brand.js` — visible copy, optional logo URL, hosted surface theme

If you switch `configureTheme` in `public/brand.js` to `dark`, keep `public/brand.css` in a dark palette too so hosted Configure surfaces and the shell stay aligned.

## Runtime surface

- `server.mjs` — backend prompt, model provider, tool behavior
- `.env` — agent handle, display name, Configure keys, provider keys

## What this demonstrates

- hosted linking with `Configure.link()`
- streaming chat over Server-Sent Events
- `profile.tools()` and `profile.executeTool()`
- inline hosted Configure surfaces (connections, memory import, profile editor) mounted from the shell's action buttons
- background `profile.commit()` after a turn in which the model read the profile

## How the profile gets read

`server.mjs` does not read the profile at the start of a conversation. It declares the Configure tools and lets the model call `configure_profile_read` or `configure_profile_search` when it needs context. The commit in the `finally` block runs only when one of those two tools ran during the turn, because a commit exists to discharge a read.

The "Reading approved profile" indicator in the shell is a client-side affordance. It appears when someone types before signing in: after Link completes, that pending message is sent and the indicator stays up until the response finishes.

If you want context in the model's very first sentence, add an explicit `await profile.read(...)` before the model call and put `read.profile.format({ guidelines: true })` in the system prompt. That trades one request per conversation for guaranteed context.

## Reference

- **skill.md:** [configure.dev/skill.md](https://configure.dev/skill.md)
- **llms.txt:** [configure.dev/llms.txt](https://configure.dev/llms.txt)
- **Reference agents:** `apps/agents/` in the repo — fuller production examples with persistence and additional product chrome