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
TheApiLoader 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:| 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 theagentmark dev server:
| 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 tocreateAgentMark and the client renders each prompt to the neutral shape ({ messages, text_config }); your code or an executor calls the model.
ApiLoader.cloud when AGENTMARK_API_KEY is present, ApiLoader.local otherwise).
Caching
TheApiLoader includes built-in caching. You can customize caching behavior when loading prompts:
Loading datasets
TheApiLoader can also stream datasets for experiments:
FileLoader
TheFileLoader 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:Usage
| Parameter | Type | Description |
|---|---|---|
builtDir | string | Path to the directory containing built prompt JSON files |
Path resolution
TheFileLoader accepts prompt paths with or without extensions:
Usage with client
Pass it tocreateAgentMark({ loader }) exactly like ApiLoader. See Client setup.
Loading datasets
TheFileLoader can also load dataset files (.jsonl):
Security
TheFileLoader 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
- Fast development iteration
- Hot reloading with
agentmark dev - No AgentMark authentication required
- Zero network latency
- Works offline / air-gapped
- Requires rebuild for prompt changes
- Smaller bundle (no API client code)
Have questions?
Reach out any time:
- Email the team at hello@agentmark.co for support
- Schedule an Enterprise Demo to learn about AgentMark’s business solutions