Cloudflare AI Agent with OpenTelemetry

A self-contained Cloudflare Workers template featuring:

• AI Agent Framework: Cloudflare Agents with local MCP-style tools (no external service required)
• Web Framework: Hono API on Cloudflare Workers
• Observability: Full OpenTelemetry tracing covering requests, LLM calls, and tool usage
• Local Development: OTel traces exported to localhost:4318/v1/traces with otel-tui visualization

Prerequisites

• Cloudflare Account: $5/month paid Workers plan (includes AI inference access)
• Local Setup:

  npm install -g wrangler
  wrangler login

For full Cloudflare Workers setup, see: Getting Started Guide

Quick Start

npm install
npm run dev        # Start local dev server with hot reload

Deploy to Cloudflare:

npm run deploy

Sync types from your Cloudflare configuration:

npm run cf-typegen

See wrangler commands reference for more

Project Structure

• src/index.ts: Hono app entry point with CloudflareBindings
• src/sandbox-agent/: Cloudflare Agent implementation
• src/tools/: MCP-style tool definitions (local, no external service)
• src/tests/: Test suite
• wrangler.jsonc: Worker configuration & bindings

Key Technologies

Hono Framework

A small, simple, and ultrafast web framework for any JavaScript runtime

Documentation • TypeScript Support • Cloudflare Workers Integration

Cloudflare Agents

Build and deploy AI-powered agents that autonomously perform tasks with tool calling

Agents SDK Docs • Tool Definitions • API Reference

OpenTelemetry

Vendor-neutral observability framework for collecting traces, metrics, and logs

Official Docs • JS SDK • Getting Started

Model Context Protocol (MCP)

Standard protocol for AI applications to access tools and context without requiring external services

MCP Specification • Implementations • Tool Protocol

Monitoring Traces Locally

Start the OTel TUI collector to visualize traces in real-time:

# Install otel-tui (one time)
npm install -g @ymtdzzz/otel-tui

# Run during development
otel-tui

This displays all spans from:

• HTTP requests through Hono
• LLM inference calls to Cloudflare Models
• Tool execution and results

See otel-tui for advanced filtering and export options

Environment Configuration

Bindings are defined in wrangler.jsonc and typed via worker-configuration.d.ts:

// src/index.ts
const app = new Hono<{ Bindings: CloudflareBindings }>()

Environment & Bindings Guide

Further Reading

• Cloudflare AI Models
• Durable Objects (for persistent state)
• Workers KV (for caching)
• D1 Database (for structured data)