agents 0.16.1 → 0.17.0

package/dist/workflows.d.ts

@@ -1,26 +1,26 @@
-import { b as Agent } from "./agent-tool-types-NofdbL9X.js";
+import { O as Agent } from "./agent-tool-types-Cd1TZPfB.js";
 import {
-  S as WorkflowTrackingRow,
-  _ as WorkflowPage,
-  a as ApprovalEventPayload,
-  b as WorkflowRejectedError,
-  c as WaitForApprovalOptions,
-  d as WorkflowCallbackType,
-  f as WorkflowCompleteCallback,
-  g as WorkflowInfo,
-  h as WorkflowEventPayload,
-  i as AgentWorkflowStep,
-  l as WorkflowCallback,
-  m as WorkflowEventCallback,
-  o as DefaultProgress,
-  p as WorkflowErrorCallback,
-  r as AgentWorkflowParams,
-  s as RunWorkflowOptions,
+  C as WorkflowStatus,
+  S as WorkflowRejectedError,
+  _ as WorkflowEventPayload,
+  b as WorkflowProgressCallback,
+  c as DefaultProgress,
+  d as WorkflowCallback,
+  g as WorkflowEventCallback,
+  h as WorkflowErrorCallback,
+  i as AgentWorkflowParams,
+  l as RunWorkflowOptions,
+  m as WorkflowCompleteCallback,
+  o as AgentWorkflowStep,
+  p as WorkflowCallbackType,
+  s as ApprovalEventPayload,
   t as AgentWorkflowEvent,
-  v as WorkflowProgressCallback,
-  x as WorkflowStatus,
-  y as WorkflowQueryCriteria
-} from "./workflow-types-SrZK_o9p.js";
+  u as WaitForApprovalOptions,
+  v as WorkflowInfo,
+  w as WorkflowTrackingRow,
+  x as WorkflowQueryCriteria,
+  y as WorkflowPage
+} from "./workflow-types-Baz_PO5v.js";
 import { WorkflowEntrypoint, WorkflowEvent } from "cloudflare:workers";
 
 //#region src/workflows.d.ts
@@ -68,6 +68,7 @@ declare class AgentWorkflow<
    * Called automatically before run() executes.
    */
   private _initAgent;
+  private _initFacetAgent;
   /**
    * Call user workflow code and report unhandled errors to the Agent.
    */

package/dist/workflows.js

@@ -1,3 +1,4 @@
+import { isInternalJsStubProp } from "./utils.js";
 import { getAgentByName } from "./index.js";
 import { WorkflowRejectedError } from "./workflow-types.js";
 import { WorkflowEntrypoint } from "cloudflare:workers";
@@ -59,8 +60,8 @@ var AgentWorkflow = class extends WorkflowEntrypoint {
 			const originalRun = proto.run;
 			proto.run = async function(event, step) {
 				if (!this.__agentInitCalled) {
-					const { __agentName, __agentBinding, __workflowName, ...userParams } = event.payload;
-					await this._initAgent(__agentName, __agentBinding, __workflowName, event.instanceId);
+					const { __agentName, __agentBinding, __workflowName, __agentOrigin, ...userParams } = event.payload;
+					await this._initAgent(__agentName, __agentBinding, __workflowName, __agentOrigin, event.instanceId);
 					this.__agentInitCalled = true;
 					try {
 						const cleanedEvent = {
@@ -82,14 +83,37 @@ var AgentWorkflow = class extends WorkflowEntrypoint {
 	* Initialize the Agent stub from workflow params.
 	* Called automatically before run() executes.
 	*/
-	async _initAgent(agentName, agentBinding, workflowName, instanceId) {
-		if (!agentName || !agentBinding || !workflowName) throw new Error("AgentWorkflow requires __agentName, __agentBinding, and __workflowName in params. Use agent.runWorkflow() to start workflows with proper agent context.");
+	async _initAgent(agentName, agentBinding, workflowName, agentOrigin, instanceId) {
+		if (!workflowName || !agentOrigin && (!agentName || !agentBinding)) throw new Error("AgentWorkflow requires __agentName, __agentBinding, and __workflowName in params. Use agent.runWorkflow() to start workflows with proper agent context.");
 		this._workflowId = instanceId;
 		this._workflowName = workflowName;
 		this._errorReported = false;
-		const namespace = this.env[agentBinding];
-		if (!namespace) throw new Error(`Agent binding '${agentBinding}' not found in environment`);
-		this._agent = await getAgentByName(namespace, agentName);
+		if (agentOrigin && agentOrigin.version !== 1) throw new Error(`AgentWorkflow received an unsupported origin version (${agentOrigin.version}). Upgrade the "agents" package running this Workflow to match the Agent that started it.`);
+		if (agentOrigin?.kind === "facet") {
+			this._agent = await this._initFacetAgent(agentOrigin);
+			return;
+		}
+		const resolvedAgentName = agentOrigin?.kind === "agent" ? agentOrigin.name : agentName;
+		const resolvedAgentBinding = agentOrigin?.kind === "agent" ? agentOrigin.binding : agentBinding;
+		if (!resolvedAgentName || !resolvedAgentBinding) throw new Error("AgentWorkflow requires a valid Agent origin. Use agent.runWorkflow() to start workflows with proper agent context.");
+		const namespace = this.env[resolvedAgentBinding];
+		if (!namespace) throw new Error(`Agent binding '${resolvedAgentBinding}' not found in environment`);
+		this._agent = await getAgentByName(namespace, resolvedAgentName);
+	}
+	async _initFacetAgent(origin) {
+		const root = origin.path[0];
+		if (!root) throw new Error("AgentWorkflow facet origin requires a non-empty path");
+		const namespace = this.env[origin.rootBinding];
+		if (!namespace) throw new Error(`Agent binding '${origin.rootBinding}' not found in environment`);
+		const rootAgent = await getAgentByName(namespace, root.name);
+		return new Proxy({}, { get(_target, prop) {
+			if (isInternalJsStubProp(prop)) return void 0;
+			if (typeof prop !== "string") return void 0;
+			if (prop === "fetch") return () => {
+				throw new Error("AgentWorkflow.agent for sub-agent origins is an RPC-only stub — .fetch() is not supported. Use routeSubAgentRequest() or the /agents/{parent}/{name}/sub/{child}/{name} URL for external HTTP/WS routing.");
+			};
+			return async (...args) => rootAgent._cf_invokeAgentPath(origin.path, prop, args);
+		} });
 	}
 	/**
 	* Call user workflow code and report unhandled errors to the Agent.

package/dist/workflows.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.js","names":[],"sources":["../src/workflows.ts"],"sourcesContent":["/**\n * AgentWorkflow - Base class for Workflows that integrate with Agents\n *\n * Extends Cloudflare's WorkflowEntrypoint to provide seamless access to\n * the Agent that started the workflow, enabling bidirectional communication.\n *\n * @example\n * ```typescript\n * import { AgentWorkflow } from 'agents/workflows';\n * import type { MyAgent } from './agent';\n *\n * type TaskParams = { taskId: string; data: string };\n *\n * export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {\n *   async run(event: AgentWorkflowEvent<TaskParams>, step: WorkflowStep) {\n *     // Access the originating Agent via typed RPC\n *     await this.agent.updateTaskStatus(event.payload.taskId, 'processing');\n *\n *     const result = await step.do('process', async () => {\n *       // ... processing logic\n *       return { processed: true };\n *     });\n *\n *     // Report progress to Agent (typed)\n *     await this.reportProgress({ step: 'process', status: 'complete', percent: 0.5 });\n *\n *     // Broadcast to connected clients\n *     await this.broadcastToClients({ type: 'progress', data: result });\n *\n *     return result;\n *   }\n * }\n * ```\n */\n\nimport { WorkflowEntrypoint } from \"cloudflare:workers\";\nimport type {\n  WorkflowEvent,\n  WorkflowStep,\n  WorkflowStepEvent\n} from \"cloudflare:workers\";\nimport { getAgentByName, type Agent } from \"./index\";\nimport type {\n  AgentWorkflowParams,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  DefaultProgress,\n  WaitForApprovalOptions\n} from \"./workflow-types\";\nimport { WorkflowRejectedError } from \"./workflow-types\";\n\n/**\n * WeakSet to track which prototypes have been wrapped.\n * This prevents re-wrapping on subsequent instantiations of the same class.\n */\nconst wrappedPrototypes = new WeakSet<object>();\n\n/**\n * Base class for Workflows that need access to their originating Agent.\n *\n * @template AgentType - The Agent class type (for typed RPC access)\n * @template Params - User-defined params passed to the workflow (optional)\n * @template ProgressType - Type for progress reporting (defaults to DefaultProgress)\n * @template Env - Environment type (defaults to Cloudflare.Env)\n */\nexport class AgentWorkflow<\n  AgentType extends Agent = Agent,\n  Params = unknown,\n  ProgressType = DefaultProgress,\n  Env extends Cloudflare.Env = Cloudflare.Env\n> extends WorkflowEntrypoint<Env, AgentWorkflowParams<Params>> {\n  /**\n   * The Agent stub - initialized before run() is called.\n   * Use this.agent to access the Agent's RPC methods.\n   */\n  private _agent?: DurableObjectStub<AgentType>;\n\n  /**\n   * Workflow instance ID\n   */\n  private _workflowId!: string;\n\n  /**\n   * Workflow binding name (for callbacks)\n   */\n  private _workflowName!: string;\n\n  /**\n   * Instance-level guard to prevent double initialization.\n   * Used when a subclass calls super.run() after its own run() was wrapped.\n   */\n  private __agentInitCalled = false;\n\n  /**\n   * Guard to prevent double error notification.\n   * Set to true when reportError() is called explicitly, so the automatic\n   * error catch in the run() wrapper doesn't send a duplicate notification.\n   */\n  private _errorReported = false;\n\n  constructor(ctx: ExecutionContext, env: Env) {\n    super(ctx, env);\n\n    const proto = Object.getPrototypeOf(this);\n\n    // Only wrap if:\n    // 1. This prototype defines its own run method (hasOwnProperty)\n    // 2. It hasn't been wrapped yet (WeakSet check)\n    // This prevents double-wrapping inherited methods and ensures each subclass\n    // that defines run() gets wrapped exactly once.\n    if (Object.hasOwn(proto, \"run\") && !wrappedPrototypes.has(proto)) {\n      const originalRun = proto.run as (\n        event: WorkflowEvent<Params>,\n        step: AgentWorkflowStep\n      ) => Promise<unknown>;\n\n      // Replace the prototype's run method with a wrapper that initializes\n      // the agent before calling the user's implementation\n      proto.run = async function (\n        this: AgentWorkflow<AgentType, Params, ProgressType, Env>,\n        event: WorkflowEvent<AgentWorkflowParams<Params>>,\n        step: WorkflowStep\n      ) {\n        // Instance-level guard: only init once per instance\n        // (prevents double init if super.run() is called from a subclass)\n        if (!this.__agentInitCalled) {\n          const { __agentName, __agentBinding, __workflowName, ...userParams } =\n            event.payload;\n\n          // Initialize agent connection\n          await this._initAgent(\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            event.instanceId\n          );\n          this.__agentInitCalled = true;\n\n          try {\n            // Pass cleaned event and wrapped step to user's implementation\n            const cleanedEvent = {\n              ...event,\n              payload: userParams as Params\n            } as WorkflowEvent<Params>;\n\n            const wrappedStep = this.extendStep(\n              this._wrapStep(step),\n              cleanedEvent\n            );\n\n            return await this._runWithErrorReporting(\n              originalRun,\n              cleanedEvent,\n              wrappedStep\n            );\n          } finally {\n            this._disposeAgent();\n          }\n        }\n\n        // If already initialized (e.g., called via super.run()),\n        // just call the original with the event as-is.\n        return await this._runWithErrorReporting(\n          originalRun,\n          event as WorkflowEvent<Params>,\n          step as AgentWorkflowStep\n        );\n      };\n\n      wrappedPrototypes.add(proto);\n    }\n  }\n\n  /**\n   * Initialize the Agent stub from workflow params.\n   * Called automatically before run() executes.\n   */\n  private async _initAgent(\n    agentName: string | undefined,\n    agentBinding: string | undefined,\n    workflowName: string | undefined,\n    instanceId: string\n  ): Promise<void> {\n    if (!agentName || !agentBinding || !workflowName) {\n      throw new Error(\n        \"AgentWorkflow requires __agentName, __agentBinding, and __workflowName in params. \" +\n          \"Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    this._workflowId = instanceId;\n    this._workflowName = workflowName;\n    this._errorReported = false;\n\n    // Get the Agent namespace from env\n    const namespace = (this.env as Record<string, unknown>)[\n      agentBinding\n    ] as DurableObjectNamespace<AgentType>;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${agentBinding}' not found in environment`\n      );\n    }\n\n    // Get the Agent stub by name\n    this._agent = await getAgentByName<Cloudflare.Env, AgentType>(\n      namespace,\n      agentName\n    );\n  }\n\n  /**\n   * Call user workflow code and report unhandled errors to the Agent.\n   */\n  private async _runWithErrorReporting(\n    originalRun: (\n      event: WorkflowEvent<Params>,\n      step: AgentWorkflowStep\n    ) => Promise<unknown>,\n    event: WorkflowEvent<Params>,\n    step: AgentWorkflowStep\n  ): Promise<unknown> {\n    try {\n      return await originalRun.call(this, event, step);\n    } catch (err) {\n      await this._autoReportError(err);\n      throw err;\n    }\n  }\n\n  /**\n   * Dispose the Agent stub owned by this workflow run.\n   */\n  private _disposeAgent(): void {\n    const agent = this._agent;\n    this._agent = undefined;\n    this.__agentInitCalled = false;\n    disposeIfPresent(agent);\n  }\n\n  /**\n   * Wrap WorkflowStep with durable Agent communication methods.\n   * Methods added to the wrapped step are idempotent and won't repeat on retry.\n   *\n   * Note: We add methods directly to the step object to preserve instanceof checks\n   * that Cloudflare's runtime may perform on the WorkflowStep class.\n   */\n  private _wrapStep(step: WorkflowStep): AgentWorkflowStep {\n    let stepCounter = 0;\n\n    // Cast step to our extended type and add methods directly\n    // This preserves the original object identity and instanceof relationship\n    const wrappedStep = step as AgentWorkflowStep;\n\n    // Add durable Agent methods directly to the step object\n    wrappedStep.reportComplete = async <T>(result?: T): Promise<void> => {\n      await step.do(`__agent_reportComplete_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"complete\",\n          result,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.reportError = async (error: Error | string): Promise<void> => {\n      const errorMessage = error instanceof Error ? error.message : error;\n      this._errorReported = true;\n      await step.do(`__agent_reportError_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"error\",\n          error: errorMessage,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.sendEvent = async <T>(event: T): Promise<void> => {\n      await step.do(`__agent_sendEvent_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"event\",\n          event,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.updateAgentState = async (state: unknown): Promise<void> => {\n      await step.do(`__agent_updateState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"set\", state);\n      });\n    };\n\n    wrappedStep.mergeAgentState = async (\n      partialState: Record<string, unknown>\n    ): Promise<void> => {\n      await step.do(`__agent_mergeState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"merge\", partialState);\n      });\n    };\n\n    wrappedStep.resetAgentState = async (): Promise<void> => {\n      await step.do(`__agent_resetState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"reset\");\n      });\n    };\n\n    return wrappedStep;\n  }\n\n  /**\n   * Extend the Agent-aware workflow step before user code receives it.\n   *\n   * Subclasses can override this to add framework-specific step helpers while\n   * preserving the underlying WorkflowStep object identity.\n   */\n  protected extendStep(\n    step: AgentWorkflowStep,\n    _event: WorkflowEvent<Params>\n  ): AgentWorkflowStep {\n    return step;\n  }\n\n  /**\n   * Get the Agent stub for RPC calls.\n   * Provides typed access to the Agent's methods.\n   *\n   * @example\n   * ```typescript\n   * // Call any public method on the Agent\n   * await this.agent.updateStatus('processing');\n   * const data = await this.agent.getData();\n   * ```\n   */\n  get agent(): DurableObjectStub<AgentType> {\n    if (!this._agent) {\n      throw new Error(\n        \"Agent not initialized. Ensure you're accessing this.agent inside run().\"\n      );\n    }\n    return this._agent;\n  }\n\n  /**\n   * Get the workflow instance ID\n   */\n  get workflowId(): string {\n    return this._workflowId;\n  }\n\n  /**\n   * Get the workflow binding name\n   */\n  get workflowName(): string {\n    return this._workflowName;\n  }\n\n  /**\n   * Automatically report an unhandled error to the Agent.\n   * Skipped if reportError() was already called (prevents double notification).\n   * Best-effort: notification failures are swallowed so the original error propagates.\n   *\n   * @param err - The caught error\n   */\n  private async _autoReportError(err: unknown): Promise<void> {\n    if (this._errorReported) {\n      return;\n    }\n    this._errorReported = true;\n    const errorMessage = err instanceof Error ? err.message : String(err);\n    try {\n      await this.notifyAgent({\n        workflowName: this._workflowName,\n        workflowId: this._workflowId,\n        type: \"error\",\n        error: errorMessage,\n        timestamp: Date.now()\n      });\n    } catch (_notifyErr) {\n      // Best-effort: don't mask the original error\n    }\n  }\n\n  /**\n   * Send a notification to the Agent via RPC.\n   *\n   * @param callback - Callback payload to send\n   */\n  protected async notifyAgent(callback: WorkflowCallback): Promise<void> {\n    await this.agent._workflow_handleCallback(callback);\n  }\n\n  /**\n   * Report progress to the Agent with typed progress data.\n   * Triggers onWorkflowProgress() on the Agent.\n   *\n   * @param progress - Typed progress data\n   *\n   * @example\n   * ```typescript\n   * // Using default progress type\n   * await this.reportProgress({ step: 'fetch', status: 'running' });\n   * await this.reportProgress({ step: 'fetch', status: 'complete', percent: 0.5 });\n   *\n   * // With custom progress type\n   * await this.reportProgress({ stage: 'extract', recordsProcessed: 100 });\n   * ```\n   */\n  protected async reportProgress(progress: ProgressType): Promise<void> {\n    await this.notifyAgent({\n      workflowName: this._workflowName,\n      workflowId: this._workflowId,\n      type: \"progress\",\n      progress: progress as DefaultProgress,\n      timestamp: Date.now()\n    });\n  }\n\n  /**\n   * Broadcast a message to all connected WebSocket clients via the Agent.\n   * This is non-durable and may repeat on workflow retry.\n   *\n   * @param message - Message to broadcast (will be JSON-stringified)\n   */\n  protected broadcastToClients(message: unknown): void {\n    this.agent._workflow_broadcast(message);\n  }\n\n  /**\n   * Wait for approval from the Agent.\n   * Handles rejection by reporting error (durably) and throwing WorkflowRejectedError.\n   *\n   * @param step - AgentWorkflowStep object\n   * @param options - Wait options (timeout, eventType, stepName)\n   * @returns Approval payload (throws WorkflowRejectedError if rejected)\n   *\n   * @example\n   * ```typescript\n   * const approval = await this.waitForApproval(step, { timeout: '7 days' });\n   * // approval contains the payload from approveWorkflow()\n   * ```\n   */\n  protected async waitForApproval<T = unknown>(\n    step: AgentWorkflowStep,\n    options?: WaitForApprovalOptions\n  ): Promise<T> {\n    const stepName = options?.stepName ?? \"wait-for-approval\";\n    const eventType = options?.eventType ?? \"approval\";\n    const timeout = options?.timeout;\n\n    // Wait for the approval event\n    // Note: Call reportProgress() before this method if you want to update progress\n    const event = (await step.waitForEvent(stepName, {\n      type: eventType,\n      timeout\n    })) as WorkflowStepEvent<{\n      approved: boolean;\n      reason?: string;\n      metadata?: T;\n    }>;\n\n    try {\n      const payload = event.payload;\n\n      // Check if rejected\n      if (!payload.approved) {\n        const reason = payload.reason;\n        await step.reportError(reason ?? \"Workflow rejected\");\n        throw new WorkflowRejectedError(reason, this._workflowId);\n      }\n\n      // Return the approval metadata as the result\n      return payload.metadata as T;\n    } finally {\n      disposeIfPresent(event);\n    }\n  }\n}\n\ntype DisposableResource = {\n  [Symbol.dispose](): void;\n};\n\nfunction isDisposableResource(value: unknown): value is DisposableResource {\n  return (\n    !!value &&\n    typeof value === \"object\" &&\n    Symbol.dispose in value &&\n    typeof value[Symbol.dispose] === \"function\"\n  );\n}\n\nfunction disposeIfPresent(value: unknown): void {\n  if (isDisposableResource(value)) {\n    value[Symbol.dispose]();\n  }\n}\n\n// Re-export types for convenience\nexport type {\n  AgentWorkflowEvent,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  WorkflowCallbackType,\n  WorkflowProgressCallback,\n  WorkflowCompleteCallback,\n  WorkflowErrorCallback,\n  WorkflowEventCallback,\n  DefaultProgress,\n  WaitForApprovalOptions,\n  ApprovalEventPayload,\n  WorkflowStatus,\n  WorkflowTrackingRow,\n  RunWorkflowOptions,\n  WorkflowEventPayload,\n  WorkflowInfo,\n  WorkflowQueryCriteria,\n  WorkflowPage\n} from \"./workflow-types\";\n\nexport { WorkflowRejectedError } from \"./workflow-types\";\n"],"mappings":"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"}
+{"version":3,"file":"workflows.js","names":[],"sources":["../src/workflows.ts"],"sourcesContent":["/**\n * AgentWorkflow - Base class for Workflows that integrate with Agents\n *\n * Extends Cloudflare's WorkflowEntrypoint to provide seamless access to\n * the Agent that started the workflow, enabling bidirectional communication.\n *\n * @example\n * ```typescript\n * import { AgentWorkflow } from 'agents/workflows';\n * import type { MyAgent } from './agent';\n *\n * type TaskParams = { taskId: string; data: string };\n *\n * export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {\n *   async run(event: AgentWorkflowEvent<TaskParams>, step: WorkflowStep) {\n *     // Access the originating Agent via typed RPC\n *     await this.agent.updateTaskStatus(event.payload.taskId, 'processing');\n *\n *     const result = await step.do('process', async () => {\n *       // ... processing logic\n *       return { processed: true };\n *     });\n *\n *     // Report progress to Agent (typed)\n *     await this.reportProgress({ step: 'process', status: 'complete', percent: 0.5 });\n *\n *     // Broadcast to connected clients\n *     await this.broadcastToClients({ type: 'progress', data: result });\n *\n *     return result;\n *   }\n * }\n * ```\n */\n\nimport { WorkflowEntrypoint } from \"cloudflare:workers\";\nimport type {\n  WorkflowEvent,\n  WorkflowStep,\n  WorkflowStepEvent\n} from \"cloudflare:workers\";\nimport { getAgentByName, type Agent } from \"./index\";\nimport type {\n  AgentWorkflowParams,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  DefaultProgress,\n  WaitForApprovalOptions\n} from \"./workflow-types\";\nimport { WorkflowRejectedError } from \"./workflow-types\";\nimport type {\n  AgentWorkflowOrigin,\n  AgentWorkflowPathStep\n} from \"./workflow-types\";\nimport { isInternalJsStubProp } from \"./utils\";\n\ntype AgentPathInvoker = {\n  _cf_invokeAgentPath(\n    path: ReadonlyArray<AgentWorkflowPathStep>,\n    method: string,\n    args: unknown[]\n  ): Promise<unknown>;\n};\n\n/**\n * WeakSet to track which prototypes have been wrapped.\n * This prevents re-wrapping on subsequent instantiations of the same class.\n */\nconst wrappedPrototypes = new WeakSet<object>();\n\n/**\n * Base class for Workflows that need access to their originating Agent.\n *\n * @template AgentType - The Agent class type (for typed RPC access)\n * @template Params - User-defined params passed to the workflow (optional)\n * @template ProgressType - Type for progress reporting (defaults to DefaultProgress)\n * @template Env - Environment type (defaults to Cloudflare.Env)\n */\nexport class AgentWorkflow<\n  AgentType extends Agent = Agent,\n  Params = unknown,\n  ProgressType = DefaultProgress,\n  Env extends Cloudflare.Env = Cloudflare.Env\n> extends WorkflowEntrypoint<Env, AgentWorkflowParams<Params>> {\n  /**\n   * The Agent stub - initialized before run() is called.\n   * Use this.agent to access the Agent's RPC methods.\n   */\n  private _agent?: DurableObjectStub<AgentType>;\n\n  /**\n   * Workflow instance ID\n   */\n  private _workflowId!: string;\n\n  /**\n   * Workflow binding name (for callbacks)\n   */\n  private _workflowName!: string;\n\n  /**\n   * Instance-level guard to prevent double initialization.\n   * Used when a subclass calls super.run() after its own run() was wrapped.\n   */\n  private __agentInitCalled = false;\n\n  /**\n   * Guard to prevent double error notification.\n   * Set to true when reportError() is called explicitly, so the automatic\n   * error catch in the run() wrapper doesn't send a duplicate notification.\n   */\n  private _errorReported = false;\n\n  constructor(ctx: ExecutionContext, env: Env) {\n    super(ctx, env);\n\n    const proto = Object.getPrototypeOf(this);\n\n    // Only wrap if:\n    // 1. This prototype defines its own run method (hasOwnProperty)\n    // 2. It hasn't been wrapped yet (WeakSet check)\n    // This prevents double-wrapping inherited methods and ensures each subclass\n    // that defines run() gets wrapped exactly once.\n    if (Object.hasOwn(proto, \"run\") && !wrappedPrototypes.has(proto)) {\n      const originalRun = proto.run as (\n        event: WorkflowEvent<Params>,\n        step: AgentWorkflowStep\n      ) => Promise<unknown>;\n\n      // Replace the prototype's run method with a wrapper that initializes\n      // the agent before calling the user's implementation\n      proto.run = async function (\n        this: AgentWorkflow<AgentType, Params, ProgressType, Env>,\n        event: WorkflowEvent<AgentWorkflowParams<Params>>,\n        step: WorkflowStep\n      ) {\n        // Instance-level guard: only init once per instance\n        // (prevents double init if super.run() is called from a subclass)\n        if (!this.__agentInitCalled) {\n          const {\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            __agentOrigin,\n            ...userParams\n          } = event.payload;\n\n          // Initialize agent connection\n          await this._initAgent(\n            __agentName,\n            __agentBinding,\n            __workflowName,\n            __agentOrigin,\n            event.instanceId\n          );\n          this.__agentInitCalled = true;\n\n          try {\n            // Pass cleaned event and wrapped step to user's implementation\n            const cleanedEvent = {\n              ...event,\n              payload: userParams as Params\n            } as WorkflowEvent<Params>;\n\n            const wrappedStep = this.extendStep(\n              this._wrapStep(step),\n              cleanedEvent\n            );\n\n            return await this._runWithErrorReporting(\n              originalRun,\n              cleanedEvent,\n              wrappedStep\n            );\n          } finally {\n            this._disposeAgent();\n          }\n        }\n\n        // If already initialized (e.g., called via super.run()),\n        // just call the original with the event as-is.\n        return await this._runWithErrorReporting(\n          originalRun,\n          event as WorkflowEvent<Params>,\n          step as AgentWorkflowStep\n        );\n      };\n\n      wrappedPrototypes.add(proto);\n    }\n  }\n\n  /**\n   * Initialize the Agent stub from workflow params.\n   * Called automatically before run() executes.\n   */\n  private async _initAgent(\n    agentName: string | undefined,\n    agentBinding: string | undefined,\n    workflowName: string | undefined,\n    agentOrigin: AgentWorkflowOrigin | undefined,\n    instanceId: string\n  ): Promise<void> {\n    if (!workflowName || (!agentOrigin && (!agentName || !agentBinding))) {\n      throw new Error(\n        \"AgentWorkflow requires __agentName, __agentBinding, and __workflowName in params. \" +\n          \"Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    this._workflowId = instanceId;\n    this._workflowName = workflowName;\n    this._errorReported = false;\n\n    // The origin payload is durably persisted in workflow params, so a workflow\n    // started by an older SDK can resume against newer code (and vice versa).\n    // Reject origin versions this build does not understand rather than\n    // silently misreading a future shape.\n    if (agentOrigin && agentOrigin.version !== 1) {\n      throw new Error(\n        `AgentWorkflow received an unsupported origin version (${\n          (agentOrigin as { version?: unknown }).version\n        }). Upgrade the \"agents\" package running this Workflow to match the Agent that started it.`\n      );\n    }\n\n    if (agentOrigin?.kind === \"facet\") {\n      this._agent = await this._initFacetAgent(agentOrigin);\n      return;\n    }\n\n    const resolvedAgentName =\n      agentOrigin?.kind === \"agent\" ? agentOrigin.name : agentName;\n    const resolvedAgentBinding =\n      agentOrigin?.kind === \"agent\" ? agentOrigin.binding : agentBinding;\n\n    if (!resolvedAgentName || !resolvedAgentBinding) {\n      throw new Error(\n        \"AgentWorkflow requires a valid Agent origin. Use agent.runWorkflow() to start workflows with proper agent context.\"\n      );\n    }\n\n    // Get the Agent namespace from env\n    const namespace = (this.env as Record<string, unknown>)[\n      resolvedAgentBinding\n    ] as DurableObjectNamespace<AgentType>;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${resolvedAgentBinding}' not found in environment`\n      );\n    }\n\n    // Get the Agent stub by name\n    this._agent = await getAgentByName<Cloudflare.Env, AgentType>(\n      namespace,\n      resolvedAgentName\n    );\n  }\n\n  private async _initFacetAgent(\n    origin: Extract<AgentWorkflowOrigin, { kind: \"facet\" }>\n  ): Promise<DurableObjectStub<AgentType>> {\n    const root = origin.path[0];\n    if (!root) {\n      throw new Error(\"AgentWorkflow facet origin requires a non-empty path\");\n    }\n\n    const namespace = (this.env as Record<string, unknown>)[\n      origin.rootBinding\n    ] as DurableObjectNamespace<Agent> | undefined;\n\n    if (!namespace) {\n      throw new Error(\n        `Agent binding '${origin.rootBinding}' not found in environment`\n      );\n    }\n\n    const rootAgent = (await getAgentByName<Cloudflare.Env, Agent>(\n      namespace,\n      root.name\n    )) as unknown as AgentPathInvoker;\n\n    return new Proxy(\n      {},\n      {\n        get(_target, prop) {\n          if (isInternalJsStubProp(prop)) return undefined;\n          if (typeof prop !== \"string\") return undefined;\n          if (prop === \"fetch\") {\n            return () => {\n              throw new Error(\n                \"AgentWorkflow.agent for sub-agent origins is an RPC-only stub — .fetch() is not supported. Use routeSubAgentRequest() or the /agents/{parent}/{name}/sub/{child}/{name} URL for external HTTP/WS routing.\"\n              );\n            };\n          }\n          return async (...args: unknown[]) =>\n            rootAgent._cf_invokeAgentPath(origin.path, prop, args);\n        }\n      }\n    ) as DurableObjectStub<AgentType>;\n  }\n\n  /**\n   * Call user workflow code and report unhandled errors to the Agent.\n   */\n  private async _runWithErrorReporting(\n    originalRun: (\n      event: WorkflowEvent<Params>,\n      step: AgentWorkflowStep\n    ) => Promise<unknown>,\n    event: WorkflowEvent<Params>,\n    step: AgentWorkflowStep\n  ): Promise<unknown> {\n    try {\n      return await originalRun.call(this, event, step);\n    } catch (err) {\n      await this._autoReportError(err);\n      throw err;\n    }\n  }\n\n  /**\n   * Dispose the Agent stub owned by this workflow run.\n   */\n  private _disposeAgent(): void {\n    const agent = this._agent;\n    this._agent = undefined;\n    this.__agentInitCalled = false;\n    disposeIfPresent(agent);\n  }\n\n  /**\n   * Wrap WorkflowStep with durable Agent communication methods.\n   * Methods added to the wrapped step are idempotent and won't repeat on retry.\n   *\n   * Note: We add methods directly to the step object to preserve instanceof checks\n   * that Cloudflare's runtime may perform on the WorkflowStep class.\n   */\n  private _wrapStep(step: WorkflowStep): AgentWorkflowStep {\n    let stepCounter = 0;\n\n    // Cast step to our extended type and add methods directly\n    // This preserves the original object identity and instanceof relationship\n    const wrappedStep = step as AgentWorkflowStep;\n\n    // Add durable Agent methods directly to the step object\n    wrappedStep.reportComplete = async <T>(result?: T): Promise<void> => {\n      await step.do(`__agent_reportComplete_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"complete\",\n          result,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.reportError = async (error: Error | string): Promise<void> => {\n      const errorMessage = error instanceof Error ? error.message : error;\n      this._errorReported = true;\n      await step.do(`__agent_reportError_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"error\",\n          error: errorMessage,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.sendEvent = async <T>(event: T): Promise<void> => {\n      await step.do(`__agent_sendEvent_${stepCounter++}`, async () => {\n        await this.notifyAgent({\n          workflowName: this._workflowName,\n          workflowId: this._workflowId,\n          type: \"event\",\n          event,\n          timestamp: Date.now()\n        });\n      });\n    };\n\n    wrappedStep.updateAgentState = async (state: unknown): Promise<void> => {\n      await step.do(`__agent_updateState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"set\", state);\n      });\n    };\n\n    wrappedStep.mergeAgentState = async (\n      partialState: Record<string, unknown>\n    ): Promise<void> => {\n      await step.do(`__agent_mergeState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"merge\", partialState);\n      });\n    };\n\n    wrappedStep.resetAgentState = async (): Promise<void> => {\n      await step.do(`__agent_resetState_${stepCounter++}`, async () => {\n        await this.agent._workflow_updateState(\"reset\");\n      });\n    };\n\n    return wrappedStep;\n  }\n\n  /**\n   * Extend the Agent-aware workflow step before user code receives it.\n   *\n   * Subclasses can override this to add framework-specific step helpers while\n   * preserving the underlying WorkflowStep object identity.\n   */\n  protected extendStep(\n    step: AgentWorkflowStep,\n    _event: WorkflowEvent<Params>\n  ): AgentWorkflowStep {\n    return step;\n  }\n\n  /**\n   * Get the Agent stub for RPC calls.\n   * Provides typed access to the Agent's methods.\n   *\n   * @example\n   * ```typescript\n   * // Call any public method on the Agent\n   * await this.agent.updateStatus('processing');\n   * const data = await this.agent.getData();\n   * ```\n   */\n  get agent(): DurableObjectStub<AgentType> {\n    if (!this._agent) {\n      throw new Error(\n        \"Agent not initialized. Ensure you're accessing this.agent inside run().\"\n      );\n    }\n    return this._agent;\n  }\n\n  /**\n   * Get the workflow instance ID\n   */\n  get workflowId(): string {\n    return this._workflowId;\n  }\n\n  /**\n   * Get the workflow binding name\n   */\n  get workflowName(): string {\n    return this._workflowName;\n  }\n\n  /**\n   * Automatically report an unhandled error to the Agent.\n   * Skipped if reportError() was already called (prevents double notification).\n   * Best-effort: notification failures are swallowed so the original error propagates.\n   *\n   * @param err - The caught error\n   */\n  private async _autoReportError(err: unknown): Promise<void> {\n    if (this._errorReported) {\n      return;\n    }\n    this._errorReported = true;\n    const errorMessage = err instanceof Error ? err.message : String(err);\n    try {\n      await this.notifyAgent({\n        workflowName: this._workflowName,\n        workflowId: this._workflowId,\n        type: \"error\",\n        error: errorMessage,\n        timestamp: Date.now()\n      });\n    } catch (_notifyErr) {\n      // Best-effort: don't mask the original error\n    }\n  }\n\n  /**\n   * Send a notification to the Agent via RPC.\n   *\n   * @param callback - Callback payload to send\n   */\n  protected async notifyAgent(callback: WorkflowCallback): Promise<void> {\n    await this.agent._workflow_handleCallback(callback);\n  }\n\n  /**\n   * Report progress to the Agent with typed progress data.\n   * Triggers onWorkflowProgress() on the Agent.\n   *\n   * @param progress - Typed progress data\n   *\n   * @example\n   * ```typescript\n   * // Using default progress type\n   * await this.reportProgress({ step: 'fetch', status: 'running' });\n   * await this.reportProgress({ step: 'fetch', status: 'complete', percent: 0.5 });\n   *\n   * // With custom progress type\n   * await this.reportProgress({ stage: 'extract', recordsProcessed: 100 });\n   * ```\n   */\n  protected async reportProgress(progress: ProgressType): Promise<void> {\n    await this.notifyAgent({\n      workflowName: this._workflowName,\n      workflowId: this._workflowId,\n      type: \"progress\",\n      progress: progress as DefaultProgress,\n      timestamp: Date.now()\n    });\n  }\n\n  /**\n   * Broadcast a message to all connected WebSocket clients via the Agent.\n   * This is non-durable and may repeat on workflow retry.\n   *\n   * @param message - Message to broadcast (will be JSON-stringified)\n   */\n  protected broadcastToClients(message: unknown): void {\n    this.agent._workflow_broadcast(message);\n  }\n\n  /**\n   * Wait for approval from the Agent.\n   * Handles rejection by reporting error (durably) and throwing WorkflowRejectedError.\n   *\n   * @param step - AgentWorkflowStep object\n   * @param options - Wait options (timeout, eventType, stepName)\n   * @returns Approval payload (throws WorkflowRejectedError if rejected)\n   *\n   * @example\n   * ```typescript\n   * const approval = await this.waitForApproval(step, { timeout: '7 days' });\n   * // approval contains the payload from approveWorkflow()\n   * ```\n   */\n  protected async waitForApproval<T = unknown>(\n    step: AgentWorkflowStep,\n    options?: WaitForApprovalOptions\n  ): Promise<T> {\n    const stepName = options?.stepName ?? \"wait-for-approval\";\n    const eventType = options?.eventType ?? \"approval\";\n    const timeout = options?.timeout;\n\n    // Wait for the approval event\n    // Note: Call reportProgress() before this method if you want to update progress\n    const event = (await step.waitForEvent(stepName, {\n      type: eventType,\n      timeout\n    })) as WorkflowStepEvent<{\n      approved: boolean;\n      reason?: string;\n      metadata?: T;\n    }>;\n\n    try {\n      const payload = event.payload;\n\n      // Check if rejected\n      if (!payload.approved) {\n        const reason = payload.reason;\n        await step.reportError(reason ?? \"Workflow rejected\");\n        throw new WorkflowRejectedError(reason, this._workflowId);\n      }\n\n      // Return the approval metadata as the result\n      return payload.metadata as T;\n    } finally {\n      disposeIfPresent(event);\n    }\n  }\n}\n\ntype DisposableResource = {\n  [Symbol.dispose](): void;\n};\n\nfunction isDisposableResource(value: unknown): value is DisposableResource {\n  return (\n    !!value &&\n    typeof value === \"object\" &&\n    Symbol.dispose in value &&\n    typeof value[Symbol.dispose] === \"function\"\n  );\n}\n\nfunction disposeIfPresent(value: unknown): void {\n  if (isDisposableResource(value)) {\n    value[Symbol.dispose]();\n  }\n}\n\n// Re-export types for convenience\nexport type {\n  AgentWorkflowEvent,\n  AgentWorkflowStep,\n  WorkflowCallback,\n  WorkflowCallbackType,\n  WorkflowProgressCallback,\n  WorkflowCompleteCallback,\n  WorkflowErrorCallback,\n  WorkflowEventCallback,\n  DefaultProgress,\n  WaitForApprovalOptions,\n  ApprovalEventPayload,\n  WorkflowStatus,\n  WorkflowTrackingRow,\n  RunWorkflowOptions,\n  WorkflowEventPayload,\n  WorkflowInfo,\n  WorkflowQueryCriteria,\n  WorkflowPage\n} from \"./workflow-types\";\n\nexport { WorkflowRejectedError } from \"./workflow-types\";\n"],"mappings":"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"}

package/docs/adding-to-existing-project.md

@@ -0,0 +1,450 @@
+# Adding Agents to an Existing Project
+
+This guide shows how to add agents to an existing Cloudflare Workers project. If you're starting fresh, see [Getting Started](./getting-started.md) instead.
+
+---
+
+## Prerequisites
+
+- An existing Cloudflare Workers project with `wrangler.jsonc`
+- Node.js 18+
+
+---
+
+## 1. Install the Package
+
+```bash
+npm install agents
+```
+
+For React applications, no additional packages are needed—React bindings are included.
+
+For Hono applications:
+
+```bash
+npm install agents hono-agents
+```
+
+---
+
+## 2. Create an Agent
+
+Create a new file for your agent (e.g., `src/agents/counter.ts`):
+
+```typescript
+import { Agent } from "agents";
+
+type CounterState = {
+  count: number;
+};
+
+export class Counter extends Agent<Env, CounterState> {
+  initialState: CounterState = { count: 0 };
+
+  increment() {
+    this.setState({ count: this.state.count + 1 });
+    return this.state.count;
+  }
+
+  decrement() {
+    this.setState({ count: this.state.count - 1 });
+    return this.state.count;
+  }
+}
+```
+
+---
+
+## 3. Update wrangler.jsonc
+
+Add the Durable Object binding and migration:
+
+```jsonc
+{
+  "name": "my-existing-project",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"], // Required for agents
+
+  // Add this section
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "Counter",
+        "class_name": "Counter"
+      }
+    ]
+  },
+
+  // Add this section
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["Counter"]
+    }
+  ]
+}
+```
+
+**Key points:**
+
+- `name` in bindings becomes the property on `env` (e.g., `env.Counter`)
+- `class_name` must match your exported class name exactly
+- `new_sqlite_classes` enables SQLite storage for state persistence
+- The `nodejs_compat` flag is required for the agents package
+
+---
+
+## 4. Configure TypeScript and Vite
+
+If you use `@callable()` decorators, you need two build configurations.
+
+**tsconfig.json** — extend `agents/tsconfig` (or add `"target": "ES2021"` manually):
+
+```json
+{
+  "extends": "agents/tsconfig"
+}
+```
+
+If you have an existing `tsconfig.json` with custom settings, you can extend and override:
+
+```json
+{
+  "extends": "agents/tsconfig",
+  "compilerOptions": {
+    "paths": { "~/*": ["./src/*"] }
+  }
+}
+```
+
+**vite.config.ts** — add the `agents()` plugin (handles TC39 decorator transforms for Vite 8):
+
+```typescript
+import agents from "agents/vite";
+
+export default defineConfig({
+  plugins: [
+    agents()
+    // ... your existing plugins
+  ]
+});
+```
+
+If your project does not use Vite, the `tsconfig.json` change alone is sufficient — your bundler must support TC39 decorators (stage 3, version `2023-11`).
+
+---
+
+## 5. Export the Agent Class
+
+Your agent class must be exported from your main entry point. Update your `src/index.ts`:
+
+```typescript
+// Export the agent class (required for Durable Objects)
+export { Counter } from "./agents/counter";
+
+// Your existing exports...
+export default {
+  // ...
+};
+```
+
+---
+
+## 6. Wire Up Routing
+
+Choose the approach that matches your project structure:
+
+### Plain Workers (fetch handler)
+
+```typescript
+import { routeAgentRequest } from "agents";
+export { Counter } from "./agents/counter";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    // Try agent routing first
+    const agentResponse = await routeAgentRequest(request, env);
+    if (agentResponse) return agentResponse;
+
+    // Your existing routing logic
+    const url = new URL(request.url);
+    if (url.pathname === "/api/hello") {
+      return Response.json({ message: "Hello!" });
+    }
+
+    return new Response("Not found", { status: 404 });
+  }
+};
+```
+
+### Hono
+
+```typescript
+import { Hono } from "hono";
+import { agentsMiddleware } from "hono-agents";
+export { Counter } from "./agents/counter";
+
+const app = new Hono<{ Bindings: Env }>();
+
+// Add agents middleware - handles WebSocket upgrades and agent HTTP requests
+app.use("*", agentsMiddleware());
+
+// Your existing routes continue to work
+app.get("/api/hello", (c) => c.json({ message: "Hello!" }));
+
+export default app;
+```
+
+### With Static Assets
+
+If you're serving static assets alongside agents:
+
+```typescript
+import { routeAgentRequest } from "agents";
+export { Counter } from "./agents/counter";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    // Try agent routing first
+    const agentResponse = await routeAgentRequest(request, env);
+    if (agentResponse) return agentResponse;
+
+    // Fall back to static assets
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+Make sure your `wrangler.jsonc` has the assets binding:
+
+```jsonc
+{
+  "assets": {
+    "binding": "ASSETS"
+  }
+}
+```
+
+---
+
+## 7. Add TypeScript Types
+
+Update your `Env` type to include the agent namespace. Create or update `env.d.ts`:
+
+```typescript
+import type { Counter } from "./agents/counter";
+
+interface Env {
+  // Your existing bindings
+  MY_KV: KVNamespace;
+  MY_DB: D1Database;
+
+  // Add agent bindings
+  Counter: DurableObjectNamespace<Counter>;
+}
+```
+
+---
+
+## 8. Connect from the Frontend
+
+### React
+
+```tsx
+import { useAgent } from "agents/react";
+
+type CounterState = { count: number };
+
+function CounterWidget() {
+  const agent = useAgent<CounterState>({
+    agent: "Counter"
+  });
+
+  return (
+    <div>
+      <span>{agent.state?.count ?? 0}</span>
+      <button onClick={() => agent.stub.increment()}>+</button>
+      <button onClick={() => agent.stub.decrement()}>-</button>
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```typescript
+import { AgentClient } from "agents/client";
+
+const agent = new AgentClient({
+  agent: "Counter",
+  name: "user-123", // Optional: unique instance name
+  host: window.location.host,
+  onStateUpdate: (state) => {
+    // Update the DOM when state changes
+    document.getElementById("count").textContent = String(state.count);
+  }
+});
+
+// Call methods — agent.state is also readable directly
+document.getElementById("increment").onclick = () => agent.call("increment");
+```
+
+---
+
+## Adding Multiple Agents
+
+Add more agents by extending the configuration:
+
+```typescript
+// src/agents/chat.ts
+export class Chat extends Agent<Env, ChatState> {
+  // ...
+}
+
+// src/agents/scheduler.ts
+export class Scheduler extends Agent<Env> {
+  // ...
+}
+```
+
+Update `wrangler.jsonc`:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "Counter", "class_name": "Counter" },
+      { "name": "Chat", "class_name": "Chat" },
+      { "name": "Scheduler", "class_name": "Scheduler" }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["Counter", "Chat", "Scheduler"]
+    }
+  ]
+}
+```
+
+Export all agents from your entry point:
+
+```typescript
+export { Counter } from "./agents/counter";
+export { Chat } from "./agents/chat";
+export { Scheduler } from "./agents/scheduler";
+```
+
+---
+
+## Common Integration Patterns
+
+### Agents Behind Authentication
+
+Check auth before routing to agents:
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    // Check auth for agent routes
+    if (request.url.includes("/agents/")) {
+      const authResult = await checkAuth(request, env);
+      if (!authResult.valid) {
+        return new Response("Unauthorized", { status: 401 });
+      }
+    }
+
+    const agentResponse = await routeAgentRequest(request, env);
+    if (agentResponse) return agentResponse;
+
+    // ... rest of routing
+  }
+};
+```
+
+### Custom Agent Path Prefix
+
+By default, agents are routed at `/agents/{agent-name}/{instance-name}`. You can customize this:
+
+```typescript
+import { routeAgentRequest } from "agents";
+
+const agentResponse = await routeAgentRequest(request, env, {
+  prefix: "/api/agents" // Now routes at /api/agents/{agent-name}/{instance-name}
+});
+```
+
+### Accessing Agents from Server Code
+
+You can interact with agents directly from your Worker code:
+
+```typescript
+import { getAgentByName } from "agents";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    if (request.url.endsWith("/api/increment")) {
+      // Get a specific agent instance
+      const counter = await getAgentByName(env.Counter, "shared-counter");
+      const newCount = await counter.increment();
+      return Response.json({ count: newCount });
+    }
+    // ...
+  }
+};
+```
+
+---
+
+## Troubleshooting
+
+### "Agent not found" or 404 errors
+
+1. **Check the export** - Agent class must be exported from your main entry point
+2. **Check the binding** - `class_name` in `wrangler.jsonc` must match the exported class name exactly
+3. **Check the route** - Default route is `/agents/{agent-name}/{instance-name}`
+
+### "No such Durable Object class" error
+
+Add the migration to `wrangler.jsonc`:
+
+```jsonc
+"migrations": [
+  {
+    "tag": "v1",
+    "new_sqlite_classes": ["YourAgentClass"]
+  }
+]
+```
+
+### WebSocket connection fails
+
+Ensure your routing passes the response through unchanged:
+
+```typescript
+// ✅ Correct - return the response directly
+const agentResponse = await routeAgentRequest(request, env);
+if (agentResponse) return agentResponse;
+
+// ❌ Wrong - don't wrap or modify the response
+const agentResponse = await routeAgentRequest(request, env);
+if (agentResponse) return new Response(agentResponse.body); // Breaks WebSocket
+```
+
+### State not persisting
+
+Check that:
+
+1. You're using `this.setState()`, not mutating `this.state` directly
+2. The agent class is in `new_sqlite_classes` in migrations
+3. You're connecting to the same agent instance name
+
+---
+
+## Next Steps
+
+- [State Management](./state.md) - Deep dive into agent state
+- [Scheduling](./scheduling.md) - Background tasks and cron jobs
+- [Agent Class](./agent-class.md) - Full lifecycle and methods
+- [Client SDK](./client-sdk.md) - Complete client API reference