Skip to content

Agent class docs #636

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 8 commits into from
Nov 7, 2025
Merged

Agent class docs #636

merged 8 commits into from
Nov 7, 2025

Conversation

@deathbyknowledge
Copy link
Contributor

@deathbyknowledge deathbyknowledge commented Nov 5, 2025

No description provided.

@changeset-bot
Copy link

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

⚠️ 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
Copy link

claude bot commented Nov 5, 2025 •
edited
Loading

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
Copy link

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

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 <[email protected]>
@threepointone
Copy link
Contributor

threepointone commented Nov 5, 2025

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
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**.
Copy link
Contributor

@mattzcarey mattzcarey Nov 5, 2025

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
docs/agent-class.md
await stub.bar();
```

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

@mattzcarey mattzcarey Nov 5, 2025

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
Copy link
Contributor

@mattzcarey mattzcarey left a comment

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
@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
@threepointone
Copy link
Contributor

threepointone commented Nov 7, 2025

📚 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