AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

references/agents-sdk/gotchas.md

Gotchas & Best Practices

Common Errors

"setState() not syncing"

Cause: Mutating state directly or not calling setState() after modifications
Solution: Always use setState() with immutable updates:

// ❌ this.state.count++
// ✅ this.setState({...this.state, count: this.state.count + 1})

"Message history grows unbounded (AIChatAgent)"

Cause: this.messages in AIChatAgent accumulates all messages indefinitely
Solution: Manually trim old messages periodically:

export class ChatAgent extends AIChatAgent<Env> {
  async onChatMessage(onFinish) {
    // Keep only last 50 messages
    if (this.messages.length > 50) {
      this.messages = this.messages.slice(-50);
    }
    
    return this.streamText({ model: openai("gpt-4"), messages: this.messages, onFinish });
  }
}

"SQL injection vulnerability"

Cause: Direct string interpolation in SQL queries Solution: Use parameterized queries:

// ❌ this.sql`...WHERE id = '${userId}'`
// ✅ this.sql`...WHERE id = ${userId}`

"WebSocket connection timeout"

Cause: Not calling conn.accept() in onConnect Solution: Always accept connections:

async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: "123"}); }

"Schedule limit exceeded"

Cause: More than 1000 scheduled tasks per agent Solution: Clean up old schedules and limit creation rate:

async checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn("Near limit!"); }

"AI Gateway unavailable"

Cause: AI service timeout or quota exceeded
Solution: Add error handling and fallbacks:

try { 
  return await this.env.AI.run(model, {prompt}); 
} catch (e) { 
  console.error("AI error:", e);
  return {error: "Unavailable"}; 
}

"@callable method returns undefined"

Cause: Method doesn't return JSON-serializable value, or has non-serializable types
Solution: Ensure return values are plain objects/arrays/primitives:

// ❌ Returns class instance
@callable()
async getData() { return new Date(); }

// ✅ Returns serializable object
@callable()
async getData() { return { timestamp: Date.now() }; }

"Resumable stream not resuming"

Cause: Stream ID must be deterministic for resumption to work
Solution: Use AIChatAgent (automatic) or ensure consistent stream IDs:

// AIChatAgent handles this automatically
export class ChatAgent extends AIChatAgent<Env> {
  // Resumption works out of the box
}

"MCP connection loss on hibernation"

Cause: MCP server connections don't survive hibernation
Solution: Re-register servers in onStart() or check connection status:

onStart() {
  // Re-register MCP servers after hibernation
  await this.mcp.registerServer("github", { url: env.MCP_URL, auth: {...} });
}

"Agent not found"

Cause: Durable Object binding missing or incorrect class name
Solution: Verify DO binding in wrangler.jsonc and class name matches

Rate Limits & Quotas

| Resource/Limit | Value | Notes | |----------------|-------|-------| | CPU per request | 30s (std), 300s (max) | Set in wrangler.jsonc | | Memory per instance | 128MB | Shared with WebSockets | | Storage per agent | 10GB | SQLite storage | | Scheduled tasks | 1000 per agent | Monitor with getSchedules() | | WebSocket connections | Unlimited | Within memory limits | | SQL columns | 100 | Per table | | SQL row size | 2MB | Key + value | | WebSocket message | 32MiB | Max size | | DO requests/sec | ~1000 | Per unique DO instance; rate limit if needed | | AI Gateway (Workers AI) | Model-specific | Check dashboard for limits | | MCP requests | Depends on server | Implement retry/backoff |

Best Practices

State Management

  • Use immutable updates: setState({...this.state, key: newValue})
  • Trim unbounded arrays (messages, logs) periodically
  • Store large data in SQL, not state

SQL Usage

  • Create tables in onStart(), not onRequest()
  • Use parameterized queries: sql`WHERE id = ${id}` (NOT sql`WHERE id = '${id}'`)
  • Index frequently queried columns

Scheduling

  • Monitor schedule count: await this.getSchedules()
  • Cancel completed tasks to stay under 1000 limit
  • Use cron strings for recurring tasks

WebSockets

  • Always call conn.accept() in onConnect()
  • Handle client disconnects gracefully
  • Broadcast to this.connections efficiently

AI Integration

  • Use AIChatAgent for chat interfaces (auto-streaming, resumption)
  • Trim message history to avoid token limits
  • Handle AI errors with try/catch and fallbacks

Production Deployment

  • Rate limiting: Implement request throttling for high-traffic agents (>1000 req/s)
  • Monitoring: Log critical errors, track schedule count, monitor storage usage
  • Graceful degradation: Handle AI service outages with fallbacks
  • Message trimming: Enforce max history length (e.g., 100 messages) in AIChatAgent
  • MCP reliability: Re-register servers on hibernation, implement retry logic