feat(api): enhance error handling and add structured hints for agent operations

backend/app/schemas/errors.py

@@ -2,7 +2,49 @@
 
 from __future__ import annotations
 
-from sqlmodel import Field, SQLModel
+from pydantic import ConfigDict, Field
+from sqlmodel import SQLModel
+
+
+class LLMErrorResponse(SQLModel):
+    """Standardized LLM-facing error payload used by API contracts."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "title": "LLMErrorResponse",
+            "x-llm-intent": "llm_error_handling",
+            "x-when-to-use": [
+                "Structured, tool-facing API errors for agent workflows",
+                "Gateway handoff and delegated-task operations",
+            ],
+            "x-required-actor": "agent",
+            "x-side-effects": [
+                "Returns explicit machine-readable error context",
+                "Includes request_id for end-to-end traceability",
+            ],
+        },
+    )
+
+    detail: str | dict[str, object] | list[object] = Field(
+        description=(
+            "Error payload. Agents should rely on `code` when present and default "
+            "to `message` for fallback display."
+        ),
+        examples=["Invalid payload for lead escalation.", {"code": "not_found", "message": "Agent not found."}],
+    )
+    request_id: str | None = Field(
+        default=None,
+        description="Request correlation identifier injected by middleware.",
+    )
+    code: str | None = Field(
+        default=None,
+        description="Optional machine-readable error code.",
+        examples=["gateway_unavailable", "dependency_validation_failed"],
+    )
+    retryable: bool | None = Field(
+        default=None,
+        description="Whether a client should retry the call after remediating transient conditions.",
+    )
 
 
 class BlockedTaskDetail(SQLModel):