@mondaydotcomorg/atp-client
Version:
Client SDK for Agent Tool Protocol
210 lines • 7.34 kB
JavaScript
import { ClientSession, InProcessSession, APIOperations, ExecutionOperations, ServiceProviders, } from './core/index.js';
import { createSearchApiTool, createFetchAllApisTool, createExecuteCodeTool, createExploreApiTool, } from './tools/index.js';
/**
* AgentToolProtocolClient provides a client interface for connecting to
* Agent Tool Protocol servers and executing code.
*/
export class AgentToolProtocolClient {
session;
inProcessSession;
apiOps;
execOps;
serviceProviders;
/**
* Creates a new client instance.
*
* @example
* ```typescript
* // HTTP mode
* const client = new AgentToolProtocolClient({
* baseUrl: 'http://localhost:3333',
* headers: { Authorization: 'Bearer token' },
* hooks: {
* preRequest: async (context) => {
* const token = await refreshToken();
* return { headers: { ...context.currentHeaders, Authorization: `Bearer ${token}` } };
* }
* }
* });
*
* // In-process mode (no port binding)
* const server = createServer();
* server.use(myApiGroup);
* const client = new AgentToolProtocolClient({ server });
* ```
*/
constructor(options) {
const { baseUrl, server, headers, serviceProviders, hooks } = options;
if (!baseUrl && !server) {
throw new Error('Either baseUrl or server must be provided');
}
if (baseUrl && server) {
throw new Error('Cannot provide both baseUrl and server');
}
this.serviceProviders = new ServiceProviders(serviceProviders);
if (server) {
this.inProcessSession = new InProcessSession(server);
this.session = this.inProcessSession;
this.apiOps = new APIOperations(this.session, this.inProcessSession);
this.execOps = new ExecutionOperations(this.session, this.serviceProviders, this.inProcessSession);
}
else {
this.session = new ClientSession(baseUrl, headers, hooks);
this.apiOps = new APIOperations(this.session);
this.execOps = new ExecutionOperations(this.session, this.serviceProviders);
}
}
/**
* Initializes the client session with the server.
* Automatically registers any client-provided tools and services with the server.
*/
async init(clientInfo) {
const toolDefinitions = this.serviceProviders.getToolDefinitions();
const services = {
hasLLM: !!this.serviceProviders.getLLM(),
hasApproval: !!this.serviceProviders.getApproval(),
hasEmbedding: !!this.serviceProviders.getEmbedding(),
hasTools: this.serviceProviders.hasTools(),
};
return await this.session.init(clientInfo, toolDefinitions, services);
}
/**
* Gets the unique client ID.
*/
getClientId() {
return this.session.getClientId();
}
/**
* Provides an LLM implementation for server to use during execution.
*/
provideLLM(handler) {
this.serviceProviders.provideLLM(handler);
}
/**
* Provides an approval handler for server to request human approval.
*/
provideApproval(handler) {
this.serviceProviders.provideApproval(handler);
}
/**
* Provides an embedding model for server to use.
*/
provideEmbedding(handler) {
this.serviceProviders.provideEmbedding(handler);
}
/**
* Provides custom tools that execute on the client side.
* Note: Must be called before init() or re-initialize after calling this.
*/
provideTools(tools) {
this.serviceProviders.provideTools(tools);
}
/**
* Gets all client-provided tools (registered via provideTools).
* Returns the full tool objects including handlers.
*/
getClientTools() {
return this.serviceProviders.getTools() || [];
}
/**
* Gets client-provided tool definitions (without handlers).
* Useful for sending tool metadata to servers.
*/
getClientToolDefinitions() {
return this.serviceProviders.getToolDefinitions();
}
/**
* Gets the ATP tools (execute_code, explore_api, search_api, fetch_all_apis).
* These are ready-to-use tools that can be exposed to MCP or other frameworks.
*
* @example
* ```typescript
* const tools = client.getATPTools();
* for (const tool of tools) {
* mcpServer.tool(tool.name, tool.description, tool.inputSchema, async (args) => {
* const result = await tool.func(args);
* return { content: [{ type: 'text', text: result }] };
* });
* }
* ```
*/
getATPTools() {
return [
createSearchApiTool(this),
createFetchAllApisTool(this),
createExecuteCodeTool(this),
createExploreApiTool(this),
];
}
/**
* Connects to the server and retrieves API definitions.
*/
async connect(options) {
return await this.apiOps.connect(options);
}
/**
* Gets the TypeScript type definitions for available APIs.
*/
getTypeDefinitions() {
return this.apiOps.getTypeDefinitions();
}
/**
* Searches for available API functions.
*/
async searchAPI(query, options) {
return await this.apiOps.searchAPI(query, options);
}
/**
* Explores the API filesystem at the given path.
*/
async exploreAPI(path) {
return await this.apiOps.exploreAPI(path);
}
/**
* Executes code on the server with real-time progress updates via SSE.
*/
async executeStream(code, config, onProgress) {
return await this.execOps.executeStream(code, config, onProgress);
}
/**
* Executes code on the server in a sandboxed environment.
*/
async execute(code, config) {
return await this.execOps.execute(code, config);
}
/**
* Resumes a paused execution with a callback result.
*/
async resume(executionId, callbackResult) {
return await this.execOps.resume(executionId, callbackResult);
}
/**
* Handles a callback request from the server during execution.
*/
async handleCallback(callbackType, payload) {
return await this.serviceProviders.handleCallback(callbackType, payload);
}
/**
* Gets information about the server.
*/
async getServerInfo() {
return await this.apiOps.getServerInfo();
}
/**
* Gets ATP runtime API definitions as TypeScript declarations.
* Returns the full TypeScript definitions for atp.llm.*, atp.cache.*, etc.
* These are the APIs available during code execution.
*
* Behavior:
* - No options: Returns APIs based on client capabilities (default filtering)
* - apis: ['llm', 'cache']: Returns only specified APIs (intersection with client capabilities)
* - apis: []: Returns all APIs regardless of client capabilities
*
* @param options - Optional filtering options
* @param options.apis - Specific APIs to include (e.g., ['llm', 'cache', 'approval'])
*/
async getRuntimeDefinitions(options) {
return await this.apiOps.getRuntimeDefinitions(options);
}
}
//# sourceMappingURL=client.js.map