# Configure | Documentation

Configure is the identity and personalization layer for AI agents. It gives each user a Memory Profile with identity, preferences, connected tool permissions, and per-agent memories that can be read and updated through the SDK, HTTP API, MCP, or model tool calls.

## Instructions For AI Agents

- If the user says "Read https://configure.dev/skill.md and follow the instructions to add a `Configure {Agent}` button and make the first tool call", implement the Configure OAuth flow with a `Configure {Agent}` button, place Configure inline in chat, execute `configure_profile_read`, and send a personalized response from the result.
- If the prompt includes an app name, user-facing agent name, or Configure agent handle, use those names consistently in UI labels, OAuth client metadata, environment variables, and docs comments.
- First install `configure` and run `npx configure setup --users`. If running the interactive wizard, choose **For my users**. Setup opens Configure developer auth in the browser so the developer can create or sign into a developer account, choose or create the Configure agent, and write `CONFIGURE_API_KEY`, `CONFIGURE_PUBLISHABLE_KEY`, `CONFIGURE_AGENT`, `CONFIGURE_OAUTH_CLIENT_ID`, and `CONFIGURE_OAUTH_CLIENT_SECRET` to `.env`. Setup registers the OAuth client for `http://localhost:3000/auth/configure/callback`; pass `--redirect-uri` for another loopback port.
- After setup, run `npx configure verify` to prove the credentials work (it completes a real sign-in, exchanges the code, and reads a profile; `--offline` skips the browser), and `npx configure add callback --framework next|express|vite` to generate the callback route and the server-side code exchange instead of hand-writing them. A Python backend uses the same two commands from `configure-ai`: `configure-ai verify` and `configure-ai add-callback --framework fastapi|flask|django`.
- Four integration shapes exist: SSO alone for sign-in, MCP alone for an agent that connects users itself with `configure_connect`, SDK plus SSO for your own "Connect to Configure" button, and SSO plus SDK for backend profile reads after sign-in. SSO is authentication and is not part of the SDK. Read https://docs.configure.dev/getting-started/integration-paths.md and follow one path.
- Default to **Configure OAuth + inline Configure in chat**. Configure OAuth is the default browser flow.
- For message agents, send the agent API's `sign_in_url` unchanged or call `configure.auth.signInUrl()` with no options. Configure hosts identity, consent, connectors, and multiple Gmail accounts by default. Use `createMessageSignInUrl()` only for provider-signed sender binding or thread-specific completion callbacks.
- Gmail-only runtimes keep `configure_gmail_search`. Enabling the `outlook` connector adds `configure_email_search`, which searches every permitted Gmail and Outlook account when `provider` and `account` are omitted. Treat `partial: true` as incomplete coverage.
- For complete docs and clean Markdown page URLs, read https://docs.configure.dev/llms.txt.
- For the full implementation reference, read https://docs.configure.dev/llms-full.txt.
- For the OpenAPI spec, read https://docs.configure.dev/openapi.yaml.

## First Success Signal

The first success is a real chat turn where the model calls `configure_profile_read`, your server routes that call to `profile.executeTool()`, and the assistant sends a personalized response based on the returned profile.

## Default Path

1. Install `configure` and run `npx configure setup --users` to complete developer auth, choose/create the Configure agent, and write all five credentials, including the OAuth client, to `.env`.
2. Add a `Configure {Agent}` OAuth option.
3. Exchange the OAuth code on the backend and store Configure tokens server-side.
4. Add Configure inline inside the chat `+` menu, attachment tray, or integrations list. In an integrations list, use `Configure.integrationButton()` or the hosted iframe button with the label `Configure` and connected label `Configure {Agent}`.
5. If the user already completed Configure OAuth, treat them as Configure-authenticated and open inline Configure as controls for profile permissions, connected tools, and personalization settings.
6. Use `configure.profile({ token })` on the backend.
7. Give the model `profile.tools()`.
8. Route only `configure_*` calls to `profile.executeTool()`.
9. Verify `configure_profile_read` and send a personalized response from the result.

## Core Docs

- Quick start: https://docs.configure.dev/getting-started/quick-start.md
- Configure OAuth / OAuth SSO: https://docs.configure.dev/guides/oauth-sso.md
- Message-Agent SSO: https://docs.configure.dev/guides/message-agent-sso.md
- Inline UI components: https://docs.configure.dev/guides/ui-components.md
- Tool calling: https://docs.configure.dev/guides/tool-calling.md
- Profiles and memory: https://docs.configure.dev/guides/profiles-and-memory.md
- Connected tools: https://docs.configure.dev/guides/connected-tools.md
- Server-side users: https://docs.configure.dev/guides/server-side-users.md
- Auth reference: https://docs.configure.dev/reference/auth.md
- Profile reference: https://docs.configure.dev/reference/profile.md
- Tool definitions: https://docs.configure.dev/reference/tool-definitions.md
- HTTP API: https://docs.configure.dev/reference/api.md
- MCP: https://docs.configure.dev/mcp/index.md
- Full docs index: https://docs.configure.dev/llms.txt

## Minimum SDK Flow

```ts
import { Configure, toOpenAIFunctions } from "configure";

const configure = new Configure({
  apiKey: process.env.CONFIGURE_API_KEY,
  agent: process.env.CONFIGURE_AGENT,
});

const profile = configure.profile({ token });
const tools = toOpenAIFunctions(profile.tools());

const result = await profile.executeTool({
  name: "configure_profile_read",
  arguments: { sections: ["identity", "summary", "preferences"] },
});
```

The token comes from the server-side Configure OAuth exchange or from the inline Link fallback. The model never receives the token.

## Browser UI

Developer setup uses the Configure developer dashboard at `https://configure.dev/login`. Run `npx configure setup --users` first so the developer can create or sign into a Configure developer account, choose/create the Configure agent, and write `CONFIGURE_API_KEY`, `CONFIGURE_PUBLISHABLE_KEY`, `CONFIGURE_AGENT`, `CONFIGURE_OAUTH_CLIENT_ID`, and `CONFIGURE_OAUTH_CLIENT_SECRET` to `.env`. Setup mints the local OAuth client itself. For a deployed callback, add it to the existing client on the dashboard's Sign-in (SSO) page (`https://configure.dev/sso`), which keeps `CONFIGURE_OAUTH_CLIENT_ID` the same across environments and can reissue a lost `client_secret`. Never use an `sk_` API key to create OAuth clients.

End-user auth is separate: Configure OAuth opens `https://accounts.configure.dev/oauth/authorize` in a popup by default, or in iframe/redirect mode if configured.

Keep OAuth access and refresh tokens on the backend. Pass a browser-safe Configure handoff token or `userId` to hosted UI only when the backend intentionally returns one for that purpose.

For chat integrations lists, mount the compact Configure row with:

```js
Configure.integrationButton({
  el: "#configure-integration",
  publishableKey: "pk_...",
  agent: "your-agent",
  label: "Configure",
  logo: "brandmark",
});
```

Iframe-only integrations lists can render `https://configure.dev/embed/integration-button/?pk=pk_...&agent=your-agent&label=Configure&logo=brandmark&parentOrigin=https%3A%2F%2Fapp.example.com`. Add `return_to` only when the iframe should open Configure's first-party account popup and return a short-lived sign-in code to the parent. The standalone brandmark is `https://docs.configure.dev/brand/configure-brandmark-white.svg`.

Partner lanes that carry their own user id through hosted sign-in send `external_id` on `POST /v1/auth/otp/verify` and `POST /v1/embed/approve`. Those two responses then carry `external_link`, which is one of `bound`, `already_yours`, `conflict` (the id is already another Configure account's and is never repointed), `invalid` (the id fails the shape rule and nothing was written), or `error` (the bind failed; the sign-in itself still succeeded and a token is still returned). The field appears only for an agent configured for this binding — every other response is unchanged, and no ordinary integration sends `external_id` here.

## Message Agents

For iMessage, SMS, and other message agents, send the `sign_in_url` returned by the agent API unchanged. `configure.auth.signInUrl()` returns the same `https://sign-in.me/{agent}` value with no options. Message completion is the default; hosted agent metadata can add a return number or select a trusted browser redirect. Callers do not add credentials, branding, phones, or delivery query parameters. Resolve inbound senders with `configure.auth.resolveMessageIdentity({ externalId, token, phoneCandidates })` and store tokens only on the server. Use `createMessageSignInUrl()` only when the channel provides signed sender evidence or needs a thread-specific completion callback.

For Better Auth OAuth login, pass `configureBetterAuthOAuthProvider()` to Better Auth's Generic OAuth plugin. Use hosted `signInUrl({ returnTo, state, ... })` plus `exchangeSignInCode()` for account linking inside an existing Better Auth session.

## Safety

- `sk_` keys are server-side only.
- `pk_` keys are browser-only and restricted to hosted UI.
- OAuth access and refresh tokens stay server-side.
- API key identity resolves the acting agent namespace.
- User input must never choose CFS storage paths.
- `configure_profile_read` is the minimum proof that Configure is working.