docs: Sync observability documentation from agents PR #639

[threepointone]

Summary

This PR syncs documentation changes from cloudflare/agents PR #639 which adds comprehensive observability documentation for the Agents SDK.

Changes

• New file: src/content/docs/agents/api-reference/observability.mdx
  • Documents the observability property for Agent instances
  • Details all event types (connection, state, message, AI, tool events)
  • Provides custom observability implementation examples
  • Includes integration examples for logging services, metrics, and event filtering
  • Best practices for performance, security, and debugging

Source PR

• Repository: cloudflare/agents
• PR: Colos: additions and removals #639
• Title: update msg publishing logic (docs workflow)

Documentation Quality

This documentation follows the Diátaxis framework:

• Reference: Complete API documentation for the observability interface
• Examples: Multiple practical code examples for common use cases
• Best Practices: Guidance on performance, security, and debugging

Test Plan

• Documentation builds successfully
• All code examples are syntactically correct
• Links and references are valid
• Content follows cloudflare-docs style guide

---

🤖 Generated with Claude Code

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/agents/	@irvinebroque, @rita3ko, @elithrar, @thomasgauvin, @threepointone, @cloudflare/pcx-technical-writing

[github-actions]

Preview URL: https://cf11542b.preview.developers.cloudflare.com
Preview Branch URL: https://sync-docs-pr-639.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/platform/observability/	https://sync-docs-pr-639.preview.developers.cloudflare.com/agents/platform/observability/