docs: add SqlError class documentation for SQL error handling

Document the new SqlError class that provides detailed information about
failed SQL queries. This change syncs documentation for PR #768 which
introduces SqlError for better error handling in the agents SDK.

Changes:
- Add SqlError section in API reference with properties and usage example
- Add SQL Error Handling subsection under this.sql in agent-class.mdx
- Update onError section to demonstrate SqlError handling
- Add cross-references between related documentation sections

Related: cloudflare/agents#768

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

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: github-actions[bot]

src/content/docs/agents/api-reference/agents-api.mdx

@@ -800,6 +800,60 @@ function useAgent<State = unknown>(
 };
 ```
 
+### SqlError
+
+The `SqlError` class is thrown when a SQL query executed via `this.sql` fails. It provides detailed information about the failed query and the underlying error, allowing you to implement custom error handling logic in your Agent's `onError` method.
+
+#### Properties
+
+- **query** (`string`): The SQL query that failed
+- **cause** (`unknown`): The original error that caused the failure
+- **message** (`string`): A formatted error message combining both the query and cause
+
+#### Example
+
+<TypeScriptExample>
+
+```ts
+import { Agent, SqlError } from "agents";
+
+class MyAgent extends Agent {
+	async performDatabaseOperation() {
+		// SQL errors are automatically caught and passed to onError
+		const result = this.sql`
+      INSERT INTO users (id, email)
+      VALUES (${userId}, ${email})
+    `;
+	}
+
+	onError(error: unknown) {
+		if (error instanceof SqlError) {
+			// Access the failed query
+			console.error("Failed query:", error.query);
+
+			// Access the underlying error
+			console.error("Cause:", error.cause);
+
+			// Implement custom logic based on the query
+			if (error.query.includes("INSERT INTO users")) {
+				// Handle user insertion failures
+				// For example, check for duplicate key errors
+			}
+
+			// Log to external monitoring service
+			// this.logToMonitoring(error);
+		}
+
+		// Re-throw to propagate the error
+		throw error;
+	}
+}
+```
+
+</TypeScriptExample>
+
+Learn more about SQL error handling in the [Agent class internals](/agents/concepts/agent-class/#sql-error-handling).
+
 ### Chat Agent
 
 The Agents SDK exposes an `AIChatAgent` class that extends the `Agent` class and exposes an `onChatMessage` method that simplifies building interactive chat agents.

src/content/docs/agents/concepts/agent-class.mdx

@@ -245,6 +245,45 @@ class MyAgent extends Agent {
 }
 ```
 
+#### SQL Error Handling
+
+When a SQL query fails, the `this.sql` method throws a `SqlError` instead of logging to the console. This error is automatically passed to your `onError` handler, allowing you to implement custom error handling logic.
+
+The `SqlError` class includes:
+- `query`: The SQL query that failed
+- `cause`: The original error that caused the failure
+- `message`: A formatted error message
+
+```ts
+import { Agent, SqlError } from "agents";
+
+class MyAgent extends Agent {
+  onStart() {
+    try {
+      // This query might fail
+      this.sql`INSERT INTO users (id, name) VALUES (${userId}, ${userName})`;
+    } catch (error) {
+      // Errors are wrapped in SqlError and passed to onError
+      // See the onError section below for how to handle SQL errors
+    }
+  }
+
+  onError(error: unknown) {
+    if (error instanceof SqlError) {
+      console.error("SQL query failed:", error.query);
+      console.error("Original error:", error.cause);
+
+      // Implement custom logic based on the query or error type
+      if (error.query.includes("INSERT")) {
+        // Handle insert failures specifically
+      }
+    }
+
+    throw error;
+  }
+}
+```
+
 ### RPC and Callable Methods
 
 `agents` take Durable Objects RPC one step forward by implementing RPC through WebSockets, so clients can also call methods on the Agent directly. To make a method callable through WS, developers can use the `@callable` decorator. Methods can return a serializable value or a stream (when using `@callable({ stream: true })`).
@@ -411,15 +450,27 @@ function someUtilityFunction() {
 
 `Agent` extends `Server`'s `onError` so it can be used to handle errors that are not necessarily WebSocket errors. It is called with a `Connection` or `unknown` error.
 
+All SQL errors from `this.sql` are automatically wrapped in a `SqlError` and passed to `onError`, allowing you to implement centralized error handling for SQL operations.
+
 ```ts
+import { Agent, SqlError } from "agents";
+
 class MyAgent extends Agent {
   onError(connectionOrError: Connection | unknown, error?: unknown) {
     if (error) {
       // WebSocket connection error
       console.error("Connection error:", error);
     } else {
-      // Server error
-      console.error("Server error:", connectionOrError);
+      // Server error (including SQL errors)
+      if (connectionOrError instanceof SqlError) {
+        console.error("SQL query failed:", connectionOrError.query);
+        console.error("Cause:", connectionOrError.cause);
+
+        // Implement custom SQL error handling
+        // For example, log to external monitoring service
+      } else {
+        console.error("Server error:", connectionOrError);
+      }
     }
 
     // Optionally throw to propagate the error