feat(sdk): add external sink

[namrataghadi-galileo]

Summary

Added a vendor-neutral external control-event sink registration API in the Python SDK so integrations can receive finalized ControlExecutionEvent payloads without adding vendor-specific logic to OSS.

Updated observability delivery so observability_enabled is the master gate, and when enabled the SDK uses registered sinks if present, otherwise the existing default OSS batcher sink.

Added docs and test coverage for sink registration, override behavior, fallback to default delivery, and local/server/merged event delivery parity.

Scope

User-facing/API changes:

• Added register_control_event_sink(...), unregister_control_event_sink(...), and get_registered_control_event_sinks(...) to the Python SDK public API
• Documented how external integrations can register a sink

Internal changes:

• Added active sink resolution in the SDK observability layer
• Enforced observability_enabled before any sink delivery occurs
• Preserved existing event construction flow for local, server, merged, and partial/error cases
• Added mock-sink tests covering override semantics and delivery behavior

Out of scope:

• Config-driven sink selection for SDK/server
• OTEL sink implementation and configuration
• Server-side sink resolution changes

Risk and Rollout

Risk level: medium

Rollback plan: Revert the SDK observability sink-resolution changes and public sink registration API additions in the Python SDK. Since default OSS delivery remains the fallback when no external sink is registered, rollback is isolated to the SDK observability layer.

Testing

• Added or updated automated tests
• Ran make check — focused validation was run instead. Full workspace checks were unnecessary for this scoped SDK change. There is also a pre-existing unrelated SDK typecheck issue around google.adk untyped imports.
• Manually verified behavior

Checklist

• Linked issue/spec (if applicable)
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.59459% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
sdks/python/src/agent_control/observability.py	94.59%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

I like the direction here, but I don't think this base PR is ready to merge yet. The main thing I'd fix first is the enabled= override becoming sticky process state. I also think we need an explicit lifecycle/ownership story for external sinks before we merge the base abstraction.

[namrataghadi-galileo]

@lan17 Thanks, I agree those were the two biggest issues in the base abstraction.

I fixed the sticky enabled= behavior first. init_observability(enabled=...) no longer writes back into the process-global SDK settings, so it now behaves as a per-call override for that initialization path instead of poisoning later init/re-init flows for the rest of the process.

I also made the external-sink ownership model explicit. Caller-registered sinks are now documented as caller-owned: the SDK does not flush, close, or unregister them during shutdown, and shutdown_observability() only drains SDK-owned resources like the built-in batcher. I added regression coverage for both behaviors so the base API has a clear lifecycle boundary before we build on it further.

[lan17]

Looks good to me. The main issues from the earlier round were addressed, and the overall shape here makes sense. I left a couple of follow-up comments around fanout semantics and sink registration bookkeeping, but I don't think either one should hold this up.

[galileo-automation]

🎉 This PR is included in version 2.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀