npm package: @jack230230/agent
Description: AI Agent that can be started from a remote configuration URL or local config file
Author: Zhenwei Wang
Latest version: 0.0.19

# @zhenwei/agent

AI Agent that can be started from a remote configuration URL. This package allows you to quickly spin up an AI agent using Claude or OpenAI, configured through a centralized dashboard.

## Quick Start

Start an agent using npx (no installation required):

```bash
# From a remote configuration URL
npx -y @jack230230/agent https://your-dashboard.com/api/ac/your-token

# From a local configuration file
npx -y @jack230230/agent ./agent-config.json
```

## Features

- 🤖 Support for Claude (Anthropic) and OpenAI providers
- 🔌 Model Context Protocol (MCP) support
- 🔧 Built-in tools: file operations, shell operations, web automation, and more
- 📝 Memory management
- ⏰ Scheduled tasks
- 🌐 Remote configuration via API

## Prerequisites

### Required Environment Variables

Depending on which AI provider you're using, you'll need one of these API keys:

```bash
# For Claude (Anthropic)
export ANTHROPIC_API_KEY="your-api-key"

# For OpenAI
export OPENAI_API_KEY="your-api-key"
```

### Optional Environment Variables

For Mac automation features:

```bash
export UITARS_URL="http://localhost:8083"  # Default
export CUA_PROVIDER="uitars"               # Default
```

## Usage

### Using npx (Recommended)

The easiest way to start an agent is using npx with either a config URL or a local config file:

#### From Remote URL
```bash
npx -y @zhenwei/agent https://localhost:3001/api/ac/token_abc123
```

The config URL should be in the format: `https://your-dashboard/api/ac/<token>`

#### From Local Config File
```bash
# Relative path
npx -y @zhenwei/agent ./agent-config.json

# Absolute path
npx -y @zhenwei/agent /path/to/agent-config.json

# Home directory
npx -y @zhenwei/agent ~/my-agents/config.json
```

### Using the CLI after installation

```bash
# Install globally
npm install -g @zhenwei/agent

# Run with URL
agent https://your-dashboard.com/api/ac/your-token

# Run with local config file
agent ./agent-config.json
```

## Configuration

The agent configuration can be fetched from a remote URL or loaded from a local JSON file. The configuration includes:

- Agent name and provider (Claude/OpenAI)
- System prompt
- Enabled tools (file operations, shell, web, etc.)
- MCP server configurations
- Provider-specific settings (model, temperature, etc.)
- Authentication credentials for dashboard connection

### Example Local Configuration File

Here's an example of a local configuration file (`agent-config.json`):

```json
{
  "name": "my-agent",
  "provider": "claude",
  "profile": "You are a helpful AI assistant",
  "workingDirectory": "~/.workers/my-agent",
  "maxTurns": 100,
  "scheduleCron": null,
  "providerConfig": {
    "model": "claude-sonnet-4-20250514",
    "maxThinkingTokens": 10000
  },
  "tools": {
    "fileOperations": true,
    "shellOperations": true,
    "webOperations": true,
    "taskManagement": true,
    "fileNavigation": true
  },
  "auth": {
    "agentId": 1,
    "token": "your-agent-token",
    "dashboardUrl": "http://localhost:3001",
    "websocketUrl": "http://localhost:3005"
  }
}
```

**Note**: The `auth` section is required and contains:
- `agentId`: The agent ID from your dashboard
- `token`: Authentication token for the agent
- `dashboardUrl`: URL of your dashboard
- `websocketUrl`: WebSocket server URL for real-time communication

## Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/zhenwei/Jessica.git
cd Jessica/apps/agent

# Install dependencies
pnpm install

# Run in development mode
pnpm dev
```

### Building

```bash
pnpm build
```

### Publishing

```bash
# From the root of the workspace
pnpm publish:agent
```

## Architecture

This agent connects to a dashboard via WebSocket to receive commands and report status. It supports:

- **Multiple AI Providers**: Claude (Anthropic) and OpenAI
- **MCP (Model Context Protocol)**: Connect to various MCP servers for extended capabilities
- **Built-in Tools**: File operations, shell commands, web automation, task management
- **Remote Configuration**: Fetch configuration from a centralized dashboard
- **Real-time Communication**: WebSocket connection for bi-directional communication

## License

MIT

## Author

Zhenwei

## Repository

https://github.com/zhenwei/Jessica