API Documentation

Agent

The Agent is the core orchestrator that manages prompts, tools, memory, and execution flow.

createAgent(config)

function createAgent(config: AgentConfig): Agent

Parameters

name string required

Unique identifier for the agent instance

model string optional

OpenAI model to use (e.g., "gpt-5.2"). Optional if the client sets a default.

client RunMeshOpenAI optional

Optional OpenAI client from @runmesh/core. If omitted, RunMesh creates one.

systemPrompt string optional

System message that defines the agent's behavior and role

tools ToolRegistry optional

Registry of tools the agent can use

memory MemoryAdapter optional

Memory adapter for conversation history and context

policies Policy[] optional

Array of policies to enforce on agent actions

agent.run(prompt)

async run(prompt: string): Promise<AgentRunResult>

Execute the agent with a single prompt. Handles tool loops automatically.

Example
const agent = createAgent({
  name: "assistant",
  model: "gpt-5.2",
  systemPrompt: "You are a helpful assistant"
});

const result = await agent.run("What is 2+2?");
console.log(result.response.choices[0].message.content);

agent.stream(prompt)

async stream(prompt: string): Promise<ResponseStream>

Stream the agent's response in real-time.

Example
const stream = await agent.stream("Tell me a story");

for await (const event of stream) {
  if (event.type === 'token') {
    process.stdout.write(event.value);
  }
}

Tools

Tools are functions that agents can call to perform specific actions.

tool(definition)

function tool(definition: ToolDefinition): Tool

name string required

Unique tool name (snake_case recommended)

description string required

Clear description of what the tool does

schema ZodSchema required

Zod schema for input validation

handler (input) => any required

Function that executes the tool's logic

Example: Weather Tool
import { tool } from "@runmesh/tools";
import { z } from "zod";

const weatherTool = tool({
  name: "get_weather",
  description: "Get current weather for a location",
  schema: z.object({
    location: z.string().describe("City name or coordinates"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius")
  }),
  handler: async (input) => {
    // Call weather API
    const response = await fetch(`api.weather.com?q=${input.location}`);
    const data = await response.json();
    return {
      temperature: data.temp,
      conditions: data.weather
    };
  }
});

ToolRegistry

class ToolRegistry

Example: Registering Multiple Tools
const tools = new ToolRegistry();

tools.register(weatherTool);
tools.register(calculatorTool);
tools.register(searchTool);

const agent = createAgent({
  name: "assistant",
  model: "gpt-5.2",
  tools // Pass the registry
});

Memory

Memory adapters enable agents to maintain conversation history and context.

MemoryAdapter Interface

interface MemoryAdapter {
  add(agentName: string, message: ChatMessage): Promise<void>;
  history(agentName: string, limit?: number): Promise<MemoryMessage[]>;
}

Example: In-Memory Adapter
import { InMemoryAdapter } from "@runmesh/memory";

const memory = new InMemoryAdapter();

const agent = createAgent({
  name: "assistant",
  model: "gpt-5.2",
  memory // Agent will remember conversation history
});

Note: RunMesh supports custom memory adapters. Implement the MemoryAdapter interface to integrate with databases, Redis, or other storage solutions.

Streaming

Stream responses in real-time for responsive user experiences.

Event Types

token StreamEvent

Emitted for each token in the response

tool_call StreamEvent

Emitted when the agent decides to use a tool

final StreamEvent

Emitted with the complete response

Example: CLI with Streaming
const stream = await agent.stream(userInput);

for await (const event of stream) {
  switch (event.type) {
    case 'token':
      process.stdout.write(event.value);
      break;
    
    case 'tool_call':
      console.log(`Tool call: ${event.toolCall?.function?.name ?? "unknown"}`);
      break;
    
    case 'final':
      console.log(`Final: ${event.message?.content ?? ""}`);
      break;
  }
}

Policies

Policies enforce rules and constraints on agent behavior.

Policy Function

type Policy = (context: PolicyContext) => PolicyResult | Promise<PolicyResult>

Example: Rate Limiting Policy
const rateLimitPolicy: Policy = async (context) => {
  const requestCount = await getRequestCount(context.agent);
  
  if (requestCount > 100) {
    return {
      allow: false,
      reason: "Rate limit exceeded"
    };
  }
  
  return { allow: true };
};

const agent = createAgent({
  name: "assistant",
  model: "gpt-5.2",
  policies: [rateLimitPolicy]
});

Example: Content Filtering Policy
const contentFilterPolicy: Policy = (context) => {
  const lastMessage = context.messages[context.messages.length - 1];
  const content = lastMessage.content.toLowerCase();
  
  const bannedWords = ["spam", "abuse"];
  const hasBannedContent = bannedWords.some(word => content.includes(word));
  
  if (hasBannedContent) {
    return {
      allow: false,
      reason: "Content violates policy"
    };
  }
  
  return { allow: true };
};

Structured Outputs

Extract structured, validated data from agent responses.

generateStructuredOutput()

async function generateStructuredOutput<T>(
  options: StructuredGenerateOptions<T>
): Promise<StructuredResult<T>>

Example: Extract Contact Information
import { createOpenAI, generateStructuredOutput } from "@runmesh/core";
import { z } from "zod";

const contactSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  phone: z.string().optional(),
  company: z.string().optional()
});

const client = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  defaultModel: "gpt-5.2"
});

const result = await generateStructuredOutput({
  client,
  request: {
    messages: [
      { role: "user", content: "Extract contact info: John Doe, john@example.com, works at Acme Inc" }
    ]
  },
  schema: contactSchema,
  maxRetries: 2
});

console.log(result.value);
// { name: "John Doe", email: "john@example.com", company: "Acme Inc" }

Warning: Structured outputs may retry multiple times if the response doesn't match the schema. Set appropriate timeouts and handle errors.

Advanced Examples

Multi-Tool Agent with Memory

                    import { createAgent } from "@runmesh/agent";
import { tool, ToolRegistry } from "@runmesh/tools";
import { InMemoryAdapter } from "@runmesh/memory";
import { z } from "zod";

// Define tools
const tools = new ToolRegistry();

tools.register(tool({
  name: "calculator",
  description: "Perform mathematical calculations",
  schema: z.object({
    expression: z.string()
  }),
  handler: (input) => eval(input.expression)
}));

tools.register(tool({
  name: "search_web",
  description: "Search the web for information",
  schema: z.object({
    query: z.string()
  }),
  handler: async (input) => {
    // Implement web search
    return { results: [...] };
  }
}));

// Create agent with memory
const agent = createAgent({
  name: "research-assistant",
  model: "gpt-5.2",
  systemPrompt: "You are a research assistant with web search and calculation capabilities.",
  tools,
  memory: new InMemoryAdapter()
});

// Use the agent
const result1 = await agent.run("What is 15 * 23?");
const result2 = await agent.run("Search for recent AI developments");
const result3 = await agent.run("What did you calculate earlier?"); // Uses memory
                

Quick Navigation