agents28 0.1.0__tar.gz

agents28-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to the `agents28` package. The project follows
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.0 (unreleased)
+
+First public release.
+
+- `Agents28` client, configured by arguments or `AGENTS28_*` environment
+  variables. It disables itself when not configured, and requires `https`
+  except for `localhost`.
+- Runs: the `client.run()` context manager and the `@client.trace` decorator
+  (sync and async), plus timed steps (`run.tool()`, `run.action()`) and
+  `agents28.current_run()`.
+- Background delivery:
+  - batches of up to 100 events, with a bounded queue
+  - retries with backoff and jitter, honoring `Retry-After`
+  - fork safety, flushing at exit, and `stats()`
+- Privacy:
+  - content is opt-in
+  - emails, API keys and bearer tokens are redacted, with linear-time patterns
+  - a `before_send` hook can edit or drop events
+- Every value is repaired to the API's limits, so one bad value never fails a
+  batch.
+- Shared Context: `publish_context`, `read_context`.
+- Agent Handoff: `list_teammates`, `request_handoff`, `my_handoffs`,
+  `update_handoff`.

agents28-0.1.0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md
+graft tests
+global-exclude __pycache__ *.py[cod]

agents28-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,173 @@
+# 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/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-0.1.0/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)