@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/references/agent-patterns.md

@@ -0,0 +1,461 @@
+# Agent Patterns
+
+Advanced patterns for building sophisticated agents.
+
+## Tool Calling
+
+Agents can expose tools that AI models can call:
+
+```typescript
+import { Agent, Connection } from "agents";
+import { z } from "zod";
+
+interface Tool {
+  name: string;
+  description: string;
+  parameters: z.ZodSchema;
+  handler: (params: any) => Promise<string>;
+}
+
+export class ToolAgent extends Agent<Env, State> {
+  private tools: Map<string, Tool> = new Map();
+
+  async onStart() {
+    // Register tools
+    this.registerTool({
+      name: "get_weather",
+      description: "Get current weather for a city",
+      parameters: z.object({ city: z.string() }),
+      handler: async ({ city }) => {
+        const res = await fetch(`https://api.weather.com/${city}`);
+        return JSON.stringify(await res.json());
+      },
+    });
+
+    this.registerTool({
+      name: "search_database",
+      description: "Search the document database",
+      parameters: z.object({ query: z.string(), limit: z.number().default(10) }),
+      handler: async ({ query, limit }) => {
+        const results = await this.sql`
+          SELECT * FROM documents
+          WHERE content LIKE ${`%${query}%`}
+          LIMIT ${limit}
+        `;
+        return JSON.stringify(results);
+      },
+    });
+  }
+
+  private registerTool(tool: Tool) {
+    this.tools.set(tool.name, tool);
+  }
+
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "chat") {
+      await this.handleChatWithTools(connection, data.content);
+    }
+  }
+
+  private async handleChatWithTools(connection: Connection, userMessage: string) {
+    // Build tool descriptions for the AI
+    const toolDescriptions = Array.from(this.tools.values()).map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: JSON.parse(JSON.stringify(t.parameters)),
+      },
+    }));
+
+    // First AI call - may request tool use
+    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+      messages: [
+        { role: "system", content: "You are a helpful assistant with access to tools." },
+        ...this.state.messages,
+        { role: "user", content: userMessage },
+      ],
+      tools: toolDescriptions,
+    });
+
+    // Check if AI wants to use a tool
+    if (response.tool_calls) {
+      for (const toolCall of response.tool_calls) {
+        const tool = this.tools.get(toolCall.function.name);
+        if (tool) {
+          const params = JSON.parse(toolCall.function.arguments);
+          const result = await tool.handler(params);
+
+          // Send tool result back to AI
+          const finalResponse = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+            messages: [
+              ...this.state.messages,
+              { role: "user", content: userMessage },
+              { role: "assistant", tool_calls: response.tool_calls },
+              { role: "tool", tool_call_id: toolCall.id, content: result },
+            ],
+          });
+
+          connection.send(JSON.stringify({
+            type: "response",
+            content: finalResponse.response,
+            toolUsed: toolCall.function.name,
+          }));
+        }
+      }
+    } else {
+      connection.send(JSON.stringify({
+        type: "response",
+        content: response.response,
+      }));
+    }
+  }
+}
+```
+
+## RAG (Retrieval Augmented Generation)
+
+Combine Vectorize with Agents for knowledge-grounded responses:
+
+```typescript
+interface Env {
+  AI: Ai;
+  VECTORIZE: VectorizeIndex;
+}
+
+export class RAGAgent extends Agent<Env, State> {
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "chat") {
+      // 1. Generate embedding for query
+      const embedding = await this.env.AI.run("@cf/baai/bge-base-en-v1.5", {
+        text: data.content,
+      });
+
+      // 2. Search vector database
+      const results = await this.env.VECTORIZE.query(embedding.data[0], {
+        topK: 5,
+        returnMetadata: true,
+      });
+
+      // 3. Build context from results
+      const context = results.matches
+        .map((m) => m.metadata?.text || "")
+        .join("\n\n");
+
+      // 4. Generate response with context
+      const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+        messages: [
+          {
+            role: "system",
+            content: `Answer based on this context:\n\n${context}\n\nIf the context doesn't contain relevant information, say so.`,
+          },
+          { role: "user", content: data.content },
+        ],
+      });
+
+      // 5. Update state and respond
+      this.setState({
+        messages: [
+          ...this.state.messages,
+          { role: "user", content: data.content },
+          { role: "assistant", content: response.response },
+        ],
+      });
+
+      connection.send(JSON.stringify({
+        type: "response",
+        content: response.response,
+        sources: results.matches.map((m) => m.metadata?.source),
+      }));
+    }
+  }
+
+  // Ingest documents into vector store
+  async ingestDocument(doc: { id: string; text: string; source: string }) {
+    const embedding = await this.env.AI.run("@cf/baai/bge-base-en-v1.5", {
+      text: doc.text,
+    });
+
+    await this.env.VECTORIZE.upsert([{
+      id: doc.id,
+      values: embedding.data[0],
+      metadata: { text: doc.text, source: doc.source },
+    }]);
+  }
+}
+```
+
+## Multi-Agent Orchestration
+
+Coordinate multiple specialized agents:
+
+```typescript
+interface Env {
+  RESEARCHER: DurableObjectNamespace;
+  WRITER: DurableObjectNamespace;
+  REVIEWER: DurableObjectNamespace;
+}
+
+export class OrchestratorAgent extends Agent<Env, State> {
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "create_article") {
+      connection.send(JSON.stringify({ type: "status", step: "researching" }));
+
+      // Step 1: Research agent gathers information
+      const researchResult = await this.callAgent(
+        this.env.RESEARCHER,
+        data.topic,
+        { action: "research", topic: data.topic }
+      );
+
+      connection.send(JSON.stringify({ type: "status", step: "writing" }));
+
+      // Step 2: Writer agent creates draft
+      const draftResult = await this.callAgent(
+        this.env.WRITER,
+        data.topic,
+        { action: "write", research: researchResult, topic: data.topic }
+      );
+
+      connection.send(JSON.stringify({ type: "status", step: "reviewing" }));
+
+      // Step 3: Reviewer agent improves draft
+      const finalResult = await this.callAgent(
+        this.env.REVIEWER,
+        data.topic,
+        { action: "review", draft: draftResult }
+      );
+
+      connection.send(JSON.stringify({
+        type: "complete",
+        article: finalResult,
+      }));
+    }
+  }
+
+  private async callAgent(
+    namespace: DurableObjectNamespace,
+    id: string,
+    payload: any
+  ): Promise<string> {
+    const agentId = namespace.idFromName(id);
+    const agent = namespace.get(agentId);
+
+    const response = await agent.fetch("http://agent/task", {
+      method: "POST",
+      body: JSON.stringify(payload),
+    });
+
+    return response.text();
+  }
+}
+```
+
+## Human-in-the-Loop
+
+Pause agent execution for human approval:
+
+```typescript
+interface State {
+  pendingApprovals: Array<{
+    id: string;
+    action: string;
+    data: any;
+    requestedAt: string;
+  }>;
+}
+
+export class ApprovalAgent extends Agent<Env, State> {
+  initialState: State = { pendingApprovals: [] };
+
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "request_action") {
+      // Action requires approval
+      if (this.requiresApproval(data.action)) {
+        const approvalId = crypto.randomUUID();
+
+        this.setState({
+          pendingApprovals: [
+            ...this.state.pendingApprovals,
+            {
+              id: approvalId,
+              action: data.action,
+              data: data.payload,
+              requestedAt: new Date().toISOString(),
+            },
+          ],
+        });
+
+        connection.send(JSON.stringify({
+          type: "approval_required",
+          approvalId,
+          action: data.action,
+          description: this.describeAction(data.action, data.payload),
+        }));
+
+        return;
+      }
+
+      // Execute immediately if no approval needed
+      await this.executeAction(connection, data.action, data.payload);
+    }
+
+    if (data.type === "approve") {
+      const approval = this.state.pendingApprovals.find(
+        (a) => a.id === data.approvalId
+      );
+
+      if (approval) {
+        // Remove from pending
+        this.setState({
+          pendingApprovals: this.state.pendingApprovals.filter(
+            (a) => a.id !== data.approvalId
+          ),
+        });
+
+        // Execute the approved action
+        await this.executeAction(connection, approval.action, approval.data);
+      }
+    }
+
+    if (data.type === "reject") {
+      this.setState({
+        pendingApprovals: this.state.pendingApprovals.filter(
+          (a) => a.id !== data.approvalId
+        ),
+      });
+
+      connection.send(JSON.stringify({
+        type: "action_rejected",
+        approvalId: data.approvalId,
+      }));
+    }
+  }
+
+  private requiresApproval(action: string): boolean {
+    const sensitiveActions = ["delete", "send_email", "make_payment", "publish"];
+    return sensitiveActions.includes(action);
+  }
+
+  private describeAction(action: string, data: any): string {
+    // Generate human-readable description
+    return `${action}: ${JSON.stringify(data)}`;
+  }
+
+  private async executeAction(connection: Connection, action: string, data: any) {
+    // Execute the action
+    const result = await this.performAction(action, data);
+
+    connection.send(JSON.stringify({
+      type: "action_completed",
+      action,
+      result,
+    }));
+  }
+}
+```
+
+## Streaming Responses
+
+Stream AI responses in real-time:
+
+```typescript
+export class StreamingAgent extends Agent<Env, State> {
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "chat") {
+      // Start streaming response
+      const stream = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+        messages: [
+          { role: "system", content: "You are a helpful assistant." },
+          ...this.state.messages,
+          { role: "user", content: data.content },
+        ],
+        stream: true,
+      });
+
+      let fullResponse = "";
+
+      // Stream chunks to client
+      for await (const chunk of stream) {
+        if (chunk.response) {
+          fullResponse += chunk.response;
+          connection.send(JSON.stringify({
+            type: "stream",
+            content: chunk.response,
+            done: false,
+          }));
+        }
+      }
+
+      // Update state with complete response
+      this.setState({
+        messages: [
+          ...this.state.messages,
+          { role: "user", content: data.content },
+          { role: "assistant", content: fullResponse },
+        ],
+      });
+
+      // Signal completion
+      connection.send(JSON.stringify({
+        type: "stream",
+        content: "",
+        done: true,
+      }));
+    }
+  }
+}
+```
+
+## Connecting to MCP Servers
+
+Agents can connect to MCP servers as clients:
+
+```typescript
+export class MCPClientAgent extends Agent<Env, State> {
+  async onStart() {
+    // Connect to external MCP server
+    await this.addMcpServer(
+      "github",
+      "https://github-mcp.example.com/sse",
+      { headers: { Authorization: `Bearer ${this.env.GITHUB_TOKEN}` } }
+    );
+
+    await this.addMcpServer(
+      "database",
+      "https://db-mcp.example.com/sse"
+    );
+  }
+
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "use_tool") {
+      // Call tool on connected MCP server
+      const servers = await this.getMcpServers();
+      const server = servers.find((s) => s.name === data.server);
+
+      if (server) {
+        const result = await server.callTool(data.tool, data.params);
+        connection.send(JSON.stringify({ type: "tool_result", result }));
+      }
+    }
+  }
+
+  async onClose() {
+    // Cleanup MCP connections
+    await this.removeMcpServer("github");
+    await this.removeMcpServer("database");
+  }
+}
+```

package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/references/examples.md

@@ -0,0 +1,188 @@
+# Project Bootstrapping
+
+Instructions for creating new agent projects.
+
+---
+
+## Create Command
+
+Execute in terminal to generate a new project:
+
+```bash
+npm create cloudflare@latest -- my-agent \
+  --template=cloudflare/agents-starter
+```
+
+Or use npx directly:
+
+```bash
+npx create-cloudflare@latest --template cloudflare/agents-starter
+```
+
+Includes:
+- Persistent data via `this.setState` and `this.sql`
+- WebSocket real-time connections
+- Workers AI bindings ready
+- React chat interface example
+
+---
+
+## Project Layout
+
+Generated structure:
+
+```
+my-agent/
+├── src/
+│   ├── app.tsx       # React chat interface
+│   ├── server.ts     # Agent implementation
+│   ├── tools.ts      # Tool definitions
+│   └── utils.ts      # Helpers
+├── wrangler.toml     # Platform configuration
+└── package.json
+```
+
+---
+
+## Agent Variations
+
+**Chat-focused:**
+
+Inherit from base `Agent` class, implement `onMessage` handler:
+- Manual conversation tracking
+- Full control over responses
+- Integrates with any AI provider
+
+**Persistent data:**
+
+Use `this.setState()` for automatic persistence:
+- JSON-serializable data
+- Auto-syncs to connected clients
+- Survives instance eviction
+
+**Per-session isolation:**
+
+Route by unique identifier in URL path:
+- Each identifier gets dedicated instance
+- Isolated data storage
+- Horizontal scaling automatic
+
+---
+
+## Platform Documentation
+
+- developers.cloudflare.com/agents/
+- developers.cloudflare.com/agents/getting-started/
+- developers.cloudflare.com/agents/api-reference/
+
+**Source repositories:**
+- `github.com/cloudflare/agents-starter` (starter template)
+- `github.com/cloudflare/agents/tree/main/examples` (reference implementations)
+
+**Related services:**
+
+- developers.cloudflare.com/workers-ai/ (AI models)
+- developers.cloudflare.com/vectorize/ (vector search)
+- developers.cloudflare.com/d1/ (SQL database)
+
+---
+
+## Reference Implementations
+
+Located at `github.com/cloudflare/agents/tree/main/examples`:
+
+| Example | Description |
+|---------|-------------|
+| `resumable-stream-chat` | Chat with reconnection-safe streaming |
+| `email-agent` | Handle incoming emails via Email Routing |
+| `mcp-client` | Connect agents to external MCP servers |
+| `mcp-worker` | Expose agent capabilities via MCP protocol |
+| `cross-domain` | Multi-domain authentication patterns |
+| `tictactoe` | Multiplayer game with shared state |
+| `a2a` | Agent-to-agent communication |
+| `codemode` | Code transformation workflows |
+| `playground` | Interactive testing sandbox |
+
+Browse each folder for complete implementation code and wrangler configuration.
+
+---
+
+## Selection Matrix
+
+| Goal | Approach |
+|------|----------|
+| Conversational bot | Agent + onMessage handler |
+| Custom data schema | Agent + setState() |
+| Knowledge retrieval | Agent + Vectorize |
+| Background jobs | Agent + schedule() |
+| External integrations | Agent + tool definitions |
+
+---
+
+## Commands Reference
+
+**Local execution:**
+
+```bash
+cd my-agent
+npm install
+npm start
+# Accessible at http://localhost:8787
+```
+
+**Production push:**
+
+```bash
+npx wrangler deploy
+# Accessible at https://[name].[subdomain].workers.dev
+```
+
+**WebSocket connection:**
+
+```javascript
+// URL pattern: /agents/:className/:instanceName
+const socket = new WebSocket("wss://my-agent.workers.dev/agents/MyAgent/session-123");
+
+socket.onmessage = (e) => {
+  console.log("Received:", JSON.parse(e.data));
+};
+
+socket.send(JSON.stringify({ type: "chat", content: "Hello" }));
+```
+
+**React integration:**
+
+```tsx
+import { useAgent } from "agents/react";
+
+function Chat() {
+  const { state, send } = useAgent({
+    agent: "my-agent",
+    name: "session-123",
+  });
+
+  // state auto-updates, send() dispatches messages
+}
+```
+
+---
+
+## Key Methods (from Agent class)
+
+| Method | Purpose |
+|--------|---------|
+| `onStart()` | Runs on instance startup |
+| `onConnect()` | Handles new WebSocket connections |
+| `onMessage()` | Processes incoming messages |
+| `onClose()` | Cleanup on disconnect |
+| `setState()` | Persist and broadcast data |
+| `this.sql` | Query embedded SQLite |
+| `schedule()` | Delayed/recurring tasks |
+| `broadcast()` | Message all connections |
+
+---
+
+## Help Channels
+
+- Cloudflare Discord
+- GitHub discussions on cloudflare/agents repository