[dx] Improve Agent file upload DX

[chris-freeman-glean]

Summary

Addresses a common DX issue where developers attempt to pass file objects directly to agents.run().

Changes

• Adds an AgentFileUploadErrorHook that intercepts 400 errors with "permission" issues in agent runs.
• Returns a clear, actionable error message explaining the required two-step process (Upload -> Get ID -> Pass ID).
• Adds a straightforward example file examples/agent_with_file_upload.py demonstrating the correct workflow.

Testing

• Verified the hook registration logic.
• Verified the example code pattern against the SDK types.