Document onSqlError hook for customizable SQL error handling

Adds documentation for the new onSqlError hook that allows users to
customize SQL error logging behavior. The hook is called when SQL
queries fail, giving users full control over error handling and
logging.

Related to 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

@@ -596,6 +596,56 @@ export class YourAgent extends Agent {
 
 </TypeScriptExample>
 
+#### SQL error handling
+
+Handle SQL execution errors by overriding the `onSqlError` method. This allows you to customize logging behavior or implement error recovery strategies.
+
+```ts
+// SQL error handling in the Agent class
+class Agent<Env, State = unknown> {
+	// Called when a SQL query execution fails
+	// Override this method to customize error logging or implement recovery logic
+	onSqlError(query: string, error: unknown): void;
+}
+```
+
+<TypeScriptExample>
+
+```ts
+// Example of customizing SQL error handling
+export class YourAgent extends Agent {
+	// Override onSqlError to customize error handling
+	onSqlError(query: string, error: unknown): void {
+		// Log to a custom logging service
+		console.error(`SQL query failed: ${query}`, {
+			error,
+			timestamp: Date.now(),
+			agentName: this.name,
+		});
+
+		// You could also:
+		// - Send errors to an external monitoring service
+		// - Implement custom retry logic
+		// - Filter sensitive information from logs
+	}
+
+	async getUserById(id: string) {
+		try {
+			// If this query fails, onSqlError will be called before the error is thrown
+			const users = this.sql<{ id: string; name: string }>`
+        SELECT * FROM users WHERE id = ${id}
+      `;
+			return users[0];
+		} catch (error) {
+			// Handle the error after onSqlError has logged it
+			return null;
+		}
+	}
+}
+```
+
+</TypeScriptExample>
+
 :::note
 
 Visit the [state management API documentation](/agents/api-reference/store-and-sync-state/) within the Agents SDK, including the native `state` APIs and the built-in `this.sql` API for storing and querying data within your Agents.