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
