agents28 0.1.0__py3-none-any.whl

agents28/__init__.py

@@ -0,0 +1,20 @@
+"""Agents28: see what every AI agent in your business is working on.
+
+Quick start::
+
+    import agents28
+
+    client = agents28.Agents28()  # reads AGENTS28_API_KEY and AGENTS28_BASE_URL
+
+    with client.run("Refund request review") as run:
+        run.message("user")
+        with run.tool("lookup_order"):
+            ...
+"""
+
+from ._run import Run, Step, current_run
+from ._sanitize import redact
+from ._version import __version__
+from .client import Agents28
+
+__all__ = ["Agents28", "Run", "Step", "current_run", "redact", "__version__"]

agents28/_delivery.py

@@ -0,0 +1,206 @@
+"""Background delivery of events, off the agent's critical path.
+
+Events go into a bounded in-memory queue and a daemon thread sends them in
+batches. The agent never waits for the network and never sees an exception:
+
+* A full queue drops the new event and counts it (``dropped``).
+* Network errors, ``429`` and ``5xx`` are retried with exponential backoff and
+  jitter; ``429`` honours the server's ``Retry-After``. Retrying is safe because
+  the API ignores an ``event_id`` it has already stored.
+* Other ``4xx`` answers are not retried: the batch is counted as ``failed`` and
+  the reason is kept in ``last_error``.
+* After ``os.fork()`` the child process starts its own queue and thread.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import queue
+import random
+import threading
+import time
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("agents28")
+
+MAX_BATCH_SIZE = 100  # API limit per request
+_BACKOFF_BASE_SECONDS = 0.5
+_BACKOFF_MAX_SECONDS = 8.0
+_RETRY_AFTER_MAX_SECONDS = 30.0
+
+
+def _backoff(attempt: int) -> float:
+    delay = min(_BACKOFF_MAX_SECONDS, _BACKOFF_BASE_SECONDS * (2.0**attempt))
+    return delay * (0.5 + random.random() / 2)  # full jitter, at least half
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    try:
+        seconds = float(response.headers.get("retry-after", ""))
+    except ValueError:
+        return None
+    return max(0.0, min(_RETRY_AFTER_MAX_SECONDS, seconds))
+
+
+class Delivery:
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str],
+        *,
+        timeout: float,
+        max_queue_size: int,
+        batch_size: int,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.url = url
+        self.headers = headers
+        self.timeout = timeout
+        self.max_queue_size = max(1, int(max_queue_size))
+        self.batch_size = max(1, min(MAX_BATCH_SIZE, int(batch_size)))
+        self.max_retries = max(0, int(max_retries))
+        self.transport = transport
+
+        self.delivered = 0
+        self.failed = 0
+        self.dropped = 0
+        self.last_error: str | None = None
+        self._counter_lock = threading.Lock()
+        self._warned: set[str] = set()
+        self._closed = False
+        self._start()
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def _start(self) -> None:
+        self._pid = os.getpid()
+        self._queue: queue.Queue[dict[str, Any]] = queue.Queue(
+            maxsize=self.max_queue_size
+        )
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run, daemon=True, name="agents28-delivery"
+        )
+        self._thread.start()
+
+    def _ensure_started(self) -> None:
+        if self._pid != os.getpid():
+            # Forked: the parent's thread does not exist in this process.
+            self._start()
+
+    def submit(self, event: dict[str, Any]) -> bool:
+        if self._closed:
+            self._count("dropped", 1)
+            return False
+        self._ensure_started()
+        try:
+            self._queue.put_nowait(event)
+            return True
+        except queue.Full:
+            self._count("dropped", 1)
+            self._warn_once(
+                "queue_full", "Event queue is full; new events are being dropped."
+            )
+            return False
+
+    def flush(self, timeout: float) -> bool:
+        deadline = time.monotonic() + max(0.0, timeout)
+        while self._queue.unfinished_tasks:
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.01)
+        return True
+
+    def close(self, timeout: float) -> bool:
+        if self._closed:
+            return True
+        completed = self.flush(timeout)
+        self._closed = True
+        self._stop.set()
+        self._thread.join(timeout=1)
+        return completed
+
+    @property
+    def queued(self) -> int:
+        return self._queue.unfinished_tasks
+
+    # -- worker --------------------------------------------------------------
+
+    def _run(self) -> None:
+        with httpx.Client(
+            timeout=self.timeout, headers=self.headers, transport=self.transport
+        ) as http:
+            while not self._stop.is_set() or not self._queue.empty():
+                try:
+                    first = self._queue.get(timeout=0.05)
+                except queue.Empty:
+                    continue
+                batch = [first]
+                while len(batch) < self.batch_size:
+                    try:
+                        batch.append(self._queue.get_nowait())
+                    except queue.Empty:
+                        break
+                try:
+                    ok = self._send(http, batch)
+                except Exception:  # never let the thread die
+                    logger.debug("Unexpected delivery error", exc_info=True)
+                    ok = False
+                finally:
+                    for _ in batch:
+                        self._queue.task_done()
+                self._count("delivered" if ok else "failed", len(batch))
+
+    def _send(self, http: httpx.Client, batch: list[dict[str, Any]]) -> bool:
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = http.post(self.url, json={"events": batch})
+            except httpx.HTTPError as error:
+                self.last_error = f"network: {type(error).__name__}"
+                wait = _backoff(attempt)
+            else:
+                status = response.status_code
+                if status == 202:
+                    return True
+                if status == 429:
+                    self.last_error = "rate_limited"
+                    wait = _retry_after(response) or _backoff(attempt)
+                elif status >= 500:
+                    self.last_error = f"server_error: {status}"
+                    wait = _backoff(attempt)
+                elif status in (401, 403):
+                    self.last_error = "api_key_rejected"
+                    self._warn_once(
+                        "auth",
+                        "The API key was rejected (HTTP %s); events are not stored.",
+                        status,
+                    )
+                    return False
+                else:
+                    self.last_error = f"rejected: {status}"
+                    self._warn_once(
+                        f"status_{status}",
+                        "Events were rejected by the API (HTTP %s).",
+                        status,
+                    )
+                    return False
+
+            if attempt < self.max_retries:
+                # Shutting down: retry right away instead of waiting.
+                self._stop.wait(wait)
+        return False
+
+    # -- helpers -------------------------------------------------------------
+
+    def _count(self, field: str, amount: int) -> None:
+        with self._counter_lock:
+            setattr(self, field, getattr(self, field) + amount)
+
+    def _warn_once(self, key: str, message: str, *args: object) -> None:
+        if key not in self._warned:
+            self._warned.add(key)
+            logger.warning("Agents28: " + message, *args)

agents28/_run.py

@@ -0,0 +1,194 @@
+"""Runs: one unit of agent work, from start to finish."""
+
+from __future__ import annotations
+
+import contextvars
+import time
+import uuid
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+from . import _sanitize as clean
+
+if TYPE_CHECKING:
+    from .client import Agents28
+
+_current: contextvars.ContextVar[Run | None] = contextvars.ContextVar(
+    "agents28_current_run", default=None
+)
+
+
+def current_run() -> Run | None:
+    """The run active in this thread or task, or None outside a run."""
+    return _current.get()
+
+
+def _elapsed_ms(started: float) -> int:
+    return clean.duration_ms((time.perf_counter() - started) * 1000)
+
+
+class Run:
+    """One unit of work. Use it as a context manager::
+
+        with client.run(task_title="Refund request review") as run:
+            run.message("user")
+            with run.tool("lookup_order"):
+                ...
+
+    On exit the run is reported completed with its duration, or failed with
+    the exception's class name if one escaped (the exception is re-raised).
+    """
+
+    def __init__(
+        self,
+        client: Agents28,
+        *,
+        task_title: str | None = None,
+        task_type: str | None = None,
+        conversation_id: str | None = None,
+        run_id: str | None = None,
+    ) -> None:
+        self._client = client
+        self.run_id = clean.identifier(run_id) or uuid.uuid4().hex
+        self.conversation_id = clean.identifier(conversation_id) or self.run_id
+        self.task_title = task_title
+        self.task_type = task_type
+        self._started_at: float | None = None
+        self._finished = False
+        self._token: contextvars.Token[Run | None] | None = None
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def start(self) -> Run:
+        if self._started_at is None:
+            self._started_at = time.perf_counter()
+            self._client.run_started(
+                self.conversation_id,
+                self.run_id,
+                task_title=self.task_title,
+                task_type=self.task_type,
+            )
+        return self
+
+    def complete(self) -> None:
+        """Report the run completed. Called for you by the context manager."""
+        if self._finish():
+            self._client.run_completed(
+                self.conversation_id, self.run_id, self._duration()
+            )
+
+    def fail(self, error_type: str = "error") -> None:
+        """Report the run failed, e.g. ``run.fail("PolicyViolation")``."""
+        if self._finish():
+            self._client.run_failed(self.conversation_id, self.run_id, error_type)
+
+    def _finish(self) -> bool:
+        if self._finished:
+            return False
+        self.start()
+        self._finished = True
+        return True
+
+    def _duration(self) -> int:
+        return _elapsed_ms(self._started_at) if self._started_at is not None else 0
+
+    def __enter__(self) -> Run:
+        self.start()
+        self._token = _current.set(self)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._token is not None:
+            _current.reset(self._token)
+            self._token = None
+        if exc_type is None:
+            self.complete()
+        else:
+            self.fail(exc_type.__name__)
+
+    # -- events --------------------------------------------------------------
+
+    def message(self, role: str, content: str | None = None) -> bool:
+        """Record a message. Content is sent only with ``capture_content=True``."""
+        return self._client.message(self.conversation_id, self.run_id, role, content)
+
+    def tool_completed(
+        self,
+        name: str,
+        success: bool = True,
+        duration_ms: float = 0,
+        result_summary: str | None = None,
+    ) -> bool:
+        return self._client.tool_completed(
+            self.conversation_id,
+            self.run_id,
+            name,
+            success,
+            duration_ms,
+            result_summary,
+        )
+
+    def action_completed(
+        self,
+        name: str,
+        action_type: str = "other",
+        success: bool = True,
+        duration_ms: float = 0,
+        result_summary: str | None = None,
+    ) -> bool:
+        return self._client.action_completed(
+            self.conversation_id,
+            self.run_id,
+            action_type,
+            name,
+            success,
+            duration_ms,
+            result_summary,
+        )
+
+    def tool(self, name: str) -> Step:
+        """Time a tool call; success is False if an exception escapes."""
+        return Step(self, "tool", name)
+
+    def action(self, name: str, action_type: str = "other") -> Step:
+        """Time a business action, e.g. ``run.action("issue_refund", "business_operation")``."""
+        return Step(self, "action", name, action_type)
+
+
+class Step:
+    """A timed tool call or action inside a run. Set ``result_summary`` if useful."""
+
+    def __init__(
+        self, run: Run, kind: str, name: str, action_type: str = "other"
+    ) -> None:
+        self._run = run
+        self._kind = kind
+        self.name = name
+        self.action_type = action_type
+        self.result_summary: str | None = None
+        self.success: bool | None = None
+        self._started_at = 0.0
+
+    def __enter__(self) -> Step:
+        self._started_at = time.perf_counter()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        success = (exc_type is None) if self.success is None else bool(self.success)
+        duration = _elapsed_ms(self._started_at)
+        if self._kind == "tool":
+            self._run.tool_completed(self.name, success, duration, self.result_summary)
+        else:
+            self._run.action_completed(
+                self.name, self.action_type, success, duration, self.result_summary
+            )

agents28/_sanitize.py

@@ -0,0 +1,102 @@
+"""Make every value safe to send and valid for the Agents28 API.
+
+The API validates each event strictly and rejects a whole batch when one event
+is invalid, so the SDK fixes or drops bad values here instead. Nothing in this
+module raises on bad input.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Limits enforced by the Agents28 API (POST /v1/events/batch).
+ID_MAX_LENGTH = 100
+NAME_MAX_LENGTH = 100
+AGENT_VERSION_MAX_LENGTH = 64
+TASK_TITLE_MAX_LENGTH = 120
+TASK_TYPE_MAX_LENGTH = 64
+CONTENT_MAX_LENGTH = 10_000
+SUMMARY_MAX_LENGTH = 4_000
+DURATION_MAX_MS = 3_600_000
+ROLES = frozenset({"user", "assistant", "system", "tool"})
+ACTION_TYPES = frozenset({"api_call", "business_operation", "handoff", "other"})
+
+_ID_INVALID = re.compile(r"[^A-Za-z0-9_-]+")
+_NAME_INVALID = re.compile(r"[^A-Za-z0-9_.-]+")
+_TASK_TYPE = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]+")
+
+_REDACTIONS = (
+    # Our own API keys, OpenAI-style keys and AWS access key ids.
+    (re.compile(r"\back_[A-Za-z0-9_-]{8,256}"), "[REDACTED_API_KEY]"),
+    (re.compile(r"(?i)\bsk-[A-Za-z0-9_-]{8,256}"), "[REDACTED_API_KEY]"),
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "[REDACTED_API_KEY]"),
+    (
+        re.compile(r"(?i)\bbearer\s{1,8}[A-Za-z0-9._~+/-]{8,4096}=*"),
+        "Bearer [REDACTED_TOKEN]",
+    ),
+    # Bounded repeats (RFC 5321 limits) keep this linear on long text; an
+    # unbounded "[...]+@" is quadratic and stalled agents on large messages.
+    (
+        re.compile(
+            r"(?i)[A-Z0-9._%+-]{1,64}@[A-Z0-9-]{1,63}(?:\.[A-Z0-9-]{1,63}){0,8}\.[A-Z]{2,24}"
+        ),
+        "[REDACTED_EMAIL]",
+    ),
+)
+
+
+def redact(text: str) -> str:
+    """Replace email addresses, API keys and bearer tokens in ``text``."""
+    for pattern, replacement in _REDACTIONS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def identifier(value: object) -> str | None:
+    """A conversation or run id the API accepts, or None if nothing is left."""
+    if value is None:
+        return None
+    cleaned = _ID_INVALID.sub("-", str(value)).strip("-")[:ID_MAX_LENGTH]
+    return cleaned or None
+
+
+def name(
+    value: object, fallback: str = "unknown", max_length: int = NAME_MAX_LENGTH
+) -> str:
+    """A tool, action or error name in the API's allowed characters."""
+    cleaned = _NAME_INVALID.sub("_", str(value or "")).strip("_")[:max_length]
+    return cleaned or fallback
+
+
+def task_title(value: object) -> str | None:
+    """One short, redacted line, or None. Never the conversation content."""
+    if not isinstance(value, str):
+        return None
+    cleaned = _CONTROL_CHARS.sub(" ", redact(value))
+    cleaned = " ".join(cleaned.split())[:TASK_TITLE_MAX_LENGTH].strip()
+    return cleaned or None
+
+
+def task_type(value: object) -> str | None:
+    """A stable slug such as ``refund_review``; anything else is dropped."""
+    if isinstance(value, str) and _TASK_TYPE.match(value):
+        return value
+    return None
+
+
+def text(value: object, max_length: int) -> str | None:
+    """Redacted free text, cut to the API limit."""
+    if value is None:
+        return None
+    # Cut first (with room for a secret straddling the limit), then redact.
+    return redact(str(value)[: max_length + 512])[:max_length]
+
+
+def duration_ms(value: object) -> int:
+    """Whole milliseconds within the API's range (0 to one hour)."""
+    try:
+        number = int(float(value))  # type: ignore[arg-type]
+    except (TypeError, ValueError, OverflowError):
+        return 0
+    return max(0, min(DURATION_MAX_MS, number))

agents28/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agents28/client.py

@@ -0,0 +1,516 @@
+"""The Agents28 client."""
+
+from __future__ import annotations
+
+import atexit
+import functools
+import inspect
+import logging
+import os
+import platform
+import uuid
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any, TypeVar, overload
+from urllib.parse import urlsplit
+
+import httpx
+
+from . import _sanitize as clean
+from ._delivery import Delivery
+from ._run import Run
+from ._version import __version__
+
+logger = logging.getLogger("agents28")
+
+# Set when the permanent API domain is live; until then pass base_url or set
+# AGENTS28_BASE_URL. Published releases must point at a domain we own.
+DEFAULT_BASE_URL: str | None = None
+DEFAULT_AGENT_VERSION = "unversioned"
+SCHEMA_VERSION = "1.0"
+_LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+Event = dict[str, Any]
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _env_flag(name: str) -> bool | None:
+    raw = os.getenv(name, "").strip().lower()
+    if raw in ("1", "true", "yes", "on"):
+        return True
+    if raw in ("0", "false", "no", "off"):
+        return False
+    return None
+
+
+def _list_field(response: Any, field: str) -> list[dict[str, Any]]:
+    """``response[field]`` if it is a list of objects, else an empty list."""
+    items = response.get(field) if isinstance(response, dict) else None
+    if not isinstance(items, list):
+        return []
+    return [item for item in items if isinstance(item, dict)]
+
+
+class Agents28:
+    """Reports what an AI agent is working on to Agents28.
+
+    Telemetry never breaks the agent: no method raises, and events are sent
+    from a background thread. Configuration falls back to environment
+    variables: ``AGENTS28_API_KEY``, ``AGENTS28_BASE_URL``,
+    ``AGENTS28_AGENT_VERSION`` and ``AGENTS28_ENABLED``.
+
+    Without an API key or base URL the client is disabled: every call is a
+    cheap no-op, so the same code runs in development without credentials.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        agent_version: str | None = None,
+        capture_content: bool = False,
+        enabled: bool | None = None,
+        before_send: Callable[[Event], Event | None] | None = None,
+        timeout: float = 5.0,
+        max_queue_size: int = 5000,
+        batch_size: int = 100,
+        max_retries: int = 2,
+        flush_at_exit: bool = True,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.api_key = (api_key or os.getenv("AGENTS28_API_KEY") or "").strip()
+        resolved_url = (
+            base_url or os.getenv("AGENTS28_BASE_URL") or DEFAULT_BASE_URL or ""
+        )
+        self.base_url = resolved_url.strip().rstrip("/")
+        self.agent_version = clean.name(
+            agent_version
+            or os.getenv("AGENTS28_AGENT_VERSION")
+            or DEFAULT_AGENT_VERSION,
+            fallback=DEFAULT_AGENT_VERSION,
+            max_length=clean.AGENT_VERSION_MAX_LENGTH,
+        )
+        self.capture_content = bool(capture_content)
+        self.before_send = before_send
+        self.timeout = timeout
+        self._transport = transport
+        self._http: httpx.Client | None = None
+        self._delivery: Delivery | None = None
+
+        if enabled is None:
+            enabled = _env_flag("AGENTS28_ENABLED")
+        problem = self._configuration_problem() if enabled is not False else "disabled"
+        self.enabled = problem is None
+        self.disabled_reason = problem
+        if problem not in (None, "disabled"):
+            logger.warning("Agents28 is disabled: %s.", problem)
+
+        self.headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": (
+                f"agents28-python/{__version__} "
+                f"python/{platform.python_version()} {platform.system().lower()}"
+            ),
+        }
+
+        if self.enabled:
+            self._delivery = Delivery(
+                self.base_url + "/v1/events/batch",
+                self.headers,
+                timeout=timeout,
+                max_queue_size=max_queue_size,
+                batch_size=batch_size,
+                max_retries=max_retries,
+                transport=transport,
+            )
+            self._flush_at_exit = flush_at_exit
+            if flush_at_exit:
+                atexit.register(self._at_exit)
+
+    def _configuration_problem(self) -> str | None:
+        if not self.api_key:
+            return "no API key (pass api_key or set AGENTS28_API_KEY)"
+        if not self.base_url:
+            return "no base URL (pass base_url or set AGENTS28_BASE_URL)"
+        parts = urlsplit(self.base_url)
+        if parts.scheme not in ("http", "https") or not parts.hostname:
+            return "base URL must look like https://api.example.com"
+        if parts.scheme == "http" and parts.hostname not in _LOCAL_HOSTS:
+            return "base URL must use https (http is allowed only for localhost)"
+        return None
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def flush(self, timeout: float = 10) -> bool:
+        """Wait until queued events are sent. Returns False on timeout."""
+        return self._delivery.flush(timeout) if self._delivery else True
+
+    def close(self, timeout: float = 10) -> bool:
+        """Send what is queued and stop. Safe to call more than once."""
+        completed = self._delivery.close(timeout) if self._delivery else True
+        if self._delivery and self._flush_at_exit:
+            atexit.unregister(self._at_exit)
+        if self._http is not None:
+            self._http.close()
+            self._http = None
+        return completed
+
+    def _at_exit(self) -> None:
+        if self._delivery:
+            self._delivery.close(timeout=2.0)
+
+    def __enter__(self) -> Agents28:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    @property
+    def delivered_events(self) -> int:
+        return self._delivery.delivered if self._delivery else 0
+
+    @property
+    def failed_events(self) -> int:
+        return self._delivery.failed if self._delivery else 0
+
+    @property
+    def dropped_events(self) -> int:
+        return self._delivery.dropped if self._delivery else 0
+
+    def stats(self) -> dict[str, Any]:
+        """Delivery counters and the last delivery problem, for health checks."""
+        delivery = self._delivery
+        return {
+            "enabled": self.enabled,
+            "disabled_reason": self.disabled_reason,
+            "delivered": delivery.delivered if delivery else 0,
+            "failed": delivery.failed if delivery else 0,
+            "dropped": delivery.dropped if delivery else 0,
+            "queued": delivery.queued if delivery else 0,
+            "last_error": delivery.last_error if delivery else None,
+        }
+
+    # -- runs ----------------------------------------------------------------
+
+    def run(
+        self,
+        task_title: str | None = None,
+        *,
+        task_type: str | None = None,
+        conversation_id: str | None = None,
+        run_id: str | None = None,
+    ) -> Run:
+        """Start a run; use it as a context manager. See :class:`Run`."""
+        return Run(
+            self,
+            task_title=task_title,
+            task_type=task_type,
+            conversation_id=conversation_id,
+            run_id=run_id,
+        )
+
+    @overload
+    def trace(self, function: F) -> F: ...
+
+    @overload
+    def trace(
+        self, *, task_title: str | None = None, task_type: str | None = None
+    ) -> Callable[[F], F]: ...
+
+    def trace(
+        self,
+        function: F | None = None,
+        *,
+        task_title: str | None = None,
+        task_type: str | None = None,
+    ) -> F | Callable[[F], F]:
+        """Decorator: each call of the function is one run (sync or async).
+
+        Inside, ``agents28.current_run()`` returns the run.
+        """
+
+        def decorate(fn: F) -> F:
+            if inspect.iscoroutinefunction(fn):
+
+                @functools.wraps(fn)
+                async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                    with self.run(task_title, task_type=task_type):
+                        return await fn(*args, **kwargs)
+
+                return async_wrapper  # type: ignore[return-value]
+
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with self.run(task_title, task_type=task_type):
+                    return fn(*args, **kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        return decorate(function) if function is not None else decorate
+
+    # -- events (low level) --------------------------------------------------
+
+    def emit(
+        self,
+        event_type: str,
+        conversation_id: str,
+        run_id: str,
+        payload: dict[str, Any],
+    ) -> bool:
+        """Queue one event. Returns False if it was not queued."""
+        if self._delivery is None:
+            return False
+        event: Event = {
+            "event_id": uuid.uuid4().hex,
+            "schema_version": SCHEMA_VERSION,
+            "conversation_id": clean.identifier(conversation_id) or "unknown",
+            "run_id": clean.identifier(run_id) or "unknown",
+            "agent_version": self.agent_version,
+            "occurred_at": datetime.now(UTC).isoformat(),
+            "event_type": event_type,
+            "payload": payload,
+        }
+        if self.before_send is not None:
+            try:
+                edited = self.before_send(event)
+            except Exception:
+                logger.warning(
+                    "Agents28: before_send raised; the event was dropped.",
+                    exc_info=True,
+                )
+                return False
+            if edited is None:
+                return False
+            event = edited
+        return self._delivery.submit(event)
+
+    def run_started(
+        self,
+        conversation_id: str,
+        run_id: str,
+        task_title: str | None = None,
+        task_type: str | None = None,
+    ) -> bool:
+        """Report a run start, optionally with what it is working on.
+
+        ``task_title`` is a short human description ("Refund request review");
+        never put customer names or other personal data in it.
+        ``task_type`` is a stable slug ("refund_review"). Invalid values are
+        dropped, never raised.
+        """
+        payload: dict[str, Any] = {"source": "python-sdk"}
+        title = clean.task_title(task_title)
+        if title:
+            payload["task_title"] = title
+        kind = clean.task_type(task_type)
+        if kind:
+            payload["task_type"] = kind
+        return self.emit("run_started", conversation_id, run_id, payload)
+
+    def message(
+        self, conversation_id: str, run_id: str, role: str, content: str | None = None
+    ) -> bool:
+        if role not in clean.ROLES:
+            logger.warning("Agents28: unknown message role %r; event dropped.", role)
+            return False
+        payload: dict[str, Any] = {"role": role}
+        if self.capture_content and content is not None:
+            payload["content"] = clean.text(content, clean.CONTENT_MAX_LENGTH)
+        return self.emit("message", conversation_id, run_id, payload)
+
+    def tool_completed(
+        self,
+        conversation_id: str,
+        run_id: str,
+        tool_name: str,
+        success: bool,
+        duration_ms: float,
+        result_summary: str | None = None,
+    ) -> bool:
+        payload: dict[str, Any] = {
+            "tool_name": clean.name(tool_name),
+            "success": bool(success),
+            "duration_ms": clean.duration_ms(duration_ms),
+        }
+        if self.capture_content and result_summary is not None:
+            payload["result_summary"] = clean.text(
+                result_summary, clean.SUMMARY_MAX_LENGTH
+            )
+        return self.emit("tool_completed", conversation_id, run_id, payload)
+
+    def action_completed(
+        self,
+        conversation_id: str,
+        run_id: str,
+        action_type: str,
+        action_name: str,
+        success: bool,
+        duration_ms: float,
+        result_summary: str | None = None,
+    ) -> bool:
+        payload: dict[str, Any] = {
+            "action_type": action_type
+            if action_type in clean.ACTION_TYPES
+            else "other",
+            "action_name": clean.name(action_name),
+            "success": bool(success),
+            "duration_ms": clean.duration_ms(duration_ms),
+        }
+        if self.capture_content and result_summary is not None:
+            payload["result_summary"] = clean.text(
+                result_summary, clean.SUMMARY_MAX_LENGTH
+            )
+        return self.emit("action_completed", conversation_id, run_id, payload)
+
+    def run_completed(
+        self, conversation_id: str, run_id: str, duration_ms: float
+    ) -> bool:
+        return self.emit(
+            "run_completed",
+            conversation_id,
+            run_id,
+            {"duration_ms": clean.duration_ms(duration_ms)},
+        )
+
+    def run_failed(self, conversation_id: str, run_id: str, error_type: str) -> bool:
+        return self.emit(
+            "run_failed",
+            conversation_id,
+            run_id,
+            {"error_type": clean.name(error_type, "error")},
+        )
+
+    # -- synchronous API calls -------------------------------------------------
+    # Short timeout, never raise: on any problem they return None, [] or False.
+
+    def _call(self, method: str, path: str, **kwargs: Any) -> tuple[int | None, Any]:
+        if not self.enabled:
+            return None, None
+        try:
+            if self._http is None:
+                self._http = httpx.Client(
+                    base_url=self.base_url,
+                    headers=self.headers,
+                    timeout=self.timeout,
+                    transport=self._transport,
+                )
+            response = self._http.request(method, path, **kwargs)
+            return response.status_code, response.json()
+        except (httpx.HTTPError, ValueError):
+            return None, None
+
+    # Shared Context: knowledge shared between agents of one workspace. Items
+    # read from other agents are untrusted data, never instructions.
+
+    def publish_context(
+        self,
+        key: str,
+        title: str,
+        data: dict[str, Any] | None = None,
+        item_type: str = "fact",
+        run_id: str | None = None,
+        conversation_id: str | None = None,
+        expires_in_hours: int | None = None,
+    ) -> str | None:
+        """Publish (or update) a knowledge item. Returns its id or None."""
+        body: dict[str, Any] = {
+            "key": key,
+            "item_type": item_type,
+            "title": clean.task_title(title) or "",
+            "data": data if isinstance(data, dict) else {},
+        }
+        if run_id:
+            body["run_id"] = run_id
+        if conversation_id:
+            body["conversation_id"] = conversation_id
+        if expires_in_hours:
+            body["expires_in_hours"] = expires_in_hours
+        status, response = self._call("POST", "/v1/context", json=body)
+        if status == 201 and isinstance(response, dict):
+            value = response.get("item_id")
+            return value if isinstance(value, str) else None
+        return None
+
+    def read_context(
+        self, key: str | None = None, item_type: str | None = None, limit: int = 20
+    ) -> list[dict[str, Any]]:
+        """Read knowledge shared in this agent's workspace."""
+        params: dict[str, Any] = {"limit": limit}
+        if key:
+            params["key"] = key
+        if item_type:
+            params["item_type"] = item_type
+        status, response = self._call("GET", "/v1/context", params=params)
+        return _list_field(response, "items") if status == 200 else []
+
+    # Agent Handoff: pass a task to another agent in the same workspace.
+
+    def list_teammates(self) -> list[dict[str, Any]]:
+        """Other agents in this workspace you can hand work to."""
+        status, response = self._call("GET", "/v1/workspace-agents")
+        return _list_field(response, "agents") if status == 200 else []
+
+    def request_handoff(
+        self,
+        to_agent_id: str,
+        title: str,
+        context: dict[str, Any] | None = None,
+        context_item_ids: list[str] | None = None,
+        task_type: str | None = None,
+        request_key: str | None = None,
+        run_id: str | None = None,
+        conversation_id: str | None = None,
+    ) -> str | None:
+        """Ask another agent to take a task. Returns the handoff id or None.
+
+        Reusing the same ``request_key`` returns the existing handoff instead of
+        creating a duplicate, so it is safe to retry.
+        """
+        payload: dict[str, Any] = {
+            "to_agent_id": to_agent_id,
+            "title": clean.task_title(title) or "Handoff",
+            "context": context if isinstance(context, dict) else {},
+            "context_item_ids": list(context_item_ids or []),
+        }
+        kind = clean.task_type(task_type)
+        if kind:
+            payload["task_type"] = kind
+        for field, value in (
+            ("request_key", request_key),
+            ("run_id", run_id),
+            ("conversation_id", conversation_id),
+        ):
+            if value:
+                payload[field] = value
+        status, response = self._call("POST", "/v1/handoffs", json=payload)
+        if status == 201 and isinstance(response, dict):
+            value = response.get("handoff_id")
+            return value if isinstance(value, str) else None
+        return None
+
+    def my_handoffs(
+        self, direction: str = "incoming", status: str | None = None, limit: int = 20
+    ) -> list[dict[str, Any]]:
+        """Handoffs sent to this agent (incoming) or by it (outgoing)."""
+        params: dict[str, Any] = {"direction": direction, "limit": limit}
+        if status:
+            params["status"] = status
+        code, response = self._call("GET", "/v1/handoffs", params=params)
+        return _list_field(response, "handoffs") if code == 200 else []
+
+    def update_handoff(
+        self,
+        handoff_id: str,
+        status: str,
+        note: str | None = None,
+        result: dict[str, Any] | None = None,
+    ) -> bool:
+        """Accept, decline, complete, fail or cancel a handoff."""
+        payload: dict[str, Any] = {"status": status}
+        if note:
+            payload["note"] = clean.task_title(note)
+        if isinstance(result, dict):
+            payload["result"] = result
+        code, _ = self._call("POST", f"/v1/handoffs/{handoff_id}/status", json=payload)
+        return code == 200

agents28-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: agents28
+Version: 0.1.0
+Summary: See what every AI agent in your business is working on. The official Python SDK for Agents28.
+License-Expression: MIT
+Project-URL: Homepage, https://agentcheck-theta.vercel.app
+Keywords: ai,agents,llm,monitoring,observability,telemetry,agent-handoff
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# Agents28 Python SDK
+
+**See what every AI agent in your business is working on.**
+
+Agents28 is one office for all your AI agents, whatever model they run on. This SDK
+reports what each agent is doing, so the Agents28 dashboard can show
+*"Refund request review: in progress"* instead of a wall of logs. It also lets
+agents share knowledge and hand work to each other.
+
+- **Never breaks your agent.** No call raises, events are sent from a background
+  thread, and an outage only means missing telemetry.
+- **Private by default.** Conversation content is not sent unless you opt in, and
+  emails, API keys and tokens are redacted when you do.
+- **Small.** One dependency (`httpx`), Python 3.11+, fully typed.
+
+## Install
+
+```bash
+pip install agents28
+```
+
+## Quick start
+
+Create an agent in the Agents28 dashboard and generate its API key. The
+dashboard shows the key and your API URL once.
+
+```bash
+export AGENTS28_API_KEY="ack_..."
+export AGENTS28_BASE_URL="https://..."   # shown in the dashboard
+```
+
+```python
+import agents28
+
+client = agents28.Agents28(agent_version="support-v3")
+
+with client.run("Refund request review", task_type="refund_review") as run:
+    run.message("user")
+
+    with run.tool("lookup_order"):
+        order = lookup_order(order_id)
+
+    with run.action("issue_refund", "business_operation"):
+        issue_refund(order)
+
+    run.message("assistant")
+```
+
+That one block reports the run's start, every step with its duration and
+success, and the run's completion. If an exception escapes, the run is
+reported failed with the exception's type, and the exception is re-raised
+unchanged.
+
+Pending events are sent when the program exits. In long-running services,
+call `client.close()` on shutdown.
+
+## Decorator
+
+Every call of a decorated function is one run. It works on `async` functions
+too.
+
+```python
+@client.trace(task_title="Answer support ticket", task_type="support_ticket")
+async def answer(ticket):
+    run = agents28.current_run()
+    run.message("user")
+    ...
+```
+
+## What is sent
+
+| Call | Sent by default | Sent only with `capture_content=True` |
+|---|---|---|
+| `run.message(role, content)` | role | content, redacted and cut to 10,000 characters |
+| `run.tool(name)` / `run.action(name, type)` | name, success, duration | `step.result_summary`, redacted and cut to 4,000 characters |
+| `client.run(task_title, task_type=...)` | title and type | |
+
+`task_title` is always redacted and kept to one line of up to 120 characters.
+Don't put customer names or other personal data in it.
+
+To change or drop any event before it leaves the process, pass a hook:
+
+```python
+def scrub(event):
+    if event["event_type"] == "message":
+        return None          # drop it
+    return event             # or return an edited copy
+
+client = agents28.Agents28(before_send=scrub)
+```
+
+## Shared knowledge between agents
+
+Agents in the same workspace can share knowledge, even when they run on
+different models:
+
+```python
+client.publish_context(
+    key="customer:acme",
+    title="Acme renewal status",
+    data={"plan": "enterprise", "renewal": "2026-12-01"},
+)
+
+items = client.read_context(key="customer:acme")
+```
+
+Each item records which agent published it, when, and its version. Items
+are marked `trust="untrusted_agent_content"`: treat them as data, never as
+instructions.
+
+## Handing work to another agent
+
+```python
+teammates = client.list_teammates()
+
+handoff_id = client.request_handoff(
+    to_agent_id=teammates[0]["agent_id"],
+    title="Research Acme before the renewal call",
+    context={"account": "acme"},
+    request_key="acme-renewal-research",   # retrying with the same key never duplicates
+)
+
+# On the receiving agent:
+for handoff in client.my_handoffs(status="requested"):
+    client.update_handoff(handoff["handoff_id"], "accepted")
+    ...
+    client.update_handoff(handoff["handoff_id"], "completed", result={"summary": "done"})
+```
+
+A handoff moves from `requested` to `accepted` or `declined`. An accepted
+handoff ends as `completed` or `failed`. The sender, or a person in Agents28,
+can cancel an open handoff.
+
+## Configuration
+
+| Argument | Environment variable | Default |
+|---|---|---|
+| `api_key` | `AGENTS28_API_KEY` | none: the client is disabled |
+| `base_url` | `AGENTS28_BASE_URL` | none: the client is disabled |
+| `agent_version` | `AGENTS28_AGENT_VERSION` | `unversioned` |
+| `enabled` | `AGENTS28_ENABLED` | on when the key and URL are set |
+| `capture_content` | | `False` |
+| `before_send` | | none |
+| `timeout` | | `5.0` seconds |
+| `max_queue_size` / `batch_size` | | `5000` / `100` |
+
+If the key or URL is missing, or the URL is not `https` (plain `http` is
+allowed only for `localhost`), the client turns itself off and every call
+does nothing. The same code then runs in development and CI without
+credentials.
+
+## Reliability
+
+- Events are batched and sent in the background. A full queue drops new
+  events rather than slowing your agent.
+- Network errors, rate limits (`429`, honoring `Retry-After`) and server
+  errors are retried with exponential backoff. Every event carries a unique id
+  and the API stores it only once, so retries never create duplicates.
+- Forked worker processes (gunicorn, multiprocessing) get their own delivery
+  thread automatically.
+- `client.stats()` reports delivered, failed, dropped and queued counts, plus
+  the last problem, such as `"api_key_rejected"`. Use it in a health check.
+- Warnings go to the standard `logging` logger named `agents28`.
+
+## Lower-level API
+
+For full control over ids and timing, every event can also be sent directly:
+`run_started`, `message`, `tool_completed`, `action_completed`,
+`run_completed`, `run_failed`. Each takes `conversation_id` and `run_id`.
+
+## License
+
+MIT

agents28-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+agents28/__init__.py,sha256=ytk2N5f2PnxiRP5jdj9LxqElJGm1XnP_ek0v0E51rwk,542
+agents28/_delivery.py,sha256=LQqlWmBwXstIkn9yZVwzN1o9j7o5ILnfZzji7-YxMyk,7191
+agents28/_run.py,sha256=6d714pV4OdkilrQJsh_upgDXEOsMgndaQ4KU-sGYzJQ,6019
+agents28/_sanitize.py,sha256=VHpjOz5G_nVAjs30wlpUkHJ3H_IPAeJU78V_RcXP4Oc,3546
+agents28/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+agents28/client.py,sha256=ODBcAKZaG7QnWyXTfUjYK2ORcE4038WCBX6upPZS1N8,18651
+agents28/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agents28-0.1.0.dist-info/licenses/LICENSE,sha256=6hxIEIHqsZjyLS-JyJx4hZDfdqPods8xbfxLOZ3DEpo,1065
+agents28-0.1.0.dist-info/METADATA,sha256=2sNLj6aB1IByfp16nkj22p5LkUzm7T5lYga4jLBKDRo,6703
+agents28-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agents28-0.1.0.dist-info/top_level.txt,sha256=y0aZ81KNQZY4YHtIiu7u-4qeSzJZxUVHSWR9qH1PIwY,9
+agents28-0.1.0.dist-info/RECORD,,

agents28-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agents28-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agents28
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agents28-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agents28