AgentMark provides full Python support with multiple adapter options. Python projects benefit from the same prompt management, testing, and observability features as TypeScript projects.
Getting Started
The fastest way to create a Python project:
npm create agentmark@latest my-app
# Select "Python" when prompted for language
# Select your adapter: Pydantic AI or Claude Agent SDK
Project Structure
A Python AgentMark project has this structure:
my-app/
├── agentmark/ # Prompt files
│ └── prompts/
│ └── party-planner.prompt.mdx
├── agentmark_client.py # Python client configuration
├── main.py # Application entry point
├── .agentmark/
│ └── dev_server.py # Auto-generated dev server
├── pyproject.toml # Python dependencies
├── agentmark.json # AgentMark configuration
└── .env # Environment variables
Supported Adapters
Choose the adapter that fits your use case:
| Adapter | Best For | Features |
|---|
| Pydantic AI | Type-safe LLM apps | Multi-model support, structured output, streaming |
| Claude Agent SDK | Agentic tasks | Tool use, multi-turn reasoning, budget controls |
Client Configuration
All Python projects require an agentmark_client.py file that configures the AgentMark client:
from pathlib import Path
from dotenv import load_dotenv
from agentmark.prompt_core import FileLoader
from agentmark_pydantic_ai_v0 import (
create_pydantic_ai_client,
create_default_model_registry,
PydanticAIToolRegistry,
)
load_dotenv()
model_registry = create_default_model_registry()
tool_registry = PydanticAIToolRegistry()
loader = FileLoader(base_dir=str(Path(__file__).parent.resolve()))
client = create_pydantic_ai_client(
model_registry=model_registry,
tool_registry=tool_registry,
loader=loader,
)
Running the Dev Server
Start the development server:
The CLI automatically detects Python projects via:
pyproject.tomlagentmark_client.py.agentmark/dev_server.py
See Dev Server for configuration options.
Python SDK
The agentmark-sdk package provides observability utilities for Python applications:
pip install agentmark-sdk
SDK Exports
from agentmark_sdk import (
# Core SDK class
AgentMarkSDK,
# Tracing utilities
trace, # Trace an async operation
trace_context, # Context manager for tracing
TraceOptions, # Configuration for traces
TraceContext, # Context passed to traced functions
TraceResult, # Result with trace_id
# Sampler for filtering spans
AgentmarkSampler,
)
Initializing Tracing
from agentmark_sdk import AgentMarkSDK, trace, TraceOptions
# Initialize the SDK
sdk = AgentMarkSDK(
api_key="sk-...",
app_id="app_123",
)
sdk.init_tracing()
# Trace an operation
result = await trace(
TraceOptions(name="my-operation", user_id="user-1"),
my_async_function,
)
# Submit a score
await sdk.score(
resource_id=result.trace_id,
name="accuracy",
score=0.95,
)
TraceOptions
Configure tracing with these options:
| Option | Type | Description |
|---|
name | str | Name of the trace/span (required) |
metadata | dict[str, str] | Additional key-value pairs |
session_id | str | Session identifier for grouping |
session_name | str | Human-readable session name |
user_id | str | User identifier |
dataset_run_id | str | Dataset run ID (for experiments) |
dataset_run_name | str | Dataset run name |
dataset_item_name | str | Dataset item name |
dataset_expected_output | str | Expected output for comparison |
Context Manager API
For more control over the span lifecycle:
from agentmark_sdk import trace_context, TraceOptions
async with trace_context(TraceOptions(name="my-operation")) as ctx:
print(f"Trace ID: {ctx.trace_id}")
# Add custom attributes
ctx.set_attribute("custom_key", "value")
# Add events
ctx.add_event("checkpoint", {"step": 1})
# Create child spans
async with ctx.span("sub-operation") as child:
result = await perform_step()
Requirements
- Python 3.12 or higher
- Node.js (for CLI and dev server orchestration)
- API keys for your chosen model provider
Next Steps
Have Questions?
We’re here to help! Choose the best way to reach us:
