agent-worker Isolate Profile

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 on a configurable Cloudflare Cron schedule (1–1440 minutes) to monitor portfolio health, enforce risk limits, and optimize position exits. The default in this repo is every 15 minutes (*/15 * * * *).

Core Capabilities

Architecture & Flow

1. Trigger: Cloudflare® Cron triggers the worker (interval set in wrangler.jsonc → triggers.crons, 1–1440 minutes).
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.

Test trading note: The agent closes live positions only. At routine start it filters out any OPEN position whose id contains -testnet- (trade-worker writes those for test: true fills). Testnet rows never enter trailing-stop, take-profit, or drawdown math, so sandbox fills cannot trip the live kill switch or issue live closes. Use test: true on webhook/email signals for sandbox rehearsal; close testnet exposure via a follow-up signal with test: true (or the Dashboard Positions Close action, which sets test automatically). See Test Trading.

Endpoints & Interactions

Note: For the canonical endpoint directory with full request/response examples across all workers, see /docs/devops/api/endpoints.

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-fp8",
    "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-fp8",
  "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

Analyze images with AI vision models (Workers AI). Supports base64 (preferred) or a public https imageUrl (private/metadata hosts and non-HTTPS URLs are rejected for SSRF safety).

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

Planned / not yet shipped

The following endpoints appear in earlier design notes but are not implemented in the current isolate. Prefer /agent/chat with a reasoning model id, and track usage via Cloudflare AI Gateway dashboards until these land:

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, and/or adjust trailing-stop percent.

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

Supported action values: engage_kill_switch, release_kill_switch, set_trailing_stop. You may also pass trailingStopPercent (0–1) alone or with set_trailing_stop.

{
  "action": "set_trailing_stop",
  "trailingStopPercent": 0.03,
  "reason": "Tighter stops into FOMC"
}

GET /agent/status

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

Configuration

Cron schedule (1–1440 minutes)

The schedule is not hard-coded to 5 minutes. Set triggers.crons in workers/agent-worker/wrangler.jsonc (or the example file) to any interval from 1 to 1440 minutes:

• Align dashboard.jsonc → cron.interval_minutes (free number, validated 1–1440) with your wrangler expression for operator docs.
• Disable scheduled runs with "crons": []; manual POST /agent/housekeeping still works.
• Redeploy after changing the schedule.

See the agent-worker README for the full mapping table.

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-fp8",
    "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 on each cron tick
• 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

Run from the monorepo root:

bun test workers/agent-worker

Coverage targets the isolate under workers/agent-worker/src and test/ (providers, routine, housekeeping, prompt-sanitizer, HTTP routes).

---

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