Agent Worker - Hoox Autonomous AI & Risk Manager

Last Updated: May 2026 (Post-Enhancement)

The agent-worker serves as the proactive intelligence layer of the Hoox trading ecosystem. Rather than waiting for webhooks, it runs continuously on a cron schedule to monitor portfolio health, enforce risk limits, and optimize position exits.

Core Capabilities

Architecture & Flow

1. Trigger: Cloudflare® Cron triggers the worker.
2. State Sync: Fetches active OPEN positions via the d1-worker.
3. Market Pulse: Pings public exchange APIs for the latest markPrice.
4. Risk Evaluation: Cross-references current price with KV-stored watermarks and global drawdown limits.
5. AI Processing: Uses configured AI provider with automatic fallback chain.
6. Execution: Dispatches actions to trade-worker (closing positions) and telegram-worker (alerts) via internal Service Bindings.

Endpoints & Interactions

Management Endpoints

GET /agent/config

Returns current agent configuration including provider settings.

{
  "success": true,
  "config": {
    "defaultProvider": "workers-ai",
    "fallbackChain": ["workers-ai", "openai"],
    "modelMap": { ... },
    "trailingStopPercent": 0.05,
    "takeProfitPercent": 0.10
  }
}

POST /agent/config

Update agent configuration at runtime.

{
  "defaultProvider": "openai",
  "fallbackChain": ["openai", "workers-ai", "anthropic", "google", "azure"],
  "modelMap": {
    "workers-ai": "@cf/meta/llama-3.1-8b-instruct",
    "openai": "gpt-4o-mini-2024-07-18",
    "anthropic": "claude-3-haiku-20240307",
    "google": "gemini-1.5-flash-002",
    "azure": "gpt-4o-mini"
  },
  "timeoutMs": 30000,
  "retryCount": 3
}

GET /agent/models

Returns all available models from Cloudflare Workers AI and external providers.

POST /agent/test-model

Test a specific AI model.

{
  "prompt": "Say hello",
  "model": "@cf/meta/llama-3.1-8b-instruct",
  "provider": "workers-ai"
}

GET /agent/health

Returns health status of all configured AI providers.

{
  "success": true,
  "providers": {
    "workers-ai": { "healthy": true, "latency": 150 },
    "openai": { "healthy": true, "latency": 200 }
  }
}

AI Interaction Endpoints

POST /agent/chat

Send a chat request with automatic provider fallback and SSE streaming support.

Request:

{
  "messages": [{ "role": "user", "content": "Analyze BTC market sentiment" }],
  "systemPrompt": "You are a professional crypto trading analyst.",
  "temperature": 0.7,
  "maxTokens": 500,
  "stream": true
}

Streaming Response (SSE):

data: {"content": "Based on current market conditions..."}
data: {"content": " technical indicators suggest..."}
data: [DONE]

POST /agent/vision (NEW!)

Analyze images with AI vision models. Supports both URL and base64 input.

{
  "imageUrl": "https://example.com/chart.png",
  "prompt": "Analyze this price chart and identify key support/resistance levels",
  "model": "@cf/meta/llama-3.2-11b-vision-instruct"
}

Or with base64:

{
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "prompt": "What pattern do you see in this chart?"
}

POST /agent/reasoning (NEW!)

Extended thinking queries with reasoning models like OpenAI o1.

{
  "prompt": "Design a risk management strategy for a $100k portfolio",
  "model": "o1-preview",
  "reasoningEffort": "medium"
}

Response:

{
  "reasoning": "Let me think through this step by step...",
  "answer": "Here's a comprehensive risk management strategy...",
  "model": "o1-preview"
}

GET /agent/usage (NEW!)

Get AI API usage statistics across all providers.

{
  "success": true,
  "usage": {
    "workers-ai": { "requests": 150, "tokens": 45000 },
    "openai": { "requests": 75, "tokens": 22000 }
  }
}

GET /agent/prompts (NEW!)

List available prompt templates.

{
  "success": true,
  "prompts": ["trading-analyst", "risk-assessor", "market-scanner"]
}

POST /agent/embedding

Generate text embeddings using Workers AI embedding models.

{
  "text": "Bitcoin price analysis for position sizing",
  "provider": "workers-ai"
}

Legacy Endpoints

POST /agent/risk-override

Manually enforce or release risk locks.

{
  "action": "engage_kill_switch",
  "reason": "Manual override from dashboard"
}

GET /agent/status

Retrieve the real-time health of the agent and active trailing stops.

Configuration

KV Keys

All configuration is stored in CONFIG_KV for real-time adjustments.

Default Agent Config

{
  "defaultProvider": "workers-ai",
  "fallbackChain": ["workers-ai", "openai", "anthropic", "google", "azure"],
  "modelMap": {
    "workers-ai": "@cf/meta/llama-3.1-8b-instruct",
    "openai": "gpt-4o-mini-2024-07-18",
    "anthropic": "claude-3-haiku-20240307",
    "google": "gemini-1.5-flash-002",
    "azure": "gpt-4o-mini"
  },
  "timeoutMs": 30000,
  "retryCount": 3,
  "maxDailyDrawdownPercent": -5,
  "trailingStopPercent": 0.05,
  "takeProfitPercent": 0.1
}

Supported Models

Workers AI Models

External Providers

AI Gateway Features

The AI Gateway provides:

• Fallback Chain: Automatically tries providers in order on failure
• Health Checks: Providers self-report health status every 5 minutes
• Retry Logic: Exponential backoff with configurable max retries
• Timeout Protection: Configurable per-request timeout (default 30s)
• Usage Tracking: Automatic token and request counting per provider

Internal Service Bindings

The agent-worker requires the following bindings to operate:

• D1_SERVICE: To fetch open positions and system logs.
• TRADE_SERVICE: To execute trailing stops and profit-taking.
• TELEGRAM_SERVICE: To broadcast AI summaries and emergency alerts.
• CONFIG_KV: For dynamic configuration and state.
• AI: Workers AI binding for inference.

Testing

The agent-worker includes comprehensive tests (171 tests across 33 files):

# Run all tests
bun test

# Run specific test file
bun test tests/ai/providers/openai.test.ts

# Run with coverage
bun test --coverage

Test Coverage: >80% across all modules

Test Structure

tests/
├── ai/
│   ├── providers/       # Tests for each AI provider
│   ├── gateway.test.ts  # AI Gateway fallback tests
│   ├── streaming.test.ts # SSE streaming tests
│   └── prompts.test.ts  # Prompt template tests
├── handlers/           # Tests for all endpoints
├── middleware/          # Tests for auth, validation, logging
├── market/             # Tests for exchange clients
├── risk/               # Tests for risk manager/executor
├── routine/            # Tests for housekeeping
└── integration/        # End-to-end integration tests

Cloudflare® and the Cloudflare logo are trademarks and/or registered trademarks of Cloudflare, Inc. in the United States and other jurisdictions.