@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

$3

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

$3

For Mac automation features:

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

Usage

$3

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/

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

$3

`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

$3

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

$3

`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
`

$3

`bash
pnpm build
`

$3

`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