TypeScript SDK

The Marlo TypeScript SDK captures your agent’s behavior and sends it to Marlo for evaluation and learning. With just a few lines of code, you can start tracking tasks, recording interactions, and applying learnings.

Installation


npm install @marshmallo/marlo

Quick Start

Here’s the fastest way to get Marlo working with your agent:


import * as marlo from '@marshmallo/marlo';
import OpenAI from 'openai';
 
// 1. Initialize Marlo (once at startup)
await marlo.init(process.env.MARLO_API_KEY!);
 
// 2. Register your agent
marlo.registerAgent(
  'my-agent',
  'You are a helpful assistant.',
  [],  // tools
  [],  // mcp
  { model: 'gpt-4' }
);
 
// 3. Wrap your agent logic in a task
const client = new OpenAI();
 
const task = marlo.task('user-123', 'my-agent').start();
task.input('What is 2 + 2?');
 
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'What is 2 + 2?' }],
});
 
// Record the LLM call
task.llm({
  model: 'gpt-4',
  usage: {
    input_tokens: response.usage?.prompt_tokens || 0,
    output_tokens: response.usage?.completion_tokens || 0,
  },
});
 
const answer = response.choices[0].message.content || '';
task.output(answer);
task.end();
 
// 4. Shutdown before exit
await marlo.shutdown();

Configuration

Initialize the SDK once when your application starts. You’ll find your API key in Settings → Project at marshmallo.ai .


import * as marlo from '@marshmallo/marlo';
 
await marlo.init(process.env.MARLO_API_KEY!);

Core Concepts

Tasks

A task represents a single agent execution. Unlike Python’s context manager, TypeScript uses explicit start() and end() calls:


const task = marlo.task(
  'user-123-session-456',
  'my-agent',
  'Support Chat'  // optional thread name
).start();
 
task.input("User's question here");
 
// Your agent logic...
 
task.output("Agent's response here");
task.end();

Parameters:

threadId (string): Stable identifier for the conversation. Tasks with the same threadId are grouped together
agent (string): Name of the registered agent handling this task
threadName (string, optional): Human-readable label shown in the dashboard

Agents


marlo.registerAgent(
  'support-agent',
  'You are a helpful customer support agent.',
  [
    {
      name: 'lookup_order',
      description: 'Find order details by order ID',
      parameters: {
        type: 'object',
        properties: { order_id: { type: 'string' } },
        required: ['order_id'],
      },
    },
  ],
  [],  // mcp
  { model: 'gpt-4' }
);

Shutdown

Always call marlo.shutdown() before your application exits:


await marlo.shutdown();

For web servers:


// Express
process.on('SIGTERM', async () => {
  await marlo.shutdown();
  process.exit(0);
});
 
// Next.js API routes - use cleanup in serverless function

What’s Next?

Auto Instrumentation - Automatically capture LLM calls
Tool Tracking - Record tool calls
Learnings - Fetch and apply learnings to improve your agent
Multi-Agent - Track complex multi-agent workflows
API Reference - Complete method documentation