Skip to content

Agent class docs#636

Merged
deathbyknowledge merged 8 commits into
mainfrom
agent-class-docs
Nov 7, 2025
Merged

Agent class docs#636
deathbyknowledge merged 8 commits into
mainfrom
agent-class-docs

Conversation

@deathbyknowledge

@deathbyknowledge deathbyknowledge commented Nov 5, 2025

Copy link
Copy Markdown
Contributor

No description provided.

@changeset-bot

changeset-bot Bot commented Nov 5, 2025 •
edited
Loading

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: e47a9a9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@claude

claude Bot commented Nov 5, 2025 •
edited
Loading

Copy link
Copy Markdown

Claude Code Review

This is a high-quality documentation addition. The PR adds comprehensive documentation explaining the Agent class architecture through its inheritance layers (DurableObject → Server → Agent). The content is technically accurate and well-structured.

Code Quality: ✓

  • Technically accurate (verified against source code in packages/agents/src/index.ts)
  • Code examples are syntactically correct and follow TypeScript conventions
  • SQL table names (cf_agents_state, cf_agents_queues, cf_agents_schedules) match implementation
  • API signatures match actual implementation

Architecture Alignment: ✓

  • Follows existing docs structure (similar to docs/context-management.md)
  • Correctly explains the layered architecture (DO → Server → Agent)
  • Accurately describes key features: state persistence, RPC, scheduling, queuing, MCP, email handling

Testing Coverage: N/A

  • Documentation-only change, no code modifications
  • Existing tests in packages/agents/src/tests/ cover the features documented

Minor observation (not blocking):
The document references initialState as a property developers define (line 205), which is correct per the implementation. The layered explanation from Layer 0 → Layer 1 → Layer 2 is pedagogically effective.

Verdict: LGTM - Ready to merge.

@pkg-pr-new

pkg-pr-new Bot commented Nov 5, 2025 •
edited
Loading

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@636

commit: e47a9a9

@threepointone threepointone mentioned this pull request Nov 5, 2025
Merged
5 tasks
@deathbyknowledge
deathbyknowledge marked this pull request as ready for review November 5, 2025 17:27
threepointone pushed a commit to cloudflare/cloudflare-docs that referenced this pull request Nov 5, 2025
@github-actions @claude
Add Agent class architecture documentation
4571a52 
Syncs documentation from cloudflare/agents PR #636 which adds comprehensive explanations of the Agent class architecture, including its inheritance chain from DurableObject → Server → Agent.

This document provides:
- Detailed explanation of the three-layer architecture
- Understanding of underlying Durable Object primitives
- PartyKit Server layer enhancements
- Agent-specific features like state management, scheduling, queuing, MCP integration, and email handling
- Code examples for all major Agent APIs

Source: cloudflare/agents#636

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@threepointone

threepointone commented Nov 5, 2025

Copy link
Copy Markdown
Contributor

Documentation Sync

The documentation changes from this PR have been synced to the cloudflare-docs repository.

Documentation PR: cloudflare/cloudflare-docs#26320

The new documentation has been added to /agents/concepts/agent-class.mdx and covers:

  • Layer 0: Durable Object - Base primitives (constructor, RPC, fetch, WebSockets, alarms, storage)
  • Layer 1: PartyKit Server - Opinionated wrapper with developer-friendly callbacks
  • Layer 2: Agent - Full-featured implementation with state persistence, scheduling, MCP, email handling, and more

🤖 Automated documentation sync via Claude Code

mattzcarey
mattzcarey reviewed Nov 5, 2025
View reviewed changes
Comment thread docs/agent-class.md
The `Agent` class is an extension of `DurableObject`. That is to say, they _are_ **Durable Objects**. If you're not familiar with Durable Objects, it is highly recommended that you read ["What are Durable Objects"](https://developers.cloudflare.com/durable-objects/) but at their core, Durable Objects are globally addressable (each instance has a unique ID) single-threaded compute instances with long term storage (KV/SQLite).
That being said, `Agent` does **not** extend `DurableObject` directly but instead `Server`. `Server` is a class provided by [PartyKit](https://github.com/cloudflare/partykit/tree/main/packages/partyserver).

You can visualize the logic as a Matryoshka doll: **DurableObject** -> **Server** -> **Agent**.

@mattzcarey mattzcarey Nov 5, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

love this

mattzcarey
mattzcarey reviewed Nov 5, 2025
View reviewed changes
Comment thread docs/agent-class.md
await stub.bar();
```

Since we have a URL addressing scheme, we also get access to `routePartykitRequest()`.

@mattzcarey mattzcarey Nov 5, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is the docs I wished I had

mattzcarey
mattzcarey approved these changes Nov 5, 2025
View reviewed changes

@mattzcarey mattzcarey left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So good. No notes

jcheese1
jcheese1 reviewed Nov 7, 2025
View reviewed changes
Comment thread docs/agent-class.md
@cloudflare cloudflare deleted a comment from threepointone Nov 7, 2025
@cloudflare cloudflare deleted a comment from threepointone Nov 7, 2025
deathbyknowledge
deathbyknowledge commented Nov 7, 2025
View reviewed changes
Comment thread docs/agent-class.md Outdated
@threepointone

threepointone commented Nov 7, 2025

Copy link
Copy Markdown
Contributor

📚 Documentation sync initiated

A PR has been created in cloudflare-docs to sync these documentation changes:

cloudflare-docs PR: cloudflare/cloudflare-docs#26320

The documentation has been adapted for the cloudflare-docs structure and is ready for review.

🤖 Automated comment via Claude Code

@deathbyknowledge
deathbyknowledge merged commit a3b7e23 into main Nov 7, 2025
5 checks passed
@deathbyknowledge
deathbyknowledge deleted the agent-class-docs branch November 7, 2025 17:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mattzcarey mattzcarey mattzcarey approved these changes
+1 more reviewer
@jcheese1 jcheese1 jcheese1 left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@deathbyknowledge @threepointone @jcheese1 @mattzcarey