Quick Start

Get started with Agent Tool Protocol in less than 5 minutes! This guide will walk you through creating a simple server and client.

Prerequisites

• Node.js 18+ or 20+
• npm, yarn, or pnpm package manager
• Basic knowledge of TypeScript/JavaScript

Step 1: Create a Project

mkdir my-atp-project
cd my-atp-project
npm init -y

Step 2: Install Dependencies

npm install @mondaydotcomorg/atp-server @mondaydotcomorg/atp-client

Step 3: Create a Server

Create a file named server.ts:

import { createServer } from '@mondaydotcomorg/atp-server';

// Create server instance
const server = createServer({
  execution: {
    timeout: 30000,      // 30 second timeout
    memory: 128 * 1024 * 1024,  // 128MB memory limit
  },
});

// Register a simple API
server.registerAPI('calculator', {
  add: {
    description: 'Add two numbers',
    inputSchema: {
      type: 'object',
      properties: {
        a: { type: 'number', description: 'First number' },
        b: { type: 'number', description: 'Second number' },
      },
      required: ['a', 'b'],
    },
    handler: async ({ a, b }) => {
      return a + b;
    },
  },
  multiply: {
    description: 'Multiply two numbers',
    inputSchema: {
      type: 'object',
      properties: {
        a: { type: 'number' },
        b: { type: 'number' },
      },
      required: ['a', 'b'],
    },
    handler: async ({ a, b }) => {
      return a * b;
    },
  },
});

// Start the server
server.listen(3333, () => {
  console.log('🚀 Agent Tool Protocol Server running on http://localhost:3333');
});

Step 4: Create a Client

Create a file named client.ts:

import { AgentToolProtocolClient } from '@mondaydotcomorg/atp-client';

async function main() {
  // Create client instance
  const client = new AgentToolProtocolClient({
    baseUrl: 'http://localhost:3333',
  });

  // Initialize session
  await client.init({ name: 'my-agent', version: '1.0.0' });
  console.log('✅ Client initialized');

  // Connect and discover APIs
  await client.connect();
  console.log('✅ Connected to server');

  // Execute code that uses the calculator API
  const result = await client.execute(`
    // Add two numbers
    const sum = await calculator.add({ a: 10, b: 5 });
    console.log('Sum:', sum);

    // Multiply the result by 2
    const product = await calculator.multiply({ a: sum, b: 2 });
    console.log('Product:', product);

    return { sum, product };
  `);

  console.log('Result:', result.result);
  // Output: { sum: 15, product: 30 }

  console.log('Stats:', result.stats);
  // Output: execution time, memory used, etc.
}

main().catch(console.error);

Step 5: Run the Code

Terminal 1 - Start the server:

npx tsx server.ts

Terminal 2 - Run the client:

npx tsx client.ts

Expected Output

Server Terminal:

🚀 Agent Tool Protocol Server running on http://localhost:3333

Client Terminal:

✅ Client initialized
✅ Connected to server
Sum: 15
Product: 30
Result: { sum: 15, product: 30 }
Stats: {
  duration: 45,
  memoryUsed: 1234567,
  llmCallsCount: 0,
  approvalCallsCount: 0
}

What Just Happened?

1. Server Setup: You created a server that exposes a calculator API with add and multiply functions
2. Client Connection: The client connected to the server and discovered available APIs
3. Code Execution: The client executed TypeScript code in a secure sandbox on the server
4. API Calls: The sandboxed code called the calculator APIs, which executed securely
5. Results: The execution result and statistics were returned to the client

Key Concepts

Secure Sandbox

The code runs in an isolated V8 sandbox with:

• No file system access
• No network access (except approved APIs)
• Memory and time limits
• Full TypeScript support

Type Safety

The client automatically generates TypeScript type definitions for all available APIs, providing:

• Autocomplete in your IDE
• Type checking
• Documentation

API Registration

APIs are registered with:

• Description: What the function does
• Input Schema: JSON Schema for validation
• Handler: The actual implementation

Next Steps

Now that you have a basic setup working, explore more features:

• Installation Guide: Production-ready installation
• Create Your First Server: Learn about server configuration
• Create Your First Client: Explore client capabilities
• Architecture Overview: Understand how ATP works

Common Issues

Port Already in Use

If port 3333 is already in use, change the port in both server and client:

// server.ts
server.listen(3334);

// client.ts
const client = new AgentToolProtocolClient({
  baseUrl: 'http://localhost:3334',
});

TypeScript Not Found

If you get "tsx: command not found", install it:

npm install -g tsx

Or use Node.js with ts-node:

npm install -D ts-node
npx ts-node server.ts

Module Not Found

Make sure you're in the project directory and dependencies are installed:

npm install

Full Example Repository

Check out the examples directory for more complete examples.