===============
LIBRARY RULES
===============
From library maintainers:
- Eidentic is a TypeScript SDK published on npm as `eidentic` and `@eidentic/*`. Always use the TypeScript API and ESM imports.
- Construct an agent with `new Agent({ id, model, store })`; wrap any AI SDK provider via `new AIModel(provider(modelId))`.
- Use `@eidentic/libsql` (LibsqlStore, pure-JS) for Next.js/serverless; `@eidentic/sqlite` (SqliteStore) for Node/Bun.
- `agent.query(input, { sessionId })` returns an async generator of StreamEvents; text deltas are `ev.type === 'stream.delta'` with `ev.delta.text`.
- Next.js: `export const POST = withEidentic(agent)` from `@eidentic/nextjs`. React: `useEidenticStream(endpoint)` from `@eidentic/react`.

### Post-Scaffolding Commands

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Navigate into the project directory, install dependencies, set necessary environment variables (like API keys), and start the development server.

```bash
cd my-agent
pnpm install
export ANTHROPIC_API_KEY=sk-ant-...
pnpm dev
```

--------------------------------

### Local Development Setup

Source: https://github.com/eidentic/docs/blob/main/README.md

Install project dependencies and start the development server or build for static deployment. These commands are essential for local development and testing.

```bash
npm install
npm start        # dev server
npm run build    # static build → build/
```

--------------------------------

### Deno Setup with Import Map

Source: https://github.com/eidentic/docs/blob/main/docs/guides/runtimes.md

Provides an example of configuring Eidentic package imports in Deno using a `deno.json` import map for cleaner import paths.

```json
{
  "imports": {
    "@eidentic/core": "npm:@eidentic/core",
    "@eidentic/model": "npm:@eidentic/model",
    "@eidentic/libsql": "npm:@eidentic/libsql"
  }
}
```

--------------------------------

### Install @eidentic/prompts

Source: https://github.com/eidentic/docs/blob/main/docs/guides/prompt-versioning.md

Install the library using npm.

```bash
npm install @eidentic/prompts
```

--------------------------------

### Install @eidentic/mcp and SDK

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/mcp.md

Install the core @eidentic/mcp package. Install @modelcontextprotocol/sdk if you plan to use transport helpers like streamableHttpClient or stdioClient.

```bash
npm install @eidentic/mcp
# For transport helpers (streamableHttpClient, stdioClient, createMcpServer):
npm install @modelcontextprotocol/sdk
```

--------------------------------

### Install @eidentic/better-auth and better-auth

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/auth.md

Install the necessary packages using npm.

```bash
npm install @eidentic/better-auth better-auth
```

--------------------------------

### Run Eidentic Examples with npm

Source: https://github.com/eidentic/docs/blob/main/docs/examples.md

Examples can be run using npm scripts. Ensure you are in the repository root.

```bash
# By npm script name (from the repo root)
pnpm --filter eidentic-examples hello:stateful

# Or directly with tsx from the examples/ directory
tsx examples/hello-stateful.ts
```

--------------------------------

### Install @eidentic/server

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Install the server package using npm.

```bash
npm install @eidentic/server
```

--------------------------------

### Install QdrantVectorStore Dependencies

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/vector-stores.md

Install the necessary packages for using QdrantVectorStore.

```bash
npm install @eidentic/qdrant @qdrant/js-client-rest
```

--------------------------------

### Install @eidentic/tools

Source: https://github.com/eidentic/docs/blob/main/docs/guides/tools.md

Install the necessary package using npm.

```bash
npm install @eidentic/tools
```

--------------------------------

### Install Skills Package

Source: https://github.com/eidentic/docs/blob/main/docs/memory/skills.md

Install the skills package using pnpm.

```bash
pnpm add @eidentic/skills
```

--------------------------------

### Install Eidentic SDK

Source: https://github.com/eidentic/docs/blob/main/README.md

Install the Eidentic SDK using npm. This is the first step to using the library in your project.

```bash
npm install eidentic
```

--------------------------------

### Install and Use PostgresStore

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/stores.md

Installs the `PostgresStore` and `pg` packages, then initializes the store using a `pg.Pool`. Automatically handles schema migrations on first use.

```bash
npm install @eidentic/postgres pg
```

```typescript
import { PostgresStore } from "@eidentic/postgres";
import pg from "pg";

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const store = await PostgresStore.create({ client: pool });
```

--------------------------------

### Install Convex and Eidentic Packages

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/stores.md

Install the necessary packages for using ConvexStore with Convex.

```bash
npm install @eidentic/convex convex
```

--------------------------------

### Install @eidentic/eval

Source: https://github.com/eidentic/docs/blob/main/docs/guides/evals-ci.md

Install the package as a development dependency.

```bash
npm install --save-dev @eidentic/eval
```

--------------------------------

### Install @eidentic/react

Source: https://github.com/eidentic/docs/blob/main/docs/guides/react-hooks.md

Install the @eidentic/react package using npm.

```bash
npm install @eidentic/react
```

--------------------------------

### Install Eidentic CLI Globally

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Install the `eidentic` CLI globally for easy access to its commands, or use `npx` to run commands without global installation.

```bash
npm install -g eidentic
# or: npx eidentic <command>
```

--------------------------------

### Install Eidentic and AI SDK Packages

Source: https://github.com/eidentic/docs/blob/main/docs/guides/building-your-own-ui.md

Install the necessary packages for Eidentic, Next.js integration, and AI SDK components.

```bash
npm install eidentic @eidentic/nextjs @eidentic/libsql ai @ai-sdk/anthropic @ai-sdk/react
```

--------------------------------

### Install @eidentic/workflow

Source: https://github.com/eidentic/docs/blob/main/docs/guides/workflows.md

Install the @eidentic/workflow package using npm.

```bash
npm install @eidentic/workflow
```

--------------------------------

### Install and Use SqliteStore

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/stores.md

Installs the necessary packages and initializes a `SqliteStore` for agent persistence. Supports in-memory or file-based storage.

```bash
npm install @eidentic/sqlite better-sqlite3
```

```typescript
import { SqliteStore } from "@eidentic/sqlite";
import { Agent, AIModel } from "eidentic";
import { anthropic } from "@ai-sdk/anthropic";

const store = new SqliteStore("./eidentic.sqlite");
// or in-memory:
// const store = new SqliteStore(":memory:");

const agent = new Agent({
  id: "assistant",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store,
});
```

--------------------------------

### Initialize Eidentic Project with CLI

Source: https://github.com/eidentic/docs/blob/main/docs/getting-started.md

Alternatively, install the Eidentic CLI globally and use the init command to scaffold a project.

```bash
npm install -g eidentic
eidentic init
```

--------------------------------

### Install and Use LibsqlStore

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/stores.md

Installs the `LibsqlStore` package for use in various environments, including serverless and edge. Supports local file or remote Turso instances.

```bash
npm install @eidentic/libsql
```

```typescript
import { LibsqlStore } from "@eidentic/libsql";

// Local file (development)
const store = new LibsqlStore("file:eidentic.db");

// Turso remote (production)
const store = new LibsqlStore(process.env.LIBSQL_URL!, {
  authToken: process.env.LIBSQL_AUTH_TOKEN,
});
```

--------------------------------

### Basic Server Setup

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Set up a basic Eidentic server with agents and API key authentication. Ensure your agent instance is imported correctly.

```typescript
import { createServer, serveNode, ApiKeyAuth } from "@eidentic/server";
import { agent } from "./agent.js"; // your Agent instance

const app = createServer({
  agents: { support: agent },
  auth: ApiKeyAuth({ "key_live_abc123": { userId: "tenant-1" } }),
});

await serveNode(app, { port: 3000 });
```

--------------------------------

### Eidentic Configuration Example

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Define agents, models, tools, and storage in `eidentic.config.ts`. This example shows setting up an agent with a tool and SQLite store.

```typescript
import {
  defineConfig,
  Agent,
  AIModel,
  SqliteStore,
  createTool,
  defaultPrices,
} from "eidentic";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

const store = new SqliteStore("./eidentic.sqlite");
await store.migrate();

const getTime = createTool({
  id: "get_time",
  description: "Get the current server time.",
  inputSchema: z.object({}),
  execute: async () => ({ now: new Date().toISOString() }),
});

export default defineConfig({
  agents: {
    assistant: new Agent({
      id: "assistant",
      instructions: "You are a helpful assistant.",
      model: new AIModel(anthropic("claude-sonnet-4-5")),
      tools: [getTime],
      store,
      prices: defaultPrices,
    }),
  },
  port: 3000,
  // auth: ApiKeyAuth({ "key_live_123": { userId: "u1" } }),
});
```

--------------------------------

### Install Browser Tools Package

Source: https://github.com/eidentic/docs/blob/main/docs/guides/browser-tools.md

Install the necessary packages for browser automation using npm.

```bash
npm install @eidentic/browser playwright-core
```

--------------------------------

### Install PDF Support

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/rag.md

For PDF document support, install the optional pdf-parse peer dependency.

```bash
npm install pdf-parse
```

--------------------------------

### Install @eidentic/a2a

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/a2a.md

Install the @eidentic/a2a package using npm.

```bash
npm install @eidentic/a2a
```

--------------------------------

### Install E2B Dependencies

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/sandboxes.md

Install the necessary E2B packages for sandbox integration.

```bash
npm install @eidentic/e2b @e2b/code-interpreter
```

--------------------------------

### Install Eidentic Packages

Source: https://github.com/eidentic/docs/blob/main/docs/getting-started.md

Install the core Eidentic package along with AI SDK providers for agent functionality.

```bash
npm install eidentic ai @ai-sdk/anthropic
```

--------------------------------

### Start Development Server with `eidentic dev`

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Use the `eidentic dev` command to start your agent configuration in development mode with hot-reloading. This command also opens Studio.

```bash
npx eidentic dev
```

--------------------------------

### Install PineconeVectorStore Dependencies

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/vector-stores.md

Install the necessary packages for using PineconeVectorStore.

```bash
npm install @eidentic/pinecone @pinecone-database/pinecone
```

--------------------------------

### Launch Studio CLI

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Start the Eidentic Studio developer dashboard using the CLI command.

```bash
npx eidentic studio
```

--------------------------------

### Install Eidentic CLI Globally

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Install the Eidentic CLI globally for convenient access to its commands.

```bash
npm install -g eidentic
```

--------------------------------

### Install Langfuse Exporter

Source: https://github.com/eidentic/docs/blob/main/docs/guides/observability.md

Install the Langfuse exporter package for Eidentic.

```bash
npm install @eidentic/langfuse
```

--------------------------------

### Install PgVectorStore Dependencies

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/vector-stores.md

Install the necessary packages for using PgVectorStore. Choose between a standard PostgreSQL client or the in-process PGlite.

```bash
npm install @eidentic/pgvector pg
# or with PGlite (in-process, no server needed):
# npm install @eidentic/pgvector @electric-sql/pglite
```

--------------------------------

### Start Eidentic Development Server

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Run `eidentic dev` to start the development server. It automatically loads `eidentic.config.ts` (or `.js`/`.mjs`) and provides live-reloading without a build step.

```bash
eidentic dev
```

--------------------------------

### Install Eidentic Server Dependencies

Source: https://github.com/eidentic/docs/blob/main/docs/guides/deployment.md

Install the necessary packages for running an Eidentic agent as a standalone Node.js server.

```bash
npm install eidentic @eidentic/server @hono/node-server ai @ai-sdk/anthropic
```

--------------------------------

### Install LanceDB Dependencies

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/vector-stores.md

Install the necessary packages for using LanceDBVectorStore.

```bash
npm install @eidentic/lancedb @lancedb/lancedb apache-arrow
```

--------------------------------

### Add Custom Skill to Project

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Install a skill from a local directory into the `skills/` folder using `eidentic add skill`. Ensure the directory contains a `SKILL.md` file.

```bash
eidentic add skill ./path/to/my-skill
```

--------------------------------

### Full RAG Integration Example

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/rag.md

Demonstrates ingesting local Markdown files and live URLs into an Eidentic agent's memory. Requires setting up an agent, store, and memory.

```typescript
import { Agent, AIModel, SqliteStore } from "eidentic";
import { Memory } from "@eidentic/memory";
import { ingestDocument, loadMarkdown } from "@eidentic/rag";
import { anthropic } from "@ai-sdk/anthropic";
import { readFileSync } from "node:fs";

const store = new SqliteStore("./eidentic.sqlite");
const memory = new Memory({ store });

const agent = new Agent({
  id: "support",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store,
  memory,
});

// Ingest a local Markdown file
const raw = readFileSync("./docs/faq.md", "utf8");
const doc = loadMarkdown(raw, { source: "faq.md" });
const chunks = chunkText(doc.text, { size: 512, overlap: 64 });
// or use ingestDocument directly:
await ingestDocument(
  { type: "markdown", data: raw, source: "faq.md" },
  { memory, scope: { kind: "agent", agentId: "support" } },
);

// Ingest a live URL
await ingestDocument(
  { url: "https://docs.example.com/api" },
  { memory, scope: { kind: "agent", agentId: "support" } },
);
```

--------------------------------

### Deno Setup with npm Specifiers

Source: https://github.com/eidentic/docs/blob/main/docs/guides/runtimes.md

Illustrates how to import Eidentic core packages in Deno using npm specifiers directly in import statements.

```typescript
import { Agent } from "npm:@eidentic/core";
import { AIModel } from "npm:@eidentic/model";
import { LibsqlStore } from "npm:@eidentic/libsql";
```

--------------------------------

### Deno Deploy Agent Setup

Source: https://github.com/eidentic/docs/blob/main/docs/guides/deployment.md

Set up an Eidentic agent for deployment on Deno Deploy. Uses environment variables for configuration.

```typescript
// main.ts
import { Agent } from "npm:@eidentic/core";
import { AIModel } from "npm:@eidentic/model";
import { LibsqlStore } from "npm:@eidentic/libsql";
import { anthropic } from "npm:@ai-sdk/anthropic";

const store = new LibsqlStore({
  url: Deno.env.get("LIBSQL_URL")!,
  authToken: Deno.env.get("LIBSQL_TOKEN"),
});
await store.migrate();

const agent = new Agent({
  id: "support",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store,
});

Deno.serve(async (req) => {
  const { input, sessionId } = await req.json();
  const stream = new ReadableStream({
    async start(c) {
      const enc = new TextEncoder();
      for await (const ev of agent.query(input, { sessionId, signal: req.signal })) {
        c.enqueue(enc.encode(JSON.stringify(ev) + "\n"));
      }
      c.close();
    },
  });
  return new Response(stream, { headers: { "Content-Type": "application/x-ndjson" } });
});
```

--------------------------------

### Install Eidentic Packages

Source: https://github.com/eidentic/docs/blob/main/docs/guides/nextjs.md

Install the necessary Eidentic packages for Next.js integration, including the core library, Next.js bindings, and a bundler-safe SQL store.

```bash
npm install eidentic @eidentic/nextjs @eidentic/libsql ai @ai-sdk/anthropic
```

--------------------------------

### Next.js Agent Setup

Source: https://github.com/eidentic/docs/blob/main/docs/guides/deployment.md

Minimal setup for an Eidentic agent within a Next.js application. Uses a local or remote libsql database.

```typescript
// lib/agent.ts
import { Agent, AIModel } from "@eidentic/core";
import { LibsqlStore } from "@eidentic/libsql";
import { anthropic } from "@ai-sdk/anthropic";

const store = new LibsqlStore(process.env.LIBSQL_URL ?? "file:eidentic.db");
await store.migrate();

export const agent = new Agent({
  id: "support",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store,
});
```

--------------------------------

### Install AIEmbedder Package

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/embedders.md

Install the `@eidentic/model` package along with an AI SDK provider like `@ai-sdk/openai`. This is required for using hosted AI embedding models.

```bash
npm install @eidentic/model ai @ai-sdk/openai
# or any other @ai-sdk/* provider
```

--------------------------------

### Langfuse Tracer Integration Example

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/tracing.md

Demonstrates setting up the Langfuse tracer and passing it to the Eidentic Agent. Includes agent initialization, query execution, and tracer shutdown for flushing spans.

```typescript
import { Agent } from "@eidentic/core";
import { langfuseTracer } from "@eidentic/langfuse";
import { AIModel } from "@eidentic/model";
import { SqliteStore } from "@eidentic/sqlite";
import { openai } from "@ai-sdk/openai";

const model = new AIModel(openai("gpt-4o-mini"));
const store = await SqliteStore.create("./eidentic.sqlite");

const tracer = langfuseTracer({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  // Optional — defaults to https://cloud.langfuse.com (EU)
  // baseUrl: "https://us.cloud.langfuse.com",
});

const agent = new Agent({
  id: "my-agent",
  model,
  store,
  tracer,
});

for await (const event of agent.query("Hello!")) {
  if (event.type === "result") console.log(event.output);
}

// Flush remaining spans and cancel the auto-flush timer on process exit.
await tracer.shutdown();
```

--------------------------------

### Consuming Streaming Agent Output

Source: https://github.com/eidentic/docs/blob/main/docs/concepts/agent-loop.md

Example of how to instantiate an Agent and consume its streaming output from `agent.query()`, printing token deltas and final usage information.

```typescript
import { Agent, AIModel, SqliteStore } from "eidentic";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new Agent({
  id: "assistant",
  instructions: "You are a helpful assistant.",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store: new SqliteStore("./eidentic.sqlite"),
});

process.stdout.write("assistant: ");
for await (const ev of agent.query("Say hello.", { sessionId: "s1" })) {
  if (ev.type === "stream.delta") process.stdout.write(ev.delta.text);
  if (ev.type === "result") console.log("\nusage:", ev.usage);
}
```

--------------------------------

### Install @eidentic/langfuse Adapter

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/tracing.md

Command to add the Langfuse adapter for Eidentic tracing to your project dependencies.

```bash
pnpm add @eidentic/langfuse
```

--------------------------------

### Expose Tools with createMcpServer (Stdio and HTTP)

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/mcp.md

Use createMcpServer to expose local Eidentic tools via MCP. This example shows how to register file tools and then serve them over stdio or HTTP.

```typescript
import { createMcpServer } from "@eidentic/mcp";
import { fileTools } from "@eidentic/tools";

const handle = await createMcpServer(
  fileTools({ root: process.cwd() }),
  { name: "my-tools", version: "1.0.0" },
);

// Wire into stdio (for Claude Desktop or npx-style servers):
await handle.serveStdio(); // blocks

// Or over Streamable HTTP:
import { createServer } from "node:http";
import { randomUUID } from "node:crypto";
const { handleRequest } = handle.serveHttp({ sessionIdGenerator: () => randomUUID() });
createServer((req, res) => handleRequest(req, res)).listen(3000);
```

--------------------------------

### Multi-tenant Session Authentication

Source: https://github.com/eidentic/docs/blob/main/docs/guides/deployment.md

Example of setting up API key authentication for multi-tenant sessions with Eidentic.

```typescript
const app = createServer({
  agents: { support: agent },
  auth: ApiKeyAuth({
    [process.env.TENANT_A_KEY!]: { userId: "tenant-a" },
    [process.env.TENANT_B_KEY!]: { userId: "tenant-b" },
  }),
});
```

--------------------------------

### Starting Sleep-time Consolidation Scheduler

Source: https://github.com/eidentic/docs/blob/main/docs/guides/memory.md

This snippet shows how to initialize and start a ConsolidationScheduler for background distillation of raw episodes into durable summary facts. It uses a fast/cheap model and is grounded in actual conversation history.

```typescript
import { ConsolidationScheduler } from "@eidentic/memory";

const scheduler = new ConsolidationScheduler({
  memory,
  model: new AIModel(anthropic("claude-haiku-4-5")), // use a fast/cheap model
  intervalMs: 5 * 60 * 1000, // every 5 minutes
});

scheduler.start();
```

--------------------------------

### Initialize Memory with Graph Backend

Source: https://github.com/eidentic/docs/blob/main/docs/guides/memory-governance.md

Instantiate the Memory class with a SqliteStore and a graph backend. This setup is required for all APIs on this page.

```typescript
import { Memory } from "@eidentic/memory";
import { SqliteStore } from "eidentic";

const memory = new Memory({ store: new SqliteStore("./eidentic.sqlite"), graph: store });
```

--------------------------------

### Per-Session History Example

Source: https://github.com/eidentic/docs/blob/main/docs/guides/memory.md

This snippet demonstrates how per-session history works by continuing a conversation using the same sessionId. No extra setup is required as the store persists the event log automatically.

```typescript
// Same sessionId → agent sees the full prior conversation
for await (const ev of agent.query("Remind me what we discussed.", {
  sessionId: "user-42-support",
}));
```

--------------------------------

### Per-User Cross-Session Memory Setup

Source: https://github.com/eidentic/docs/blob/main/docs/guides/memory.md

This code sets up an agent with a SqliteStore and a Memory instance, enabling per-user cross-session memory. A userId must be provided at query time to activate this feature.

```typescript
import { Agent, AIModel, SqliteStore } from "eidentic";
import { Memory } from "@eidentic/memory";
import { anthropic } from "@ai-sdk/anthropic";

const store = new SqliteStore("./eidentic.sqlite");

const agent = new Agent({
  id: "assistant",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store,
  memory: new Memory({ store }),
});
```

--------------------------------

### Quick Start with Playwright and Browser Tools

Source: https://github.com/eidentic/docs/blob/main/docs/guides/browser-tools.md

Demonstrates how to launch Playwright, create a new page, and initialize an agent with browser tools. The agent then queries a URL and processes the text delta results.

```typescript
import { chromium } from "playwright-core";
import { browserTools } from "@eidentic/browser";
import { Agent } from "eidentic";

const browser = await chromium.launch();
const page = await browser.newPage();

const agent = new Agent({
  id: "web-agent",
  model,
  store,
  tools: browserTools(page, {
    allowlist: ["docs.example.com", "api.example.com"],
  }),
});

for await (const ev of agent.query("Summarise the pricing page at https://docs.example.com/pricing", { sessionId: "s1" })) {
  if (ev.type === "text_delta") process.stdout.write(ev.delta);
}

await browser.close();
```

--------------------------------

### Install @eidentic/rag

Source: https://github.com/eidentic/docs/blob/main/docs/guides/citations.md

Install the @eidentic/rag package using npm.

```bash
npm install @eidentic/rag
```

--------------------------------

### Install @eidentic/rag

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/rag.md

Install the core @eidentic/rag package using npm.

```bash
npm install @eidentic/rag
```

--------------------------------

### Open Eidentic Studio

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Launch the local Studio dashboard using `eidentic studio`. This tool is for development only and provides a visual interface for project assets.

```bash
eidentic studio
```

--------------------------------

### Configure Web Tools with Allowlist and Search Provider

Source: https://github.com/eidentic/docs/blob/main/docs/guides/tools.md

Set up web tools, specifying allowed hosts and a custom search provider.

```typescript
import { webTools } from "@eidentic/tools";

const agent = new Agent({
  // ...
  tools: webTools({
    allowlist: ["docs.example.com", "api.example.com"],
    searchProvider: mySearchProvider,
  }),
});
```

--------------------------------

### Expose Tools and Agent with mcpServer

Source: https://github.com/eidentic/docs/blob/main/docs/integrations/mcp.md

Use the recommended mcpServer API to expose local tools and an optional agent. This example demonstrates exposing tools and an agent, enabling destructive actions, and serving over stdio.

```typescript
import { mcpServer } from "@eidentic/mcp";

const handle = await mcpServer({
  tools: myTools,
  agent: myAgent,
  agentId: "support",
  agentDescription: "Customer support agent.",
  allowDestructive: true, // required to expose the agent tool
  name: "support-server",
  version: "1.0.0",
});
await handle.serveStdio();
```

--------------------------------

### Initializing and Migrating SqliteStore

Source: https://github.com/eidentic/docs/blob/main/docs/concepts/sessions.md

Demonstrates how to initialize a SqliteStore and run schema migrations. The migrate() function is idempotent and safe to re-run, ensuring the database schema is up-to-date.

```typescript
const store = new SqliteStore("./eidentic.sqlite");
await store.migrate(); // forward-only schema migrations, safe to re-run
```

--------------------------------

### Initialize Eidentic in Existing Project

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Use `eidentic init` to scaffold Eidentic configuration files into an existing project directory. This command is idempotent and will not overwrite existing files.

```bash
eidentic init
```

--------------------------------

### Webhook Completion Notification Example

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-hardening.md

Example of the JSON payload sent by the server to the callbackUrl upon run completion.

```json
{
  "runId": "…",
  "agentId": "support",
  "status": "completed",
  "output": "…",
  "usage": { "inputTokens": 120, "outputTokens": 80 }
}
```

--------------------------------

### Webhook Request Body Example

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-hardening.md

Example of a client request body for an async run, including the callbackUrl for webhook notifications.

```json
{ "input": "Summarise Q3", "callbackUrl": "https://yourapp.com/webhooks/eidentic" }
```

--------------------------------

### Configure Web Search Providers

Source: https://github.com/eidentic/docs/blob/main/docs/guides/tools.md

Set up a web search provider, either by auto-detecting from environment variables or configuring explicitly.

```typescript
import {
  tavilySearch,
  exaSearch,
  serperSearch,
  searxngSearch,
  webSearchFromEnv,
} from "@eidentic/tools";

// Auto-detect from environment variables:
const provider = webSearchFromEnv();
//   TAVILY_API_KEY → tavilySearch
//   EXA_API_KEY    → exaSearch
//   SERPER_API_KEY → serperSearch

// Or configure explicitly:
const provider = tavilySearch({ apiKey: process.env.TAVILY_API_KEY! });
```

--------------------------------

### Install LocalEmbedder Package

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/embedders.md

Install the `@eidentic/transformers` package along with `@huggingface/transformers`. This is necessary for using on-device, local embedding and reranking models.

```bash
npm install @eidentic/transformers @huggingface/transformers
```

--------------------------------

### Configure Agent with Permission Policy

Source: https://github.com/eidentic/docs/blob/main/docs/concepts/permissions.md

Set up an agent with a default permission policy that denies tools starting with 'delete_' and allows tools starting with 'read_'.

```typescript
import {
  Agent,
} from "@eidentic/core";

const agent = new Agent({
  id: "assistant",
  model,
  store,
  tools: [readFile, deleteFile, sendEmail],
  permissions: {
    mode: "default",
    deny: ["delete_*"],
    allow: ["read_*"],
  },
});
```

--------------------------------

### Prompt Skills with SkillSet

Source: https://github.com/eidentic/docs/blob/main/docs/memory/skills.md

Initialize an agent with a SkillSet that loads SKILL.md files from a directory.

```typescript
import { Agent } from "@eidentic/core";
import { SkillSet } from "@eidentic/skills";
import { SqliteStore } from "@eidentic/sqlite";
import { AIModel } from "@eidentic/model";
import { anthropic } from "@ai-sdk/anthropic";

const store = await SqliteStore.create("./eidentic.sqlite");
const model = new AIModel(anthropic("claude-sonnet-4-5"));

const skills = new SkillSet("./skills");  // directory of SKILL.md files

const agent = new Agent({
  id: "my-agent",
  instructions: "Help the user.",
  model,
  store,
  skills,
});
```

--------------------------------

### Edge-Safe à la Carte Setup

Source: https://github.com/eidentic/docs/blob/main/docs/guides/runtimes.md

Shows how to compose Eidentic directly from individual packages for Deno, Cloudflare Workers, or other edge runtimes. This setup avoids the umbrella package and uses pure-JS/HTTP-only modules.

```typescript
import { Agent } from "@eidentic/core";
import { AIModel } from "@eidentic/model";
import { LibsqlStore } from "@eidentic/libsql"; // or PostgresStore from @eidentic/postgres
import { anthropic } from "@ai-sdk/anthropic";

const agent = new Agent({
  id: "edge-agent",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store: new LibsqlStore(process.env.LIBSQL_URL!),
});
```

--------------------------------

### Initiating and Monitoring Background Jobs

Source: https://github.com/eidentic/docs/blob/main/docs/guides/building-your-own-ui.md

Use the `useAsyncRun` hook to start and monitor background jobs. It provides status, output, error handling, and polling state. The `start` function takes job-specific parameters.

```tsx
import { useAsyncRun } from "@eidentic/react";

export function BackgroundJob() {
  const { start, status, output, error, isPolling } = useAsyncRun("research-agent");

  return (
    <div>
      <button
        onClick={() => start({ topic: "quantum computing" })}
        disabled={isPolling}
      >
        Start
      </button>
      <p>Status: {status}</p>
      {status === "completed" && <pre>{JSON.stringify(output, null, 2)}</pre>}
      {error && <p style={{ color: "red" }}>{error}</p>}
    </div>
  );
}

```

--------------------------------

### Inject Ephemeral Context with onTurnStart

Source: https://github.com/eidentic/docs/blob/main/docs/guides/agent-hooks.md

Use `onTurnStart` to inject dynamic context into the system prompt for a single turn. The injected context is not persisted. Return a string or an array of strings; void or undefined suppresses injection.

```typescript
const agent = new Agent({
  id: "assistant",
  model,
  store,
  onTurnStart: async ({ turn, sessionId }) => {
    const userPrefs = await prefs.load(sessionId);
    return `User preferences: ${JSON.stringify(userPrefs)}`;
  },
});
```

--------------------------------

### Add React UI Component

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Copies a pre-built React UI component into your src/components directory. Use `--list` to see available components and `--overwrite` to replace existing ones.

```bash
eidentic add component --list          # show available components
eidentic add component chat            # chat bubble UI
eidentic add component workflow-trace  # step-trace visualisation
eidentic add component run-status      # async run status card
eidentic add component chat --overwrite  # replace existing
```

--------------------------------

### Using Built-in Tool Set

Source: https://github.com/eidentic/docs/blob/main/docs/examples.md

Demonstrates the use of built-in tools like `fileTools`, `bashTool`, and `webTools`, including enforcement of allowlists and sandboxing.

```typescript
import { Agent } from "@eidentic/agent"
import { fileTools, bashTool, webTools } from "@eidentic/tools"

const agent = new Agent({
  model: new MockModel(),
  tools: [fileTools, bashTool, webTools],
})

await agent.chat("List files in the current directory.")
```

--------------------------------

### Use Eidentic CLI with npx

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-studio.md

Execute Eidentic CLI commands using npx without global installation.

```bash
npx eidentic studio
```

```bash
npx eidentic dev
```

--------------------------------

### Create a New Eidentic Project

Source: https://github.com/eidentic/docs/blob/main/docs/scaffold.md

Use `npm create` or `npx create` to scaffold a new Eidentic project. Follow the interactive prompts to select a model provider and project template.

```bash
npm create eidentic@latest my-agent
# or
npx create-eidentic my-agent
```

--------------------------------

### Initialize ConvexStore with ConvexHttpClient

Source: https://github.com/eidentic/docs/blob/main/docs/adapters/stores.md

Initialize the ConvexStore by creating a ConvexHttpClient and a runner. The store implements StorePort, GraphPort, and DurablePort for data management.

```typescript
import { ConvexHttpClient } from "convex/browser";
import { ConvexStore, convexHttpRunner } from "@eidentic/convex";

const client = new ConvexHttpClient(process.env.CONVEX_URL!);
const runner = convexHttpRunner(client);

const store = new ConvexStore(runner); // StorePort, GraphPort & DurablePort
```

--------------------------------

### Configure OpenTelemetry SDK

Source: https://github.com/eidentic/docs/blob/main/docs/guides/deployment.md

Set up the OpenTelemetry Node.js SDK with an OTLP exporter to send traces to a backend. Ensure the OTLP endpoint is correctly configured.

```typescript
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
  }),
});
sdk.start();
```

--------------------------------

### Configure CORS Options

Source: https://github.com/eidentic/docs/blob/main/docs/guides/server-hardening.md

Set CORS options to control cross-origin requests. The example configures a specific origin and allows credentials.

```typescript
const app = createServer({
  agents: { support: agent },
  cors: { origin: "https://app.example.com", credentials: true },
  // cors: { origin: "*" }  // for public unauthenticated APIs only
});
```

--------------------------------

### Structured Output with Tools

Source: https://github.com/eidentic/docs/blob/main/docs/guides/structured-output.md

Shows how to combine `outputSchema` with an agent that has tools defined. The final assistant turn is constrained by the schema, while tool calls occur on intermediate turns.

```typescript
import { webTools } from "@eidentic/tools";

const researchAgent = new Agent({
  id: "researcher",
  model: new AIModel(anthropic("claude-sonnet-4-5")),
  store: new SqliteStore("./eidentic.sqlite"),
  tools: webTools({ searchProvider: mySearchProvider }),
});

const reportSchema = z.object({
  title: z.string(),
  findings: z.array(z.string()),
  sources: z.array(z.string().url()),
});

for await (const ev of researchAgent.query(
  "Research the latest developments in edge AI inference.",
  { sessionId: "s-2", outputSchema: reportSchema }
)) {
  if (ev.type === "result" && ev.subtype === "success") {
    console.log(ev.object.findings);
  }
}

```