Type safety

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.

​

Defining types

---
name: math/addition
object_config:
  model_name: openai/gpt-4o
  schema:
    type: object
    properties:
      answer:
        type: number
        description: "The sum of the two numbers"
    required: [answer]
input_schema:
  type: object
  properties:
    a:
      type: number
      description: "First number to add"
    b:
      type: number
      description: "Second number to add"
  required: [a, b]
---

<System>You compute sums.</System>
<User>What is {props.a} + {props.b}?</User>

​

Generating types

npx agentmark generate-types --root-dir ./agentmark > agentmark.types.ts

// Auto-generated types from AgentMark
// Do not edit this file directly

interface Math$AdditionIn {
  a: number;
  b: number;
}


interface Math$AdditionOut {
  answer: number;
}


type Math$Addition = {
  kind: 'object';
  input:  Math$AdditionIn;
  output: Math$AdditionOut;
};

export default interface AgentmarkTypes {
  "math/addition.prompt.mdx": Math$Addition,
  "math/addition.prompt": Math$Addition,
  "math/addition": Math$Addition
}

1. The wrapper (Math$Addition) is a type alias, while Math$AdditionIn / Math$AdditionOut are interfaces.
2. Each prompt gets three key aliases — the full path with .prompt.mdx, the path ending in .prompt, and the bare name. Any of the three resolves to the same type when you call loadTextPrompt / loadObjectPrompt.

​

Using generated types

import PromptTypes from './agentmark.types';
import { createAgentMarkClient, VercelAIModelRegistry } from "@agentmark-ai/ai-sdk-v5-adapter";
import { ApiLoader } from "@agentmark-ai/loader-api";
import { openai } from "@ai-sdk/openai";
import { generateObject, tool } from "ai";
import { z } from "zod";

const loader = ApiLoader.local({ baseUrl: "http://localhost:9418" });

const modelRegistry = new VercelAIModelRegistry();
modelRegistry.registerProviders({ openai });

// AI SDK v5 uses `inputSchema`, not `parameters` (that's v4).
const sumTool = tool({
  description: "Add two numbers together",
  inputSchema: z.object({
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  }),
  execute: async ({ a, b }) => ({ answer: a + b }),
});

const client = createAgentMarkClient<PromptTypes>({
  loader,
  modelRegistry,
  tools: { sum: sumTool },
});

// TypeScript enforces correct types
const prompt = await client.loadObjectPrompt("math/addition.prompt.mdx");
const input = await prompt.format({
  props: {
    a: 5,   // must be number per input_schema
    b: 3,
  },
});

const result = await generateObject(input);
const answer: number = result.object.answer;  // type-safe

from agentmark_pydantic_ai_v0 import (
    create_pydantic_ai_client,
    PydanticAIModelRegistry,
    run_object_prompt,
)
from agentmark.prompt_core import FileLoader

loader = FileLoader("./dist/agentmark")

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

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

# Python type safety comes from Pydantic models
# generated from the prompt's JSON Schema.
prompt = await client.load_object_prompt("math/addition.prompt.mdx")
params = await prompt.format(props={"a": 5, "b": 3})

result = await run_object_prompt(params)
print(result.output.answer)

​

Benefits

1. Compile-time safety — TypeScript flags prop-shape mismatches before runtime.
2. IDE support — autocomplete and inline descriptions on props and outputs.
3. Consistent interfaces — the same PromptTypes drives both the loader and the caller.
4. Documentation — JSON Schema descriptions flow through to TS JSDoc comments.
5. Validation — the adapter validates inputs and structured outputs against the schema at runtime.

​

Best practices

1. Define both input_schema and object_config.schema (when the prompt is an object prompt) in your prompt files.
2. Use descriptive property names and add description fields — they become JSDoc comments.
3. Mark required properties using required.
4. Regenerate types after any schema edit: npx agentmark generate-types --root-dir ./agentmark > agentmark.types.ts.
5. Commit agentmark.types.ts to version control so CI type-checks the contract.