Cloudflare で AI エージェント基盤を作る 4 ステップ — Hono → Queues → Workers AI → Agents SDK

pnpm create hono@latest cf-agent-step1
# テンプレ選択: cloudflare-workers
cd cf-agent-step1
pnpm install

import { Hono } from 'hono'

type Bindings = {}

const app = new Hono<{ Bindings: Bindings }>()

app.get('/', (c) => c.text('hello from cf-agent step 1'))

app.get('/ping', (c) =>
  c.json({
    ok: true,
    cf: c.req.raw.cf,
    ts: new Date().toISOString(),
  })
)

export default app

pnpm dev          # localhost:8787 で起動
curl http://localhost:8787/ping
pnpm deploy       # ⇒ https://cf-agent-step1.<account>.workers.dev/ にデプロイ
curl https://cf-agent-step1.<account>.workers.dev/ping

[ 外部サービス ] --POST--> [ Producer Worker ] --send--> [ Cloudflare Queue ]
                                |
                                └--200 OK (3秒以内)
                                                              |
                                                              v
                                                     [ Consumer Worker ]
                                                              |
                                                              v
                                                  ( 外部 API / DB / 通知 )

wrangler queues create agent-jobs

name = "cf-agent-step2"
main = "src/index.ts"
compatibility_date = "2026-06-01"

# Producer 側（Queue にメッセージを送る）
[[queues.producers]]
queue = "agent-jobs"
binding = "AGENT_JOBS"

# Consumer 側（Queue からメッセージを取り出して処理する）
[[queues.consumers]]
queue = "agent-jobs"
max_batch_size = 10
max_batch_timeout = 5
max_retries = 3
dead_letter_queue = "agent-jobs-dlq"

import { Hono } from 'hono'

type Bindings = {
  AGENT_JOBS: Queue
  WEBHOOK_SECRET: string
}

const app = new Hono<{ Bindings: Bindings }>()

// HMAC-SHA256 で署名検証する小さな関数
const verifySignature = async (body: string, signature: string, secret: string) => {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  )
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(body))
  const expected = Array.from(new Uint8Array(mac))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('')
  return expected === signature
}

app.post('/webhook/:source', async (c) => {
  const source = c.req.param('source')
  const body = await c.req.text()
  const signature = c.req.header('x-signature') ?? ''

  if (!(await verifySignature(body, signature, c.env.WEBHOOK_SECRET))) {
    return c.json({ error: 'invalid signature' }, 401)
  }

  await c.env.AGENT_JOBS.send({
    source,
    payload: JSON.parse(body),
    receivedAt: new Date().toISOString(),
  })

  return c.json({ ok: true }, 200)
})

// Consumer ハンドラ
export default {
  fetch: app.fetch,
  async queue(batch: MessageBatch, env: Bindings) {
    for (const msg of batch.messages) {
      try {
        const job = msg.body as { source: string; payload: unknown }
        console.log('process job', job.source, job.payload)
        // ここで時間のかかる処理（外部 API、DB 書き込み、LLM 呼び出し）
        msg.ack()
      } catch (e) {
        msg.retry()
      }
    }
  },
}

wrangler secret put WEBHOOK_SECRET   # 適当な文字列を入力
pnpm deploy

# 別タブで Consumer のログを流す
wrangler tail

# 署名付きで叩く
BODY='{"hello":"queue"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "<さっき入れた文字列>" -hex | awk '{print $2}')
curl -X POST https://cf-agent-step2.<account>.workers.dev/webhook/slack \
  -H "content-type: application/json" \
  -H "x-signature: $SIG" \
  -d "$BODY"

[ai]
binding = "AI"

app.post('/chat', async (c) => {
  const { prompt } = await c.req.json<{ prompt: string }>()

  // Workers AI（Cloudflare 自前のモデル）を AI Gateway 経由で叩く
  const result = await c.env.AI.run(
    '@cf/meta/llama-3.1-8b-instruct',
    { prompt },
    {
      gateway: {
        id: 'agent-gateway',
        cacheTtl: 3600,           // 同じ入力なら 1 時間キャッシュ
        skipCache: false,
      },
    }
  )

  return c.json(result)
})

curl -X POST https://cf-agent-step2.<account>.workers.dev/chat \
  -H "content-type: application/json" \
  -d '{"prompt":"give me one sentence haiku about cloudflare"}'

# 同じ prompt を 2 回叩く → 2 回目は AI Gateway のキャッシュヒットでミリ秒応答

pnpm create cloudflare@latest cf-agent-step4 -- --template=cloudflare/agents-starter
cd cf-agent-step4
pnpm install

import { Agent } from 'agents'

type State = {
  history: Array<{ role: 'user' | 'assistant'; content: string }>
}

export class ChatAgent extends Agent<Env, State> {
  initialState: State = { history: [] }

  async onMessage(connection, message: string) {
    const userMsg = { role: 'user' as const, content: message }
    this.setState({ history: [...this.state.history, userMsg] })

    const result = await this.env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
      messages: this.state.history,
    })
    const reply = { role: 'assistant' as const, content: result.response }

    this.setState({ history: [...this.state.history, reply] })
    connection.send(JSON.stringify(reply))
  }
}

pnpm dev
# ブラウザのコンソールで
const ws = new WebSocket('ws://localhost:8787/agents/chat-agent/my-session-1')
ws.onmessage = (e) => console.log('reply:', e.data)
ws.onopen = () => ws.send('hello, who are you?')

// Consumer 内
const id = env.CHAT_AGENT.idFromName(job.payload.sessionId)
const stub = env.CHAT_AGENT.get(id)
await stub.fetch('https://internal/agents/chat-agent/' + job.payload.sessionId, {
  method: 'POST',
  body: JSON.stringify({ message: job.payload.text }),
})