computer-agent-py 0.1.0__tar.gz → 0.1.3__tar.gz

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: computer-agent-py
-Version: 0.1.0
+Version: 0.1.3
 Summary: Drop-in replacement for claude-agent-sdk that adds a proxied telemetry pipeline (PII redaction + guardrails) with OpenTelemetry and AgentOS sinks.
 Keywords: computeragent,claude-agent-sdk,claude,agent,telemetry,otel,opentelemetry,agentos,pii
 Author: Abhi Bhat
@@ -114,10 +114,11 @@ That's it — same shape as `claude-agent-sdk`. Telemetry is configured from env
 
 | Variable | Effect |
 |---|---|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Enables OTLP/HTTP export. Unset → console exporter (debug). |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL of an OTLP/HTTP backend. The sink appends `/v1/traces` and `/v1/metrics` automatically — pass the base. Unset → console exporter (debug). |
 | `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` (e.g. `api-key=NRRX-...` for New Relic). |
 | `OTEL_SERVICE_NAME` | `service.name` attribute on every span. Default: `computeragent`. |
 | `COMPUTERAGENT_OTEL` | `disabled` to suppress OtelSink. |
+| `COMPUTERAGENT_OTEL_TEMPORALITY` | `delta` (default) or `cumulative`. SaaS OTLP intakes (New Relic, Datadog direct, Honeycomb) require delta; cumulative is only correct when exporting to a collector that aggregates downstream. |
 | `AGENTOS_MONGO_URL` | When set + `[agentos]` installed, attaches AgentOS sinks (registry, logs, sessions, agent_messages, slack_threads). |
 | `AGENTOS_MONGO_DB` | Mongo database name. Default: `agentos`. |
 | `COMPUTERAGENT_CAPTURE_CONTENT` | `1` to include prompts/responses on OTel spans. Default: off. |

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/README.md

@@ -71,10 +71,11 @@ That's it — same shape as `claude-agent-sdk`. Telemetry is configured from env
 
 | Variable | Effect |
 |---|---|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Enables OTLP/HTTP export. Unset → console exporter (debug). |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL of an OTLP/HTTP backend. The sink appends `/v1/traces` and `/v1/metrics` automatically — pass the base. Unset → console exporter (debug). |
 | `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` (e.g. `api-key=NRRX-...` for New Relic). |
 | `OTEL_SERVICE_NAME` | `service.name` attribute on every span. Default: `computeragent`. |
 | `COMPUTERAGENT_OTEL` | `disabled` to suppress OtelSink. |
+| `COMPUTERAGENT_OTEL_TEMPORALITY` | `delta` (default) or `cumulative`. SaaS OTLP intakes (New Relic, Datadog direct, Honeycomb) require delta; cumulative is only correct when exporting to a collector that aggregates downstream. |
 | `AGENTOS_MONGO_URL` | When set + `[agentos]` installed, attaches AgentOS sinks (registry, logs, sessions, agent_messages, slack_threads). |
 | `AGENTOS_MONGO_DB` | Mongo database name. Default: `agentos`. |
 | `COMPUTERAGENT_CAPTURE_CONTENT` | `1` to include prompts/responses on OTel spans. Default: off. |

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "computer-agent-py"
-version = "0.1.0"
+version = "0.1.3"
 description = "Drop-in replacement for claude-agent-sdk that adds a proxied telemetry pipeline (PII redaction + guardrails) with OpenTelemetry and AgentOS sinks."
 authors = [
     { name = "Abhi Bhat", email = "abhishek.bhat@lyzr.ai" },

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/src/computeragent/_proxy/client.py

@@ -20,7 +20,7 @@ import claude_agent_sdk
 from claude_agent_sdk.types import AssistantMessage, ResultMessage, TextBlock
 
 from ..telemetry import TelemetryEvent, get_pipeline, new_session_id
-from .query import _derive_agent_name
+from .query import _derive_agent_description, _derive_agent_name
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterable, AsyncIterator
@@ -50,6 +50,7 @@ class ClaudeSDKClient:
         # placeholder-vs-upstream rationale).
         self._upstream_session_id: str | None = None
         self._agent_name = _derive_agent_name(options)
+        self._agent_description = _derive_agent_description(options)
         self._started_at: float | None = None
         self._last_result: ResultMessage | None = None
         self._last_assistant_text: str = ""
@@ -75,6 +76,7 @@ class ClaudeSDKClient:
             TelemetryEvent.session_started(
                 session_id=self._session_id,
                 agent_name=self._agent_name,
+                agent_description=self._agent_description,
                 options=self._options,
                 prompt=prompt if prompt is not None else "<connect>",
             )
@@ -122,6 +124,8 @@ class ClaudeSDKClient:
             for ev in TelemetryEvent.from_message(
                 msg, session_id=self._session_id, agent_name=self._agent_name
             ):
+                if self._agent_description is not None:
+                    ev.agent_description = self._agent_description
                 await pipeline.emit(ev)
             if isinstance(msg, AssistantMessage):
                 for block in getattr(msg, "content", []) or []:
@@ -145,6 +149,8 @@ class ClaudeSDKClient:
             for ev in TelemetryEvent.from_message(
                 msg, session_id=self._session_id, agent_name=self._agent_name
             ):
+                if self._agent_description is not None:
+                    ev.agent_description = self._agent_description
                 await pipeline.emit(ev)
             if isinstance(msg, AssistantMessage):
                 for block in getattr(msg, "content", []) or []:
@@ -203,6 +209,7 @@ class ClaudeSDKClient:
                 duration_ms=duration_ms,
                 last_assistant_text=self._last_assistant_text,
             )
+            ev.agent_description = self._agent_description
             if self._upstream_session_id is not None:
                 ev.payload["upstream_session_id"] = self._upstream_session_id
             await pipeline.emit(ev)
@@ -212,6 +219,7 @@ class ClaudeSDKClient:
                     kind="session_ended",
                     session_id=self._session_id,
                     agent_name=self._agent_name,
+                    agent_description=self._agent_description,
                     payload={
                         "is_error": False,
                         "subtype": "no_result",

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/src/computeragent/_proxy/query.py

@@ -39,6 +39,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
     pipeline = get_pipeline()
     session_id = new_session_id()
     agent_name = _derive_agent_name(options)
+    agent_description = _derive_agent_description(options)
     started_at = time.monotonic()
     last_assistant_text = ""
 
@@ -47,6 +48,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
             TelemetryEvent.session_started(
                 session_id=session_id,
                 agent_name=agent_name,
+                agent_description=agent_description,
                 options=options,
                 prompt=prompt,
             )
@@ -78,6 +80,11 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
             for ev in TelemetryEvent.from_message(
                 msg, session_id=session_id, agent_name=agent_name
             ):
+                # Carry the description forward on every event so sinks that
+                # group by description (or want to surface it on per-message
+                # telemetry) don't have to back-reference session_started.
+                if agent_description is not None:
+                    ev.agent_description = agent_description
                 await pipeline.emit(ev)
 
             if isinstance(msg, AssistantMessage):
@@ -100,6 +107,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
                 duration_ms=duration_ms,
                 last_assistant_text=last_assistant_text,
             )
+            ev.agent_description = agent_description
             if upstream_session_id is not None:
                 ev.payload["upstream_session_id"] = upstream_session_id
             await pipeline.emit(ev)
@@ -110,6 +118,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
                     kind="session_ended",
                     session_id=session_id,
                     agent_name=agent_name,
+                    agent_description=agent_description,
                     payload={
                         "is_error": False,
                         "subtype": "no_result",
@@ -124,14 +133,14 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
     except BaseException as exc:
         duration_ms = (time.monotonic() - started_at) * 1000.0
         try:
-            await pipeline.emit(
-                TelemetryEvent.session_ended_error(
-                    session_id=session_id,
-                    agent_name=agent_name,
-                    exc=exc,
-                    duration_ms=duration_ms,
-                )
+            err_ev = TelemetryEvent.session_ended_error(
+                session_id=session_id,
+                agent_name=agent_name,
+                exc=exc,
+                duration_ms=duration_ms,
             )
+            err_ev.agent_description = agent_description
+            await pipeline.emit(err_ev)
         except Exception:  # noqa: BLE001
             logger.debug("error-path telemetry emit failed", exc_info=True)
         raise
@@ -163,3 +172,20 @@ def _derive_agent_name(options: Any) -> str | None:
         if first:
             return first[:80]
     return None
+
+
+def _derive_agent_description(options: Any) -> str | None:
+    """Pick an agent description from options.
+
+    Mirrors :func:`_derive_agent_name` — the description is purely opt-in.
+    Callers set it on options via ``options.agent_description = "..."`` and
+    the proxy threads it through to the telemetry pipeline. Unlike the
+    name, there's no implicit fallback to system_prompt: a description is
+    a human label, not something we want to synthesize from the prompt.
+    """
+    if options is None:
+        return None
+    desc = getattr(options, "agent_description", None)
+    if isinstance(desc, str) and desc:
+        return desc
+    return None

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/src/computeragent/telemetry/config.py

@@ -45,6 +45,7 @@ def configure(
     capture_content_mode: Literal["events", "attributes", "both"] = "events",
     max_attribute_length: int = 8192,
     fail_open: bool = False,
+    temporality: Literal["delta", "cumulative"] | None = None,
 ) -> Pipeline:
     """Programmatic configuration. Idempotent — replaces the active pipeline.
 
@@ -52,6 +53,11 @@ def configure(
     and :class:`~computeragent.telemetry.sinks.agentos.AgentRegistrySink` if their
     extras are installed and not already in ``sinks``. Pass ``sinks=[]`` to
     disable all auto-attachment.
+
+    ``temporality`` controls metric aggregation temporality. Defaults to
+    delta (set by OtelSink) which is what every major SaaS OTLP intake
+    requires — pass ``"cumulative"`` only when exporting to a collector that
+    aggregates downstream.
     """
     global _PIPELINE, _CONFIG
     _CONFIG = {
@@ -65,6 +71,7 @@ def configure(
         "capture_content": capture_content,
         "capture_content_mode": capture_content_mode,
         "max_attribute_length": max_attribute_length,
+        "temporality": temporality,
     }
 
     effective_sinks: list[TelemetrySink] = list(sinks) if sinks is not None else _auto_sinks()
@@ -106,6 +113,7 @@ def _build_default_pipeline() -> Pipeline:
         "endpoint": os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT"),
         "headers": _parse_headers(os.environ.get("OTEL_EXPORTER_OTLP_HEADERS")),
         "sample_rate": 1.0,
+        "temporality": os.environ.get("COMPUTERAGENT_OTEL_TEMPORALITY"),
         "capture_content": _env_bool("COMPUTERAGENT_CAPTURE_CONTENT", default=False),
         "capture_content_mode": os.environ.get("COMPUTERAGENT_CAPTURE_CONTENT_MODE", "events"),
         "max_attribute_length": int(os.environ.get("COMPUTERAGENT_MAX_ATTRIBUTE_LENGTH", "8192")),

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/src/computeragent/telemetry/event.py

@@ -46,6 +46,12 @@ class TelemetryEvent:
     session_id: str
     timestamp: datetime = field(default_factory=_utcnow)
     agent_name: str | None = None
+    # Human-readable description of the agent. Mirrors `agent_name`'s
+    # opt-in shape: derived from ``options.agent_description`` (set via
+    # setattr by the caller) and propagated through the same event path.
+    # ``None`` when the caller doesn't supply one — sinks fall back to an
+    # empty string in the registry doc.
+    agent_description: str | None = None
     payload: dict[str, Any] = field(default_factory=dict)
     raw: Any = None
 
@@ -60,6 +66,7 @@ class TelemetryEvent:
         *,
         session_id: str,
         agent_name: str | None,
+        agent_description: str | None = None,
         options: Any,
         prompt: Any,
     ) -> TelemetryEvent:
@@ -86,6 +93,7 @@ class TelemetryEvent:
             kind="session_started",
             session_id=session_id,
             agent_name=agent_name,
+            agent_description=agent_description,
             payload=payload,
             raw=options,
         )

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/src/computeragent/telemetry/sinks/agentos.py

@@ -151,6 +151,7 @@ class AgentRegistrySink:
 
     async def _upsert_registry(self, event: TelemetryEvent) -> None:
         name = event.agent_name or _agent_name_from_event(event)
+        description = event.agent_description or ""
         now = _utcnow()
         await self._registry.update_one(
             {"_id": name},
@@ -161,8 +162,12 @@ class AgentRegistrySink:
                 },
                 "$set": {
                     "harness": "claude-agent-sdk",
-                    "source": _inline_source_for(name, event.payload),
+                    # `source.manifest` carries the description too so any
+                    # downstream consumer that reads the inline manifest
+                    # gets the same value as the top-level `description`.
+                    "source": _inline_source_for(name, event.payload, description),
                     "model": event.payload.get("model"),
+                    "description": description,
                     "registeredBy": self._registered_by,
                     "updatedAt": now,
                     "lastSeen": now,
@@ -359,7 +364,11 @@ DEFAULT_AGENT_INSTRUCTIONS = (
 )
 
 
-def _inline_source_for(name: str, options_payload: dict[str, Any]) -> dict[str, Any]:
+def _inline_source_for(
+    name: str,
+    options_payload: dict[str, Any],
+    description: str = "",
+) -> dict[str, Any]:
     """Build a complete inline ``IdentitySource`` the harness can clone into a
     sandbox workdir for live chat.
 
@@ -386,11 +395,16 @@ def _inline_source_for(name: str, options_payload: dict[str, Any]) -> dict[str,
         allowed_tools=allowed_tools,
         max_turns=max_turns,
         permission_mode=permission_mode,
+        description=description,
     )
 
+    manifest: dict[str, Any] = {"name": name, "version": "0.1.0"}
+    if description:
+        manifest["description"] = description
+
     return {
         "type": "inline",
-        "manifest": {"name": name, "version": "0.1.0"},
+        "manifest": manifest,
         "model": model,
         "files": {
             "agent.yaml": agent_yaml,
@@ -406,6 +420,7 @@ def _build_agent_yaml(
     allowed_tools: list[str],
     max_turns: int | None,
     permission_mode: str,
+    description: str = "",
 ) -> str:
     """Render the agent.yaml the harness's inline loader expects.
 
@@ -419,6 +434,8 @@ def _build_agent_yaml(
         f"name: {safe_name}",
         "version: 0.1.0",
     ]
+    if description:
+        lines.append(f"description: {_yaml_str(description)}")
     if model:
         lines += [
             "model:",

{computer_agent_py-0.1.0 → computer_agent_py-0.1.3}/src/computeragent/telemetry/sinks/otel.py

@@ -22,7 +22,8 @@ from __future__ import annotations
 
 import contextlib
 import logging
-from typing import TYPE_CHECKING, Any
+import os
+from typing import TYPE_CHECKING, Any, Literal
 
 try:
     from opentelemetry import metrics, trace  # noqa: F401 - probe imports only
@@ -33,7 +34,26 @@ try:
         OTLPSpanExporter as HttpSpanExporter,
     )
     from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics._internal.instrument import (
+        Counter as _SDKCounter,
+    )
+    from opentelemetry.sdk.metrics._internal.instrument import (
+        Histogram as _SDKHistogram,
+    )
+    from opentelemetry.sdk.metrics._internal.instrument import (
+        ObservableCounter as _SDKObservableCounter,
+    )
+    from opentelemetry.sdk.metrics._internal.instrument import (
+        ObservableGauge as _SDKObservableGauge,
+    )
+    from opentelemetry.sdk.metrics._internal.instrument import (
+        ObservableUpDownCounter as _SDKObservableUpDownCounter,
+    )
+    from opentelemetry.sdk.metrics._internal.instrument import (
+        UpDownCounter as _SDKUpDownCounter,
+    )
     from opentelemetry.sdk.metrics.export import (
+        AggregationTemporality,
         ConsoleMetricExporter,
         PeriodicExportingMetricReader,
     )
@@ -49,6 +69,8 @@ except ImportError as _exc:  # pragma: no cover - guarded by lazy export
         "OtelSink requires the [otel] extra. Install with: pip install 'computer-agent-py[otel]'"
     ) from _exc
 
+Temporality = Literal["delta", "cumulative"]
+
 if TYPE_CHECKING:
     from opentelemetry.trace import Span
 
@@ -62,6 +84,7 @@ logger = logging.getLogger("computeragent.telemetry")
 # constants for these keys move between alpha versions; literals are safer.
 GEN_AI_SYSTEM = "gen_ai.system"
 GEN_AI_AGENT_NAME = "gen_ai.agent.name"
+GEN_AI_AGENT_DESCRIPTION = "gen_ai.agent.description"
 GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"
 GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
 GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
@@ -93,19 +116,61 @@ class OtelSink:
         exporter: str | None = None,
         endpoint: str | None = None,
         headers: dict[str, str] | None = None,
+        temporality: Temporality | None = None,
         tracer_provider: Any | None = None,
         meter_provider: Any | None = None,
     ) -> None:
-        # Read effective config from the module-level resolver if no overrides.
+        # Resolve effective config. The user pattern is
+        # ``configure(sinks=[OtelSink(), ...])``: Python builds the sinks list
+        # (running this __init__) BEFORE configure() populates _CONFIG, so
+        # falling back through cfg alone misses env vars. Resolution order:
+        # explicit kwarg → configure()'d _CONFIG → env var → final default.
         from ..config import get_config
 
         cfg = get_config()
-        self._service_name = service_name or cfg.get("service_name") or "computeragent"
-        self._exporter = (
-            exporter or cfg.get("exporter") or _infer_exporter(endpoint or cfg.get("endpoint"))
+        self._service_name = (
+            service_name
+            or cfg.get("service_name")
+            or os.environ.get("OTEL_SERVICE_NAME")
+            or "computeragent"
+        )
+        self._endpoint = (
+            endpoint or cfg.get("endpoint") or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+        )
+        if headers is not None:
+            self._headers: dict[str, str] = headers
+        elif cfg.get("headers"):
+            self._headers = cfg["headers"]
+        else:
+            self._headers = _parse_otlp_headers_env(os.environ.get("OTEL_EXPORTER_OTLP_HEADERS"))
+        self._exporter = exporter or cfg.get("exporter") or _infer_exporter(self._endpoint)
+        self._temporality: Temporality = _resolve_temporality(temporality or cfg.get("temporality"))
+
+        # Content capture — opt-in. When on, the sink writes prompt /
+        # completion / tool input / tool output to spans per the GenAI
+        # semconv. Middleware (PiiRedactor, GuardrailFilter) has already
+        # mutated the payload by this point, so what lands on spans is the
+        # redacted projection — never raw content from the agent stream.
+        self._capture_content = bool(
+            cfg.get("capture_content")
+            if "capture_content" in cfg
+            else _env_bool("COMPUTERAGENT_CAPTURE_CONTENT", False)
         )
-        self._endpoint = endpoint or cfg.get("endpoint")
-        self._headers = headers or cfg.get("headers") or {}
+        mode = cfg.get("capture_content_mode") or os.environ.get(
+            "COMPUTERAGENT_CAPTURE_CONTENT_MODE", "events"
+        )
+        if mode not in ("attributes", "events", "both"):
+            mode = "events"
+        self._capture_mode: str = mode
+        # Cap attribute size so a runaway prompt doesn't blow OTLP packet
+        # limits. Honors the same env that GuardrailFilter consumes.
+        try:
+            self._max_attr_length = int(
+                cfg.get("max_attribute_length")
+                or os.environ.get("COMPUTERAGENT_MAX_ATTRIBUTE_LENGTH", "8192")
+            )
+        except (TypeError, ValueError):
+            self._max_attr_length = 8192
 
         self._tracer_provider = tracer_provider or _build_tracer_provider(
             service_name=self._service_name,
@@ -118,6 +183,7 @@ class OtelSink:
             exporter=self._exporter,
             endpoint=self._endpoint,
             headers=self._headers,
+            temporality=self._temporality,
         )
         self._tracer = self._tracer_provider.get_tracer("computeragent")
         self._meter = self._meter_provider.get_meter("computeragent")
@@ -171,37 +237,148 @@ class OtelSink:
 
     # ── handlers (one per event kind) --------------------------------------
 
+    def _emit_content(
+        self,
+        span: Any,
+        role: str,
+        content: str,
+        attr_prefix: str,
+        event_name: str,
+    ) -> None:
+        """Write content to ``span`` per ``capture_content_mode``.
+
+        * ``attributes`` — ``<attr_prefix>.role`` + ``<attr_prefix>.content``
+          per the GenAI semconv 1.27 ``gen_ai.prompt.{i}.*`` / ``gen_ai.completion.{i}.*``
+          pattern. Easy to query in NRQL, lossy beyond ~32 KB.
+        * ``events`` — ``span.add_event(event_name, {role, content})``.
+          Preserves multi-message history without overwriting prior attrs.
+        * ``both`` — write both shapes. Useful while migrating backends.
+
+        Content is truncated to ``max_attribute_length`` chars to stay
+        under OTLP per-attribute limits. The middleware
+        (``PiiRedactor`` / ``GuardrailFilter``) has already mutated the
+        payload by this point, so the redacted projection is what lands.
+        """
+        if not self._capture_content or not content:
+            return
+        text = (
+            content
+            if len(content) <= self._max_attr_length
+            else (content[: self._max_attr_length - 14] + "...[truncated]")
+        )
+        if self._capture_mode in ("attributes", "both"):
+            span.set_attribute(f"{attr_prefix}.role", role)
+            span.set_attribute(f"{attr_prefix}.content", text)
+        if self._capture_mode in ("events", "both"):
+            try:
+                span.add_event(event_name, attributes={"role": role, "content": text})
+            except Exception:  # noqa: BLE001 — never break a session for an event-emit
+                logger.debug("add_event(%s) failed", event_name, exc_info=True)
+
+    def _parent_ctx(self, session_id: str) -> Any:
+        """Build an OTel Context pinned to the active invoke_agent span so
+        child spans (chat / execute_tool / policy_decision) nest correctly.
+
+        ``invoke_agent`` is created via ``start_span`` (not
+        ``start_as_current_span``) because its lifetime spans many event
+        handler calls — we can't hold a ``with`` block across them. The
+        trade-off is that the span is never the "current" span by default, so
+        children would orphan into new traces unless we re-pin context here.
+        """
+        parent = self._invoke_spans.get(session_id)
+        if parent is None:
+            return None
+        return trace.set_span_in_context(parent)
+
     def _on_session_started(self, event: TelemetryEvent) -> None:
         span = self._tracer.start_span(name=f"invoke_agent {event.agent_name or 'agent'}")
         span.set_attribute(GEN_AI_SYSTEM, "claude-agent-sdk")
         if event.agent_name:
             span.set_attribute(GEN_AI_AGENT_NAME, event.agent_name)
+        if event.agent_description:
+            span.set_attribute(GEN_AI_AGENT_DESCRIPTION, event.agent_description)
         span.set_attribute(GEN_AI_CONVERSATION_ID, event.session_id)
         span.set_attribute(GEN_AI_OPERATION_NAME, "invoke_agent")
         if event.payload.get("model"):
             span.set_attribute(GEN_AI_REQUEST_MODEL, str(event.payload["model"]))
+        # Content capture — system prompt + initial user prompt, both on the
+        # invoke_agent root so a single span query surfaces what the agent
+        # was asked to do.
+        system_prompt = event.payload.get("system_prompt")
+        if isinstance(system_prompt, str) and system_prompt:
+            self._emit_content(
+                span,
+                "system",
+                system_prompt,
+                "gen_ai.prompt.0",
+                "gen_ai.system.message",
+            )
+        prompt = event.payload.get("prompt")
+        if isinstance(prompt, str) and prompt and prompt != "<streaming>":
+            # When the caller streams the prompt (AsyncIterable), the proxy
+            # writes the sentinel "<streaming>" instead of the body — skip
+            # capture in that case because there's nothing to record yet.
+            self._emit_content(
+                span,
+                "user",
+                prompt,
+                "gen_ai.prompt.1",
+                "gen_ai.user.message",
+            )
         self._invoke_spans[event.session_id] = span
 
     def _on_assistant_message(self, event: TelemetryEvent) -> None:
         # Open or reuse a chat span; spec models chat as one span per LLM call,
         # but the upstream stream gives us one AssistantMessage per LLM call,
         # so open/close per event.
-        chat = self._tracer.start_span(name=f"chat {event.payload.get('model') or 'unknown'}")
+        chat = self._tracer.start_span(
+            name=f"chat {event.payload.get('model') or 'unknown'}",
+            context=self._parent_ctx(event.session_id),
+        )
         chat.set_attribute(GEN_AI_OPERATION_NAME, "chat")
         if event.payload.get("model"):
             chat.set_attribute(GEN_AI_REQUEST_MODEL, str(event.payload["model"]))
         chat.set_attribute(GEN_AI_CONVERSATION_ID, event.session_id)
+        text = event.payload.get("text")
+        if isinstance(text, str) and text:
+            self._emit_content(
+                chat,
+                "assistant",
+                text,
+                "gen_ai.completion.0",
+                "gen_ai.assistant.message",
+            )
         chat.end()
 
     def _on_tool_use(self, event: TelemetryEvent) -> None:
         tool_name = str(event.payload.get("tool_name") or "tool")
-        span = self._tracer.start_span(name=f"execute_tool {tool_name}")
+        span = self._tracer.start_span(
+            name=f"execute_tool {tool_name}",
+            context=self._parent_ctx(event.session_id),
+        )
         span.set_attribute(GEN_AI_OPERATION_NAME, "execute_tool")
         span.set_attribute(GEN_AI_TOOL_NAME, tool_name)
         call_id = str(event.payload.get("tool_use_id") or "")
         if call_id:
             span.set_attribute(GEN_AI_TOOL_CALL_ID, call_id)
         span.set_attribute(GEN_AI_CONVERSATION_ID, event.session_id)
+        # Tool arguments — JSON-encoded so multi-key inputs survive the
+        # attribute-string projection.
+        tool_input = event.payload.get("tool_input")
+        if isinstance(tool_input, dict) and tool_input:
+            import json
+
+            try:
+                serialised = json.dumps(tool_input, default=str)
+            except (TypeError, ValueError):
+                serialised = str(tool_input)
+            self._emit_content(
+                span,
+                "tool",
+                serialised,
+                "gen_ai.tool.call.arguments",
+                "gen_ai.tool.call.start",
+            )
         self._tool_spans.setdefault(event.session_id, {})[call_id] = span
 
     def _on_tool_result(self, event: TelemetryEvent) -> None:
@@ -211,6 +388,27 @@ class OtelSink:
             return
         if event.payload.get("is_error"):
             span.set_attribute("error.type", "tool_error")
+        # Tool output — agent-readable text projection. The block may be a
+        # str OR a list[dict] (Anthropic tool-result content blocks); we
+        # serialise dicts to JSON, leave strings alone.
+        content = event.payload.get("content")
+        if content:
+            if isinstance(content, str):
+                serialised = content
+            else:
+                import json
+
+                try:
+                    serialised = json.dumps(content, default=str)
+                except (TypeError, ValueError):
+                    serialised = str(content)
+            self._emit_content(
+                span,
+                "tool",
+                serialised,
+                "gen_ai.tool.call.result",
+                "gen_ai.tool.call.end",
+            )
         span.end()
 
     def _on_usage_snapshot(self, event: TelemetryEvent) -> None:
@@ -269,6 +467,18 @@ class OtelSink:
             v = usage.get(key)
             if isinstance(v, int):
                 invoke.set_attribute(attr, v)
+        # Final answer — surface the ResultMessage.result (or last assistant
+        # text fallback) on the invoke_agent root so a single span query
+        # returns the agent's response.
+        result_text = event.payload.get("result")
+        if isinstance(result_text, str) and result_text:
+            self._emit_content(
+                invoke,
+                "assistant",
+                result_text,
+                "gen_ai.completion.final",
+                "gen_ai.assistant.message",
+            )
         invoke.end()
         duration_s = float(event.payload.get("duration_ms", 0.0) or 0.0) / 1000.0
         if duration_s > 0:
@@ -341,6 +551,78 @@ def _infer_exporter(endpoint: str | None) -> str:
     return "otlp-http" if endpoint else "console"
 
 
+def _signal_url(endpoint: str | None, signal: str) -> str | None:
+    """Append ``/v1/<signal>`` if ``endpoint`` looks like a base URL.
+
+    OTLP HTTP exporters treat a non-None ``endpoint`` constructor arg as the
+    full URL — no automatic path appending — so passing the documented base
+    URL (e.g. New Relic's ``https://otlp.nr-data.net``) produces 404s. When
+    the caller has already supplied a signal-specific URL, return it
+    unchanged so we never double-append.
+    """
+    if endpoint is None:
+        return None
+    e = endpoint.rstrip("/")
+    if any(e.endswith(suffix) for suffix in ("/v1/traces", "/v1/metrics", "/v1/logs")):
+        return endpoint
+    return f"{e}/v1/{signal}"
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _parse_otlp_headers_env(raw: str | None) -> dict[str, str]:
+    """Parse ``OTEL_EXPORTER_OTLP_HEADERS`` per the OTel env-spec format.
+
+    Comma-separated ``key=value`` pairs; whitespace around either side is
+    stripped. Lines without an ``=`` are dropped silently.
+    """
+    if not raw:
+        return {}
+    out: dict[str, str] = {}
+    for pair in raw.split(","):
+        if "=" not in pair:
+            continue
+        k, _, v = pair.partition("=")
+        k = k.strip()
+        v = v.strip()
+        if k:
+            out[k] = v
+    return out
+
+
+_VALID_TEMPORALITIES: frozenset[str] = frozenset(("delta", "cumulative"))
+
+
+def _resolve_temporality(value: Temporality | str | None) -> Temporality:
+    """Pick a temporality, falling back through env then to the default.
+
+    Default is ``"delta"`` because every major SaaS OTLP intake (New Relic,
+    Datadog direct, Honeycomb) requires delta for histograms — cumulative
+    silently ingests but renders as zero. Users running their own collector
+    can opt into cumulative.
+    """
+    candidate = value or os.environ.get("COMPUTERAGENT_OTEL_TEMPORALITY") or "delta"
+    if candidate not in _VALID_TEMPORALITIES:
+        return "delta"
+    return candidate  # type: ignore[return-value]
+
+
+def _delta_temporality_map() -> dict[Any, AggregationTemporality]:
+    return {
+        _SDKCounter: AggregationTemporality.DELTA,
+        _SDKUpDownCounter: AggregationTemporality.DELTA,
+        _SDKHistogram: AggregationTemporality.DELTA,
+        _SDKObservableCounter: AggregationTemporality.DELTA,
+        _SDKObservableUpDownCounter: AggregationTemporality.DELTA,
+        _SDKObservableGauge: AggregationTemporality.DELTA,
+    }
+
+
 def _build_tracer_provider(
     *,
     service_name: str,
@@ -351,7 +633,10 @@ def _build_tracer_provider(
     resource = Resource.create({"service.name": service_name})
     provider = TracerProvider(resource=resource)
     if exporter == "otlp-http":
-        span_exporter = HttpSpanExporter(endpoint=endpoint, headers=headers or None)
+        span_exporter = HttpSpanExporter(
+            endpoint=_signal_url(endpoint, "traces"),
+            headers=headers or None,
+        )
         provider.add_span_processor(BatchSpanProcessor(span_exporter))
     else:
         provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
@@ -364,11 +649,18 @@ def _build_meter_provider(
     exporter: str,
     endpoint: str | None,
     headers: dict[str, str],
+    temporality: Temporality = "delta",
 ) -> MeterProvider:
     resource = Resource.create({"service.name": service_name})
     metric_exporter: Any
     if exporter == "otlp-http":
-        metric_exporter = HttpMetricExporter(endpoint=endpoint, headers=headers or None)
+        kwargs: dict[str, Any] = {
+            "endpoint": _signal_url(endpoint, "metrics"),
+            "headers": headers or None,
+        }
+        if temporality == "delta":
+            kwargs["preferred_temporality"] = _delta_temporality_map()
+        metric_exporter = HttpMetricExporter(**kwargs)
     else:
         metric_exporter = ConsoleMetricExporter()
     reader = PeriodicExportingMetricReader(metric_exporter, export_interval_millis=5000)