Configure Reference

Configure is the public TypeScript SDK client.

import { Configure } from "configure";

const configure = new Configure({
  apiKey: process.env.CONFIGURE_API_KEY!,
  agent: "your-agent",
});

Constructor

new Configure(options: ConfigureOptions)

ConfigureOptions:

Field	Required in type	Runtime behavior
apiKey	no	Server-side Configure secret key. Falls back to CONFIGURE_API_KEY; construction fails if neither is set.
agent	no	Public agent handle. Falls back to CONFIGURE_AGENT; construction fails if neither is set or validation fails.
externalId	no	Default app-local user ID for unlinked developer-scoped profile operations.
timeout	no	Optional request timeout in milliseconds.
fetch	no	Custom fetch implementation for runtimes without native fetch.
baseUrl	no	Advanced override for local/staging development.

Do not expose secret keys in browser code. Browser flows should use Configure UI components and publishable keys.

Agent Handle Rules

The agent handle is the one public identifier for an agent, similar to a social username.

• Lowercase letters, numbers, and hyphens only.
• 2 to 63 characters.
• Starts and ends with a letter or number.
• Reserved names are rejected.

Runtime Handles

Create a per-user runtime handle with configure.profile().

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

The runtime handle owns profile reads, memory search, explicit remembers, bounded conversation commits, model tool definitions, and tool execution.

For app-local unlinked users, use configure.profile({ externalId: "customer-123" }).

Bulk Import

Create historical/onboarding backfill jobs with configure.importProfiles().

const job = await configure.importProfiles({
  mode: "backfill",
  users: [
    {
      externalId: "customer-123",
      profile: { preferences: ["Prefers concise replies."] },
    },
  ],
});

const status = await configure.importJobs.get(job.id);

Import is server-side and secret-key only. It is separate from profile.commit() and is not exposed through profile.tools().