@agentikos/omega-os 0.2.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/managed_agent.py

@@ -0,0 +1,467 @@
+"""Anthropic Managed Agents — provider + client.
+
+What this is
+------------
+
+Wraps Anthropic's Managed Agents beta API (``/v1/agents``,
+``/v1/environments``, ``/v1/sessions``, SSE event stream) so OmegaOS can
+dispatch missions to Anthropic's server-side agent runtime instead of —
+or alongside — the local ``claude`` CLI.
+
+Three resources, in order
+-------------------------
+
+  1. **Agent** — reusable template: model + system + tools. Created once,
+     referenced by ``agent_id`` across many sessions.
+  2. **Environment** — sandbox config: ``cloud`` (Anthropic-managed
+     container) or ``self_hosted`` (your infra). Also reusable.
+  3. **Session** — a running agent instance inside an environment. You
+     send ``user.message`` events into it and stream
+     ``agent.message`` / ``agent.tool_use`` / ``session.status_idle``
+     events back.
+
+This module ships:
+
+  * :class:`ManagedAgentClient` — thin REST wrapper (zero deps beyond
+    stdlib). Send events, list resources, stream via SSE.
+  * :class:`ManagedAgentProvider` — implements the OmegaOS
+    ``AgentProvider`` contract so it slots into ``ModelRouter`` next to
+    ``ClaudeMaxProvider``.
+  * Persistent ID cache at
+    ``$OMEGA_HOME/Agentik_Runtime/managed_agents.json`` so we don't
+    re-create the agent + environment on every call (~250 ms saved per
+    request).
+
+When to use this vs. ClaudeMaxProvider
+--------------------------------------
+
+  ClaudeMaxProvider   = local ``claude -p`` subprocess, Max OAuth, $0 per
+                         call beyond the $200/month cap, requires tmux.
+  ManagedAgentProvider = Anthropic-managed sandbox, API key required,
+                         per-token billing, persistent sessions,
+                         long-running async work, no local subprocess.
+
+Default routing stays on ``claude-max`` to honour OmegaOS's "no API key
+burn" principle. Opt-in via:
+
+  * ``ANTHROPIC_API_KEY`` env var (the provider is added to the router
+    when ``ModelRouter.auto()`` sees it, but Max stays default).
+  * Explicit topology entry: ``role_provider: {worker: claude-managed-agent}``.
+
+Beta header
+-----------
+
+All requests carry ``anthropic-beta: managed-agents-2026-04-01``. The
+constant is exposed as :data:`MANAGED_AGENTS_BETA` so callers can override
+when Anthropic bumps it.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator
+
+
+MANAGED_AGENTS_BETA = "managed-agents-2026-04-01"
+ANTHROPIC_VERSION = "2023-06-01"
+_BASE_URL = "https://api.anthropic.com/v1"
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class ManagedAgentError(RuntimeError):
+    """Raised by the client when the API returns a non-2xx response."""
+
+
+# ---------------------------------------------------------------------------
+# REST client (stdlib-only)
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ManagedAgentClient:
+    api_key: str
+    timeout_s: int = 60
+    beta: str = MANAGED_AGENTS_BETA
+
+    def _headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        h = {
+            "x-api-key": self.api_key,
+            "anthropic-version": ANTHROPIC_VERSION,
+            "anthropic-beta": self.beta,
+            "content-type": "application/json",
+        }
+        if extra:
+            h.update(extra)
+        return h
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+        *,
+        accept: str = "application/json",
+        timeout: int | None = None,
+    ) -> Any:
+        url = f"{_BASE_URL}{path}"
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data, method=method,
+            headers=self._headers({"Accept": accept}),
+        )
+        try:
+            with urllib.request.urlopen(  # noqa: S310
+                req, timeout=timeout or self.timeout_s,
+            ) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:400]
+            raise ManagedAgentError(
+                f"{method} {path} → HTTP {exc.code}: {detail}"
+            ) from exc
+        except (OSError, urllib.error.URLError) as exc:
+            raise ManagedAgentError(
+                f"{method} {path} → network: {exc}"
+            ) from exc
+        if not raw:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            return raw
+
+    # ----- Agents ---------------------------------------------------------
+
+    def create_agent(
+        self,
+        *,
+        name: str,
+        model: str = "claude-opus-4-7",
+        system: str = "",
+        tools: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        tools = tools if tools is not None else [{"type": "agent_toolset_20260401"}]
+        body: dict[str, Any] = {"name": name, "model": model, "tools": tools}
+        if system:
+            body["system"] = system
+        return self._request("POST", "/agents", body)
+
+    def get_agent(self, agent_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/agents/{agent_id}")
+
+    def list_agents(self, *, limit: int = 20) -> dict[str, Any]:
+        return self._request("GET", f"/agents?limit={limit}")
+
+    def delete_agent(self, agent_id: str) -> dict[str, Any] | None:
+        return self._request("DELETE", f"/agents/{agent_id}")
+
+    # ----- Environments ---------------------------------------------------
+
+    def create_environment(
+        self,
+        *,
+        name: str,
+        config: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        config = config or {
+            "type": "cloud",
+            "networking": {"type": "unrestricted"},
+        }
+        return self._request(
+            "POST", "/environments", {"name": name, "config": config},
+        )
+
+    def get_environment(self, env_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/environments/{env_id}")
+
+    def list_environments(self, *, limit: int = 20) -> dict[str, Any]:
+        return self._request("GET", f"/environments?limit={limit}")
+
+    def delete_environment(self, env_id: str) -> dict[str, Any] | None:
+        return self._request("DELETE", f"/environments/{env_id}")
+
+    # ----- Sessions -------------------------------------------------------
+
+    def create_session(
+        self,
+        *,
+        agent_id: str,
+        environment_id: str,
+        title: str = "",
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "agent": agent_id,
+            "environment_id": environment_id,
+        }
+        if title:
+            body["title"] = title
+        return self._request("POST", "/sessions", body)
+
+    def get_session(self, session_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/sessions/{session_id}")
+
+    def list_sessions(self, *, limit: int = 20) -> dict[str, Any]:
+        return self._request("GET", f"/sessions?limit={limit}")
+
+    def delete_session(self, session_id: str) -> dict[str, Any] | None:
+        return self._request("DELETE", f"/sessions/{session_id}")
+
+    def send_event(
+        self,
+        session_id: str,
+        events: list[dict[str, Any]],
+    ) -> Any:
+        return self._request(
+            "POST", f"/sessions/{session_id}/events",
+            {"events": events},
+        )
+
+    def send_user_message(self, session_id: str, text: str) -> Any:
+        """Convenience wrapper for the most common event shape."""
+        return self.send_event(session_id, [{
+            "type": "user.message",
+            "content": [{"type": "text", "text": text}],
+        }])
+
+    def stream_events(
+        self,
+        session_id: str,
+        *,
+        stop_on_idle: bool = True,
+        timeout_s: int = 600,
+    ) -> Iterator[dict[str, Any]]:
+        """Open the SSE stream + yield parsed event dicts.
+
+        Stops at the first ``session.status_idle`` when
+        ``stop_on_idle=True`` (the natural "agent is done" boundary).
+        """
+        url = f"{_BASE_URL}/sessions/{session_id}/stream"
+        req = urllib.request.Request(
+            url, headers=self._headers({"Accept": "text/event-stream"}),
+        )
+        try:
+            resp = urllib.request.urlopen(req, timeout=timeout_s)  # noqa: S310
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[:400]
+            raise ManagedAgentError(
+                f"stream HTTP {exc.code}: {detail}"
+            ) from exc
+        try:
+            for line_bytes in resp:
+                line = line_bytes.decode("utf-8", errors="replace").strip()
+                if not line.startswith("data:"):
+                    continue
+                payload = line[len("data:"):].strip()
+                if not payload:
+                    continue
+                try:
+                    event = json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+                yield event
+                if stop_on_idle and event.get("type") == "session.status_idle":
+                    return
+        finally:
+            try:
+                resp.close()
+            except OSError:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Persistent ID cache — don't re-create the agent/env on every call
+# ---------------------------------------------------------------------------
+
+
+def _cache_path(home: Path) -> Path:
+    return home / "Agentik_Runtime" / "managed_agents.json"
+
+
+@dataclass
+class ManagedAgentCache:
+    """Atomic JSON file keyed by ``(agent_name, env_name)``."""
+
+    home: Path
+
+    def _load(self) -> dict[str, Any]:
+        p = _cache_path(self.home)
+        if not p.exists():
+            return {"agents": {}, "environments": {}}
+        try:
+            return json.loads(p.read_text())
+        except (OSError, json.JSONDecodeError):
+            return {"agents": {}, "environments": {}}
+
+    def _save(self, data: dict[str, Any]) -> None:
+        import threading
+        p = _cache_path(self.home)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(
+            p.suffix + f".tmp.{os.getpid()}.{threading.get_ident()}"
+        )
+        tmp.write_text(json.dumps(data, indent=2))
+        os.replace(tmp, p)
+
+    def get_agent(self, name: str) -> str | None:
+        return self._load()["agents"].get(name)
+
+    def get_environment(self, name: str) -> str | None:
+        return self._load()["environments"].get(name)
+
+    def set_agent(self, name: str, agent_id: str) -> None:
+        d = self._load()
+        d["agents"][name] = agent_id
+        self._save(d)
+
+    def set_environment(self, name: str, env_id: str) -> None:
+        d = self._load()
+        d["environments"][name] = env_id
+        self._save(d)
+
+
+# ---------------------------------------------------------------------------
+# Provider — slot into OmegaOS's AgentProvider contract
+# ---------------------------------------------------------------------------
+
+
+class ManagedAgentProvider:
+    """Implements the OmegaOS ``AgentProvider`` protocol via Managed Agents.
+
+    Each ``run(req)`` call:
+
+      1. Resolves agent + environment IDs (from the cache; creates them
+         on first use).
+      2. Creates a fresh session for this request (sessions are stateful,
+         we want isolation per call).
+      3. Sends a single user.message with ``req.prompt`` as text.
+      4. Streams events until ``session.status_idle``.
+      5. Aggregates every ``agent.message`` text block into the result
+         and surfaces tool-use names in ``artifacts.tool_uses``.
+
+    The cost of a request lives in ``artifacts.usage`` when the API
+    returns it (it's per-organization billed, not per-request, so we
+    surface what we can but don't claim a per-call USD figure).
+    """
+
+    id = "claude-managed-agent"
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        agent_name: str = "omega-default-agent",
+        env_name: str = "omega-default-env",
+        model: str = "claude-opus-4-7",
+        system: str = "You are an Omega OS managed agent. Execute the user's intent and stop when done.",
+        omega_home: str | Path | None = None,
+        timeout_s: int = 600,
+    ) -> None:
+        self._api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+        if not self._api_key:
+            raise ValueError(
+                "ManagedAgentProvider requires ANTHROPIC_API_KEY "
+                "(or pass api_key=...)"
+            )
+        self._client = ManagedAgentClient(
+            api_key=self._api_key, timeout_s=timeout_s,
+        )
+        self._agent_name = agent_name
+        self._env_name = env_name
+        self._model = model
+        self._system = system
+        self._timeout_s = timeout_s
+        home = Path(omega_home or os.environ.get(
+            "OMEGA_HOME", str(Path.home() / "Omega")
+        ))
+        self._cache = ManagedAgentCache(home)
+
+    # ---- AgentProvider protocol ----
+
+    @staticmethod
+    def is_available() -> bool:
+        return bool(os.environ.get("ANTHROPIC_API_KEY"))
+
+    def _ensure_agent_and_env(self) -> tuple[str, str]:
+        agent_id = self._cache.get_agent(self._agent_name)
+        if not agent_id:
+            agent = self._client.create_agent(
+                name=self._agent_name,
+                model=self._model,
+                system=self._system,
+            )
+            agent_id = agent["id"]
+            self._cache.set_agent(self._agent_name, agent_id)
+
+        env_id = self._cache.get_environment(self._env_name)
+        if not env_id:
+            env = self._client.create_environment(name=self._env_name)
+            env_id = env["id"]
+            self._cache.set_environment(self._env_name, env_id)
+
+        return agent_id, env_id
+
+    def run(self, req):  # type: ignore[no-untyped-def]
+        """Implements AgentProvider.run — synchronous: create session,
+        send prompt, drain stream, return aggregated text."""
+        # Local import to avoid forcing the provider module to depend on
+        # the rest of the engine.
+        from omega_engine.provider import AgentResult
+
+        agent_id, env_id = self._ensure_agent_and_env()
+        session = self._client.create_session(
+            agent_id=agent_id, environment_id=env_id,
+            title=f"omega:{req.role}:{(req.context or {}).get('mission_id','')[:24]}",
+        )
+        session_id = session["id"]
+        prompt = req.prompt
+        if req.system:
+            # The session's system prompt was set at agent-creation time;
+            # we prepend any per-call system text into the user message
+            # so the agent still sees it. Cheap; works for the common
+            # "use these skills" preface.
+            prompt = f"[system] {req.system}\n\n{prompt}"
+        self._client.send_user_message(session_id, prompt)
+
+        text_chunks: list[str] = []
+        tool_uses: list[str] = []
+        for ev in self._client.stream_events(
+            session_id, timeout_s=self._timeout_s,
+        ):
+            t = ev.get("type")
+            if t == "agent.message":
+                for block in ev.get("content", []):
+                    if block.get("type") == "text":
+                        text_chunks.append(block.get("text", ""))
+            elif t == "agent.tool_use":
+                name = ev.get("name") or "?"
+                tool_uses.append(name)
+            elif t == "session.status_idle":
+                break
+
+        return AgentResult(
+            text="".join(text_chunks),
+            claimed_done=True,
+            plan=[],
+            artifacts={
+                "managed_agent": {
+                    "agent_id": agent_id,
+                    "environment_id": env_id,
+                    "session_id": session_id,
+                    "tool_uses": tool_uses,
+                },
+            },
+            usage={
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "cost_usd": 0.0,
+            },
+        )