# agents - Doramagic AI Context Pack

> Purpose: pre-work context for the user's host AI. This pack does not prove that the project has been installed, run, or validated.

## Project

- canonical_name: `cloudflare/agents`
- capability: Build and deploy AI Agents on Cloudflare
- expected_user_outcome: Build and deploy AI Agents on Cloudflare

## Operating Boundaries

- Do not claim that the project has been installed, run, called through an API, or used on local files unless separate evidence proves it.
- Project facts must come from repo evidence, Claim Graph, or explicit source references.
- When a capability is not verified, mark it as unverified instead of completing it as fact.
- publish_status: `publishable`
- blocking_gaps: none

---

## Doramagic Context Augmentation

The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints.

## Human Manual Outline

Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph.

Host AI hard rules:
- Do not treat page titles, section order, summaries, or importance values as factual project evidence.
- When explaining the Human Manual outline, state that it is only a reading route or salience signal.
- Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph.

- **Core Agent Runtime, State & Routing**: importance `high`
  - source_paths: packages/agents/src/index.ts, packages/agents/src/client.ts, packages/agents/src/retries.ts, packages/agents/src/schedule.ts, packages/agents/src/sub-routing.ts
- **AI Chat, Think Framework & Sub-agent Orchestration**: importance `high`
  - source_paths: packages/agents/src/ai-chat-agent.ts, packages/agents/src/ai-react.tsx, packages/agents/src/ai-types.ts, packages/agents/src/ai-chat-v5-migration.ts, packages/agents/src/chat/index.ts
- **MCP, Code Mode, Tools & Extensibility**: importance `high`
  - source_paths: packages/agents/src/mcp/index.ts, packages/agents/src/mcp/client.ts, packages/agents/src/mcp/handler.ts, packages/agents/src/mcp/transport.ts, packages/agents/src/mcp/worker-transport.ts
- **Voice Pipeline, WebSockets & Frontend Clients**: importance `high`
  - source_paths: packages/agents/src/react.tsx, packages/agents/src/email.ts, packages/voice/src/voice.ts, packages/voice/src/voice-client.ts, packages/voice/src/voice-input.ts

## Repo Inspection Evidence

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `92a5ba1798ce12047e1e6221968d44bd5ae30d6e`
- inspected_files: `pnpm-lock.yaml`, `README.md`, `package.json`, `docs/email.md`, `docs/routing.md`, `docs/server-driven-messages.md`, `docs/scheduling.md`, `docs/workflows.md`, `docs/push-notifications.md`, `docs/chat-sdk.md`, `docs/voice.md`, `docs/callable-methods.md`, `docs/agent-class.md`, `docs/mcp-client.md`, `docs/get-current-agent.md`, `docs/durable-execution.md`, `docs/migration-to-ai-sdk-v6.md`, `docs/client-sdk.md`, `docs/client-tools-continuation.md`, `docs/http-websockets.md`

Host AI hard rules:
- Without repo_clone_verified=true, do not claim that the source code has been read.
- Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts.
- Without quick_start_verified=true, do not claim that the Quick Start path has run successfully.

## Doramagic Pitfall Constraints

These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes.

### Constraint 1: Maintenance risk requires verification

- Trigger: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/cloudflare/agents/issues/1736
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 2: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: agents@0.15.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: agents@0.15.0. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: agents@0.15.0
- Evidence: failure_mode_cluster:github_release | https://github.com/cloudflare/agents/releases/tag/agents%400.15.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 3: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: create-think@0.0.3
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: create-think@0.0.3. Context: Observed when using node
- Why it matters: Upgrade or migration may change expected behavior: create-think@0.0.3
- Evidence: failure_mode_cluster:github_release | https://github.com/cloudflare/agents/releases/tag/create-think%400.0.3
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 4: Installation risk requires verification

- Trigger: Developers should check this installation risk before relying on the project: create-think@0.0.4
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: create-think@0.0.4. Context: Observed when using node
- Why it matters: Upgrade or migration may change expected behavior: create-think@0.0.4
- Evidence: failure_mode_cluster:github_release | https://github.com/cloudflare/agents/releases/tag/create-think%400.0.4
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 5: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: @cloudflare/codemode@0.4.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: @cloudflare/codemode@0.4.0. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: @cloudflare/codemode@0.4.0
- Evidence: failure_mode_cluster:github_release | https://github.com/cloudflare/agents/releases/tag/%40cloudflare/codemode%400.4.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 6: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: @cloudflare/think@0.9.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: @cloudflare/think@0.9.0. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: @cloudflare/think@0.9.0
- Evidence: failure_mode_cluster:github_release | https://github.com/cloudflare/agents/releases/tag/%40cloudflare/think%400.9.0
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 7: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: McpAgent: ctx.waitUntil(agent.destroy()) on session teardown logs "waitUntil() tasks did not complete" when the SSE client has already disconnected (0.13.3)
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: McpAgent: ctx.waitUntil(agent.destroy()) on session teardown logs "waitUntil() tasks did not complete" when the SSE client has already disconnected (0.13.3). Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: McpAgent: ctx.waitUntil(agent.destroy()) on session teardown logs "waitUntil() tasks did not complete" when the SSE client has already disconnected (0.13.3)
- Evidence: failure_mode_cluster:github_issue | https://github.com/cloudflare/agents/issues/1625
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 8: Configuration risk requires verification

- Trigger: Developers should check this configuration risk before relying on the project: [retracted]
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [retracted]. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may misconfigure credentials, environment, or host setup: [retracted]
- Evidence: failure_mode_cluster:github_issue | https://github.com/cloudflare/agents/issues/1749
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 9: Configuration risk requires verification

- Trigger: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/cloudflare/agents/issues/1738
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 10: Capability evidence risk requires verification

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | github_repo:924394244 | https://github.com/cloudflare/agents
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.