@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):

# 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:

# 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:

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

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

# 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

# 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):

{
  "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

# 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

pnpm build

Publishing

# 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