Skip to main content
AgentMark provides two loader implementations for fetching prompts: ApiLoader for API-based loading and FileLoader for static file loading.

ApiLoader

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

Installation

Cloud mode (production)

Use Cloud mode when deploying to production with AgentMark Cloud:
Configuration:

Local mode (development)

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

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.
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:

Loading datasets

The ApiLoader can also stream datasets for experiments:

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

Building prompts

First, compile your prompts using the CLI:
This creates JSON files containing pre-parsed ASTs:

Usage

Configuration:

Path resolution

The FileLoader accepts prompt paths with or without extensions:

Usage with client

Pass it to createAgentMark({ loader }) exactly like ApiLoader. See Client setup.

Loading datasets

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

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

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: