pipe SQL errors into the existing onError method using a new SqlError class

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

@@ -536,6 +536,55 @@ class Agent<Env, State = unknown> {
 }
 ```
 
+#### SQL error handling
+
+When a SQL query fails, the error is wrapped in a `SqlError` and passed to your Agent's [`onError` method](/agents/api-reference/agents-api/#websocket-api). The `SqlError` class provides access to the failed query, making it easier to debug and handle SQL-related errors.
+
+```ts
+// Error class for SQL execution failures
+class SqlError extends Error {
+	// The SQL query that failed
+	readonly query: string;
+
+	constructor(query: string, cause: unknown);
+}
+```
+
+You can handle SQL errors specifically in your `onError` method by checking if the error is an instance of `SqlError`:
+
+<TypeScriptExample>
+
+```ts
+import { Agent, SqlError } from "agents";
+
+export class YourAgent extends Agent {
+	// Handle SQL errors specifically
+	async onError(connection: Connection | unknown, error?: unknown) {
+		const err = error || connection;
+
+		if (err instanceof SqlError) {
+			// SQL-specific error handling
+			console.error("SQL query failed:", err.query);
+			console.error("Error:", err.message);
+			// Optionally access the original cause
+			console.error("Cause:", err.cause);
+		} else {
+			// Handle other errors
+			console.error("Error:", err);
+		}
+
+		throw err;
+	}
+
+	async someMethod() {
+		// SQL errors are automatically caught and passed to onError
+		const users = this.sql`SELECT * FROM users WHERE invalid_syntax`;
+	}
+}
+```
+
+</TypeScriptExample>
+
 <TypeScriptExample>
 
 ```ts
@@ -596,6 +645,57 @@ Visit the [state management API documentation](/agents/api-reference/store-and-s
 
 :::
 
+#### SQL error handling
+
+When a SQL query fails, the Agents SDK throws a `SqlError` that is passed to your `onError` method. The `SqlError` class provides access to the failed query, making it easier to debug and handle SQL-specific errors.
+
+```ts
+// Error class for SQL execution failures
+class SqlError extends Error {
+	// The SQL query that failed
+	readonly query: string;
+
+	constructor(query: string, cause: unknown);
+}
+```
+
+<TypeScriptExample>
+
+```ts
+export class YourAgent extends Agent {
+	// Override onError to handle SQL errors
+	onError(error: unknown): Error {
+		// Check if the error is a SQL error
+		if (error instanceof SqlError) {
+			console.error(`SQL query failed: ${error.query}`);
+			console.error(`Error details:`, error.cause);
+
+			// You can handle specific SQL errors differently
+			return new Error(`Database operation failed: ${error.message}`);
+		}
+
+		// Handle other errors
+		return error instanceof Error ? error : new Error(String(error));
+	}
+
+	async getUserData(userId: string) {
+		// SQL errors are automatically caught and passed to onError
+		const users = this.sql<User>`
+			SELECT * FROM users WHERE id = ${userId}
+		`;
+		return users[0];
+	}
+}
+```
+
+</TypeScriptExample>
+
+The `SqlError` class includes:
+
+- `query`: The SQL query string that failed
+- `cause`: The underlying error that caused the SQL query to fail
+- `message`: A formatted error message combining the cause
+
 ### MCP Client API
 
 The Agents SDK allows your Agent to act as an MCP (Model Context Protocol) client, connecting to remote MCP servers and using their tools, resources, and prompts.

src/content/docs/agents/api-reference/store-and-sync-state.mdx

@@ -229,6 +229,8 @@ Learn more about the zero-latency SQL storage that powers both Agents and Durabl
 
 The SQL API exposed to an Agent is similar to the one [within Durable Objects](/durable-objects/api/sqlite-storage-api/#sql-api): Durable Object SQL methods available on `this.ctx.storage.sql`. You can use the same SQL queries with the Agent's database, create tables, and query data, just as you would with Durable Objects or [D1](/d1/).
 
+When a SQL query fails, the error is automatically wrapped in a `SqlError` class and passed to your Agent's `onError` method. The `SqlError` class includes the `query` property, allowing you to inspect which SQL query failed. Refer to the [SQL error handling documentation](/agents/api-reference/agents-api/#sql-error-handling) to learn more about handling SQL errors.
+
 ### Use Agent state as model context
 
 You can combine the state and SQL APIs in your Agent with its ability to [call AI models](/agents/api-reference/using-ai-models/) to include historical context within your prompts to a model. Modern Large Language Models (LLMs) often have very large context windows (up to millions of tokens), which allows you to pull relevant context into your prompt directly.

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

@@ -411,10 +411,20 @@ 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.
 
+When SQL queries fail, the error is wrapped in a `SqlError` class and passed to this method, allowing you to distinguish SQL errors from other error types and access the failed query.
+
 ```ts
+import { Agent, SqlError } from "agents";
+
 class MyAgent extends Agent {
   onError(connectionOrError: Connection | unknown, error?: unknown) {
-    if (error) {
+    const err = error || connectionOrError;
+
+    if (err instanceof SqlError) {
+      // SQL query error - access the failed query
+      console.error("SQL query failed:", err.query);
+      console.error("Error:", err.message);
+    } else if (error) {
       // WebSocket connection error
       console.error("Connection error:", error);
     } else {
@@ -423,7 +433,7 @@ class MyAgent extends Agent {
     }
 
     // Optionally throw to propagate the error
-    throw connectionOrError;
+    throw err;
   }
 }
 ```