Tools in AgentMark allow you to extend your prompts with custom functionality, such as web searching, calculation, API calls, and more.

​
Creating Tools

Tools are simple async functions that receive parameters and return a result:

const calculateTool = async (input: { expression: string }) => {
  // Note: This is a simple example and eval should not be used in production
  const result = eval(input.expression);
  return { result };
};

​
Registering Tools

Tools can be registered using the a tool registery exported by the adapter:

// Example using vercel-ai-v4-adapter
import { VercelAIToolRegistry } from "@agentmark/vercel-ai-v4-adapter";

const toolRegistry = new VercelAIToolRegistry();
toolRegistry.registerTool("calculate", calculateTool);

​
Tool Context

Tools can access a context pass in through agentmark at runtime.

const calculateTool = async (input: { expression: string }, context: { user: { name: string } }) => {
  // Use the context to personalize the response
  const response = `Hello ${context.user.name}, the result of ${input.expression} is ${result}`;
  
  return { response };
};

// Example using vercel-ai-v4-adapter
import { VercelAIToolRegistry, VercelAIModelRegistry, createAgentMarkClient } from "@agentmark/vercel-ai-v4-adapter";
import { openai } from "@ai-sdk/openai";
import { FileLoader } from "@agentmark/agentmark-core";

const modelRegistry = new VercelAIModelRegistry();
const toolRegistry = new VercelAIToolRegistry();

modelRegistry.registerModels(['gpt-4o'], (name: string) => {
  return openai(name);
});

const loader = new FileLoader("./path/to/agentmark");

const agentmark = createAgentMarkClient({
  modelRegistry,
  toolRegistry,
  loader
});

const prompt = await agentmark.loadTextPrompt("./path/to/prompt.mdx");

const input = await agentmark.format({
  props,
  toolContext: {
    user: {
      name: "John"
    }
  }
})

​
Tool Configuration

Tools are configured using JSON Schema in your frontmatter metadata. Each tool requires:

  1. key: The name of the tool, as a property key in the tools object
  2. description: What the tool does (helps the LLM understand when to use it)
  3. parameters: JSON Schema defining the tool’s input parameters

Example:

calculator.prompt.mdx
---
name: calculator
text_config:
  model_name: gpt-4
  tools:
    calculate:
      description: Performs basic arithmetic calculations
      parameters:
        type: object
        properties:
          expression:
            type: string
            description: The mathematical expression to evaluate
        required: ["expression"]
---

<System>
You are a math tutor that can perform calculations. Use the calculate tool when you need to compute something.
</System>

<User>What's 235 * 18 plus 42?</User>

​
Agents

When setting max_calls, your LLM can make multiple calls to solve complex agentic tasks. Tools are defined in your prompt’s frontmatter configuration and can be accessed within your messages:

To enable agents:

  1. Add max_calls to your model settings
  2. Define your tools schema
  3. The SDK will automatically handle multiple LLM call communication
travel-agent.prompt.mdx
---
name: travel-agent
text_config:
  model_name: gpt-4
  max_calls: 3
  tools:
    search_flights:
      description: Search for available flights between cities
      parameters:
        type: object
        properties:
          from:
            type: string
            description: Departure city
          to:
            type: string
            description: Arrival city
          date:
            type: string
            description: Travel date (YYYY-MM-DD)
        required: ["from", "to", "date"]
    check_weather:
      description: Get weather forecast for a city
      parameters:
        type: object
        properties:
          city:
            type: string
            description: City name
          date:
            type: string
            description: Date to check (YYYY-MM-DD)
        required: ["city", "date"]
---

<System>
You are a helpful travel assistant that can search flights and check weather conditions. 
When helping users plan trips:
1. Search for available flights
2. Check the weather at the destination
3. Make recommendations based on both flight options and weather
</System>

<User>
I want to fly from San Francisco to New York next week (2024-04-20). Can you help me plan my trip?
</User>

​
Best Practices

  1. Keep tools focused on a single responsibility
  2. Provide clear descriptions to help the LLM use tools appropriately
  3. Handle errors gracefully and return informative error messages
  4. Use descriptive parameter names and include helpful descriptions

Have Questions?

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