Claude Agent SDK - AgentMark Docs

The Claude Agent SDK adapter lets you run AgentMark prompts as agentic tasks using Anthropic’s Claude Agent SDK, with tool use, budget controls, and tracing. Available for both TypeScript and Python; every section below shows both side by side.

The Python adapter (agentmark-claude-agent-sdk-v0) is in alpha. The API surface documented here is stable, but expect occasional changes ahead of the v1 release. For type-safe structured outputs across all major providers, Pydantic AI is the recommended general-purpose Python adapter. Reach for Claude Agent SDK when you specifically need Claude’s agentic capabilities.

Installation

TypeScript
Python

npm install @agentmark-ai/claude-agent-sdk-v0-adapter @anthropic-ai/claude-agent-sdk

pip install agentmark-claude-agent-sdk-v0 agentmark-prompt-core claude-agent-sdk

Set your Anthropic API key:

echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Setup

TypeScript
Python

Create your AgentMark client with a ClaudeAgentModelRegistry. The registry creator is a function that receives the model name and returns a ModelConfig. Use createDefault() for a pass-through registry, or register models explicitly if you need per-model options like maxThinkingTokens:

agentmark.client.ts

import { createAgentMarkClient, ClaudeAgentModelRegistry } from "@agentmark-ai/claude-agent-sdk-v0-adapter";

// Option 1: pass-through registry
const modelRegistry = ClaudeAgentModelRegistry.createDefault();

// Option 2: explicit registration with per-model config
const modelRegistry = new ClaudeAgentModelRegistry()
  .registerModels(["claude-sonnet-4-20250514"], (name) => ({ model: name }))
  .registerModels(["claude-opus-4-20250514"], (name) => ({
    model: name,
    maxThinkingTokens: 10000,
  }));

export const client = createAgentMarkClient({
  loader,
  modelRegistry,
});

The Python adapter does not ship a create_default() / .createDefault(). Register models or providers explicitly so the model names in your prompt frontmatter resolve.The simplest setup registers a provider by prefix (anthropic/...):

agentmark_client.py

from pathlib import Path
from dotenv import load_dotenv
from agentmark.prompt_core import FileLoader
from agentmark_claude_agent_sdk_v0 import (
    create_claude_agent_client,
    ClaudeAgentModelRegistry,
)

load_dotenv()

model_registry = ClaudeAgentModelRegistry()
model_registry.register_providers({"anthropic": "anthropic"})

loader = FileLoader(str(Path(__file__).parent / "dist" / "agentmark"))

client = create_claude_agent_client(
    model_registry=model_registry,
    loader=loader,
)

For per-model options like max_thinking_tokens, register models explicitly with a ModelConfig creator. The creator receives the model name and the run options:

agentmark_client.py

from agentmark_claude_agent_sdk_v0 import (
    create_claude_agent_client,
    ClaudeAgentModelRegistry,
    ModelConfig,
)

model_registry = ClaudeAgentModelRegistry()
model_registry.register_models(
    ["claude-sonnet-4-20250514"],
    lambda name, _: ModelConfig(model=name),
)
model_registry.register_models(
    ["claude-opus-4-20250514"],
    lambda name, _: ModelConfig(model=name, max_thinking_tokens=10000),
)

client = create_claude_agent_client(
    model_registry=model_registry,
    loader=loader,
)

Running prompts

The adapter returns { query: { prompt, options }, messages, telemetry }. Pass adapted.query directly to query() from @anthropic-ai/claude-agent-sdk:

TypeScript
Python

import { client } from "./agentmark.client";
import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = await client.loadTextPrompt("task.prompt.mdx");
const adapted = await prompt.format({
  props: { task: "Analyze the auth module and suggest improvements" },
});

for await (const message of query(adapted.query)) {
  console.log(message);
}

Use traced_query. The run_text_prompt / run_object_prompt functions are Pydantic AI symbols and are not exported by the Claude adapter:

import asyncio
from agentmark_claude_agent_sdk_v0 import traced_query
from agentmark_client import client

async def main():
    prompt = await client.load_text_prompt("code-reviewer.prompt.mdx")
    adapted = await prompt.format(props={
        "task": "Analyze the auth module and suggest improvements"
    })

    async for message in traced_query(adapted):
        print(message)

asyncio.run(main())

Adapter options

Adapter options are configured at client construction time (via createAgentMarkClient), not inside prompt.format(). prompt.format() silently ignores them:

TypeScript
Python

export const client = createAgentMarkClient({
  loader,
  modelRegistry,
  adapterOptions: {
    permissionMode: "bypassPermissions",
    maxTurns: 10,
    cwd: "/path/to/project",
    maxBudgetUsd: 5.00,
    allowedTools: ["Read", "Write", "Bash"],
    disallowedTools: ["WebFetch"],
    systemPromptPreset: false,
    onWarning: (warning) => {
      console.warn("Agent warning:", warning);
    },
  },
});

from agentmark_claude_agent_sdk_v0 import (
    create_claude_agent_client,
    ClaudeAgentAdapterOptions,
)

client = create_claude_agent_client(
    model_registry=model_registry,
    loader=loader,
    adapter_options=ClaudeAgentAdapterOptions(
        permission_mode="bypassPermissions",
        max_turns=10,
        cwd="/path/to/project",
        max_budget_usd=5.00,
        allowed_tools=["Read", "Write", "Bash"],
        disallowed_tools=["WebFetch"],
        system_prompt_preset=False,
        on_warning=lambda w: print(f"Warning: {w}"),
    ),
)

Option	TypeScript	Python	Type / values
Permission mode	`permissionMode`	`permission_mode`	`'default' \| 'acceptEdits' \| 'bypassPermissions' \| 'plan'`
Max turns	`maxTurns`	`max_turns`	`number`
Working directory	`cwd`	`cwd`	`string`
Budget limit	`maxBudgetUsd`	`max_budget_usd`	`number` (USD)
Allowed tools	`allowedTools`	`allowed_tools`	`string[]` (whitelist)
Disallowed tools	`disallowedTools`	`disallowed_tools`	`string[]` (blacklist)
System prompt preset	`systemPromptPreset`	`system_prompt_preset`	`boolean` (use Claude Code’s built-in)
Warning handler	`onWarning`	`on_warning`	`(message: string) => void`

Object generation

For structured output, use object prompts:

TypeScript
Python

import { client } from "./agentmark.client";
import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = await client.loadObjectPrompt("extract.prompt.mdx");
const adapted = await prompt.format({
  props: { text: "This product is amazing!" },
});

for await (const message of query(adapted.query)) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

from agentmark_claude_agent_sdk_v0 import traced_query
from agentmark_client import client

prompt = await client.load_object_prompt("sentiment.prompt.mdx")
adapted = await prompt.format(props={"text": "This product is amazing!"})

async for message in traced_query(adapted):
    if message.type == "result":
        print(message.result)

Tools

The Claude Agent SDK adapter handles tools differently from the AI SDK adapter. Instead of registering custom tool executors, you list tool names in your prompt frontmatter. The adapter passes these names through as allowedTools to the Claude Agent SDK. Tools can be any of the SDK’s built-in tools (Read, Write, Bash, etc.) or tools provided by MCP servers. Configure MCP servers on the client:

TypeScript
Python

agentmark.client.ts

import { createAgentMarkClient, ClaudeAgentModelRegistry } from "@agentmark-ai/claude-agent-sdk-v0-adapter";

export const client = createAgentMarkClient({
  loader,
  modelRegistry,
  mcpServers: {
    weather: { url: "https://weather-mcp.example.com/sse" },
  },
});

The TypeScript field is mcpServers (camelCase). The Python adapter uses mcp_servers (snake_case).

agentmark_client.py

client = create_claude_agent_client(
    model_registry=model_registry,
    mcp_servers={"weather": {"url": "https://weather-mcp.example.com/sse"}},
    loader=loader,
)

Then reference tools by name in your prompts:

task.prompt.mdx

---
name: task
text_config:
  model_name: claude-sonnet-4-20250514
  tools:
    - weather
---

<System>You are a helpful assistant with access to weather data.</System>
<User>{props.task}</User>

Evals

Register evaluation functions for scoring prompt outputs during experiments. Score schemas are defined separately in agentmark.json; eval functions are connected to scores by name.

TypeScript
Python

agentmark.client.ts

import type { EvalFunction } from "@agentmark-ai/prompt-core";

const evals: Record<string, EvalFunction> = {
  exact_match: ({ output, expectedOutput }) => ({
    passed: output === expectedOutput,
    score: output === expectedOutput ? 1 : 0,
  }),
};

export const client = createAgentMarkClient({
  loader,
  modelRegistry,
  evals,
});

agentmark_client.py

from agentmark.prompt_core import EvalParams, EvalResult

def exact_match(params: EvalParams) -> EvalResult:
    match = str(params["output"]).strip() == str(params.get("expectedOutput", "")).strip()
    return {"passed": match, "score": 1.0 if match else 0.0}

evals = {
    "exact_match": exact_match,
}

client = create_claude_agent_client(
    model_registry=model_registry,
    loader=loader,
    evals=evals,
)

Reference evals in your prompt frontmatter:

---
test_settings:
  dataset: ./datasets/test.jsonl
  evals:
    - exact_match
---

Learn more about evaluations

Tracing

TypeScript
Python

Wrap query with withTracing to emit OpenTelemetry spans. Pass adapted.query and adapted.telemetry in an object:

import { client } from "./agentmark.client";
import { withTracing } from "@agentmark-ai/claude-agent-sdk-v0-adapter";
import { query } from "@anthropic-ai/claude-agent-sdk";

const prompt = await client.loadTextPrompt("task.prompt.mdx");
const adapted = await prompt.format({
  props: { task: "..." },
  telemetry: { isEnabled: true },
});

const result = await withTracing(query, {
  query: adapted.query,
  telemetry: adapted.telemetry,
});

console.log("Trace ID:", result.traceId);

for await (const message of result) {
  console.log(message);
}

traced_query automatically emits OpenTelemetry spans when the adapter’s telemetry is enabled on prompt.format():

from agentmark_claude_agent_sdk_v0 import traced_query

adapted = await prompt.format(
    props={"task": "..."},
    telemetry={"isEnabled": True},
)

async for message in traced_query(adapted):
    print(message)

Learn more in Tracing setup.

Getting started (Python)

Install the adapter and its dependencies:

pip install agentmark-claude-agent-sdk-v0 agentmark-prompt-core claude-agent-sdk

Create your AgentMark client in agentmark_client.py (see the Setup section above for the full create_claude_agent_client configuration). Optionally scaffold the AgentMark config and MCP wiring with the create tool:

npm create agentmark@latest my-app

The create tool writes agentmark.json, an empty agentmark/ directory for your .prompt.mdx files, and optional IDE MCP config. It does not prompt for a language or adapter, so add the Python adapter and client yourself as shown above. Run the local dev server:

npx agentmark dev

Limitations

No image generation. Use the AI SDK adapter for experimental_generateImage.
No speech generation. Use the AI SDK adapter for experimental_generateSpeech.
Messages stream as the agent runs via query() / traced_query(), but the final aggregated result is only available after all turns complete.

Next steps

Prompts

Learn about prompt syntax

Tools and agents

Configure tools for your agents

Observability

Monitor your agents in production

Other integrations

Explore other AI frameworks

Have Questions?

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

Email us at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about our business solutions

​Installation

​Setup

​Running prompts

​Adapter options

​Object generation

​Tools

​Evals

​Tracing

​Getting started (Python)

​Limitations

​Next steps

Prompts

Tools and agents

Observability

Other integrations

​Have Questions?

Installation

Setup

Running prompts

Adapter options

Object generation

Tools

Evals

Tracing

Getting started (Python)

Limitations

Next steps

Have Questions?