mirror of
https://github.com/prdlk/dotfiles.git
synced 2026-11-02 19:32:43 +00:00
Prad Nukala
6406208b35
- 16 cross-shell utilities converted to sh/bash chezmoi executables: ai c2p cp-appid extract_agents fab gdc gh-sonr-org-migrate ghg-clone ghn gho git-summary launch_omp_livediff_overlay lc-elir mdcp mdp pj (ghg-clone not named ghg: unrelated cargo binary owns that name) - cwd/history helpers stay per-shell: yy c cd clip-last + ghg/ghn/gho cd-wrappers in bash/functions/ and zsh/functions/, loaded by rc files - fish keeps only shell-state functions; converted ones now hit PATH - cp-appid ignore gating moved to .local/bin path - dot_agents/skills: 82 skills materialized from dotstate storage so dot_claude skill symlinks resolve on fresh bootstrap; dotstate profile/symlinks.json released .agents/skills .bashrc .zshrc
89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# Cloudflare Agents SDK
|
|
|
|
Cloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.
|
|
|
|
## Core Value
|
|
Build stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.
|
|
|
|
## When to Use
|
|
- Persistent state + memory required
|
|
- Real-time WebSocket connections
|
|
- Long-running workflows (minutes/hours)
|
|
- Chat interfaces with AI models
|
|
- Scheduled/recurring tasks with state
|
|
- DB queries with agent state
|
|
|
|
## What Type of Agent?
|
|
|
|
| Use Case | Class | Key Features |
|
|
|----------|-------|--------------|
|
|
| AI chat interface | `AIChatAgent` | Auto-streaming, tools, message history, resumable |
|
|
| MCP tool provider | `Agent` + MCP | Expose tools to AI systems |
|
|
| Custom logic/routing | `Agent` | Full control, WebSockets, email, SQL |
|
|
| Real-time collaboration | `Agent` | WebSocket state, broadcasts |
|
|
| Email processing | `Agent` | `onEmail()` handler |
|
|
|
|
## Quick Start
|
|
|
|
**AI Chat Agent:**
|
|
```typescript
|
|
import { AIChatAgent } from "agents";
|
|
import { openai } from "@ai-sdk/openai";
|
|
|
|
export class ChatAgent extends AIChatAgent<Env> {
|
|
async onChatMessage(onFinish) {
|
|
return this.streamText({
|
|
model: openai("gpt-4"),
|
|
messages: this.messages,
|
|
onFinish,
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
**Base Agent:**
|
|
```typescript
|
|
import { Agent } from "agents";
|
|
|
|
export class MyAgent extends Agent<Env> {
|
|
onStart() {
|
|
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;
|
|
}
|
|
|
|
async onRequest(request: Request) {
|
|
return Response.json({ state: this.state });
|
|
}
|
|
}
|
|
```
|
|
|
|
## Reading Order
|
|
|
|
| Task | Files to Read |
|
|
|------|---------------|
|
|
| Quick start | README only |
|
|
| Build chat agent | README → api.md (AIChatAgent) → patterns.md |
|
|
| Setup project | README → configuration.md |
|
|
| Add React frontend | README → api.md (Client Hooks) → patterns.md |
|
|
| Build MCP server | api.md (MCP) → patterns.md |
|
|
| Background tasks | api.md (Scheduling, Task Queue) → patterns.md |
|
|
| Debug issues | gotchas.md |
|
|
|
|
## Package Entry Points
|
|
|
|
| Import | Purpose |
|
|
|--------|---------|
|
|
| `agents` | Server-side Agent classes, lifecycle |
|
|
| `agents/react` | `useAgent()` hook for WebSocket connections |
|
|
| `agents/ai-react` | `useAgentChat()` hook for AI chat UIs |
|
|
|
|
## In This Reference
|
|
- [configuration.md](./configuration.md) - SDK setup, wrangler config, routing
|
|
- [api.md](./api.md) - Agent classes, lifecycle, client hooks
|
|
- [patterns.md](./patterns.md) - Common workflows, best practices
|
|
- [gotchas.md](./gotchas.md) - Common issues, limits
|
|
|
|
## See Also
|
|
- durable-objects - Agent infrastructure
|
|
- d1 - External database integration
|
|
- workers-ai - AI model integration
|
|
- vectorize - Vector search for RAG patterns |