Document onSqlError hook for customizable SQL error logging

Add documentation for the new onSqlError hook that allows developers to customize SQL error logging behavior in Agents. The hook is called before errors are thrown via onError, enabling custom logging, monitoring, or observability integrations.

Changes:
- Added onSqlError method signature to Agent class API reference
- Included practical example showing custom error logging with context
- Documented that errors are still thrown via onError after this hook

Related PR: 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

@@ -111,6 +111,11 @@ class MyAgent extends Agent<Env, State> {
 		console.error(`Connection error:`, error);
 	}
 
+	// Handle SQL execution errors - override to customize logging behavior
+	onSqlError(query: string, error: unknown): void {
+		console.error(`failed to execute sql query: ${query}`, error);
+	}
+
 	// Handle WebSocket connection close events
 	async onClose(
 		connection: Connection,
@@ -533,6 +538,11 @@ class Agent<Env, State = unknown> {
 		strings: TemplateStringsArray,
 		...values: (string | number | boolean | null)[]
 	): T[];
+
+	// Handle SQL execution errors
+	// Override this method to customize SQL error logging behavior
+	// The error is still thrown via onError after this method is called
+	onSqlError(query: string, error: unknown): void;
 }
 ```
 
@@ -585,6 +595,20 @@ export class YourAgent extends Agent {
       ORDER BY created_at DESC
     `;
 	}
+
+	// Override onSqlError to customize SQL error handling
+	onSqlError(query: string, error: unknown): void {
+		// Custom logging that includes additional context
+		console.error("SQL execution failed:", {
+			query,
+			error: error instanceof Error ? error.message : String(error),
+			timestamp: new Date().toISOString(),
+			agentId: this.name,
+		});
+
+		// You could also send errors to an observability service
+		// this.observability?.emit({ type: "sql_error", query, error }, this.ctx);
+	}
 }
 ```