docs(agenteye): clarify SDK payload serialization#572
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe 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. ChangesPython SDK documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Suggested labels: Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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
📒 Files selected for processing (1)
docs/agenteye/python-sdk.mdx
|
Automated code review started - full review. Results will be posted here. |
|
⏳ Code review in progress — Phase 2 deep analysis Phase 0 complete:
Phase 1 complete:
Phase 3 in progress: Running MDX validation and analysing placement/grammar/accuracy... |
|
|
||
| `timestamp`, `type`, and `environment` are reserved and raise `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) if passed as custom fields. `session_id` and `agent_id` are required parameters on every event method and cannot be supplied a second time; Python raises `TypeError` if you do. Set the environment with `configure(environment=...)` (or the `AGENTEYE_ENVIRONMENT` variable) instead. | ||
|
|
||
| Keep payloads as structured JSON when you want to query their fields. Values JSON does not natively support—such as datetimes, UUIDs, decimals, sets, bytes, or model objects—are converted to strings so recording continues safely. |
There was a problem hiding this comment.
🟡 Grammar: Missing relative pronoun makes the sentence awkward to parse. "Values JSON does not natively support" reads as if "Values JSON" is a compound noun. It should be "Values that JSON does not natively support" to make clear that "that JSON does not natively support" is a relative clause modifying "Values." Fix: Add "that" between "Values" and "JSON" on this line. This was also flagged by CodeRabbit in a previous review pass but was not addressed.
Code Review -- PR #572Executive SummaryThis docs-only PR adds 2 lines to docs/agenteye/python-sdk.mdx documenting that the Python SDK auto-converts non-JSON values (datetimes, UUIDs, decimals, etc.) to strings so recording continues safely, plus a corresponding changelog entry. Code quality is clean -- the wording is precise, well-placed under Custom Fields, and backed by real SDK behaviour. One minor grammar issue (missing 'that') is the only finding. Breaking ChangesNo breaking changes detected. This is a documentation-only change with no code, schema, API, or configuration modifications. Issues Found
Logical / Bug Analysis
EvidenceMDX Validation: CI status: All 11 checks pass (build, docs, quality, test x4, test-e2e, CodeRabbit, OSV-Scanner, Socket Security). Issue LinkageNo issue linked. For a 2-line docs change this is reasonable. Human Review FeedbackNo human review comments on this PR. The only prior review was from CodeRabbit (bot), which flagged the same grammar issue -- that thread was auto-resolved but the fix was not applied. Suggestions
VerdictVERDICT: APPROVED_WITH_SUGGESTIONS -- |
hermes-exosphere
left a comment
hermes-exosphere
left a comment
There was a problem hiding this comment.
Automated review: Approved with suggestions. One minor grammar fix suggested (inline comment on docs/agenteye/python-sdk.mdx:415). All CI checks pass, 675 MDX pages validate cleanly. VERDICT: APPROVED_WITH_SUGGESTIONS
hermes-exosphere
left a comment
hermes-exosphere
left a comment
There was a problem hiding this comment.
Automated review: Approved. ✅
2 participants
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
Scope
This PR contains public contract wording only. Implementation and operational details remain in the signed-customer enterprise documentation in FailproofAI/agenteye#418.
Validation
Summary by CodeRabbit