From 7f3800b94334dae706ceb2ceedcf79bf188847e8 Mon Sep 17 00:00:00 2001
From: adityavkk <adityavkk@gmail.com>
Date: Sun, 5 Jul 2026 08:39:07 -0400
Subject: [PATCH] fix(agents-chat-starter): spawn entities via
 /_electric/entities

Since the routing refactor in #4307, a bare PUT /:type/:id on the
agents-server falls through to the durable-streams proxy. The proxy
creates a raw stream and returns 201, so the starter's ok-check passes,
but no entity is created and the agent never wakes. Spawn through the
entity API instead, and fix the same snippet in AGENTS.md.

Fixes #4687
---
 examples/agents-chat-starter/AGENTS.md           | 4 +++-
 examples/agents-chat-starter/src/server/index.ts | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/examples/agents-chat-starter/AGENTS.md b/examples/agents-chat-starter/AGENTS.md
index 8f9bd041dd..94a68cfeb0 100644
--- a/examples/agents-chat-starter/AGENTS.md
+++ b/examples/agents-chat-starter/AGENTS.md
@@ -76,7 +76,7 @@ Without the top-level `key`, the StreamDB won't materialize the event into the c
 Entities need an `initialMessage` when spawned — the runtime skips the handler if there's no fresh input on first wake:
 
 ```typescript
-await fetch(`${AGENTS_URL}/${type}/${id}`, {
+await fetch(`${AGENTS_URL}/_electric/entities/${type}/${id}`, {
   method: 'PUT',
   body: JSON.stringify({
     args: { chatroomId: roomId },
@@ -85,6 +85,8 @@ await fetch(`${AGENTS_URL}/${type}/${id}`, {
 })
 ```
 
+Spawn through `/_electric/entities/:type/:id`. A bare `PUT /:type/:id` falls through to the durable-streams proxy: it returns `201` and creates a raw stream, but no entity is registered and the agent never wakes.
+
 ### Preventing Agent Loops
 
 When agents write to shared state, their own writes trigger their own wake. To prevent infinite loops, check if this agent already responded after the latest user message:
diff --git a/examples/agents-chat-starter/src/server/index.ts b/examples/agents-chat-starter/src/server/index.ts
index f3ae3895f7..f668420c58 100644
--- a/examples/agents-chat-starter/src/server/index.ts
+++ b/examples/agents-chat-starter/src/server/index.ts
@@ -103,7 +103,9 @@ async function spawnAgent(room: Room, type: string): Promise<string> {
   const agentId = `${room.id}-${type}-${room.agents.length + 1}`
   const entityUrl = `/${type}/${agentId}`
 
-  const putRes = await fetch(`${AGENTS_URL}${entityUrl}`, {
+  // Spawn via the entity API — a bare PUT /:type/:id falls through to the
+  // durable-streams proxy, which creates a raw stream instead of an entity
+  const putRes = await fetch(`${AGENTS_URL}/_electric/entities${entityUrl}`, {
     method: `PUT`,
     headers: { 'Content-Type': `application/json` },
     body: JSON.stringify({