{"id":16292,"library":"acp-http-client","title":"ACP HTTP Client","description":"acp-http-client is a TypeScript-first client library designed for interacting with Agent Computer Protocol (ACP) JSON-RPC services over streamable HTTP. It facilitates communication with a 'sandbox agent,' enabling operations such as desktop computer-use APIs, agent computer providers, and lifecycle management features like auto-pause support. The library is part of the larger Rivet Sandbox Agent project, which focuses on advanced agent capabilities for AI agents. Currently, the stable version is 0.4.2, with active development progressing towards 0.5.0, as indicated by recent release candidates (e.g., 0.5.0-rc.3). Development appears continuous, with frequent releases incorporating new features and fixes related to agent providers, E2B integration, and underlying agent infrastructure. Its key differentiator lies in its specialized focus on ACP and streamable HTTP for robust agent-computer interaction, contrasting with generic HTTP or RPC clients.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/rivet-dev/sandbox-agent","tags":["javascript","typescript"],"install":[{"cmd":"npm install acp-http-client","lang":"bash","label":"npm"},{"cmd":"yarn add acp-http-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add acp-http-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for instantiating the ACP client. The library is primarily ESM, but CommonJS `require` might work with transpilation or specific Node.js settings.","wrong":"const AcpHttpClient = require('acp-http-client').AcpHttpClient;","symbol":"AcpHttpClient","correct":"import { AcpHttpClient } from 'acp-http-client';"},{"note":"For handling RPC-specific errors returned by the agent. Check `error.code` and `error.message`.","symbol":"AcpRpcError","correct":"import { AcpRpcError } from 'acp-http-client';"},{"note":"TypeScript type definition for the client configuration object, useful for ensuring correct setup parameters.","symbol":"AcpClientConfig","correct":"import type { AcpClientConfig } from 'acp-http-client';"}],"quickstart":{"code":"import { AcpHttpClient } from 'acp-http-client';\n\ninterface AgentApi {\n  desktop: {\n    getScreenResolution(): Promise<{ width: number; height: number }>;\n    click(x: number, y: number): Promise<void>;\n  };\n  fileSystem: {\n    readFile(path: string): Promise<string>;\n  };\n}\n\nasync function runAgentTask() {\n  const agentEndpoint = process.env.ACP_AGENT_ENDPOINT ?? 'http://localhost:8080';\n  const client = new AcpHttpClient<AgentApi>({\n    baseUrl: agentEndpoint,\n    // Optional: Add authentication headers if your agent requires it\n    headers: {\n      'Authorization': `Bearer ${process.env.ACP_AGENT_TOKEN ?? ''}`\n    }\n  });\n\n  try {\n    console.log('Connecting to ACP agent at:', agentEndpoint);\n    const resolution = await client.call('desktop.getScreenResolution');\n    console.log('Agent screen resolution:', resolution);\n\n    // Example: Click at the center of the screen\n    await client.call('desktop.click', resolution.width / 2, resolution.height / 2);\n    console.log('Successfully simulated a click.');\n\n    const fileContent = await client.call('fileSystem.readFile', '/etc/hostname');\n    console.log('Hostname file content:', fileContent.trim());\n\n  } catch (error) {\n    if (error instanceof AcpRpcError) {\n      console.error(`RPC Error (${error.code}): ${error.message}`);\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n    process.exit(1);\n  }\n}\n\nrunAgentTask();\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the AcpHttpClient, define an agent's API interface, and make a basic JSON-RPC call to interact with a sandboxed agent's desktop and file system APIs."},"warnings":[{"fix":"Refer to the `sandbox-agent` repository's documentation or changelog for the correct agent installation script URL and ensure your deployed agent version is compatible with the client library's expected protocol.","message":"The install script URL for the underlying sandbox agent changed between v0.3.x and v0.4.x. While this client library primarily interfaces with a running agent, changes in the agent's installation and version compatibility might require updates to your agent deployment strategy.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Always pin to exact minor or patch versions (e.g., `0.4.2` or `^0.4.0`) to avoid unexpected behavior. Review the changelog for `0.5.0` (and subsequent major versions) thoroughly before upgrading to production environments.","message":"The library is under active development, with frequent release candidates (e.g., 0.5.0-rc.X) introducing new features like 'Agent Computer providers' and 'desktop computer-use APIs.' These features may involve new RPC methods or changes to existing ones, potentially requiring updates to your client-side API interfaces.","severity":"gotcha","affected_versions":">=0.5.0-rc.1"},{"fix":"Update error handling logic to account for potentially richer `AcpRpcError` messages and consider the implications of `defaultCwd` if you rely on specific working directories for agent commands. Test existing RPC error handling after upgrade.","message":"Error handling for RPC calls has been improved to surface agent `stderr` in RPC errors, and a `defaultCwd` parameter was added. This change might affect how you parse or react to RPC errors from the agent and how you configure command execution.","severity":"breaking","affected_versions":">=0.5.0-rc.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { AcpHttpClient } from 'acp-http-client';` for modern JavaScript/TypeScript environments. If forced to use CommonJS, ensure your build tool correctly transpiles ESM imports or look for a specific CJS build if available (though unlikely for this library).","cause":"Attempting to import `AcpHttpClient` using CommonJS `require` syntax or an incorrect named import.","error":"TypeError: AcpHttpClient is not a constructor"},{"fix":"Verify that the `sandbox-agent` running matches the expected version by the `acp-http-client` library. Check the agent's logs for available RPC methods or ensure your agent's configuration properly registers the required capabilities.","cause":"The agent being communicated with does not expose the requested RPC method, likely due to a version mismatch between the client and the agent, or a misconfigured agent.","error":"Error: RPC Method '...' not found"},{"fix":"Ensure the `sandbox-agent` is running and accessible at the `baseUrl` provided during `AcpHttpClient` initialization (e.g., `http://localhost:8080`). Check firewall rules and the agent's actual listening address and port.","cause":"The `acp-http-client` could not establish a connection to the configured agent endpoint, often because the agent is not running or is listening on a different address/port.","error":"ECONNREFUSED connect ECONNREFUSED ::1:8080"}],"ecosystem":"npm"}