agents-0-24-0-6-b
Claude Code's read-only tools, web search on, ludion sync off
Question
How do I use Cap'n Web RPC with AgentClient in the Cloudflare Agents SDK?
Answer key
- A correct answer says
- `useAgent` and `AgentClient` take a `transport` option: "cf-websocket" (default, hibernating) or "capnweb" for a Cap'n Web session with native RPC stubs.
- The stale answer
- useAgent/AgentClient always use the JSON-over-WebSocket protocol; there is no transport choice.
Answer
In `agents` 0.24.0 or later, pass `transport: "capnweb"` when you create the client, e.g. `new AgentClient({ ..., transport: "capnweb" })` (`useAgent` takes the same option). The default is `"cf-websocket"`, the hibernating WebSocket that sends `call()`/`stub` as JSON `rpc` frames. With `"capnweb"`, a single Cap'n Web session carries everything, and `client.call(...)` or `client.stub.method(...)` call server methods directly: a returned `RpcTarget` arrives as a live stub, a `ReadableStream` streams, and calls can be pipelined.
On the server, `@callable()` methods are not exposed over Cap'n Web, because they stay the JSON-wire interface. An Agent that wants native Cap'n Web calls has to pass a `callables` option: an `RpcTarget` whose prototype methods become the remote interface.
Two trade-offs: the Durable Object stays in memory while a Cap'n Web connection is open, so it doesn't hibernate, and PartySocket still handles reconnection. The experimental `?__agents_rpc=capnweb` endpoint from 0.23.0 has been removed. The release notes include no full code example, so check PR #2249 for exact `callables` usage.
Sources:
- [agents@0.24.0 release notes](https://github.com/cloudflare/agents/releases/tag/agents%400.24.0)
- [PR #2249: Cap'n Web transport](https://github.com/cloudflare/agents/pull/2249)
- [Agents lifecycle docs](https://github.com/cloudflare/agents/blob/main/docs/agents/lifecycle.md)
- [Client SDK docs](https://developers.cloudflare.com/agents/api-reference/client-sdk)Grade
correct
The judge's reason: It states that useAgent/AgentClient take a transport option with default "cf-websocket" (hibernating) or "capnweb" for a Cap'n Web session with native RPC stubs, and does not present the stale behavior as current.
Session log
Tool call: ToolSearch
{ "query": "select:WebSearch,WebFetch", "max_results": 2 }Tool output
{"type":"tool_reference","tool_name":"WebSearch"} {"type":"tool_reference","tool_name":"WebFetch"}Tool call: WebSearch
{ "query": "Cloudflare Agents SDK AgentClient Cap'n Web RPC", "mode": "standard" }Tool output
Web search results for query: "Cloudflare Agents SDK AgentClient Cap'n Web RPC" Links: [{"title":"developers.cloudflare.com","url":"https://developers.cloudflare.com/agents/communication-channels/chat/client-sdk/index.md"},{"title":"agents sdk","url":"https://skills.cat/skills/kilo-org/kilocode/agents-sdk"},{"title":"Client SDK","url":"https://developers.cloudflare.com/agents/api-reference/client-sdk"},{"title":"agents sdk","url":"https://tessl.io/registry/skills/github/openai/plugins/agents-sdk"},{"title":"cloudflare agents","url":"https://x-cmd.com/install/cloudflare-agents"},{"title":"developers.cloudflare.com","url":"https://developers.cloudflare.com/changelog/product/agents/"},{"title":"Agents SDK v0.6.0: RPC transport for MCP, optional OAuth, hardened schema conversion, and @cloudflare/ai-chat fixes","url":"https://developers.cloudflare.com/changelog/post/2026-02-25-agents-sdk-v060"},{"title":"docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com","url":"https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agents/communication-channels/chat/client-sdk/index.md"},{"title":"agents sdk","url":"https://skills.sh/cloudflare/skills/agents-sdk"}] The search results don't mention Cap'n Web, so I can't confirm whether the Agents SDK uses it. What they do cover: - **AgentClient:** It's a vanilla JavaScript/TypeScript class for any environment. It provides RPC calls, state sync, streaming, and auto-reconnection, and it sits alongside the React `useAgent` hook and the HTTP-only `agentFetch` client (The table lists useAgent, AgentClient, and agentFetch, with AgentClient described as a vanilla JavaScript/TypeScript class for any environment.). - **Typed RPC:** A changelog entry says AgentClient can take an agent type parameter for typed calls and exposes a stub proxy for RPC-style method calls (AgentClient accepts an optional agent type parameter, which gives full type inference on RPC calls.). The RPC type utilities are exported from `agents/client` (AgentMethods, AgentStub, and RPCMethods are exported from agents/client.). - **Decorator scope:** The `@callable()` decorator is needed only for calls from external runtimes such as browsers or other services. Calls from within the same Worker can use Durable Object RPC on the stub directly (@callable() is only required for methods called from external runtimes, and same-Worker calls can use standard Durable Object RPC without the decorator.). - **Agent-to-MCP RPC:** Agents SDK v0.6.0 lets an Agent and an McpAgent in the same Worker connect over RPC instead of HTTP (The release lets you define an Agent and an McpAgent in the same Worker and connect them over RPC.). I didn't find any source linking AgentClient or the Agents SDK to Cap'n Web, so a follow-up search on the Cap'n Web project itself, or on the agents package source, would be needed to check that link. REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.Tool call: WebFetch
{ "url": "https://developers.cloudflare.com/changelog/product/agents/", "prompt": "Find any mention of Cap'n Web / capnweb in relation to AgentClient or the agents SDK. Quote exact usage/code examples." }Tool call: WebFetch
{ "url": "https://developers.cloudflare.com/agents/api-reference/client-sdk", "prompt": "Does this page mention Cap'n Web / capnweb? Quote any related code. Also summarize how AgentClient does RPC (agent.call, agent.stub)." }Tool output
I found no mention of Cap'n Web or capnweb in the content provided, so I have no usage examples to quote. The page is also cut off at the end ("[Content truncated due to length...]"), partway through the March 2, 2026 Agents SDK v0.7.0 entry. The missing portion could contain a mention, so the answer may be incomplete. The March 23, 2026 Agents SDK v0.8.0 entry does cover `AgentClient`. It describes a typed `call` method and an RPC-style `stub` proxy, but it doesn't mention Cap'n Web. [WebFetch note: this page's text is 114120 characters long and the answer above covers only characters 0 to 100000; the final 14120 were not read — to read on, call WebFetch again with the same url and offset: 100000.]Tool output
No, this page doesn't mention Cap'n Web or capnweb. **How AgentClient handles RPC:** - **`agent.call(method, args?, options?)`** invokes a method on the agent by name. Arguments go in an array, and the call returns a Promise with the result. For example, `client.call("sendMessage", ["Hello!"])`. - **`agent.stub`** offers a proxy syntax for the same calls, so you pass arguments directly instead of wrapping them in an array. The page shows it on the `useAgent` object, and its reference table for `AgentClient` doesn't list it. Passing your Agent class as a type parameter makes stub methods fully typed. - **Methods must be exposed with `@callable()`** when called from external runtimes like browsers. Calls made within the same Worker can use standard Durable Object RPC on the stub without the decorator. - **Streaming** is enabled by marking a method as streaming on the agent side. On the client, the `call` options accept `onChunk`, `onDone`, and `onError` callbacks.Tool call: WebSearch
{ "query": "\"capnweb\" agents AgentClient cloudflare agents github", "mode": "extended" }Tool output
Web search results for query: ""capnweb" agents AgentClient cloudflare agents github" Links: [{"title":"Release agents@0.24.0 · cloudflare/agents","url":"https://github.com/cloudflare/agents/releases/tag/agents%400.24.0"},{"title":"agents/docs/agents/lifecycle.md at main · cloudflare/agents","url":"https://github.com/cloudflare/agents/blob/main/docs/agents/lifecycle.md"},{"title":"feat(agents): WebSockets speaks the Agent protocol for plain hosts; Cap'n Web transport as a socket class by mattzcarey · Pull Request #2249 · cloudflare/agents","url":"https://github.com/cloudflare/agents/pull/2249"},{"title":"Version Packages by github-actions[bot] · Pull Request #2251 · cloudflare/agents","url":"https://github.com/cloudflare/agents/pull/2251"},{"title":"[Candidate] cloudflare/computer/.agents/skills/capnweb - capnweb · Issue #6129 · ProSkillsMD/proskills","url":"https://github.com/ProSkillsMD/proskills/issues/6129"},{"title":"GitHub - cloudflare/agents: Build and deploy AI Agents on Cloudflare · GitHub","url":"https://github.com/cloudflare/agents"},{"title":"agents/README.md at main · cloudflare/agents","url":"https://github.com/cloudflare/agents/blob/main/README.md"},{"title":"agents-sdk","url":"https://mcpservers.org/agent-skills/cloudflare/agents-sdk"},{"title":"Cloudflare · GitHub","url":"https://github.com/cloudflare"}] The search turned up the Cloudflare Agents SDK changes that add a Cap'n Web transport to `AgentClient`. - **Release 0.24.0:** It added a Cap'n Web transport for plain Durable Objects that use WebSockets, which the release notes describe as WebSockets speaks the Agent protocol for plain hosts, and gains a Cap'n Web transport. - **Choosing the wire:** Both `useAgent` and `AgentClient` take a transport option. The default is the hibernating WebSocket, while the `capnweb` option opens a single Cap'n Web session that carries protocol frames and serves methods directly (useAgent({ transport }) and AgentClient({ transport }) pick the wire. "cf-websocket" (default) is the hibernating socket; call()/stub send JSON rpc frames. "capnweb" runs one Cap'n Web session that carries protocol frames and serves callables natively). - **Behaviour on capnweb:** Per the 0.24.0 notes, the Durable Object stays in memory while a Cap'n Web connection is open (index 1-11). - **Removed endpoint:** The experimental `?__agents_rpc=capnweb` endpoint from 0.23.0 was removed (index 1-13). - **Regular Agents:** According to the lifecycle docs, `@callable()` methods on a regular Agent are not exposed on the Cap'n Web root. An Agent that wants native calls has to pass a callables target instead (index 2-10). - **Source:** The changes come from pull request #2249 by mattzcarey, which replaced the earlier #2156 (index 3-2). The search did not surface any `AgentClient` code examples for the Cap'n Web transport, so the details above come from release notes, docs, and the PR description rather than a usage guide. A separate result, a ProSkills issue, points to a `capnweb` skill in the cloudflare/computer repo, but it is only a candidate listing and doesn't describe the agents API. REMINDER: You MUST include the sources above in your response to the user using markdown hyperlinks.Tool call: WebFetch
{ "url": "https://github.com/cloudflare/agents/releases/tag/agents%400.24.0", "prompt": "Quote exactly all text about Cap'n Web / capnweb transport, AgentClient transport option, callables target, keepalive, and any code examples." }Tool output
**Cap'n Web / capnweb transport** - "`WebSockets` speaks the Agent protocol for plain hosts, and gains a Cap'n Web transport." - "`"capnweb"` runs one Cap'n Web session that carries protocol frames and serves `callables` natively:" - "`call()`/`stub` invoke them directly, an `RpcTarget` result is a live stub, a `ReadableStream` streams, calls pipeline." - "The Durable Object stays in memory while a capnweb connection is open." - "PartySocket still owns reconnection on both." - "The experimental `?__agents_rpc=capnweb` endpoint from 0.23.0 is removed." **AgentClient transport option** - "`useAgent({ transport })` and `AgentClient({ transport })` pick the wire." - "`"cf-websocket"` (default) is the hibernating socket; `call()`/`stub` send JSON `rpc` frames." **Callables target** - "`callables` — an `RpcTarget` whose prototype methods are the host's remote interface." - "`@callable()` decorators remain the JSON-wire interface of `Agent`; an Agent wanting native calls passes `callables`." **Keepalive** - The page contains no text about keepalive. **Code examples** - The page has no code blocks for the capnweb transport or `AgentClient` transport. The only fenced example is a `new State({...})` snippet in the #2179 entry, which is unrelated. The inline code identifiers above are the only other code references.Agent
In `agents` 0.24.0 or later, pass `transport: "capnweb"` when you create the client, e.g. `new AgentClient({ ..., transport: "capnweb" })` (`useAgent` takes the same option). The default is `"cf-websocket"`, the hibernating WebSocket that sends `call()`/`stub` as JSON `rpc` frames. With `"capnweb"`, a single Cap'n Web session carries everything, and `client.call(...)` or `client.stub.method(...)` call server methods directly: a returned `RpcTarget` arrives as a live stub, a `ReadableStream` streams, and calls can be pipelined. On the server, `@callable()` methods are not exposed over Cap'n Web, because they stay the JSON-wire interface. An Agent that wants native Cap'n Web calls has to pass a `callables` option: an `RpcTarget` whose prototype methods become the remote interface. Two trade-offs: the Durable Object stays in memory while a Cap'n Web connection is open, so it doesn't hibernate, and PartySocket still handles reconnection. The experimental `?__agents_rpc=capnweb` endpoint from 0.23.0 has been removed. The release notes include no full code example, so check PR #2249 for exact `callables` usage. Sources: - [agents@0.24.0 release notes](https://github.com/cloudflare/agents/releases/tag/agents%400.24.0) - [PR #2249: Cap'n Web transport](https://github.com/cloudflare/agents/pull/2249) - [Agents lifecycle docs](https://github.com/cloudflare/agents/blob/main/docs/agents/lifecycle.md) - [Client SDK docs](https://developers.cloudflare.com/agents/api-reference/client-sdk)