AgentMark provides robust type safety through JSON Schema definitions in your prompt files. This ensures type checking for both inputs and outputs, making your prompts more reliable and maintainable.
Defining Types
You can define both input and output types in your prompt files using JSON Schema:
---
name: math-addition
object_config:
model_name: gpt-4o
schema: # Output type definition
type: "object"
properties:
sum:
type: "number"
description: "The sum of the two numbers"
required: ["sum"]
input_schema: # Input type definition
type: "object"
properties:
num1:
type: "number"
description: "First number to add"
num2:
type: "number"
description: "Second number to add"
required: ["num1", "num2"]
---
<System>You are a helpful math assistant that performs addition.</System>
<User>What is the sum of {props.num1} and {props.num2}?</User>
// Auto-generated types from Agentmark
// Do not edit this file directly
type SumArgs = { num1: number; num2: number };
export interface Tools {
sum: { args: SumArgs };
}
interface Math$AdditionIn {
/** First number to add */
num1: number;
/** Second number to add */
num2: number;
}
interface Math$AdditionOut {
/** The sum of the two numbers */
sum: number;
/** Step by step explanation */
explanation: string;
}
interface Math$Addition {
input: Math$AdditionIn;
output: Math$AdditionOut;
kind: "object"
}
export default interface AgentmarkTypes {
"math/addition.prompt.mdx": Math$Addition
}
Generating Types
AgentMark provides a CLI tool to automatically generate TypeScript types from your prompt schemas:
# Generate types from local files
npx @agentmark-ai/cli generate-types --root-dir ./prompts > agentmark.types.ts
- Input types based on your
input_schema
- Output types based on your model’s
schema
- A mapping of prompt paths to their respective types
Using Generated Types
AI SDK v5 (Recommended)
Pydantic AI (Python)
import PromptTypes, { Tools } from './agentmark.types';
import { createAgentMarkClient, VercelAIModelRegistry, VercelAIToolRegistry } from "@agentmark-ai/ai-sdk-v5-adapter";
import { ApiLoader } from "@agentmark-ai/loader-api";
import { openai } from "@ai-sdk/openai";
import { generateObject } from "ai";
const loader = ApiLoader.local({ baseUrl: "http://localhost:9418" });
const modelRegistry = new VercelAIModelRegistry()
.registerModels(["gpt-4o"], (name) => openai(name));
const toolRegistry = new VercelAIToolRegistry<Tools>()
.register('sum', ({ num1, num2 }) => ({ sum: num1 + num2 }));
const client = createAgentMarkClient<PromptTypes>({
loader,
modelRegistry,
toolRegistry,
});
// TypeScript enforces correct types
const prompt = await client.loadObjectPrompt("math/addition.prompt.mdx");
const input = await prompt.format({
props: {
num1: 5, // Must be number
num2: 3 // Must be number
}
});
const result = await generateObject(input);
const sum = result.object.sum; // Type-safe number
from agentmark_pydantic_ai_v0 import (
create_pydantic_ai_client,
create_default_model_registry,
run_object_prompt,
)
from agentmark.prompt_core import FileLoader
loader = FileLoader(base_dir="./")
model_registry = create_default_model_registry()
client = create_pydantic_ai_client(
model_registry=model_registry,
loader=loader,
)
# Python uses Pydantic models for type safety
prompt = await client.load_object_prompt("math/addition.prompt.mdx")
params = await prompt.format(props={"num1": 5, "num2": 3})
result = await run_object_prompt(params)
print(result.output.sum) # Type-safe via Pydantic model
Python type safety comes from Pydantic models auto-generated from JSON Schema. Install type stubs with pip install types-agentmark for IDE support.
Benefits
- Compile-Time Safety: Catch type errors before runtime
- IDE Support: Get autocomplete and inline documentation
- Consistent Interfaces: Ensure consistent input/output shapes across your application
- Documentation: JSON Schema descriptions serve as built-in documentation
- Validation: Automatic runtime validation of inputs and outputs
Best Practices
- Always define both
input_schema and schema (when applicable) in your prompt files
- Use descriptive property names and include descriptions
- Mark required properties using the
required field
- Regenerate types when you update your schemas
- Commit generated types to version control
Have Questions?
We’re here to help! Choose the best way to reach us:
