Introduction to Agent Tool Protocol | Agent Tool Protocol
Skip to main content

Introduction to Agent Tool Protocol

What is Agent Tool Protocol?​

Agent Tool Protocol (ATP) is a comprehensive, production-ready framework designed to solve one of the most challenging problems in AI agent development: how to safely and effectively execute agent-generated code while maintaining security, observability, and control.

The Problem ATP Solves​

Modern AI agents need to interact with the real world through APIs, databases, and various services. However, this creates several critical challenges:

  1. Security Risk: Executing agent-generated code directly is dangerous
  2. API Complexity: Agents need access to multiple APIs with different authentication schemes
  3. Data Leakage: Sensitive data can inadvertently be sent to LLMs or external services
  4. Resource Management: Uncontrolled execution can consume excessive memory or CPU
  5. Observability: Understanding what agents are doing is crucial for debugging and auditing
  6. Integration Complexity: Connecting agents to existing systems requires significant engineering effort

ATP addresses all these challenges through a carefully designed architecture that provides:

  • Secure Sandbox Execution: Isolated V8 environments with resource limits
  • Unified API Interface: Aggregate multiple API sources (OpenAPI, custom, MCP)
  • Data Provenance Tracking: Know where data comes from and where it goes
  • Pause/Resume Capability: Handle async operations like LLM calls elegantly
  • Production Features: Caching, rate limiting, monitoring, and more

Core Architecture​

ATP is built on a layered architecture that separates concerns and provides maximum flexibility:

Layer Breakdown​

1. AI Agent Layer​

This is where your business logic lives. It could be:

  • A LangChain agent that reasons about which tools to use
  • A LangGraph workflow with multiple specialized agents
  • A custom agent you've built from scratch
  • Any system that needs to execute code or call APIs

The agent generates code or makes API calls, and ATP handles the rest.

2. Client Layer​

The client layer is your interface to ATP. It provides:

Code Execution: Send TypeScript/JavaScript code to be executed in a secure sandbox

const result = await client.execute(`
  const user = await users.getUser({ userId: '123' });
  return user;
`);

API Discovery: Search and explore available APIs

const results = await client.searchAPI('find user by email');

Service Providers: Provide services that code execution might need

  • LLM Provider: Your LLM (Anthropic, OpenAI, etc.) for code to call
  • Approval Handler: Human-in-the-loop for sensitive operations
  • Embedding Provider: Vector embeddings for semantic search

3. Protocol Layer​

ATP uses JSON-RPC 2.0 over HTTP (or WebSocket for streaming). This provides:

  • Standard request/response format
  • Error handling
  • Bi-directional communication
  • Easy to implement in any language

You rarely interact with this layer directly—the client handles it for you.

4. Server Layer​

The server is where the magic happens. It consists of four main components:

Sandbox Executor: Runs code in isolated V8 isolates with:

  • Memory limits (prevent OOM)
  • CPU time limits (prevent infinite loops)
  • No file system access (unless explicitly provided)
  • No network access (except through provided APIs)

API Aggregator: Combines multiple API sources:

  • Loads OpenAPI/Swagger specifications
  • Registers custom TypeScript functions
  • Connects to MCP (Model Context Protocol) servers
  • Manages client-side tools

Security & Provenance: Tracks data flow and enforces policies:

  • Know where every piece of data comes from
  • Detect attempts to exfiltrate sensitive data
  • Block data from reaching unintended recipients
  • Audit all data access

Search & Discovery: Helps agents find the right APIs:

  • Keyword-based search
  • Semantic search with embeddings
  • API exploration (like browsing a file system)
  • Automatic TypeScript type generation

5. API Sources​

ATP can aggregate APIs from multiple sources:

OpenAPI/Swagger: Automatically load API specifications

const petstoreAPI = await loadOpenAPI({
  url: 'https://petstore3.swagger.io/api/v3/openapi.json',
  name: 'petstore',
});
server.addAPIGroup(petstoreAPI);

Custom TypeScript: Define APIs with full type safety

server.registerAPI('users', {
  getUser: {
    description: 'Get a user by ID',
    inputSchema: { /* JSON Schema */ },
    handler: async ({ userId }) => { /* implementation */ }
  }
});

MCP Servers: Connect to Model Context Protocol servers

const mcpAPI = await MCPConnector.connect({
  url: 'http://localhost:8080/mcp',
  name: 'filesystem',
});
server.addAPIGroup(mcpAPI);

Client-Side Tools: Tools that execute on the client

client.provideTools([{
  name: 'readFile',
  namespace: 'filesystem',
  description: 'Read a local file',
  handler: async ({ path }) => { /* read file */ }
}]);

Key Features Explained​

🔒 Secure Sandbox Execution​

Every code execution runs in a completely isolated environment:

What's Blocked by Default:

  • File system access (no reading or writing files)
  • Network access (no making HTTP requests)
  • Process spawning (no running other programs)
  • Native modules (no loading compiled addons)
  • Dangerous APIs (eval, Function constructor, etc.)

What's Allowed:

  • TypeScript/JavaScript execution
  • Access to APIs you explicitly provide
  • Memory allocation (up to your limit)
  • CPU usage (up to your timeout)

Resource Limits:

const server = createServer({
  execution: {
    timeout: 30000,              // Max 30 seconds
    memory: 128 * MB,            // Max 128 MB
    llmCalls: 10,                // Max 10 LLM calls
  },
});

🔌 Flexible API Integration​

ATP excels at aggregating multiple API sources into a unified interface:

Benefits:

  • Unified Interface: All APIs accessible through consistent syntax
  • Authentication: Handle API keys, OAuth, JWT in one place
  • Rate Limiting: Prevent abuse across all APIs
  • Caching: Cache responses to reduce API calls
  • Type Safety: Generate TypeScript definitions automatically

🛡️ Advanced Provenance & Security​

Provenance tracking is one of ATP's most powerful features. It tracks the origin and flow of every piece of data:

What You Can Do With Provenance:

  1. Prevent Data Exfiltration
preventDataExfiltration({
  sources: ['users.getUser', 'payments.getCreditCard'],
  recipients: ['external-api', 'logging'],
});
  1. Require User Origin
requireUserOrigin({
  apis: ['payments.makePayment', 'users.deleteUser'],
});
  1. Block LLM Access
blockLLMRecipients({
  sources: ['secrets.getAPIKey', 'users.getSSN'],
});
  1. Audit Everything
auditSensitiveAccess({
  sources: ['users.*', 'payments.*'],
  logger: (event) => {
    console.log('Access:', event);
    siemSystem.log(event);
  },
});

⏸️ Pause/Resume Execution​

This is one of ATP's most innovative features. The problem: agents often need to call LLMs, but code running in a sandbox can't make network requests. ATP's solution: pause execution, make the call on the client, then resume.

Why This Matters:

  • Security: Network access stays on the client
  • Flexibility: Use any LLM provider you want
  • Caching: Results are automatically cached for replay
  • Batching: Multiple LLM calls can be batched for parallel execution

Example:

// Code running in sandbox
const answer = await llm.call({ 
  prompt: "What is 2+2?" 
});

// Execution pauses here, client handles it:
const result = await client.execute(code);
if (result.status === 'paused') {
  const llmResult = await myLLM.call(result.needsCallback.payload);
  const finalResult = await client.resume(result.executionId, llmResult);
}

🔍 Intelligent API Discovery​

As your API surface grows, agents need help finding the right APIs:

Search Capabilities:

  1. Keyword Search: Fast, exact matching
const results = await client.searchAPI('user email');
  1. Semantic Search: Natural language queries
const results = await client.searchAPI(
  'find someone by their email address',
  { useEmbeddings: true }
);
  1. API Exploration: Browse like a file system
const root = await client.exploreAPI('/');
const usersAPI = await client.exploreAPI('/users');
const getUser = await client.exploreAPI('/users/getUser');
  1. Type Generation: Get TypeScript definitions
const types = client.getTypeDefinitions();
// Outputs:
// declare namespace users {
//   function getUser(params: { userId: string }): Promise<User>;
// }

🚀 Production Ready​

ATP isn't just a prototype—it's designed for production use:

Caching:

// Memory cache (single instance)
new MemoryCache({ maxKeys: 1000, defaultTTL: 3600 })

// Redis cache (distributed)
new RedisCache({ 
  url: process.env.REDIS_URL,
  keyPrefix: 'atp:',
})

Rate Limiting:

server.use(async (context, next) => {
  await rateLimiter.consume(context.clientId);
  return next();
});

Monitoring with OpenTelemetry:

const server = createServer({
  otel: {
    enabled: true,
    serviceName: 'atp-server',
    traceEndpoint: 'http://localhost:4318/v1/traces',
    metricsEndpoint: 'http://localhost:4318/v1/metrics',
  },
});

Horizontal Scaling:

Load Balancer
    ├── ATP Server 1
    ├── ATP Server 2
    ├── ATP Server 3
    └── ATP Server 4
           │
      Redis (shared state)

Use Cases​

🤖 AI Agent Development​

Problem: You want to build an AI agent that can interact with your APIs, but you need security, observability, and control.

Solution: Use ATP as your agent's execution environment:

// Your agent code
const agent = new LangChainAgent({
  llm: anthropic,
  tools: await ATPLangChainTools.fromClient(client),
});

// Agent can now safely call any API you've registered
await agent.invoke({ 
  input: "Find user john@example.com and send them a welcome email" 
});

Benefits:

  • Secure execution of agent-generated code
  • All API calls go through ATP (audit trail)
  • Data provenance prevents sensitive data leakage
  • Easy to add new APIs without changing agent code

🔗 API Orchestration​

Problem: You have multiple APIs (internal services, third-party APIs, databases) and want to make them accessible to agents in a unified way.

Solution: Use ATP as an API gateway:

// Register internal APIs
server.registerAPI('users', { /* custom handlers */ });
server.registerAPI('orders', { /* custom handlers */ });

// Load external APIs
const stripeAPI = await loadOpenAPI({
  url: 'https://api.stripe.com/openapi.yaml',
  name: 'stripe',
  auth: { apiKey: process.env.STRIPE_KEY },
});
server.addAPIGroup(stripeAPI);

// Connect to MCP servers
const filesystemAPI = await MCPConnector.connect({
  url: 'http://localhost:8080/mcp',
  name: 'filesystem',
});
server.addAPIGroup(filesystemAPI);

Benefits:

  • Single interface for all APIs
  • Centralized authentication
  • Rate limiting across all sources
  • Monitoring and logging

🛡️ Secure Code Execution​

Problem: You need to execute untrusted code (from users, from agents, from external sources) safely.

Solution: ATP's sandbox provides isolation and security:

// Execute untrusted code safely
const result = await client.execute(`
  // This code runs in a secure sandbox
  // It can't access your file system
  // It can't make arbitrary network requests
  // It can only use the APIs you've provided
  
  const data = await myAPI.getData();
  return processData(data);
`, {
  timeout: 10000,      // Max 10 seconds
  maxMemory: 64 * MB,  // Max 64 MB
  maxLLMCalls: 5,      // Max 5 LLM calls
});

Benefits:

  • Complete isolation from host system
  • Resource limits prevent abuse
  • Provenance tracking for audit
  • Easy to integrate with existing systems

📊 Data Provenance & Compliance​

Problem: You need to track where sensitive data goes for compliance (GDPR, PCI-DSS, HIPAA, etc.).

Solution: ATP's provenance system tracks everything:

const server = createServer({
  execution: {
    provenanceMode: 'enforce',
    securityPolicies: [
      // GDPR: EU user data can't leave EU
      preventDataExfiltration({
        sources: ['users.getEUUser'],
        recipients: ['external-*'],
      }),
      
      // PCI-DSS: Credit card data can't go to LLM
      blockLLMRecipients({
        sources: ['payments.getCreditCard'],
      }),
      
      // Audit all access to sensitive data
      auditSensitiveAccess({
        sources: ['users.*', 'payments.*'],
        logger: (event) => complianceSystem.log(event),
      }),
    ],
  },
});

Benefits:

  • Automatic tracking of all data flow
  • Enforce policies programmatically
  • Complete audit trail
  • Prevent accidental violations

Quick Example​

Here's a complete example to show how everything fits together:

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

const server = createServer({
  execution: {
    timeout: 30000,
    memory: 128 * 1024 * 1024,
    provenanceMode: 'track',
  },
});

// Register a simple calculator API
server.registerAPI('calculator', {
  add: {
    description: 'Add two numbers together',
    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;
    },
  },
});

server.listen(3333, () => {
  console.log('ATP Server running on http://localhost:3333');
});

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

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

// Initialize and connect
await client.init({ name: 'my-agent', version: '1.0.0' });
await client.connect();

console.log('✅ Connected to ATP server');

// ========================================
// EXECUTE CODE
// ========================================
const result = await client.execute(`
  // This code runs in a secure sandbox
  console.log('Calculating (10 + 5) * 3...');
  
  // Call the calculator API
  const sum = await calculator.add({ a: 10, b: 5 });
  console.log('Sum:', sum);  // 15
  
  const product = await calculator.multiply({ a: sum, b: 3 });
  console.log('Product:', product);  // 45
  
  return {
    sum,
    product,
    message: 'Calculation complete!'
  };
`);

console.log('Result:', result.result);
// Output: { sum: 15, product: 45, message: 'Calculation complete!' }

console.log('Execution took:', result.stats.duration, 'ms');
console.log('Memory used:', result.stats.memoryUsed, 'bytes');

Why Agent Tool Protocol?​

For AI Researchers & Developers​

  • Focus on Agent Logic: Don't worry about sandboxing, security, or API integration
  • Rapid Iteration: Add new APIs without rewriting agent code
  • Built-in Safety: Provenance tracking and security policies included
  • Easy Integration: Works with LangChain, LangGraph, or any framework

For Enterprise Teams​

  • Production Ready: Monitoring, caching, rate limiting built-in
  • Security First: Sandboxing, provenance, and policy enforcement
  • Compliance Friendly: Track data flow for GDPR, PCI-DSS, HIPAA
  • Scalable: Horizontal scaling with Redis for shared state

For Tool Developers​

  • Multiple API Sources: OpenAPI, custom, MCP all supported
  • Type Safe: Full TypeScript support with automatic type generation
  • Rich Metadata: Security levels, operation types, required scopes
  • Discovery: Semantic search helps agents find your APIs

What's Next?​

Start Building​

Learn Core Concepts​

Explore Examples​

Community & Support​

  • GitHub: mondaycom/agent-tool-protocol
  • Issues: Report bugs and request features
  • Discussions: Ask questions and share ideas
  • Documentation: You're reading it! 📚

License​

Agent Tool Protocol is MIT licensed. Free for commercial and personal use.

Ready to build secure, powerful AI agents?

Start with the Quick Start Guide and have your first agent running in less than 5 minutes! 🚀

Agent Tool Protocol | ATP - Code Execution for AI Agents