ClientAgentJS

ClientAgentJS

ClientAgentJS is a plain JavaScript browser library for adding AI agent capabilities to web applications without building your own backend.

ClientAgentJS uses a Zero-Backend Architecture. Unlike traditional AI applications that proxy requests through a server, this library runs entirely in the browser. It follows a Direct Client-to-Provider model where the user’s credentials never leave their device and requests go directly from the browser to the AI provider.

Use Cases

Live Examples

Try the interactive examples online:

Key Features

Model Context Protocol (MCP)

ClientAgentJS supports the Model Context Protocol, allowing agents to use external tools and data sources.

For more details on implementing or connecting to MCP servers, see the MCP Tools example.

What it does not require

What it provides

Development

Build the distributable files:

npm run build

Run tests:

npm test

Getting Started

Installation

Since the project is not yet published on npm, use the pre-built files from the dist/ folder:

ESM (recommended for modern projects):

import { createAgent } from './dist/clientagentjs.esm.js';

Global script (for classic web environments):

<script src="dist/clientagentjs.global.js"></script>
<script>
  // Access via the global variable ClientAgent
  const agent = ClientAgent.createAgent({
    storageKey: "my-app-unique-key"
  });
</script>

Basic Usage

import { createAgent } from './dist/clientagentjs.esm.js';

const agent = createAgent();

// Check if a profile is configured
if (!agent.isReady()) {
  agent.openConfigPanel();
}

// Simple request
const response = await agent.ask("Hello, who are you?");
console.log(response.text);

// Streaming request
for await (const chunk of agent.stream("Tell me a story")) {
  process.stdout.write(chunk.delta);
}

Streaming

const controller = new AbortController()

for await (const chunk of agent.stream("Write a headline", {
  signal: controller.signal
})) {
  console.log(chunk.text)
}

Sessions

const session = agent.createSession()

await session.ask("Who won the previous round?")
await session.ask("Now summarize it in one sentence.")

Profiles and import/export

Profiles store provider, model, credentials, prompt defaults and related options. MCP server configuration is stored separately and referenced from profiles.

const backup = agent.exportProfiles()
agent.importProfiles(backup)

Calling importProfiles() always shows a confirmation warning before replacing the current profiles and MCP configuration.

Local tools

The agent can register developer-defined tools that run in the browser and can be used automatically by compatible providers.

agent.registerTool("calculate_sum", ({ numbers }) => {
  return {
    total: numbers.reduce((acc, value) => acc + Number(value || 0), 0)
  }
})

Public methods:

Tool handlers receive one input object and can return plain JSON-compatible data or a string. If the tool is used through model tool-calling, the result is serialized and injected back into the model flow.

Use local tools for lightweight client-side actions. For advanced or external integrations, prefer MCP servers.

Configuration panel

The built-in UI opens from the public API:

agent.openConfigPanel()
agent.openMcpPanel()

The built-in panels use English translations.

Provider types

The profile field providerType selects the adapter implementation:

CORS

Since ClientAgentJS runs entirely in the browser, it requires AI providers to support CORS (Cross-Origin Resource Sharing). Not all providers enable CORS by default, and some require special configuration.

Provider CORS Support

When a Provider Does Not Support CORS

  1. Use your own backend proxy: Route API requests through a server you control, then point ClientAgentJS at your proxy endpoint using an OpenAI-compatible configuration.
  2. Use OpenRouter: OpenRouter supports CORS and provides access to models from OpenAI, Anthropic, Mistral, Meta, and many others through a single endpoint — useful when you need browser-compatible access to models whose native APIs do not support it.
  3. Use a public CORS proxy (development only): Services like cors-anywhere can add CORS headers to proxied requests, but are unreliable and should not be used in production.

Ollama CORS Configuration

Ollama does not enable CORS by default. To use it with ClientAgentJS, start Ollama with the appropriate CORS headers:

OLLAMA_ORIGINS="*" ollama serve

Or set the environment variable permanently:

# Linux/macOS
export OLLAMA_ORIGINS="*"
ollama serve

# Windows
set OLLAMA_ORIGINS=*
ollama serve

For production environments, restrict origins to your specific domain instead of *:

OLLAMA_ORIGINS="http://localhost:*" ollama serve

MCP and CORS

MCP servers also need to support CORS when accessed from the browser. Many MCP servers are designed to run as local processes and are not built for direct browser access.

Options:

  1. Run MCP servers locally: A server on localhost accessed from a page also on localhost is same-origin and avoids cross-origin restrictions entirely.
  2. Host your own MCP servers: Configure them to include the appropriate Access-Control-Allow-Origin response headers.
  3. Route through a backend proxy: Forward browser requests to MCP servers through your own proxy, keeping the MCP servers unexposed.

When adding an MCP server in the configuration panel, verify that the endpoint either supports CORS or is running on localhost.

Examples

API and Documentation

Deployment Models

This architecture makes the project ideal for internal tools, developer-focused products, and any application where data privacy and user control are priorities.

License

See license: ClientAgentJS

This site is open source. Improve this page.