> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Loaders

> Load prompts from different sources using ApiLoader and FileLoader

AgentMark provides two loader implementations for fetching prompts: `ApiLoader` for API-based loading and `FileLoader` for static file loading.

| Loader       | Package                                 | Use case                                              |
| ------------ | --------------------------------------- | ----------------------------------------------------- |
| `ApiLoader`  | `@agentmark-ai/prompt-core/loader-api`  | Cloud deployment or local development with dev server |
| `FileLoader` | `@agentmark-ai/prompt-core/loader-file` | Self-hosted/static deployment with pre-built prompts  |

***

## ApiLoader

The `ApiLoader` fetches prompts from the AgentMark API (Cloud) or a local development server.

### Installation

```bash theme={null}
npm install @agentmark-ai/prompt-core
```

### Cloud mode (production)

Use Cloud mode when deploying to production with AgentMark Cloud:

```typescript theme={null}
import { ApiLoader } from "@agentmark-ai/prompt-core/loader-api";

const loader = ApiLoader.cloud({
  apiKey: process.env.AGENTMARK_API_KEY!,
  appId: process.env.AGENTMARK_APP_ID!,
  baseUrl: "https://api.agentmark.co", // optional, this is the default
});
```

**Configuration:**

| Option    | Type     | Required | Description                                        |
| --------- | -------- | -------- | -------------------------------------------------- |
| `apiKey`  | `string` | Yes      | Your AgentMark API key                             |
| `appId`   | `string` | Yes      | Your AgentMark application ID                      |
| `baseUrl` | `string` | No       | API base URL (default: `https://api.agentmark.co`) |

### Local mode (development)

Use local mode during development with the `agentmark dev` server:

```typescript theme={null}
import { ApiLoader } from "@agentmark-ai/prompt-core/loader-api";

const loader = ApiLoader.local({
  baseUrl: "http://localhost:9418",
});
```

**Configuration:**

| Option    | Type     | Required | Description                                                                                             |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `baseUrl` | `string` | Yes      | Local dev server URL. `agentmark dev` binds to `9418` by default (override with the `--api-port` flag). |

### Usage with client

Pass the loader to `createAgentMark` and the client renders each prompt to the neutral shape (`{ messages, text_config }`); your code or an [executor](/getting-started/client-setup#connect-your-sdk) calls the model.

```typescript theme={null}
const client = createAgentMark({ loader });
```

See [Client setup](/getting-started/client-setup) for the full client setup, including selecting the loader by environment (`ApiLoader.cloud` when `AGENTMARK_API_KEY` is present, `ApiLoader.local` otherwise).

### Caching

The `ApiLoader` includes built-in caching. You can customize caching behavior when loading prompts:

```typescript theme={null}
// With custom cache TTL
const ast = await loader.load("prompt.prompt.mdx", "text", {
  cache: { ttl: 1000 * 60 * 5 }, // 5 minutes
});

// Disable caching
const ast = await loader.load("prompt.prompt.mdx", "text", {
  cache: false,
});
```

### Loading datasets

The `ApiLoader` can also stream datasets for experiments:

```typescript theme={null}
const stream = await loader.loadDataset("my-dataset.jsonl");

const reader = stream.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(value.input, value.expected_output);
}
```

***

## FileLoader

The `FileLoader` loads pre-built prompts from JSON files generated by `agentmark build`. Use this for self-hosted deployments where you don't want runtime API calls.

### Installation

```bash theme={null}
npm install @agentmark-ai/prompt-core
```

### Building prompts

First, compile your prompts using the CLI:

```bash theme={null}
agentmark build --out ./dist/agentmark
```

This creates JSON files containing pre-parsed ASTs:

```text theme={null}
dist/agentmark/
  manifest.json
  greeting.prompt.json
  nested/
    helper.prompt.json
```

### Usage

```typescript theme={null}
import { FileLoader } from "@agentmark-ai/prompt-core/loader-file";

// Point to the build output directory
const loader = new FileLoader("./dist/agentmark");
```

**Configuration:**

| Parameter  | Type     | Description                                              |
| ---------- | -------- | -------------------------------------------------------- |
| `builtDir` | `string` | Path to the directory containing built prompt JSON files |

### Path resolution

The `FileLoader` accepts prompt paths with or without extensions:

```typescript theme={null}
// All of these work:
await client.loadTextPrompt("greeting");
await client.loadTextPrompt("greeting.prompt");
await client.loadTextPrompt("greeting.prompt.mdx");
```

### Usage with client

Pass it to `createAgentMark({ loader })` exactly like `ApiLoader`. See [Client setup](/getting-started/client-setup).

### Loading datasets

The `FileLoader` can also load dataset files (`.jsonl`):

```typescript theme={null}
const stream = await loader.loadDataset("test-data.jsonl");

const reader = stream.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(value.input, value.expected_output);
}
```

### Security

The `FileLoader` includes path traversal protection:

* Rejects absolute paths
* Validates that resolved paths stay within the base directory
* Prevents access to files outside the build directory

***

## Choosing a loader

| Scenario                                       | Recommended loader  |
| ---------------------------------------------- | ------------------- |
| Production with AgentMark Cloud                | `ApiLoader.cloud()` |
| Local development                              | `ApiLoader.local()` |
| Self-hosted / edge deployment                  | `FileLoader`        |
| Serverless functions (cold-start optimization) | `FileLoader`        |
| Air-gapped environments                        | `FileLoader`        |

### Trade-offs

**ApiLoader (Cloud)**

* Prompts managed in AgentMark Cloud
* Real-time updates without redeployment
* Requires network connectivity to AgentMark
* Built-in caching

**ApiLoader (local)**

* Fast development iteration
* Hot reloading with `agentmark dev`
* No AgentMark authentication required

**FileLoader**

* Zero network latency
* Works offline / air-gapped
* Requires rebuild for prompt changes
* Smaller bundle (no API client code)

<div className="mt-8 rounded-lg bg-blue-50 p-6 dark:bg-blue-900/30">
  <h3 className="font-semibold mb-3">Have questions?</h3>
  <p className="mb-4">Reach out any time:</p>

  <ul>
    <li>
      Email the team at <a href="mailto:hello@agentmark.co" className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-200">[hello@agentmark.co](mailto:hello@agentmark.co)</a> for support
    </li>

    <li>
      Schedule an <a href="https://cal.com/ryan-randall/enterprise" className="text-blue-600 hover:text-blue-800 dark:text-blue-400 dark:hover:text-blue-200">Enterprise Demo</a> to learn about AgentMark's business solutions
    </li>
  </ul>
</div>