Agent Tool Protocol

A production-ready, code-first protocol for AI agents to interact with external systems through secure sandboxed code execution.

What is Agent Tool Protocol?

Agent Tool Protocol (ATP) is a next-generation protocol that enables AI agents to interact with external systems by generating and executing TypeScript/JavaScript code in a secure, sandboxed environment. Unlike traditional function-calling protocols, ATP allows LLMs to write code that can execute multiple operations in parallel, filter and transform data, chain operations together, and use familiar programming patterns.

ATP provides a complete ecosystem for building production-ready AI agents with:

Secure code execution in isolated V8 VMs with memory limits and timeouts
Runtime SDK (atp.*) for LLM calls, embeddings, approvals, caching, and logging
Stateless architecture with optional caching for scalability
Client tools for seamless integration with LangChain, LangGraph, and other frameworks
Provenance tracking to defend against prompt injection attacks
OpenAPI and MCP compatibility for connecting to any API or MCP server

Why ATP vs MCP?

Traditional function-calling protocols like Model Context Protocol (MCP) have fundamental limitations:

MCP Limitations

Context Bloat: Large schemas consume significant tokens in every request
Sequential Execution: Only one tool can be called at a time
No Data Processing: Can't filter, transform, or combine results within the protocol
Limited Model Support: Not all LLMs support function calling well
Schema Overhead: Complex nested schemas are verbose and token-expensive

ATP Advantages

✅ OpenAPI Integration: Built in open api integration allowing to connect a single server to multiple mcps & openapis
✅ Parallel Execution: Execute multiple operations simultaneously
✅ Data Processing: Filter, map, reduce, and transform data inline
✅ Code Flexibility: Use familiar programming patterns (loops, conditionals, async/await)
✅ Universal Compatibility: Works with any LLM that can generate code
✅ Reduced Token Usage: Code is more concise than verbose JSON schemas
✅ Type Safety: Full TypeScript support with generated type definitions
✅ Production Ready: Built-in security, caching, state management, and observability

ATP solves these problems by letting LLMs write code that executes in a secure sandbox, giving agents the full power of a programming language while maintaining strict security boundaries.

Architecture & Capabilities

High Level Architecture

graph TB
LLM[LLM/Agent] --> Client[ATP Client]
Client --> Server[ATP Server]
Server --> Validator[Code Validator<br/>AST Analysis]
Server --> Executor[Sandbox Executor<br/>Isolated VM]
Server --> Aggregator[API Aggregator<br/>OpenAPI/MCP/Custom]
Server --> Search[Search Engine<br/>Semantic/Keyword]
Server --> State[State Manager<br/>Pause/Resume]
Executor --> Runtime[Runtime APIs]
Runtime --> LLMAPI[atp.llm.*]
Runtime --> EmbedAPI[atp.embedding.*]
Runtime --> ApprovalAPI[atp.approval.*]
Runtime --> CacheAPI[atp.cache.*]
Runtime --> LogAPI[atp.log.*]
LLMAPI -.Pause.-> Client
EmbedAPI -.Pause.-> Client
ApprovalAPI -.Pause.-> Client
Aggregator --> OpenAPI[OpenAPI Loader]
Aggregator --> MCP[MCP Connector]
Aggregator --> Custom[Custom Functions]

Runtime SDK (`atp.*`)

Agents executing code have access to a powerful runtime SDK that provides:

atp.llm.*: Client-side LLM execution with call, extract, and classify methods
atp.embedding.*: Semantic search with embedding storage and similarity search
atp.approval.*: Human-in-the-loop approvals with pause/resume support
atp.cache.*: Key-value caching with TTL support
atp.log.*: Structured logging for debugging and observability
atp.progress.*: Progress reporting for long-running operations
atp.api.*: Dynamic APIs from OpenAPI specs, MCP servers, or custom functions

The runtime SDK enables agents to perform complex workflows that require LLM reasoning, data persistence, human approval, and more—all within the secure sandbox.

Stateless Architecture with Caching

ATP is designed as a stateless system for horizontal scalability:

Stateless Server: Can work completely stateless with distribute caching like redis
Execution State: Long-running executions can pause and resume via state management
State TTL: Configurable time-to-live for execution state

This architecture allows ATP servers to scale horizontally while maintaining execution continuity for complex workflows.

Client Execution

ATP provides the ability to execute code in the client side:

LLM Callbacks: Client-side LLM execution with automatic pause/resume
Approval Workflows: Approvals for human-in-the-loop
Client tools: Support executing tools defined in the client side
Embedding Capabilities: Execute embedding request using the client embedding model

Provenance Security

ATP includes advanced security features to defend against prompt injection and data exfiltration:

Provenance Tracking: Tracks the origin of all data (user, LLM, API, etc.)
Security Policies: Configurable policies like preventDataExfiltration and requireUserOrigin
AST Analysis: Code validation to detect forbidden patterns
Proxy Mode: Runtime interception of all external calls
Audit Logging: Complete audit trail of all executions

Provenance security is inspired by Google Research's CAMEL paper and provides defense-in-depth against adversarial inputs.

📦 Installation

# Using Yarn (recommended)
yarn add @mondaydotcomorg/atp-server @mondaydotcomorg/atp-client
# Using npm
npm install @mondaydotcomorg/atp-server @mondaydotcomorg/atp-client
# Using pnpm
pnpm add @mondaydotcomorg/atp-server @mondaydotcomorg/atp-client
# Using bun
bun add @mondaydotcomorg/atp-server @mondaydotcomorg/atp-client

📝 Note: The --no-node-snapshot flag is required for Node.js 20+

🎯 Quick Start

Quickstart Example

A single script that integrates OpenAPI (Petstore) and MCP (Playwright):

import{createServer,loadOpenAPI}from'@mondaydotcomorg/atp-server';import{AgentToolProtocolClient}from'@mondaydotcomorg/atp-client';import{MCPConnector}from'@mondaydotcomorg/atp-mcp-adapter';process.env.ATP_JWT_SECRET=process.env.ATP_JWT_SECRET||'test-secret-key';asyncfunctionmain(){constserver=createServer({});// Load OpenAPI spec (supports OpenAPI 3.0+ and Swagger 2.0)constpetstore=awaitloadOpenAPI('https://petstore.swagger.io/v2/swagger.json',{name: 'petstore',filter: {methods: ['GET']},});// Connect to MCP serverconstmcpConnector=newMCPConnector();constplaywright=awaitmcpConnector.connectToMCPServer({name: 'playwright',command: 'npx',args: ['@playwright/mcp@latest'],});server.use([petstore,playwright]);awaitserver.listen(3333);// Create client and execute codeconstclient=newAgentToolProtocolClient({baseUrl: 'http://localhost:3333',});awaitclient.init({name: 'quickstart',version: '1.0.0'});// Execute code that filters, maps, and transforms API dataconstresult=awaitclient.execute(` const pets = await api.petstore.findPetsByStatus({ status: 'available' }); const categories = pets .filter(p => p.category?.name) .map(p => p.category.name) .filter((v, i, a) => a.indexOf(v) === i); return { totalPets: pets.length, categories: categories.slice(0, 5), sample: pets.slice(0, 3).map(p => ({ name: p.name, status: p.status })) };	`);console.log('Result:',JSON.stringify(result.result,null,2));}main().catch(console.error);

Run it:

cd examples/quickstart
NODE_OPTIONS='--no-node-snapshot' npm start

LangChain Agent Example

Use ATP with LangChain/LangGraph for autonomous agents:

import{createServer,loadOpenAPI}from'@mondaydotcomorg/atp-server';import{ChatOpenAI}from'@langchain/openai';import{createReactAgent}from'@langchain/langgraph/prebuilt';import{createATPTools}from'@mondaydotcomorg/atp-langchain';asyncfunctionmain(){// Start ATP server with OpenAPIconstserver=createServer({});constpetstore=awaitloadOpenAPI('https://petstore.swagger.io/v2/swagger.json',{name: 'petstore',filter: {methods: ['GET']},});server.use([petstore]);awaitserver.listen(3333);// Create LangChain agent with ATP toolsconstllm=newChatOpenAI({modelName: 'gpt-4o-mini',temperature: 0});const{ tools }=awaitcreateATPTools({serverUrl: 'http://localhost:3333',
llm,});constagent=createReactAgent({ llm, tools });// Agent autonomously uses ATP to call APIsconstresult=awaitagent.invoke({messages: [{role: 'user',content:
'Use ATP to fetch available pets from the petstore API, then tell me how many pets are available and list 3 example pet names.',},],});console.log('Agent response:',result.messages[result.messages.length-1].content);}main().catch(console.error);

Run it:

cd examples/langchain-quickstart
export OPENAI_API_KEY=sk-...
NODE_OPTIONS='--no-node-snapshot' npm start

📝 Note: The --no-node-snapshot flag is required for Node.js 20+ and is already configured in the package.json.

🧠 Advanced LangChain Features

LLM Callbacks & Approval Workflows

ATP provides powerful LangChain/LangGraph integration with LLM callbacks and approval workflows:

import{MemorySaver}from'@langchain/langgraph';import{createATPTools}from'@mondaydotcomorg/atp-langchain';import{ChatOpenAI}from'@langchain/openai';constllm=newChatOpenAI({modelName: 'gpt-4.1'});// Create ATP tools with LLM support and LangGraph interrupt-based approvalsconst{ tools, isApprovalRequired, resumeWithApproval }=awaitcreateATPTools({serverUrl: 'http://localhost:3333',
llm,// useLangGraphInterrupts: true (default) - use LangGraph checkpoints for async approvals});constcheckpointer=newMemorySaver();constagent=createReactAgent({ llm, tools,checkpointSaver: checkpointer});try{awaitagent.invoke({messages: [...]},{configurable: {thread_id: 'thread-1'}});}catch(error){if(isApprovalRequired(error)){const{ executionId, message }=error.approvalRequest;// Notify user (Slack, email, etc.)awaitnotifyUser(message);// Wait for approval (async - can take hours/days)constapproved=awaitwaitForApproval(executionId);// Resume executionconstresult=awaitresumeWithApproval(executionId,approved);}}// Alternative: Simple synchronous approval handlerconst{ tools }=awaitcreateATPTools({serverUrl: 'http://localhost:3333',
llm,useLangGraphInterrupts: false,// Required for approvalHandlerapprovalHandler: async(message,context)=>{console.log('Approval requested:',message);returntrue;// or false to deny},});

📚 Runtime APIs Overview

The atp.* runtime SDK provides a comprehensive set of APIs for agents executing code:

atp.llm.*: Client-side LLM execution for reasoning, extraction, and classification (requires client.provideLLM())
atp.embedding.*: Semantic search with embedding storage and similarity search (requires client.provideEmbedding())
atp.approval.*: Human-in-the-loop approvals with pause/resume support (requires client.provideApproval())
atp.cache.*: Key-value caching with TTL for performance optimization
atp.log.*: Structured logging for debugging and observability
atp.progress.*: Progress reporting for long-running operations
atp.api.*: Dynamic APIs from OpenAPI specs, MCP servers, or custom functions

All runtime APIs are available within the secure sandbox and automatically handle pause/resume for operations that require client-side interaction (LLM, embeddings, approvals).

🛡️ Security Features

Sandboxed Execution

Isolated VM: Code runs in true V8 isolates with separate heaps
No Node.js Access: Zero access to fs, net, child_process, etc.
Memory Limits: Hard memory limits enforced at VM level
Timeout Protection: Automatic termination after timeout
Code Validation: AST analysis and forbidden pattern detection

Provenance Security

Defend against prompt injection with provenance tracking:

import{createServer,ProvenanceMode}from'@mondaydotcomorg/atp-server';import{preventDataExfiltration,requireUserOrigin}from'@mondaydotcomorg/atp-server';constserver=createServer({execution: {provenanceMode: ProvenanceMode.PROXY,// or ASTsecurityPolicies: [preventDataExfiltration,// Block data exfiltrationrequireUserOrigin,// Require user-originated data],},});

Runtime Controls

LLM Call Limits: Configurable max LLM calls per execution
Rate Limiting: Requests per minute and executions per hour
API Key Authentication: Optional API key requirement
Audit Logging: All executions logged for compliance

🔍 API Discovery

ATP provides intelligent API discovery to help agents find the right tools:

Semantic Search: Embedding-based search for natural language queries (requires embeddings)
Keyword Search: Fast keyword-based search across API names and descriptions
Type Definitions: Generated TypeScript definitions for all available APIs
Schema Exploration: Full API schema exploration via client.explore()

⚙️ Configuration

Full server configuration:

import{createServer}from'@mondaydotcomorg/atp-server';import{RedisCache,JSONLAuditSink}from'@mondaydotcomorg/atp-providers';constserver=createServer({execution: {timeout: 30000,// 30 secondsmemory: 128*1024*1024,// 128 MBllmCalls: 10,// Max LLM calls per executionprovenanceMode: 'proxy',// Provenance tracking modesecurityPolicies: [...],// Security policies},clientInit: {tokenTTL: 3600,// 1 hourtokenRotation: 1800,// 30 minutes},executionState: {ttl: 3600,// State TTL in secondsmaxPauseDuration: 3600,// Max pause duration},discovery: {embeddings: embeddingsModel,// Enable semantic search},audit: {enabled: true,sinks: [newJSONLAuditSink({path: './logs',rotateDaily: true}),],},otel: {enabled: true,serviceName: 'atp-server',traceEndpoint: 'http://localhost:4318/v1/traces',},});// Add providersserver.setCacheProvider(newRedisCache({ redis }));server.setAuthProvider(authProvider);awaitserver.start(3333);

🚀 Production Features

Redis Cache

import{RedisCache}from'@mondaydotcomorg/atp-providers';importRedisfrom'ioredis';constredis=newRedis(process.env.REDIS_URL);server.setCacheProvider(newRedisCache({ redis }));

Audit Logging

import{JSONLAuditSink}from'@mondaydotcomorg/atp-providers';constserver=createServer({audit: {enabled: true,sinks: [newJSONLAuditSink({path: './audit-logs',rotateDaily: true})],},});

OpenTelemetry

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

OAuth Integration

import{GoogleOAuthProvider}from'@mondaydotcomorg/atp-providers';constoauthProvider=newGoogleOAuthProvider({clientId: process.env.GOOGLE_CLIENT_ID,clientSecret: process.env.GOOGLE_CLIENT_SECRET,redirectUri: 'http://localhost:3333/oauth/callback',scopes: ['https://www.googleapis.com/auth/calendar'],});server.addAPIGroup({name: 'calendar',type: 'oauth',
oauthProvider,functions: [...],});

🏗️ Packages

@agent-tool-protocol/
├── protocol # Core types and interfaces
├── server # ATP server implementation
├── client # Client SDK
├── runtime # Runtime APIs (atp.*)
├── mcp-adapter # MCP integration
├── langchain # LangChain/LangGraph integration
├── atp-compiler # Loop transformation and optimization
├── providers # Cache, auth, OAuth, audit providers
└── provenance # Provenance security (CAMEL-inspired)

🧪 Examples

All examples are self-contained and work end-to-end without external servers.

📝 Note: Node.js 20+ requires the --no-node-snapshot flag. This is already configured in each example's package.json scripts, so just run npm start.

1. Quickstart - OpenAPI + MCP

Complete example with OpenAPI (Petstore) and MCP (Playwright) integration.

cd examples/quickstart
NODE_OPTIONS='--no-node-snapshot' npm start

Environment variables:

ATP_JWT_SECRET - Optional (defaults to test-secret-key in code)

2. LangChain Agent

Autonomous LangChain agent using ATP to interact with APIs.

cd examples/langchain-quickstart
export OPENAI_API_KEY=sk-...
NODE_OPTIONS='--no-node-snapshot' npm start

Environment variables:

OPENAI_API_KEY - Required: Your OpenAI API key
ATP_JWT_SECRET - Optional (defaults to test-secret-key in code)

3. LangChain React Agent

Advanced LangChain agent with the test server.

# Start test servercd examples/test-server
npx tsx server.ts
# Run agentcd examples/langchain-react-agent
export OPENAI_API_KEY=sk-...
npm start

Environment variables:

OPENAI_API_KEY - Required: Your OpenAI API key

4. Additional Examples

Other examples in the examples/ directory:

openapi-example - OpenAPI integration examples
oauth-example - OAuth flow examples
production-example - Production configuration examples

🚢 Development

# Clone repository
git clone https://github.com/yourusername/agent-tool-protocol.git
cd agent-tool-protocol
# Install dependencies (Node.js 18+)
yarn install
# Build all packages
yarn build
# Run tests
yarn test# Run E2E tests
yarn test:e2e
# Lint
yarn lint

Publishing

See docs/publishing.md for publishing releases and prereleases.

📦 Requirements

Node.js Version

Node.js 18+ is required. Node.js 20+ requires the --no-node-snapshot flag.

Compiler Setup (for isolated-vm)

isolated-vm requires native compilation:

macOS: xcode-select --install
Ubuntu/Debian: sudo apt-get install python3 g++ build-essential
Windows: See node-gyp Windows instructions

📄 License

This project is licensed under the MIT License - see the License file for details.

🙏 Acknowledgments

Inspired by Model Context Protocol (MCP)
Provenance security based on Google Research's CAMEL paper
Sandboxing powered by isolated-vm
LangChain integration via @langchain/core

🔗 Links

Documentation: docs/
Examples: examples/
Packages: packages/

Built with ❤️ for the AI community

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.husky		.husky
.yarn/releases		.yarn/releases
__mocks__/zod-to-json-schema		__mocks__/zod-to-json-schema
__tests__		__tests__
docs		docs
examples		examples
packages		packages
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.prettierrc.json		.prettierrc.json
.yarnrc.yml		.yarnrc.yml
LICENSE		LICENSE
README.md		README.md
commitlint.config.ts		commitlint.config.ts
env.example		env.example
eslint.config.ts		eslint.config.ts
jest-resolver.js		jest-resolver.js
jest.config.js		jest.config.js
jest.e2e.config.ts		jest.e2e.config.ts
nx.json		nx.json
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Agent Tool Protocol

What is Agent Tool Protocol?

Why ATP vs MCP?

MCP Limitations

ATP Advantages

Architecture & Capabilities

High Level Architecture

Runtime SDK (atp.*)

Stateless Architecture with Caching

Client Execution

Provenance Security

📦 Installation

🎯 Quick Start

Quickstart Example

LangChain Agent Example

🧠 Advanced LangChain Features

LLM Callbacks & Approval Workflows

📚 Runtime APIs Overview

🛡️ Security Features

Sandboxed Execution

Provenance Security

Runtime Controls

🔍 API Discovery

⚙️ Configuration

🚀 Production Features

Redis Cache

Audit Logging

OpenTelemetry

OAuth Integration

🏗️ Packages

🧪 Examples

1. Quickstart - OpenAPI + MCP

2. LangChain Agent

3. LangChain React Agent

4. Additional Examples

🚢 Development

Publishing

📦 Requirements

Node.js Version

Compiler Setup (for isolated-vm)

📄 License

🙏 Acknowledgments

🔗 Links

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Runtime SDK (`atp.*`)