feat(sdk): add otel sink to generate and emit OTEL events

examples/README.md

@@ -14,6 +14,7 @@ This directory contains runnable examples for Agent Control. Each example has it
 | Customer Support Agent | Enterprise scenario with PII protection, prompt-injection defense, and multiple tools. | https://docs.agentcontrol.dev/examples/customer-support |
 | DeepEval | Build a custom evaluator using DeepEval GEval metrics. | https://docs.agentcontrol.dev/examples/deepeval |
 | Galileo Luna-2 | Toxicity detection and content moderation with Galileo Protect. | https://docs.agentcontrol.dev/examples/galileo-luna2 |
+| OTEL Merged Events | Create controls, merge local and server events, and inspect OTEL spans locally. | https://docs.agentcontrol.dev/examples/otel-merged-events |
 | LangChain SQL Agent | Protect a SQL agent from dangerous queries with server-side controls. | https://docs.agentcontrol.dev/examples/langchain-sql |
 | Steer Action Demo | Banking transfer agent showcasing allow, deny, warn, and steer actions. | https://docs.agentcontrol.dev/examples/steer-action-demo |
 | AWS Strands | Guardrails for AWS Strands agent workflows and tool calls. | https://docs.agentcontrol.dev/examples/aws-strands |

examples/otel_merged_events/README.md

@@ -0,0 +1,68 @@
+# OTEL Merged Events Example
+
+This example shows how Agent Control can:
+
+- create one SDK-local control and one server-side control
+- merge the resulting control execution events in the SDK
+- export the merged batch through the OTEL event sink
+- collect the exported OTEL spans locally with an in-memory exporter
+
+## What this example shows
+
+- control creation and agent association on the server
+- SDK-local and server-side evaluation in the same protected function call
+- merged-event OTEL emission without needing a live collector
+- the OTEL attributes emitted for each control execution
+
+## Prerequisites
+
+1. Start the Agent Control server from the repo root:
+
+```bash
+make server-run
+```
+
+2. Install the example dependencies:
+
+```bash
+cd examples/otel_merged_events
+uv pip install -e . --upgrade
+```
+
+## Setup
+
+Create the demo agent and controls:
+
+```bash
+cd examples/otel_merged_events
+uv run python setup_controls.py
+```
+
+This creates:
+
+- `otel-merged-local-input-check`
+- `otel-merged-server-input-check`
+
+Both controls use composite `and` conditions with multiple evaluator leaves so
+the exported OTEL spans include representative and aggregate metadata such as
+`primary_evaluator`, `primary_selector_path`, `leaf_count`,
+`all_evaluators`, and `all_selector_paths`.
+
+## Run
+
+Run the demo script:
+
+```bash
+cd examples/otel_merged_events
+uv run python demo_agent.py
+```
+
+The script prints:
+
+- the protected function result
+- the number of OTEL spans collected
+- one OTEL span per reconstructed control execution event
+
+This example uses an in-memory OTEL exporter so you can inspect the spans
+locally. In a production setup, the same merged-event sink can export to an
+OTLP endpoint instead.