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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: computer-agent-py
-Version: 0.1.1
+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

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

@@ -1,6 +1,6 @@
 [project]
 name = "computer-agent-py"
-version = "0.1.1"
+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.1 → 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.1 → 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.1 → 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.1 → 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.1 → computer_agent_py-0.1.3}/src/computeragent/telemetry/sinks/otel.py

@@ -84,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"
@@ -145,6 +146,32 @@ class OtelSink:
         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)
+        )
+        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,
             exporter=self._exporter,
@@ -210,6 +237,44 @@ 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.
@@ -230,10 +295,36 @@ class OtelSink:
         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:
@@ -248,6 +339,15 @@ class OtelSink:
         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:
@@ -262,6 +362,23 @@ class OtelSink:
         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:
@@ -271,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:
@@ -329,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:
@@ -418,6 +568,13 @@ def _signal_url(endpoint: str | None, signal: str) -> str | None:
     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.