API Reference Overview | Agent Tool Protocol
Skip to main content

API Reference Overview

Complete API documentation for all Agent Tool Protocol packages.

Package Structure​

Agent Tool Protocol is organized into multiple packages, each with a specific purpose:

@mondaydotcomorg/
├── atp-server          - Server implementation
├── atp-client          - Client SDK
├── atp-runtime         - Runtime SDK (injected into sandboxes)
├── atp-protocol        - Core types and interfaces
├── atp-provenance      - Provenance tracking and security
├── atp-langchain       - LangChain integration
├── atp-mcp-adapter     - Model Context Protocol adapter
├── atp-compiler        - Code transformation
└── atp-providers       - Built-in providers (Redis, Memory, etc.)

Quick Reference​

Server​

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

const server = createServer(config);
server.registerAPI(name, functions);
server.addAPIGroup(apiGroup);
server.listen(port);

Full Server API →

Client​

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

const client = new AgentToolProtocolClient({ baseUrl });
await client.init();
await client.connect();
const result = await client.execute(code);

Full Client API →

Runtime (in sandbox)​

// Available in executed code
import { llm, cache, approval, progress } from '@mondaydotcomorg/atp-runtime';

const result = await llm.call({ prompt: "..." });
await cache.set("key", value, ttl);
const { approved } = await approval.request("message");
progress.report("status", fraction);

Full Runtime API →

Core Concepts​

Server Configuration​

interface ServerConfig {
  execution?: {
    timeout?: number;              // Execution timeout (ms)
    memory?: number;               // Memory limit (bytes)
    llmCalls?: number;             // Max LLM calls
    provenanceMode?: ProvenanceMode;
    securityPolicies?: SecurityPolicy[];
  };
  clientInit?: {
    tokenTTL?: number;             // Token time-to-live
    tokenRotation?: number;        // Token rotation interval
  };
  executionState?: {
    ttl?: number;                  // State TTL for pause/resume
    maxPauseDuration?: number;     // Max pause duration
  };
  discovery?: {
    embeddings?: boolean;          // Enable embedding-based search
  };
  audit?: {
    enabled?: boolean;             // Enable audit logging
    sinks?: AuditSink[];          // Audit sinks
  };
  otel?: {
    enabled?: boolean;             // Enable OpenTelemetry
    serviceName?: string;
    traceEndpoint?: string;
    metricsEndpoint?: string;
  };
  providers?: {
    cache?: CacheProvider;
    auth?: AuthProvider;
  };
  logger?: LogLevel | Logger;
}

Execution Result​

interface ExecutionResult {
  executionId: string;
  status: ExecutionStatus;
  result?: unknown;
  error?: {
    message: string;
    code?: ExecutionErrorCode;
    stack?: string;
    retryable?: boolean;
  };
  stats: {
    duration: number;
    memoryUsed: number;
    llmCallsCount: number;
    approvalCallsCount: number;
  };
  needsCallback?: {
    type: CallbackType;
    operation: string;
    payload: Record<string, unknown>;
  };
  needsCallbacks?: BatchCallbackRequest[];
}

Tool Definition​

interface CustomFunctionDef {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  outputSchema?: JSONSchema;
  handler: (params: unknown) => Promise<unknown>;
  keywords?: string[];
  metadata?: ToolMetadata;
}

Type Definitions​

Execution Status​

enum ExecutionStatus {
  COMPLETED = 'completed',
  FAILED = 'failed',
  TIMEOUT = 'timeout',
  CANCELLED = 'cancelled',
  PAUSED = 'paused',
  MEMORY_EXCEEDED = 'memory_exceeded',
  LLM_CALLS_EXCEEDED = 'llm_calls_exceeded',
  SECURITY_VIOLATION = 'security_violation',
}

Provenance Mode​

enum ProvenanceMode {
  NONE = 'none',      // No tracking
  TRACK = 'track',    // Track provenance
  ENFORCE = 'enforce', // Track + enforce policies
}

Callback Types​

enum CallbackType {
  LLM = 'llm',
  APPROVAL = 'approval',
  EMBEDDING = 'embedding',
  TOOL = 'tool',
}

Common Patterns​

Creating a Server​

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

const server = createServer({
  execution: {
    timeout: 30000,
    memory: 128 * MB,
  },
});

server.registerAPI('myapi', {
  myFunction: {
    description: 'My function',
    inputSchema: { type: 'object', properties: { ... } },
    handler: async (params) => { ... },
  },
});

server.listen(3333);

Creating a Client​

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

const client = new AgentToolProtocolClient({
  baseUrl: 'http://localhost:3333',
  headers: {
    'x-api-key': process.env.API_KEY,
  },
});

await client.init({ name: 'my-client' });
await client.connect();

Executing Code​

const result = await client.execute(`
  const data = await myapi.myFunction({ param: 'value' });
  return data;
`);

if (result.status === 'completed') {
  console.log('Result:', result.result);
} else {
  console.error('Error:', result.error);
}

Handling Pauses​

let result = await client.execute(code);

while (result.status === 'paused' && result.needsCallback) {
  const callback = result.needsCallback;
  const callbackResult = await handleCallback(callback);
  result = await client.resume(result.executionId, callbackResult);
}

API Documentation​

Server Package​

Client Package​

Runtime Package​

Protocol Package​

Provenance Package​

LangChain Package​

MCP Adapter Package​

Helper Functions​

Size Constants​

import { MB, GB } from '@mondaydotcomorg/atp-server';

const memory = 256 * MB;  // 256 megabytes
const storage = 2 * GB;   // 2 gigabytes

Time Constants​

import { SECOND, MINUTE, HOUR, DAY } from '@mondaydotcomorg/atp-server';

const timeout = 30 * SECOND;     // 30 seconds
const ttl = 5 * MINUTE;          // 5 minutes
const rotation = 24 * HOUR;      // 24 hours
const retention = 7 * DAY;       // 7 days

Provenance Functions​

import {
  getProvenance,
  hasProvenance,
  getAllProvenance,
  markPrimitiveTainted,
  captureProvenanceState,
  restoreProvenanceState,
} from '@mondaydotcomorg/atp-provenance';

Type Utilities​

Type Guards​

import { isPauseError } from '@mondaydotcomorg/atp-runtime';

try {
  await llm.call({ prompt: '...' });
} catch (error) {
  if (isPauseError(error)) {
    // Handle pause
  }
}

Type Assertions​

import { ExecutionStatus } from '@mondaydotcomorg/atp-protocol';

if (result.status === ExecutionStatus.COMPLETED) {
  // TypeScript knows result.result is defined
  console.log(result.result);
}

Examples by Use Case​

Building a Simple Tool​

server.registerAPI('weather', {
  getCurrentWeather: {
    description: 'Get current weather for a location',
    inputSchema: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'City name' },
        units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
      },
      required: ['location'],
    },
    handler: async ({ location, units = 'celsius' }) => {
      // Implementation
      return {
        location,
        temperature: 22,
        units,
        conditions: 'sunny',
      };
    },
  },
});

Building a Secure Tool​

server.registerAPI('database', {
  executeSQLQuery: {
    description: 'Execute a SQL query',
    inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
    handler: async ({ query }) => {
      // Execute query
      return results;
    },
    metadata: {
      operationType: ToolOperationType.WRITE,
      sensitivityLevel: ToolSensitivityLevel.SENSITIVE,
      requiresApproval: true,
    },
  },
});

Building a Client Tool​

client.provideTools([
  {
    name: 'screenshot',
    namespace: 'browser',
    description: 'Take a screenshot of the current browser window',
    inputSchema: {
      type: 'object',
      properties: {
        fullPage: { type: 'boolean', default: false },
      },
    },
    handler: async ({ fullPage }) => {
      // Take screenshot using Playwright/Puppeteer
      return screenshotBuffer;
    },
  },
]);

Version Compatibility​

PackageVersionNode.jsTypeScript
All packages1.x.x18+5.0+

Breaking Changes​

See CHANGELOG for version-specific breaking changes.

Contributing​

See the Contributing Guide for how to contribute to the API documentation.

Next Steps​

Agent Tool Protocol | ATP - Code Execution for AI Agents