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

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.

export AGENTS28_API_KEY="ack_..."
export AGENTS28_BASE_URL="https://..."   # shown in the dashboard

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.

Outcomes: what the work achieved

Tasks show what your agents did; outcomes show what it was worth. Report them inside a run, and the Agents28 Office sums them by name and unit:

with client.run("Close Globex renewal") as run:
    ...
    run.outcome("Deal closed", value=1200, unit="USD")
    run.outcome("Meeting booked", count=2)

Use a short, stable name ("Refund approved", not "Refund for order 4471"), since results are grouped by it. Agents28 never guesses outcomes: only what you report appears.

Decorator

Every call of a decorated function is one run. It works on async functions too.

@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

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:

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:

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

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

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