docs(agenteye): clarify SDK payload serialization

[NiveditJain]

Why this documentation is needed

The companion AgentEye audit reproduced a data-loss failure in the Python SDK: values outside JSON native types were serialized on the background writer thread, where one datetime-like value could terminate recording for the process after the application call had already returned. The SDK fix now preserves recording by converting unsupported leaves to strings and retaining failed batches for retry.

The public SDK page must state the observable contract customers can rely on without exposing internal architecture: structured JSON remains queryable as structured data, while unsupported leaves are safely represented as strings.

What changes

• document automatic string conversion for datetimes, UUIDs, decimals, sets, bytes, and model objects
• recommend explicit structured JSON for fields customers intend to query
• add the required changelog entry for this PR

Scope

This PR contains public contract wording only. Implementation and operational details remain in the signed-customer enterprise documentation in FailproofAI/agenteye#418.

Validation

• all 675 MDX pages parsed successfully with the repository validator
• Mintlify navigation validation is run with browser download disabled because Chromium is already provided by the test environment

Summary by CodeRabbit

• Documentation
  • Clarified how custom event payload values are handled for querying.
  • Structured JSON values are preserved where possible, while unsupported types are converted to strings so events can still be recorded.
  • Added guidance to use JSON-compatible structures for fields intended for querying.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5001d643-1634-4430-a267-4da8124d1648

📥 Commits

Reviewing files that changed from the base of the PR and between ff3d5bd and fcdc239.

📒 Files selected for processing (1)

• CHANGELOG.md

---

📝 Walkthrough

Walkthrough

The Custom Fields documentation and changelog explain that structured event payloads remain JSON where possible, while unsupported values are converted to strings so events continue recording.

Changes

Python SDK documentation

Layer / File(s)	Summary
Payload serialization guidance docs/agenteye/python-sdk.mdx, CHANGELOG.md	Documents preserving JSON-like payload values for querying and converting unsupported types to strings during event recording, with the behavior recorded in the changelog.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested labels: enhancement

Suggested reviewers: chhhee10

Poem

A rabbit reads the payload bright,
JSON tucked in neat and light.
Dates and bytes that cannot stay
Turn to strings along the way.
Events hop safely through the night.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: clarifying AgentEye SDK payload serialization in docs.
Description check	✅ Passed	It covers the motivation, contract wording, scope, and validation, though it doesn't use the exact template sections for Type of Change and Checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/agenteye/python-sdk.mdx`:
- Around line 415-416: Rephrase the sentence following “Keep payloads as
structured JSON” to use grammatically clear wording for values that JSON does
not natively support, while preserving the existing examples and meaning about
converting them to strings.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3eafccbb-6e10-47e2-b9d0-f7656cf06a78

📥 Commits

Reviewing files that changed from the base of the PR and between 691a24f and ff3d5bd.

📒 Files selected for processing (1)

• docs/agenteye/python-sdk.mdx