Type Safety

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/cli generate-types --root-dir ./prompts > agentmark.types.ts

The generated types will include:

• 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

import PromptTypes, { Tools } from './agentmark.types';
import { createAgentMarkClient, VercelAIToolRegistry } from "@agentmark/vercel-ai-v4-adapter";

const tools = new VercelAIToolRegistry<Tools>()
  .register('sum', ({ num1, num2 }) => ({ sum: num1 + num2 }));

const agentmarkClient = createAgentMarkClient<PromptTypes, typeof tools>({
  // agentmark client options
});

// TypeScript enforces correct types
const prompt = await agentmarkClient.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.result.sum;  // Type-safe number

​

Benefits

1. Compile-Time Safety: Catch type errors before runtime
2. IDE Support: Get autocomplete and inline documentation
3. Consistent Interfaces: Ensure consistent input/output shapes across your application
4. Documentation: JSON Schema descriptions serve as built-in documentation
5. Validation: Automatic runtime validation of inputs and outputs

​

Best Practices

1. Always define both input_schema and schema (when applicable) in your prompt files
2. Use descriptive property names and include descriptions
3. Mark required properties using the required field
4. Regenerate types when you update your schemas
5. Commit generated types to version control