Skip to main content
AgentMark provides two loader implementations for fetching prompts: ApiLoader for API-based loading and FileLoader for static file loading.
LoaderPackageUse case
ApiLoader@agentmark-ai/prompt-core/loader-apiCloud deployment or local development with dev server
FileLoader@agentmark-ai/prompt-core/loader-fileSelf-hosted/static deployment with pre-built prompts

ApiLoader

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

Installation

npm install @agentmark-ai/prompt-core

Cloud mode (production)

Use Cloud mode when deploying to production with AgentMark Cloud:
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:
OptionTypeRequiredDescription
apiKeystringYesYour AgentMark API key
appIdstringYesYour AgentMark application ID
baseUrlstringNoAPI base URL (default: https://api.agentmark.co)

Local mode (development)

Use local mode during development with the agentmark dev server:
import { ApiLoader } from "@agentmark-ai/prompt-core/loader-api";

const loader = ApiLoader.local({
  baseUrl: "http://localhost:9418",
});
Configuration:
OptionTypeRequiredDescription
baseUrlstringYesLocal 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 calls the model.
const client = createAgentMark({ loader });
See 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:
// 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:
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

npm install @agentmark-ai/prompt-core

Building prompts

First, compile your prompts using the CLI:
agentmark build --out ./dist/agentmark
This creates JSON files containing pre-parsed ASTs:
dist/agentmark/
  manifest.json
  greeting.prompt.json
  nested/
    helper.prompt.json

Usage

import { FileLoader } from "@agentmark-ai/prompt-core/loader-file";

// Point to the build output directory
const loader = new FileLoader("./dist/agentmark");
Configuration:
ParameterTypeDescription
builtDirstringPath to the directory containing built prompt JSON files

Path resolution

The FileLoader accepts prompt paths with or without extensions:
// 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.

Loading datasets

The FileLoader can also load dataset files (.jsonl):
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

ScenarioRecommended loader
Production with AgentMark CloudApiLoader.cloud()
Local developmentApiLoader.local()
Self-hosted / edge deploymentFileLoader
Serverless functions (cold-start optimization)FileLoader
Air-gapped environmentsFileLoader

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)

Have questions?

Reach out any time: