Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt

Use this file to discover all available pages before exploring further.

The AgentMark client is configured in agentmark_client.py. It connects your prompts to AI models, tools, and prompt loading. This file is auto-generated by npm create agentmark@latest when you select Python.

​
Installation

pip install agentmark-pydantic-ai-v0 agentmark-prompt-core
Package vs import names:
  • agentmark-prompt-core → from agentmark.prompt_core import ApiLoader, FileLoader
  • agentmark-pydantic-ai-v0 → from agentmark_pydantic_ai_v0 import ...
ApiLoader ships with agentmark-prompt-core — there’s no separate agentmark-loader-api PyPI package.

​
Configuration

The Python adapter does not ship a default registry — register providers explicitly. The "<provider>:<model>" string format tells Pydantic AI which provider to use at runtime:
agentmark_client.py
import os
from dotenv import load_dotenv
from agentmark.prompt_core import ApiLoader
from agentmark_pydantic_ai_v0 import (
    create_pydantic_ai_client,
    PydanticAIModelRegistry,
)

load_dotenv()

model_registry = PydanticAIModelRegistry()
model_registry.register_models(
    ["gpt-4o", "gpt-4o-mini"],
    lambda name, opts=None: f"openai:{name}",
)
model_registry.register_models(
    ["claude-sonnet-4-20250514"],
    lambda name, opts=None: f"anthropic:{name}",
)

if os.getenv("NODE_ENV") == "development":
    loader = ApiLoader.local(
        base_url=os.getenv("AGENTMARK_BASE_URL", "http://localhost:9418")
    )
else:
    loader = ApiLoader.cloud(
        api_key=os.environ["AGENTMARK_API_KEY"],
        app_id=os.environ["AGENTMARK_APP_ID"],
    )

client = create_pydantic_ai_client(
    model_registry=model_registry,
    loader=loader,
)

​
Model registry

PydanticAIModelRegistry.register_models(pattern, creator) accepts an exact string, a re.Pattern, or a list of strings. The creator returns either a "<provider>:<model>" string or a Pydantic AI Model instance. Use set_default(creator) for a fallback: 
import re
from agentmark_pydantic_ai_v0 import PydanticAIModelRegistry

model_registry = PydanticAIModelRegistry()

# Exact matches
model_registry.register_models(
    ["gpt-4o", "gpt-4o-mini"],
    lambda name, opts=None: f"openai:{name}",
)

# Regex pattern
model_registry.register_models(
    re.compile(r"^claude-"),
    lambda name, opts=None: f"anthropic:{name}",
)

# Fallback for unmatched names
model_registry.set_default(lambda name, opts=None: name)
Model names in the registry must match the model_name in your prompt frontmatter.

​
Prompt loading

The loader determines how prompts are fetched at runtime: 
from agentmark.prompt_core import ApiLoader

# Local — loads from dev server (development)
loader = ApiLoader.local(base_url="http://localhost:9418")

# Cloud — loads from the AgentMark HTTP API (production)
loader = ApiLoader.cloud(
    api_key=os.environ["AGENTMARK_API_KEY"],
    app_id=os.environ["AGENTMARK_APP_ID"],
)
Prompts are cached in-process in-memory for repeated loads within a process.

​
Running prompts

from agentmark_client import client
from agentmark_pydantic_ai_v0 import run_text_prompt

prompt = await client.load_text_prompt("greeting.prompt.mdx")
params = await prompt.format(props={"name": "Alice"})

result = await run_text_prompt(params)
print(result.output)

​
Dev server

Start the Python dev server for local development: 
npx agentmark dev
This starts the local API server on port 9418 and the local dev server UI on port 3000. See Dev server for configuration options.

​
Evals

You can register evaluation functions to score prompt outputs during experiments. Pass an evals dictionary of plain functions:
agentmark_client.py
from agentmark.prompt_core import EvalParams, EvalResult

evals = {
    "exact_match": lambda params: {
        "passed": params["output"] == params.get("expectedOutput"),
    },
}

client = create_pydantic_ai_client(
    model_registry=model_registry,
    loader=loader,
    evals=evals,
)
Score schemas are defined separately in agentmark.json and synced to AgentMark Cloud. Eval functions are connected to scores by name. See Evaluations for the full guide on writing eval functions and configuring score schemas.

​
Full reference

For all configuration options (including tools, MCP, and the Claude Agent SDK Python adapter), see Client config.

​
Have Questions?

We’re here to help! Choose the best way to reach us: